目录

智能小程序小部件(Widget)开发详解

Widget 代表应用的一个小部件,负责小部件的展示和交互。

小部件(Widget) 的开发在智能小程序的基础上增加一个目录即可,用于存放小部件(Widget)的代码。并在 project.tuya.json 中增加一个声明。

创建小部件(Widget)项目

在 Tuya MiniApp Tools 中,新建项目并选择小部件(Widget)对应模板即可自动创建小部件(Widget)项目。

工程配置

1. project.tuya.json 中声明小部件(Widget)开发目录

复制代码
{
  "projectname": "widget-demo",
  "i18n": true,
+ "miniprogramRoot": "app/",  # 小程序源码
+ "widgetRoot": "widget/",    # 小部件(Widget)源码
  "baseversion": "2.10.12",
  "compileType": "widget",
  "dependencies": {
    "BaseKit": "3.0.0",
    "MiniKit": "3.0.0",
    "BizKit": "3.0.1"
  }
}

注:小程序文件迁移到 app 目录下。

  • 在小程序项目内新增 widget 目录, 项目整体目录结构如下:

    ├── package.json
    ├── project.tuya.json
    ├── app
    │ ├── app.js
    │ ├── app.json
    │ ├── app.tyss
    │ ├── assets
    │ ├── i18n
    │ ├── components
    │ ├── pages
    │ │ └── home
    │ │ ├── index.json
    │ │ ├── index.tyss
    │ │ ├── index.tyml
    │ │ ├── index.js,ts
    │ │ └── index.rjs
    │ └── theme.json
    ├── widget
    │ ├── assets
    │ ├── cards
    │ │ └── weather
    │ │ ├── index.json
    │ │ ├── index.tyss
    │ │ ├── index.tyml
    │ │ ├── index.js,ts
    │ │ └── index.rjs
    └─────└── widget.json

2. widget.json 文件描述当前小部件(Widget)的信息

复制代码
{
  widgets: ['pages/home/index', 'pages/list/index'];
}

可声明多个小部件(Widget).

3. 创建小部件(Widget)页面文件

每个小部件(Widget)对应一个子目录,一般有多少个小部件(Widget),就有多少个子目录。

每个小部件(Widget)一般包含四个文件。

  • [WidgetPath].ts:注册小部件(Widget)

  • [WidgetPath].tyml:小部件(Widget)结构

  • [WidgetPath].tyss:小部件(Widget)样式

  • [WidgetPath].json:小部件(Widget)配置

  • [WidgetPath].rjs:小部件(Widget)渲染脚本文件(可选)

    widget
    ├── cards
    │ └── home
    │ ├── index.json
    │ ├── index.tyss
    │ ├── index.tyml
    │ ├── index.ts
    │ └── index.rjs
    └── widget.json

小部件(Widget)配置

  • size: 小部件(Widget)的尺寸大小, size 的值支持: tiny, small, middle, large 和 自定义的高/宽比数值(宽以页面宽为准)。size 必填, 不支持动态尺寸。

  • isDisablePadding: 是否显示间距和圆角, 布尔类型。

    {
    "size": "middle",
    // "size": "middle"
    // "size": "large"
    // "size": 0.75
    "isDisablePadding": true
    }

小部件(Widget)组件

小部件(Widget)不同于小程序页面,仅支持有限的组件,用于绘制小部件(Widget) 的 UI 界面。现支持的内置组件如下:

名称 功能说明
view 布局容器
button 按钮
text 文本
image 图像容器
swiper 滑块视图容器
swiper-item 滑块视图容器子项
canvas 画布 (使用 rjs 渲染脚本 绘制图表)
movable-area 可移动区域
movable-view 可移动的视图容器,在页面中可以拖拽滑动。movable-view 必须在 movable-area 组件中,并且必须是直接子节点,否则不能移动。
switch 开关选择器。
slider 滑动选择器。

小部件(Widget)API

小部件(Widget)不同于小程序页面, 小部件(Widget)的 API 是通过 kit 插件注入的, 小部件(Widget)的 kit 插件与所属小程序保持一致, 都是在 project.tuya.json 中声明需要的 kit, 如下:

