rvis-aiui-kit 1.1.0 → 1.2.1

package/sdk/modules/status-bar/readme.md

@@ -0,0 +1,66 @@
+# Status Bar 原生状态栏
+
+`glass3.statusBar` 通过同步 HTTP response body 的 Host RPC 控制 AIX 页面顶部的
+系统状态栏。状态栏由 Native 绘制，可显示标题、时间、网络和电量；调用结果不依赖
+页面 `onMessage`。
+
+该能力只在通过外部 `OPEN_AIX_INK` 入口打开的 AIX 页面中注册。页面建立后默认隐藏
+状态栏，普通浏览器、普通 WebView 和普通 AI 卡片中调用会失败。
+
+## API
+
+### `glass3.statusBar.setTitle({ title })`
+
+设置当前页面的状态栏标题：
+
+```js
+const result = await glass3.statusBar.setTitle({
+  title: '设备巡检'
+});
+// { updated: true }
+```
+
+- `title` 必须是字符串，SDK 不会隐式转换类型。
+- Native 会去除首尾空白，当前最多展示前 40 个字符。
+- 空字符串或全空白字符串表示清理标题。
+- 状态栏隐藏时会保存标题，并在下次显示时应用。
+
+### `glass3.statusBar.setVisible({ visible })`
+
+申请显示或重新隐藏状态栏：
+
+```js
+const result = await glass3.statusBar.setVisible({ visible: true });
+// { updated: true, visible: true }
+```
+
+`visible` 必须是 Boolean，字符串 `"true"` 和数字 `1` 均会被 SDK 拒绝。
+
+建议先设置标题，再显示状态栏：
+
+```js
+await glass3.statusBar.setTitle({ title: '设备巡检' });
+await glass3.statusBar.setVisible({ visible: true });
+```
+
+`visible: false` 会隐藏当前状态栏，但不会删除页面保存的标题。再次显示时，Native 会
+恢复此前的标题。
+
+## 返回、超时与错误
+
+两个方法都直接返回 Host RPC `result`，并严格校验响应的 `channel`、`version`、
+`kind` 和 `requestId`。每次调用的本地等待上限为 5 秒；`CALL_TIMEOUT` 只表示 SDK
+停止等待，不能据此判断 Native 一定没有执行。
+
+- 参数错误：`INVALID_PARAMS`，`stage: "params"`。
+- fetch 失败：`TRANSPORT_ERROR`，`stage: "transport"`。
+- HTTP 非 2xx：`TRANSPORT_REJECTED`，`stage: "transport"`。
+- body 不是合法 JSON：`TRANSPORT_INVALID_RESPONSE`，`stage: "transport"`。
+- Native RPC 错误：保留 Native `error.code`，`stage: "response"`。
+- 响应信封不合法：`NATIVE_REQUEST_NOT_ACCEPTED`，`stage: "response"`。
+
+## 生命周期
+
+Native 按 AIX 页面 owner 保存和回收状态栏资源。页面进入后台、释放或进程结束时，
+Native 会清理对其他页面可能产生的影响。页面可以主动调用
+`setVisible({ visible: false })`，但不需要用全局 JavaScript 状态恢复资源。