Page Definition | AIUI | Rokid

An AIUI Page combines Page configuration, Page logic, Page structure, and Page styles. The recommended .ink single-file form uses <script def> for configuration, <script …

Page Definition

An AIUI Page combines Page configuration, Page logic, Page structure, and Page styles. The recommended .ink single-file form uses <script def> for configuration, <script setup> for exported Page logic, <page> for the interface structure, and <style> for Page styles.

The distinction matters: <script def> contains JSON, not executable JavaScript. Put lifecycle callbacks, event handlers, and initial state in the object exported from <script setup>.

Complete Page Example

<script type="application/json" def>
{
  "navigationBarTitleText": "Weather",
  "description": "Displays weather for a city.",
  "schema": {
    "data": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "The city to query."
        }
      },
      "required": ["city"]
    }
  },
  "usingComponents": {
    "weather-card": "components/weather-card"
  },
  "disableScroll": true
}
</script>

<script setup>
export default {
  data: {
    city: '',
    status: 'Waiting'
  },
  onLoad(query) {
    this.setData({
      city: query.city || '',
      status: query.city ? 'Ready' : 'Choose a city'
    });
  },
  handleComplete() {
    this.finish();
  }
}
</script>

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

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

The same Page can be split into matching .json, .js, .wxml, and .wxss files. In that form, .json is equivalent to <script def>, and .js is equivalent to the default export in <script setup>. Do not mix both forms for the same route.

<script def> Page Configuration

<script def> must contain a valid JSON object. It cannot contain comments, functions, variables, or trailing commas. Keeping type="application/json" is recommended because it makes the content type explicit.

Common Fields

FieldTypeRequiredPurpose
navigationBarTitleTextstringNoSets the Page title; whether it is visible depends on how the host presents navigation
descriptionstringRecommended for conversational PagesExplains to the model what the Page does and when to use it; describe observable capability rather than a generic title
schemaObjectNoDescribes data that the host or model can provide when opening the Page; Page input belongs in schema.data
usingComponentsObjectNoRegisters custom components used by this Page; each key is a template tag name and each value is a component path or package export
disableScrollbooleanNoDisables default scrolling on the Page root; defaults to false

Together, description and schema.data describe a Page as a callable UI tool. An immersive agent commonly enters the first Page registered in app.json, so that Page does not always need to be exposed as an independent tool. A conversational card Page should define both fields precisely.

schema.data

schema.data uses JSON Schema to describe data passed into the Page. Common fields include:

FieldTypePurpose
typestringRoot data type; Page input normally uses object
propertiesObjectDefines each input field, including its type, meaning, and constraints
requiredstring[]Lists fields that must be supplied; fields not listed are optional
properties.<name>.typestringField type, such as string, number, integer, boolean, object, or array
properties.<name>.descriptionstringTells the model the field's meaning, format, unit, and value requirements
properties.<name>.enumany[]Restricts the field to a set of values
properties.<name>.itemsObjectDescribes array elements when the field type is array
properties.<name>.defaultanyDescribes a suggested default; Page logic should still handle a missing field

schema.data describes input used to open the Page. It is different from data in the Page logic object: the former helps the model and host construct invocation arguments, while the latter is local state for the first render. Read incoming values from onLoad(query), then copy them into Page state with setData().

{
  "description": "Displays weather for a city and date.",
  "schema": {
    "data": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "minLength": 1,
          "description": "City name, for example Hangzhou."
        },
        "date": {
          "type": "string",
          "description": "Query date in YYYY-MM-DD format."
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"],
          "default": "celsius",
          "description": "Temperature unit."
        }
      },
      "required": ["city"]
    }
  }
}

Other Compatibility Fields

The Page configuration parser also accepts mini-app-style window, background, renderer, and host extension fields, including navigationBarBackgroundColor, navigationBarTextStyle, navigationStyle, homeButton, backgroundColor, backgroundColorContent, backgroundTextStyle, backgroundColorTop, backgroundColorBottom, enablePullDownRefresh, onReachBottomDistance, pageOrientation, viewport, style, initialRenderingCache, singlePage, restartStrategy, handleWebviewPreload, visualEffectInBackground, enablePassiveEvent, renderer, rendererOptions, and componentFramework.

These fields primarily provide compatibility with different hosts or reserve future behavior. Their presence does not mean every host implements the corresponding visual or interaction effect. Unless your target host documents such a contract, prefer the common fields above and use <style> for Page content styling.

<script setup> Page Logic

Page logic default-exports an object. Its fields become the current Page instance's state, lifecycle callbacks, and event handlers.

FieldTypeRequiredPurpose
dataObjectNoInitial render state; values must be JSON-serializable
onLoadfunctionNoRuns once when the Page loads and receives route or tool invocation parameters
onShowfunctionNoRuns when the Page appears or returns to the foreground
onReadyfunctionNoRuns once after the first render completes
onHidefunctionNoRuns when the Page is hidden or enters the background
onUnloadfunctionNoRuns when the Page is unloaded; release timers, listeners, and other resources here
onKeyDownfunctionNoRuns when a key is pressed; read its code from event.code
onKeyUpfunctionNoRuns when a key is released; event.preventDefault() can intercept selected host defaults
onVoiceWakeupfunctionNoRuns for voice or touch wakeup events; use event.keyword when the source must be distinguished
Custom methodsfunctionNoHandle template events or share Page logic; access the Page instance through this
Custom fieldsanyNoStore members that do not participate in rendering; values that drive the UI should live in data

Do not use options here as a standard Page field. Parameters used to open a Page are received by onLoad(query), while custom component configuration belongs in usingComponents inside <script def>.

Page Instance

Inside Page callbacks and custom methods, this refers to the current Page instance.

this.data

Reads the current Page state. Do not rely on direct this.data mutation to update the UI; use this.setData() for values bound by the template.

this.setData(Object patch, Function? callback)

Asynchronously sends an update to the view layer while updating this.data. patch supports path keys such as 'user.name': 'Rokid'. The optional callback runs after this view update completes.

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

this.finish()

Notifies the host that the current Page task is complete. For a Cut agent, this commonly returns focus and leaves the current presentation. For a Scene agent, it commonly marks the end of the current interaction flow. It is not a general Page-back API, so call it only when the business task is actually complete.

Lifecycle and Events

The first opening follows onLoad → onShow → onReady. Covering a Page triggers onHide, showing it again triggers another onShow, and destroying it triggers onUnload.

For default key and wakeup behavior, event fields, and interception, see Events. For the full lifecycle, see Lifecycle.

Recommended Reading

  • Page Overview
  • Lifecycle
  • Events
  • Components