复制代码
{
  "dependencies": {
    "BaseKit": "3.0.0",
    "MiniKit": "3.0.0",
    "BizKit": "3.0.1"
  }
}

注册小部件(Widget)

Widget 函数,是一个构造函数,用来指定小部件的初始数据、生命周期回调、事件处理函数等。小部件必须使用 Widget() 函数 注册且只注册一次。

小部件(Widget)的注册方式与小程序页面选项基本一致,具体可查看 Widget() 函数使用。

复制代码
Widget({
 data: { text: '初始化数据'},
 onLoad(query){
  console.log(query); // 可以在 onLoad 的参数中获取打开当前 Widget 路径中的参数
 }, // Widget 加载
 onShow(){}, // 容器可见时触发
 onReady(options){ // Widget 初次渲染完成
   this.setData({ text: "更新数据" })
 },
 onHide(){}, // 容器隐藏时触发
 onRefresh(){} // Widget 重新加载更新, 常用于App下拉刷新场景
 onPageScroll(){} // Widget 卡片内滚动触发
 onUnload(){}, // 容器卸载时触发
 onThemeChange(){} //监听主题变化
   ...
 // 其它方法
})

Tip:

  1. 小部件(Widget)之间的间距为 12px。
  2. 小部件(Widget)各个圆角为 16px。

小部件(Widget)支持动态高度

  • 小部件(Widget) API ty.setWidgetHeight: 动态设置小部件(Widget)的高度

参数(Object object)

属性 类型 默认值 必填 说明
height number 设置的高度, 单位: px
complete function 接口调用结束的回调函数(调用成功、失败都会执行)
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
  • 小部件(Widget) 实例方法 getWidgetInfo: 获取小部件(Widget)的宽高信息
  • 小部件(Widget) 实例方法 rpxToPx: 将rpx值转为px值, 参数为数值型
  • 小部件(Widget) 生命周期 onResize: 监听小部件(Widget)动态高度变化, 回调参数为当前小部件(Widget)宽高

使用示例

复制代码
Widget({
  data: {},
  onResize(query) {
    console.log('onResize', query); // query: {height, width} 单位:px
  },
  changeHeight(e) {
    const widgetInfo = this.getWidgetInfo(); // widgetInfo: {height, width} 单位:px
    const addHeight = this.rpxToPx(100); // rpx值转为px
    
    const allHeight = widgetInfo.height + addHeight;
    ty.setWidgetHeight({
      height: allHeight, // 高度单位:px
      success: (res) => {
        console.log('Widget height set successfully', res);
      },
      fail: (err) => {
        console.log('Widget height setting failed', err);
      }
    });
  },
})

小部件(Widget)案例

本文是转载文章,点击查看原文
如有侵权,请联系 xyy@jishuzhan.net 删除
相关推荐
TDengine (老段)9 分钟前
TDengine 中的视图
数据库·物联网·oracle·时序数据库·tdengine·iotdb
charlie1145141911 小时前
从0开始的构建的天气预报小时钟(基于STM32F407ZGT6,ESP8266 + SSD1309)——第2章——构建简单的ESP8266驱动
stm32·单片机·物联网·学习·c·esp8266
努力毕业的小土博^_^3 小时前
【EI/Scopus双检索】2025年4月光电信息、传感云、边缘计算、光学成像、物联网、智慧城市、新材料国际学术盛宴来袭!
人工智能·神经网络·物联网·算法·智慧城市·边缘计算
ps酷教程4 小时前
Apache httpclient & okhttp(2)
okhttp·apache
云说智树5 小时前
破解GenAI时代工业物联网落地难题:研华IoTSuite如何用“全栈技术“重构智造未来?
人工智能·物联网
TDengine (老段)5 小时前
TDengine 中的日志系统
java·大数据·数据库·物联网·时序数据库·tdengine·iotdb
Blossom.1187 小时前
《探索边缘计算:重塑未来智能物联网的关键技术》
人工智能·深度学习·神经网络·物联网·机器学习·计算机视觉·边缘计算
沙子可可8 小时前
Apache Camel指南-第四章:路由径构建之异常处理
apache·集成学习
程序猿熊跃晖9 小时前
Excel 数据导入与 SQL 生成:基于 Hutool 和 Apache POI 的优雅实践
sql·apache·excel