Widget | AIUI | Rokid

Widget 是智能体提供的小尺寸独立界面,适合展示天气、播放状态、设备数据和订单进度等一眼即可理解的信息。它和 Page 使用相同的 .ink 语法、数据绑定、组件与样式,但拥有独立入口和更精简的生命周期。

Widget

Widget 是智能体提供的小尺寸独立界面,适合展示天气、播放状态、设备数据和订单进度等一眼即可理解的信息。它和 Page 使用相同的 .ink 语法、数据绑定、组件与样式,但拥有独立入口和更精简的生命周期。

声明 Widget

先在 app.json 的 widgets 数组中声明 Widget。每一项描述 Widget 的入口、名称、用途、尺寸类别和展示方式。

{
  "pages": ["pages/index/index"],
  "widgets": [
    {
      "path": "widgets/clock/index",
      "family": "1x1",
      "placement": "persistent",
      "displayName": "时钟",
      "description": "显示当前时间。"
    },
    {
      "path": "widgets/weather/index",
      "family": "1x2",
      "placement": "overlay",
      "displayName": "天气",
      "description": "显示当前位置的天气和温度。"
    }
  ]
}

app.json.widgets 字段

字段类型必填默认值说明
pathstring是-Widget 的项目相对路径,不包含 .ink 扩展名。路径必须对应实际存在的 .ink 文件。
family"1x1" | "1x2"是-Widget 占用的尺寸类别。还必须在 Widget 文件的 <script def> 中声明相同的值。
placement"persistent" | "overlay"否"persistent"Widget 的展示方式。该字段只在 app.json 中声明,不写入 Widget 文件。
displayNamestring是-面向用户显示的 Widget 名称,例如“天气”。多语言版本在对应的 app.<locale>.json 中声明。
descriptionstring是-对 Widget 展示内容或用途的简短说明。多语言版本在对应的 app.<locale>.json 中声明。

例如,widgets/weather/index 对应 widgets/weather/index.ink。path 应保持唯一;同一路径不要在 widgets 数组中重复声明。

family 是尺寸类别,而不是固定像素尺寸。Widget 应根据实际可用宽高进行自适应布局。

Widget 元数据的多语言

app.json 必须包含每个 Widget 的默认 displayName 和 description。如果需要提供其他语言,不要在每个 Widget 中嵌套多语言对象,而是在应用根目录创建 app.<locale>.json 覆盖文件。例如:

{
  "locale": "en-US",
  "widgets": {
    "widgets/weather/index": {
      "displayName": "Weather",
      "description": "Shows the weather and temperature for your current location."
    },
    "widgets/clock/index": {
      "displayName": "Clock",
      "description": "Shows the current time."
    }
  }
}

语言文件名使用 BCP 47 语言标签,例如 app.en-US.json 或 app.zh-TW.json。语言文件中的 widgets 是以 Widget path 为键的对象,只能覆盖 displayName 和 description,不能声明或修改 family、placement 等运行配置。

运行时会按照用户的语言偏好选择语言文件,并按 BCP 47 的逐级回退规则匹配;未匹配的语言、未声明的 Widget 或缺少的字段都会回退到 app.json 中的默认值。因此,app.json 必须始终能够独立完成应用配置和 Widget 元数据展示。

选择展示方式

placement 决定 Widget 是保持在固定位置,还是作为临时内容叠加在用户已配置的 Widget 之上。它不改变 Widget 的文件结构、数据绑定或生命周期 API。

常驻 Widget

将 placement 设置为 persistent,适合需要持续可见或位置稳定的内容,例如时钟和设备状态。

{
  "path": "widgets/clock/index",
  "family": "1x1",
  "placement": "persistent"
}

常驻 Widget 添加到布局后会保留其位置,不会因为可叠加 Widget 的打开或关闭而被移除。省略 placement 时采用此行为,因此未声明该字段的现有 Widget 保持兼容。

可叠加 Widget

