--- title: 小程序卡片(Widget) summary: "介绍小程序卡片(Widget)的开发方法，包括工程配置、支持的组件与 API 及平台配置流程。基于OEM App的微定制方案, 开放了不同程度的小程序卡片版位。" questions: - 如何创建小程序卡片(Widget)项目？ - project.tuya.json 中如何声明小程序卡片的开发目录？ - widget.json 文件的作用是什么？ - 小程序卡片(Widget)支持哪些内置组件？ - Widget 函数支持哪些生命周期回调？ - 如何使用 ty.setWidgetHeight 动态设置小程序卡片高度？ - Widget 的 size 配置支持哪些取值？ - 如何在小程序开发者平台配置小程序卡片信息？ - 小程序卡片(Widget)的 API 是如何注入的？ - 如何注册一个小程序卡片(Widget)？ --- ## 开发 Widget 代表应用的一个小程序卡片，负责小程序卡片的展示和交互（暂只支持 OEM App）。 小程序卡片(Widget) 的开发在智能小程序的基础上增加一个目录即可，用于存放小程序卡片(Widget)的代码。并在 `project.tuya.json` 中增加一个声明。 ### 创建小程序卡片(Widget)项目 在 Tuya MiniApp IDE 中, 新建项目并选择小程序卡片(Widget)对应模板即可自动创建小程序卡片(Widget)项目。 ### 工程配置 #### 1. project.tuya.json 中声明小程序卡片(Widget)开发目录 ```json { "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 目录, 项目整体目录结构如下: ```text ├── 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)的信息 填写的小程序卡片路径"cards/weather/index"需要填写在开发者平台小程序卡片路径一栏。 ```js { widgets: ['cards/weather/index', '...']; } ``` 可声明多个小程序卡片(Widget). #### 3. 创建小程序卡片(Widget)页面文件 每个小程序卡片(Widget)对应一个子目录，一般有多少个小程序卡片(Widget)，就有多少个子目录。 每个小程序卡片(Widget)一般包含四个文件。 - `[WidgetPath].ts`：注册小程序卡片(Widget) - `[WidgetPath].tyml`：小程序卡片(Widget)结构 - `[WidgetPath].tyss`：小程序卡片(Widget)样式 - `[WidgetPath].json`：小程序卡片(Widget)配置 - `[WidgetPath].rjs`：小程序卡片(Widget)渲染脚本文件（可选） ```json 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: 是否显示间距和圆角, 布尔类型。 ```json { "size": "middle", // "size": "middle" // "size": "large" // "size": 0.75 "isDisablePadding": true } ``` ### 小程序卡片(Widget)组件 小程序卡片(Widget)不同于小程序页面，仅支持有限的组件，用于绘制小程序卡片(Widget) 的 UI 界面。现支持的内置组件如下： | 名称 | 功能说明 | | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | [view](/cn/miniapp/develop/miniapp/component/view-container/view) | 布局容器 | | [button](/cn/miniapp/develop/miniapp/component/form-component/button) | 按钮 | | [text](/cn/miniapp/develop/miniapp/component/basic-content/text) | 文本 | | [image](/cn/miniapp/develop/miniapp/component/media-component/image) | 图像容器 | | [swiper](/cn/miniapp/develop/miniapp/component/view-container/swiper) | 滑块视图容器 | | [swiper-item](/cn/miniapp/develop/miniapp/component/view-container/swiper-item) | 滑块视图容器子项 | | [canvas](/cn/miniapp/develop/miniapp/component/canvas/canvas) | 画布 (使用 [rjs 渲染脚本](/cn/miniapp/develop/miniapp/framework/api/render) 绘制图表) | | [movable-area](/cn/miniapp/develop/miniapp/component/view-container/movable-area) | 可移动区域 | | [movable-view](/cn/miniapp/develop/miniapp/component/view-container/movable-view) | 可移动的视图容器，在页面中可以拖拽滑动。movable-view 必须在 movable-area 组件中，并且必须是直接子节点，否则不能移动。 | | [switch](/cn/miniapp/develop/miniapp/component/form-component/switch) | 开关选择器。 | | [slider](/cn/miniapp/develop/miniapp/component/form-component/slider) | 滑动选择器。 | ### 小程序卡片(Widget)API 小程序卡片(Widget)的 API 是通过 kit 插件注入的, 小程序卡片(Widget)的 kit 插件与所属小程序保持一致, 都是在 `project.tuya.json` 中声明需要的 kit, 如下: ```js { "dependencies": { "BaseKit": "3.0.0", "MiniKit": "3.0.0", "BizKit": "3.0.1" } } ``` ### 注册小程序卡片(Widget) Widget 函数，是一个构造函数，用来指定小程序卡片的初始数据、生命周期回调、事件处理函数等。小程序卡片必须使用 [Widget()](/cn/miniapp/develop/miniapp/framework/api/widget) 函数 注册且只注册一次。 小程序卡片(Widget)的注册方式与小程序页面选项基本一致，具体可查看 [Widget()](/cn/miniapp/develop/miniapp/framework/api/widget) 函数使用。 ```js 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(){} //监听主题变化 ... // 其它方法 }) ``` Tips: 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)宽高 使用示例 ```js 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); } }); }, }) ``` ## 平台配置 开发完成的小程序卡片需要在小程序开发者平台和 涂鸦开发者平台 上配置相关信息。 ### 小程序开发者平台 在 [小程序开发者平台](https://iot.tuya.com/miniapp)选择您自己的小程序，点击基础设置的小程序卡片信息设置的新增设置。 填写您的小程序卡片信息。 ### 涂鸦开发者平台 在[涂鸦开发者平台 app 开发](https://iot.tuya.com/oem/index)选择您自己的 app。点击详细配置。 进入 app 配置页面，在首页和页面中增加自定义卡片，内容就是您开发的小程序卡片。 更多内容请[查看](https://developer.tuya.com/cn/docs/iot/smart-life-app-updates?id=Kd4is05osruqn#title-4-%E4%B8%AA%E6%80%A7%E5%8C%96%E5%B7%A5%E5%85%B7%E5%8D%87%E7%BA%A7%EF%BC%8C%E6%94%AF%E6%8C%81%20OEM%20App%20%E5%BE%AE%E5%AE%9A%E5%88%B6)