页面定义 | AIUI | Rokid

AIUI 页面由页面配置、页面逻辑、页面结构和页面样式组成。推荐使用 .ink 单文件形式:<script def> 声明页面配置,<script setup> 导出页面逻辑,<page> 描述界面结构,<style> 定义页面样式。

页面定义

AIUI 页面由页面配置、页面逻辑、页面结构和页面样式组成。推荐使用 .ink 单文件形式:<script def> 声明页面配置,<script setup> 导出页面逻辑,<page> 描述界面结构,<style> 定义页面样式。

需要特别区分:<script def> 中是 JSON,不是可执行 JavaScript;生命周期、事件处理函数和初始状态应写在 <script setup> 的 export default 对象中。

完整页面示例

<script type="application/json" def>
{
  "navigationBarTitleText": "天气",
  "description": "根据城市展示天气信息。",
  "schema": {
    "data": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "要查询的城市名称。"
        }
      },
      "required": ["city"]
    }
  },
  "usingComponents": {
    "weather-card": "components/weather-card"
  },
  "disableScroll": true
}
</script>

<script setup>
export default {
  data: {
    city: '',
    status: '等待查询'
  },
  onLoad(query) {
    this.setData({
      city: query.city || '',
      status: query.city ? '查询完成' : '请选择城市'
    });
  },
  handleComplete() {
    this.finish();
  }
}
</script>

<page>
  <weather-card city="{{city}}" status="{{status}}" />
  <button bindtap="handleComplete">完成</button>
</page>

<style>
page {
  padding: 16px;
}
</style>

同一个页面也可以拆成同名的 .json、.js、.wxml 和 .wxss 四个文件。此时 .json 等价于 <script def>,.js 等价于 <script setup> 中的默认导出。不要为同一路由混用两种结构。

<script def> 页面配置

<script def> 必须包含一个合法的 JSON 对象,不能包含注释、函数、变量或尾随逗号。建议保留 type="application/json",用来明确内容类型。

常用字段

字段类型必填用途
navigationBarTitleTextstring否设置页面标题;是否显示由宿主的导航栏呈现方式决定
descriptionstring对话式页面建议填写向模型说明页面能完成什么任务以及何时使用该页面;应描述可观察的能力,而不是泛化标题
schemaObject否描述宿主或模型打开页面时可以提供的数据契约;页面输入写在 schema.data 中
usingComponentsObject否注册当前页面使用的自定义组件;键是模板标签名,值是组件路径或包导出名
disableScrollboolean否是否关闭页面根节点的默认滚动;默认值为 false

description 和 schema.data 共同把页面描述为可调用的 UI 工具。沉浸式智能体通常直接进入 app.json 注册的入口页面,因此页面不一定需要声明为独立工具;对话式卡片页面则应准确填写这两个字段。

schema.data

schema.data 使用 JSON Schema 描述传入页面的数据。常用字段如下:

字段类型用途
typestring数据根类型,页面输入通常使用 object
propertiesObject定义每个输入字段及其类型、说明和约束
requiredstring[]列出必须提供的字段名;未列出的字段均为可选
properties.<name>.typestring字段类型,如 string、number、integer、boolean、object 或 array
properties.<name>.descriptionstring告诉模型该字段的语义、格式、单位和取值要求
properties.<name>.enumany[]将字段限制为一组离散值
properties.<name>.itemsObject当字段为 array 时描述数组元素
properties.<name>.defaultany描述建议的默认值;页面逻辑仍应自行处理字段缺失的情况

schema.data 描述的是打开页面时的输入,不等同于页面逻辑对象里的 data。前者供模型和宿主构造调用参数,后者是页面首次渲染使用的本地状态。传入参数可在 onLoad(query) 中读取,再通过 setData() 写入页面状态。

{
  "description": "展示指定城市和日期的天气。",
  "schema": {
    "data": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "minLength": 1,
          "description": "城市名称,例如“杭州”。"
        },
        "date": {
          "type": "string",
          "description": "查询日期,格式为 YYYY-MM-DD。"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"],
          "default": "celsius",
          "description": "温度单位。"
        }
      },
      "required": ["city"]
    }
  }
}

其他兼容字段

页面配置解析器还接受小程序风格的窗口、背景、渲染器和宿主扩展字段,例如 navigationBarBackgroundColor、navigationBarTextStyle、navigationStyle、homeButton、backgroundColor、backgroundColorContent、backgroundTextStyle、backgroundColorTop、backgroundColorBottom、enablePullDownRefresh、onReachBottomDistance、pageOrientation、viewport、style、initialRenderingCache、singlePage、restartStrategy、handleWebviewPreload、visualEffectInBackground、enablePassiveEvent、renderer、rendererOptions 和 componentFramework。

这些字段主要用于兼容不同宿主或保留未来能力,并不代表所有宿主都实现了对应视觉或交互效果。除非目标宿主明确提供相应契约,否则优先使用上面的常用字段,并通过 <style> 控制页面内容样式。

<script setup> 页面逻辑

页面逻辑通过 export default 导出一个对象。该对象中的字段会成为页面实例的状态、生命周期和事件处理方法。

字段类型必填用途
dataObject否页面的初始渲染状态;内容必须可 JSON 序列化
onLoadfunction否页面加载时调用一次,并接收路由或工具调用参数
onShowfunction否页面显示或重新进入前台时调用
onReadyfunction否页面首次渲染完成后调用一次
onHidefunction否页面隐藏或切入后台时调用
onUnloadfunction否页面卸载时调用,适合释放计时器、监听器和其他资源
onKeyDownfunction否按键按下时调用,通过 event.code 读取按键编码
onKeyUpfunction否按键抬起时调用;可用 event.preventDefault() 拦截部分宿主默认行为
onVoiceWakeupfunction否收到语音或触控唤醒事件时调用,通过 event.keyword 区分来源
自定义方法function否响应模板事件或复用页面逻辑,可通过 this 访问页面实例
自定义字段any否保存不参与模板渲染的页面成员;需要驱动界面更新的数据应放入 data

页面配置中的 options 不应写入这里作为标准字段。打开页面时携带的参数由 onLoad(query) 接收;自定义组件的配置则通过 <script def> 的 usingComponents 声明。

页面实例

页面回调和自定义方法中的 this 指向当前页面实例。

this.data

读取页面当前状态。不要只直接修改 this.data 来驱动界面;需要更新绑定内容时使用 this.setData()。

this.setData(Object patch, Function? callback)

异步把数据更新发送到视图层,同时更新 this.data。patch 支持路径式键名,例如 'user.name': 'Rokid';可选回调会在本次视图更新完成后执行。

this.setData({
  status: 'ready',
  'user.name': 'Rokid'
}, () => {
  console.log('view updated');
});

this.finish()

通知宿主当前页面任务已经完成。对于 Cut(快切)智能体,这通常会交回焦点并退出当前展示;对于 Scene(场景)智能体,通常表示结束当前交互流程。它不是普通的页面返回 API,应只在业务任务确实完成时调用。

生命周期与事件

首次打开页面时依次触发 onLoad → onShow → onReady。页面被覆盖时触发 onHide,重新显示时再次触发 onShow,销毁时触发 onUnload。

按键和唤醒事件的默认行为、事件字段及拦截方式,请参阅 事件。完整生命周期说明请参阅 生命周期。

推荐阅读

  • 页面概览
  • 生命周期
  • 事件
  • 组件