将 placement 设置为 overlay,表示 Widget 可以通过 window.open(url, '_widget') 叠加在用户已配置的 Widget 之上。可叠加 Widget 适合展示具有明确开始和结束状态的生命周期信息,例如打车订单、外卖订单和配送进度。状态结束后,Widget 可以调用 window.close() 退出当前叠加层。

{
  "path": "widgets/weather/index",
  "family": "1x2",
  "placement": "overlay"
}

overlay 表示 Widget 通过打开和关闭操作进入或退出叠加层。Widget 显示和隐藏时,运行时会调用 onAttach() 或 onDetach();不要用这两个回调保存只能初始化一次的状态,也不要假设关闭叠加层后一定会保留当前实例。

如果内容必须持续可见或不应由 window.open() 临时打开,请使用 persistent。如果内容具有明确的开始和结束状态,并能正确处理打开、状态更新、结束和关闭,请使用 overlay。

创建 Widget 界面

Widget 文件使用 <widget> 作为界面根节点。为兼容 0.18,<script def> 中仍需声明 family,并且必须与 app.json 保持一致。placement 以及后续展示调度字段只在 app.json 中声明,不写入 .ink。

<script def>
{
  "widget": { "family": "1x2" },
  "usingComponents": {
    "weather-icon": "/components/weather-icon/index"
  }
}
</script>

<script setup>
export default {
  data: {
    city: '杭州',
    temperature: 24,
  },
  refresh() {
    this.setData({ temperature: this.data.temperature + 1 });
  },
};
</script>

<widget>
  <view class="weather" bindtap="refresh">
    <weather-icon />
    <text>{{city}}</text>
    <text>{{temperature}}°C</text>
  </view>
</widget>

<style>
.weather {
  display: flex;
  flex-direction: column;
  padding: 12px;
}
</style>

一个 .ink 文件不能同时包含 <page> 和 <widget>。如果文件中的 family 与 app.json 不一致,Widget 将无法加载。

更新显示内容

Widget 使用 data 保存界面数据,并通过 setData() 更新显示内容。可以更新顶层字段,也可以使用点路径更新嵌套字段。

export default {
  data: {
    status: { label: '待机' },
    count: 0,
  },
  activate() {
    this.setData({
      count: this.data.count + 1,
      'status.label': '运行中',
    });
  },
};

处理 Widget 的状态变化

Widget 提供四个可选回调:

回调适合执行的操作
onCreate(options)初始化 Widget 数据和只需执行一次的资源
onAttach()刷新即将展示的数据,恢复可见时需要的任务
onDetach()暂停只在 Widget 显示时需要的任务
onDestroy()取消请求、移除监听并释放资源
export default {
  data: { updatedAt: 0 },
  refresh() {
    this.setData({ updatedAt: Date.now() });
  },
  onCreate() {
    console.log('Widget 已创建');
  },
  onAttach() {
    this.refreshTimer = setInterval(() => this.refresh(), 60_000);
  },
  onDetach() {
    clearInterval(this.refreshTimer);
  },
  onDestroy() {
    clearInterval(this.refreshTimer);
  },
};

onAttach() 和 onDetach() 可能多次调用,因此恢复和暂停逻辑应允许重复执行。

Widget 与 Page 的区别

  • Widget 不进入 Page 导航栈。
  • Widget 使用 onCreate(options)、onAttach()、onDetach() 和 onDestroy(),不使用 Page 的 onLoad()、onShow()、onReady()、onHide() 和 onUnload()。
  • Widget 不提供 enableWorldAwareness() 和 finish() 等 Page 专属能力。
  • Widget 可以使用数据绑定、自定义组件、事件处理、图片和 Canvas。
  • Widget 的 family 用于表达界面尺寸类别;布局仍应适应实际可用宽高。

继续阅读

  • Widget API:查看 data、setData()、尺寸和状态属性
  • app.json:查看应用入口配置
  • 组件:在 Widget 中复用界面组件
  • Canvas:在 Widget 中绘制图形

URL 查询参数

window.open('widgets/weather/index?city=hangzhou', '_widget') 会把参数传给 onCreate(options)。例如通过 options.city 初始化城市;值为字符串,无参数时为 {}。完整示例见 Widget API。