diff --git a/.agents/skills/mpx-rn-style-guide/references/rn-api-reference.md b/.agents/skills/mpx-rn-style-guide/references/rn-api-reference.md
index e69de29bb2..4ade2282d5 100644
--- a/.agents/skills/mpx-rn-style-guide/references/rn-api-reference.md
+++ b/.agents/skills/mpx-rn-style-guide/references/rn-api-reference.md
@@ -0,0 +1,1581 @@
+# 跨端输出 RN 环境 API 参考
+
+## 目录
+
+- [使用说明](#使用说明)
+- [基础](#基础)
+  - [base64ToArrayBuffer](#base64toarraybuffer)
+  - [arrayBufferToBase64](#arraybuffertobase64)
+  - [canIUse](#caniuse)
+  - [getSystemInfo](#getsysteminfo)
+  - [getSystemInfoSync](#getsysteminfosync)
+  - [getWindowInfo](#getwindowinfo)
+  - [getDeviceInfo](#getdeviceinfo)
+  - [getEnterOptionsSync](#getenteroptionssync)
+  - [getLaunchOptionsSync](#getlaunchoptionssync)
+  - [onAppShow](#onappshow)
+  - [onAppHide](#onapphide)
+  - [offAppShow](#offappshow)
+  - [offAppHide](#offapphide)
+  - [onError](#onerror)
+  - [offError](#offerror)
+  - [onUnhandledRejection](#onunhandledrejection)
+  - [offUnhandledRejection](#offunhandledrejection)
+  - [onLazyLoadError](#onlazyloaderror)
+  - [offLazyLoadError](#offlazyloaderror)
+- [路由](#路由)
+  - [navigateTo](#navigateto)
+  - [redirectTo](#redirectto)
+  - [reLaunch](#relaunch)
+  - [navigateBack](#navigateback)
+- [界面](#界面)
+  - [showActionSheet](#showactionsheet)
+  - [showModal](#showmodal)
+  - [showToast](#showtoast)
+  - [hideToast](#hidetoast)
+  - [showLoading](#showloading)
+  - [hideLoading](#hideloading)
+  - [setNavigationBarTitle](#setnavigationbartitle)
+  - [setNavigationBarColor](#setnavigationbarcolor)
+  - [pageScrollTo](#pagescrollto)
+  - [createAnimation](#createanimation)
+  - [nextTick](#nexttick)
+  - [getMenuButtonBoundingClientRect](#getmenubuttonboundingclientrect)
+  - [onWindowResize](#onwindowresize)
+  - [offWindowResize](#offwindowresize)
+- [网络](#网络)
+  - [request](#request)
+  - [connectSocket](#connectsocket)
+  - [sendSocketMessage](#sendsocketmessage)
+  - [closeSocket](#closesocket)
+  - [onSocketOpen](#onsocketopen)
+  - [onSocketError](#onsocketerror)
+  - [onSocketMessage](#onsocketmessage)
+  - [onSocketClose](#onsocketclose)
+- [数据缓存](#数据缓存)
+  - [setStorage](#setstorage)
+  - [getStorage](#getstorage)
+  - [removeStorage](#removestorage)
+  - [removeStorageSync](#removestoragesync)
+  - [clearStorage](#clearstorage)
+  - [clearStorageSync](#clearstoragesync)
+  - [getStorageInfo](#getstorageinfo)
+- [媒体](#媒体)
+  - [getImageInfo](#getimageinfo)
+  - [createCameraContext](#createcameracontext)
+- [位置](#位置)
+  - [getLocation](#getlocation)
+- [设备](#设备)
+  - [getNetworkType](#getnetworktype)
+  - [onNetworkStatusChange](#onnetworkstatuschange)
+  - [offNetworkStatusChange](#offnetworkstatuschange)
+  - [hideKeyboard](#hidekeyboard)
+  - [onKeyboardHeightChange](#onkeyboardheightchange)
+  - [offKeyboardHeightChange](#offkeyboardheightchange)
+  - [makePhoneCall](#makephonecall)
+  - [vibrateShort](#vibrateshort)
+  - [vibrateLong](#vibratelong)
+  - [低功耗蓝牙](#低功耗蓝牙)
+  - [Wi-Fi](#wi-fi)
+- [WXML](#wxml)
+  - [createIntersectionObserver](#createintersectionobserver)
+  - [createSelectorQuery](#createselectorquery)
+
+---
+
+## 使用说明
+
+**@mpxjs/api-proxy** 提供跨端环境 API 抹平。输出 **React Native** 时，在应用入口执行 **`mpx.use(apiProxy, options)`**（`options` 均可省略），即可在 **`mpx`** 上使用与小程序同名的环境 API（如 `mpx.getSystemInfo` 等，以实际已接入的接口为准）。
+
+```js
+import mpx from "@mpxjs/core"
+import apiProxy from "@mpxjs/api-proxy"
+
+mpx.use(apiProxy, {
+  usePromise: true,
+  whiteList: [],
+  blackList: [],
+  custom: {
+    // 键名与当前编译目标一致（RN 常见为 ios 等，以工程配置为准）
+    ios: {
+      myCustomApi() {
+        // 合并到 mpx，仅在对应模式下可用，例如 mpx.myCustomApi()
+      },
+    },
+  },
+})
+```
+
+若无需任何配置，可简写为 **`mpx.use(apiProxy)`**。
+
+**`options` 一览**
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `usePromise` | `boolean` | `false` | 为 `true` 时，对符合 Promise 化规则的异步 API，调用返回 `Promise`（与 `success` / `fail` 语义对应到 `resolve` / `reject`）；部分接口若仍有同步句柄需保留，会挂在 `Promise.__returned` 上。 |
+| `whiteList` | `string[]` | `[]` | 仅当 `usePromise: true` 有效：列出的 API 名称**强制**参与 Promise 化，可覆盖内置排除规则。 |
+| `blackList` | `string[]` | `[]` | 仅当 `usePromise: true` 有效：列出的名称与内置排除合并，对应 API **强制**保持回调风格、不返回 `Promise`。 |
+| `custom` | `Object` | `{}` | 按编译目标扩展或覆盖 API；**`custom` 的键名**与当前目标一致（如 **`ios`**）。 |
+
+**Promise 化**
+
+只有异步 API 接口才会进行 Promise 化。**`whiteList`** 可指定 API 强制参与 Promise 化；**`blackList`** 从内置规则中排除 API，强制保持回调风格。对于 Promise 化后的 API 若同时写 `success` / `fail` 与 `.then()` / `.catch()`，两套回调都会触发，但混用更容易出现 `Unhandled Promise Rejection`，建议同一调用只选一种风格。单次调用若在**第一个参数对象**上写 **`usePromise: false`**，可临时关闭 Promise 化。
+
+若某异步 API 在**未 Promise 化**时除 **`success` / `fail`** 外还有**同步返回值**（例如 **`request`** 的 **`RequestTask`**、**`connectSocket`** 的 **`SocketTask`**），则在 **`usePromise: true`** 时：调用表达式得到的是 **`Promise`**，**`await` / `.then()` 拿到的是与 `success` 对应的成功载荷**；原同步返回值挂在本次返回的 **`Promise`** 的 **`__returned`** 属性上（无同步句柄时 **`__returned`** 可能为 **`undefined`**）。
+
+**本文档范围与 RN 支持**
+
+本文后续章节描述 **RN** 下各接口的 **说明、入参、返回值**（及必要的回调字段）。收录范围以 **`@mpxjs/api-proxy` 在 RN 上实际提供的能力**为准：与 Web 行为一致且可用的接口视为已接入；仅为占位、无实际能力或与小程序同名但未接好的接口不在此展开。**未出现在本文档中的同名小程序 API**，在 RN 上通常视为**未接入或不可用**，请用条件编译、原生扩展或宿主能力自行补齐。
+
+---
+
+## 基础
+
+**依赖（系统信息相关）**：`getSystemInfo`、`getSystemInfoSync`、`getWindowInfo`、`getDeviceInfo` 在 RN 上依赖设备信息、屏幕与安全区、当前页面导航上下文等能力；请按 **`@mpxjs/api-proxy`** 包说明安装所需的可选原生依赖，否则可能出现取值异常或运行时报错。
+
+---
+
+### base64ToArrayBuffer
+
+#### 说明
+
+将 Base64 字符串解码为 `ArrayBuffer`，用于二进制传输、文件头解析等场景。
+
+#### 入参
+
+第一个参数为 **`base64`**（`string`，必填）：待解码的 Base64 字符串。格式不合法时可能抛错，需自行 `try/catch`。
+
+#### 返回值
+
+返回 **`ArrayBuffer`**，即解码后的二进制数据。
+
+---
+
+### arrayBufferToBase64
+
+#### 说明
+
+将二进制缓冲编码为 Base64 字符串。
+
+#### 入参
+
+第一个参数为 **`arrayBuffer`**（`ArrayBuffer` 或 `Uint8Array` 等可逐字节遍历的类型，必填），与小程序常见写法一致。
+
+#### 返回值
+
+返回 **`string`**，即 Base64 编码结果。
+
+---
+
+### canIUse
+
+#### 说明
+
+同步判断某小程序 **API / 对象 / 方法** 是否在 RN 抹平层静态能力表中被标记为可用。**`schema`** 写法与小程序 `wx.canIUse` 字符串约定一致；**非 `string`**、或经实现判定为非法占位写法时返回 **`false`**。
+
+#### 入参
+
+第一个参数为 **`schema`**（`string`，必填）。
+
+#### 返回值
+
+返回 **`boolean`**。
+
+---
+
+### getSystemInfo
+
+#### 说明
+
+**异步 API**。获取系统与窗口相关信息。RN 侧字段集与微信宿主**不完全一致**：下列「成功回调参数」表中已列出的键为当前实现会填充或可读取的字段；未列出且与微信文档同名的扩展字段，在 RN 上通常**无有效宿主数据**，不要依赖其做权限或系统能力判断。
+
+#### 入参
+
+常规异步 API 回调。
+
+#### 返回值
+
+无同步返回值。
+
+#### 成功回调参数
+
+`success` 回调的 **Object** 载荷：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `errMsg` | `string` | 成功时为 **`getSystemInfo:ok`**（与小程序一致的前缀形式）。 |
+| `brand` | `string` | 设备品牌。 |
+| `model` | `string` | 设备型号。 |
+| `system` | `string` | 操作系统名称与版本。 |
+| `platform` | `string` | 平台标识；模拟器等情况可能为 `emulator` 等。 |
+| `deviceOrientation` | `string` | 设备方向语义（如 `portrait` / `landscape`）。 |
+| `fontSizeSetting` | `number` | 字体缩放相关数值。 |
+| `pixelRatio` | `number` | 设备像素比。 |
+| `screenWidth` | `number` | 屏幕宽度（逻辑像素）。 |
+| `screenHeight` | `number` | 屏幕高度（逻辑像素）。 |
+| `windowWidth` | `number` | 可使用窗口宽度。 |
+| `windowHeight` | `number` | 可使用窗口高度。 |
+| `screenTop` | `number` | 与窗口相对屏幕位置的纵向偏移类数值。 |
+| `statusBarHeight` | `number` | 状态栏高度。 |
+| `safeArea` | `Object` | 安全区：`left`、`right`、`top`、`bottom`、`width`、`height`（逻辑像素）。 |
+
+#### 失败回调参数
+
+`fail` 回调的 **Object** 载荷：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `errMsg` | `string` | 错误说明，前缀一般为 `getSystemInfo:fail`，后缀为具体原因。 |
+
+---
+
+### getSystemInfoSync
+
+#### 说明
+
+同步获取系统与窗口相关信息，字段含义与 **getSystemInfo 成功回调参数** 中列出的一致（不含异步接口里用于回调协议的那类附加字段时，以实际返回对象为准；一般仍含与小程序对齐的键）。
+
+#### 入参
+
+无。
+
+#### 返回值
+
+返回 **`Object`**：键与 **getSystemInfo → 成功回调参数** 表所列一致（设备、窗口、安全区等）。同步接口通常**不含**异步 `success` 里用于协议标记的 `errMsg`。
+
+---
+
+### getWindowInfo
+
+#### 说明
+
+同步获取窗口、屏幕与安全区信息，常用于布局与刘海区域避让。
+
+#### 入参
+
+无。
+
+#### 返回值
+
+返回 **Object**：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `pixelRatio` | `number` | 设备像素比。 |
+| `windowWidth` | `number` | 可使用窗口宽度。 |
+| `windowHeight` | `number` | 可使用窗口高度。 |
+| `screenWidth` | `number` | 屏幕宽度。 |
+| `screenHeight` | `number` | 屏幕高度。 |
+| `screenTop` | `number` | 窗口相对屏幕顶部的偏移类数值。 |
+| `statusBarHeight` | `number` | 状态栏高度。 |
+| `safeArea` | `Object` | 安全区矩形：`left`、`right`、`top`、`bottom`、`width`、`height`。 |
+
+
+---
+
+### getDeviceInfo
+
+#### 说明
+
+同步获取设备硬件与系统概要信息。
+
+#### 入参
+
+无。
+
+#### 返回值
+
+返回 **Object**：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `brand` | `string` | 设备品牌。 |
+| `model` | `string` | 设备型号。 |
+| `system` | `string` | 操作系统名称与版本。 |
+| `platform` | `string` | 平台标识。 |
+| `memorySize` | `number` | 设备内存量级（单位以实现为准，常见为 MB）。 |
+| `deviceAbi` | `string` \| `null` | 部分非 iOS 目标上主 ABI；无数据为 `null`。 |
+
+
+---
+
+### getEnterOptionsSync
+
+#### 说明
+
+同步获取**最近一次进入应用或回到前台**时的启动参数（与冷启动参数可能不同）。对象由运行时注入，字段随启动场景变化。
+
+#### 入参
+
+无。
+
+#### 返回值
+
+返回 **Object**：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `path` | `string` | 打开的页面路径或路由名。 |
+| `scene` | `number` | 场景值。 |
+| `query` | `Object` | 查询参数键值对。 |
+| `shareTicket` | `string` | 分享票据。 |
+| `referrerInfo` | `Object` | 来源信息。 |
+| `apiCategory` | `string` | API 类目等。 |
+| `chatType` | `number` | 聊天场景枚举。 |
+| （其余） | — | 运行时追加字段。 |
+
+
+---
+
+### getLaunchOptionsSync
+
+#### 说明
+
+同步获取**应用冷启动**时的参数。对象由运行时注入。
+
+#### 入参
+
+无。
+
+#### 返回值
+
+返回 **Object**：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `path` | `string` | 启动进入的页面路径或路由名。 |
+| `scene` | `number` | 场景值。 |
+| `query` | `Object` | 查询参数键值对。 |
+| `shareTicket` | `string` | 分享票据。 |
+| `referrerInfo` | `Object` | 来源信息。 |
+| `apiCategory` | `string` | API 类目等。 |
+| `chatType` | `number` | 聊天场景枚举。 |
+| （其余） | — | 运行时追加字段。 |
+
+
+---
+
+### onAppShow
+
+#### 说明
+
+监听应用进入**前台**（展示态；监听 API，非 `success` / `fail` 模型）。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 进入前台时调用，载荷见下表。 |
+
+#### 返回值
+
+无。
+
+#### 监听回调参数
+
+`callback` 被调用时收到 **Object**（与小程序「应用显示」事件对齐为主）。
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `path` | `string` | 当前路径或路由名。 |
+| `query` | `Object` | 当前路由查询参数。 |
+| `scene` | `number` | 场景值。 |
+| `shareTicket` | `string` | 分享相关。 |
+| `referrerInfo` | `Object` | 来源信息。 |
+| （其余） | — | 运行时按需附带。 |
+
+
+---
+
+### onAppHide
+
+#### 说明
+
+监听应用进入**后台**（隐藏态；监听 API）。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 进入后台时调用，载荷见下表。 |
+
+#### 返回值
+
+无。
+
+#### 监听回调参数
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `reason` | `number` | 隐藏原因枚举值，以运行时为准。 |
+
+---
+
+### offAppShow
+
+#### 说明
+
+取消 `onAppShow` 监听；**不传回调则清空该事件下全部监听**。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 否 | 须与注册时同一引用；省略则移除全部监听。 |
+
+#### 返回值
+
+无。
+
+---
+
+### offAppHide
+
+#### 说明
+
+取消 `onAppHide` 监听；**不传回调则清空全部**。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 否 | 同一引用；省略则移除全部。 |
+
+#### 返回值
+
+无。
+
+---
+
+### onError
+
+#### 说明
+
+监听全局 JavaScript 错误（监听 API）。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 错误触发时调用；实参常见为 `string` / `Error` / 封装对象。 |
+
+#### 返回值
+
+无。
+
+---
+
+### offError
+
+#### 说明
+
+取消 `onError` 监听；**不传回调则清空全部**。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 否 | 同一引用；省略则移除全部。 |
+
+#### 返回值
+
+无。
+
+---
+
+### onUnhandledRejection
+
+#### 说明
+
+监听未处理的 Promise 拒绝（监听 API）。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 拒绝时调用，载荷见下表。 |
+
+#### 监听回调参数
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `reason` | `any` | 拒绝原因。 |
+| `promise` | `Promise` | 相关 Promise，以实现为准。 |
+
+#### 返回值
+
+无。
+
+---
+
+### offUnhandledRejection
+
+#### 说明
+
+取消 `onUnhandledRejection` 监听；**不传回调则清空全部**。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 否 | 同一引用；省略则移除全部。 |
+
+#### 返回值
+
+无。
+
+---
+
+### onLazyLoadError
+
+#### 说明
+
+监听分包或懒加载资源加载失败（监听 API；RN 由运行时决定是否触发）。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 失败时调用，载荷以运行时为准。 |
+
+#### 返回值
+
+无。
+
+---
+
+### offLazyLoadError
+
+#### 说明
+
+取消 `onLazyLoadError` 监听；**不传回调则清空全部**。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 否 | 同一引用；省略则移除全部。 |
+
+#### 返回值
+
+无。
+
+---
+
+## 路由
+
+### navigateTo
+
+#### 说明
+
+**异步 API**。保留当前页并打开新页面（入栈）。RN 下由路由模块对接导航栈。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 打开的页面路径。 |
+| `events` | `Object` | 否 | 页面间通信通道等，与小程序一致；以实现为准。 |
+
+#### 返回值
+
+无同步返回值。
+
+### redirectTo
+
+#### 说明
+
+**异步 API**。关闭当前页并打开指定页（替换栈顶）。RN 下由路由模块实现。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 打开的页面路径。 |
+
+#### 返回值
+
+无同步返回值。
+
+### reLaunch
+
+#### 说明
+
+**异步 API**。关闭所有页面后打开指定页。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 打开的页面路径。 |
+
+#### 返回值
+
+无同步返回值。
+
+### navigateBack
+
+#### 说明
+
+**异步 API**。关闭当前页面，返回栈内上一层或多层。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `delta` | `number` | 否 | 回退步数，默认 `1`。 |
+
+#### 返回值
+
+无同步返回值。
+
+---
+
+## 界面
+
+本节顺序：交互 → 导航栏 → 滚动 → 动画 → 自定义组件 → 菜单 → 窗口。以下各 **异步 API** 入参均为 **Object**；表内仅列业务字段，不含 `success` / `fail` / `complete`。
+
+### showActionSheet
+
+#### 说明
+
+**异步 API**。底部操作菜单，RN 侧由弹层实现。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `itemList` | `string[]` | 是 | 按钮标题列表。 |
+| `itemColor` | `string` | 否 | 按钮文字颜色。 |
+
+#### 返回值
+
+无同步返回值。
+
+### showModal
+
+#### 说明
+
+**异步 API**。模态对话框，RN 侧由弹层实现。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `string` | 否 | 标题。 |
+| `content` | `string` | 否 | 内容。 |
+| `showCancel` | `boolean` | 否 | 是否显示取消按钮。 |
+| `cancelText` | `string` | 否 | 取消按钮文案。 |
+| `confirmText` | `string` | 否 | 确认按钮文案。 |
+
+#### 返回值
+
+无同步返回值。
+
+### showToast
+
+#### 说明
+
+**异步 API**。轻提示。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `string` | 是 | 提示文字。 |
+| `icon` | `string` | 否 | `success` / `error` / `loading` / `none` 等。 |
+| `duration` | `number` | 否 | 显示时长 ms。 |
+| `mask` | `boolean` | 否 | 是否显示透明蒙层。 |
+
+#### 返回值
+
+无同步返回值。
+
+### hideToast
+
+#### 说明
+
+**异步 API**。隐藏当前 Toast。
+
+#### 入参
+
+常规异步 API 回调。
+
+#### 返回值
+
+无同步返回值。
+
+### showLoading
+
+#### 说明
+
+**异步 API**。全屏或遮罩加载提示。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `string` | 否 | 提示文字。 |
+| `mask` | `boolean` | 否 | 是否显示透明蒙层。 |
+
+#### 返回值
+
+无同步返回值。
+
+### hideLoading
+
+#### 说明
+
+**异步 API**。隐藏 Loading。
+
+#### 入参
+
+常规异步 API 回调。
+
+#### 返回值
+
+无同步返回值。
+
+### setNavigationBarTitle
+
+#### 说明
+
+**异步 API**。设置当前页导航栏标题。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `string` | 是 | 标题文字。 |
+
+#### 返回值
+
+无同步返回值。
+
+### setNavigationBarColor
+
+#### 说明
+
+**异步 API**。设置导航栏前景色、背景色等。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `frontColor` | `string` | 否 | 前景色值。 |
+| `backgroundColor` | `string` | 否 | 背景色值。 |
+
+#### 返回值
+
+无同步返回值。
+
+### pageScrollTo
+
+#### 说明
+
+**异步 API**。将页面滚动到指定位置。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `scrollTop` | `number` | 否 | 纵向滚动位置 px。 |
+| `selector` | `string` | 否 | 选择器，滚动到节点。 |
+| `duration` | `number` | 否 | 滚动动画时长 ms。 |
+
+#### 返回值
+
+无同步返回值。
+
+### createAnimation
+
+#### 说明
+
+**同步风格工厂**：创建动画描述对象，用于节点 `animation` 绑定（非 `success`/`fail` 异步模型，入参仍为配置 **Object**）。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `duration` | `number` | 否 | 默认动画时长 ms。 |
+| `timingFunction` | `string` | 否 | 如 `linear`、`ease`。 |
+| `delay` | `number` | 否 | 延迟 ms。 |
+| `transformOrigin` | `string` | 否 | 变换原点。 |
+
+#### 返回值
+
+返回 **`Animation`** 实例；链式方法与 `export()` 与小程序对齐，全集以实现为准。
+
+### nextTick
+
+#### 说明
+
+同步调度：在下一微任务执行回调（非异步 `success`/`fail` 模型）。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `fn` | `function` | 是 | 要执行的函数。 |
+
+#### 返回值
+
+无。
+
+### getMenuButtonBoundingClientRect
+
+#### 说明
+
+同步获取「胶囊按钮」布局信息。**数值依赖安全区与导航实现**。
+
+#### 入参
+
+无。
+
+#### 返回值
+
+返回 **Object**：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `width` | `number` | 宽度 px。 |
+| `height` | `number` | 高度 px。 |
+| `top` | `number` | 上边界 px。 |
+| `right` | `number` | 右边界 px。 |
+| `bottom` | `number` | 下边界 px。 |
+| `left` | `number` | 左边界 px。 |
+
+### onWindowResize
+
+#### 说明
+
+监听窗口尺寸变化（监听 API，非 `success`/`fail` 模型）。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 尺寸变化时触发。 |
+
+#### 监听回调参数
+
+`callback` 收到 **Object**：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `size` | `Object` | 含 `windowWidth`、`windowHeight` 等，以实现为准。 |
+
+#### 返回值
+
+无。
+
+### offWindowResize
+
+#### 说明
+
+取消窗口尺寸监听；不传 `callback` 则清空全部。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 否 | 与注册时同一引用；省略则移除全部监听。 |
+
+#### 返回值
+
+无。
+
+
+---
+
+## 网络
+
+**`request`**、**`socket`** 在 RN 上与 **Web** 侧行为一致。**`downloadFile`**、**`uploadFile`** 未在本文展开；若宿主或扩展注入了对应能力，可按小程序同名用法自行接入。
+
+### request
+
+#### 说明
+
+**异步 API**。发起 **HTTPS** 请求；与小程序 **`wx.request`** 语义对齐为主。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 否 | 请求地址。 |
+| `method` | `string` | 否 | HTTP 方法。 |
+| `data` | `any` | 否 | 请求体。 |
+| `header` | `Object` | 否 | 请求头。 |
+| `timeout` | `number` | 否 | 超时 ms。 |
+
+#### 返回值
+
+同步返回 **`RequestTask`**（如取消请求等），与小程序一致。**未开启 Promise 化**时，即为 **`mpx.request(...)` 的返回值**。**开启 `usePromise: true`** 时，表达式为 **`Promise`**，**`RequestTask`** 在该 **`Promise`** 的 **`__returned`** 上；**`await` / `.then()` 的 resolve 值**仍为 **`success`** 的成功载荷（含 **`data`**、**`statusCode`** 等），与句柄分离。
+
+---
+### connectSocket
+
+#### 说明
+
+**异步 API**。建立 **WebSocket** 连接，返回 **`SocketTask`** 与小程序一致。运行环境须具备 **WebSocket** 能力；若当前环境无法发起连接，可能不会触发 **`success` / `fail` / `complete`**，且无有效同步返回值，请在业务侧做好兜底。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | `wss://` 或 `ws://` 地址。 |
+| `header` | `Object` | 否 | 请求头（是否生效取决于运行环境对 **WebSocket** 的支持）。 |
+| `protocols` | `string[]` | 否 | 子协议列表。 |
+
+#### 返回值
+
+成功建立连接时，同步返回 **`SocketTask`** 实例。**未开启 Promise 化**时即为调用返回值。**开启 `usePromise: true`** 时，**`SocketTask`** 在本次返回的 **`Promise.__returned`** 上；**`Promise` resolve** 值对应 **`success`** 载荷（如 **`errMsg: 'connectSocket:ok'`**）。失败时通常无有效 **`SocketTask`**，错误经 **`fail` / `complete`** 或 **`reject`** 交付。
+
+---
+### sendSocketMessage
+
+#### 说明
+
+兼容占位：调用时仅提示应使用 **`connectSocket`** 返回对象上的 **`send`**。不建议新业务依赖此全局函数。
+
+#### 入参
+
+无固定约定。
+
+#### 返回值
+
+无。
+
+---
+### closeSocket
+
+#### 说明
+
+兼容占位：提示应使用 **`connectSocket`** 返回对象上的 **`close`**。
+
+#### 入参
+
+无固定约定。
+
+#### 返回值
+
+无。
+
+---
+### onSocketOpen
+
+#### 说明
+
+兼容占位：提示应使用 **`connectSocket`** 返回对象上的 **`onOpen`**。
+
+#### 入参
+
+无固定约定。
+
+#### 返回值
+
+无。
+
+---
+### onSocketError
+
+#### 说明
+
+兼容占位：提示应使用 **`connectSocket`** 返回对象上的 **`onError`**。
+
+#### 入参
+
+无固定约定。
+
+#### 返回值
+
+无。
+
+---
+### onSocketMessage
+
+#### 说明
+
+兼容占位：提示应使用 **`connectSocket`** 返回对象上的 **`onMessage`**。
+
+#### 入参
+
+无固定约定。
+
+#### 返回值
+
+无。
+
+---
+### onSocketClose
+
+#### 说明
+
+兼容占位：提示应使用 **`connectSocket`** 返回对象上的 **`onClose`**。
+
+#### 入参
+
+无固定约定。
+
+#### 返回值
+
+无。
+
+---
+
+## 数据缓存
+
+以下与小程序键值语义一致；RN 侧常用本地持久化能力承载。**`setStorageSync`**、**`getStorageSync`**、**`getStorageInfoSync`** 在 RN 上不可用，本文不列出；**`removeStorageSync`**、**`clearStorageSync`** 为同步接口，可直接使用。
+
+### setStorage
+
+#### 说明
+
+**异步 API**。写入本地缓存。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `key` | `string` | 是 | 键。 |
+| `data` | `any` | 是 | 可序列化数据。 |
+
+#### 返回值
+
+无同步返回值。
+
+#### 成功回调参数
+
+`success` 回调的 **Object** 载荷：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `errMsg` | `string` | 成功时为 **`setStorage:ok`**。 |
+
+---
+### getStorage
+
+#### 说明
+
+**异步 API**。读取本地缓存。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `key` | `string` | 是 | 键。 |
+
+#### 返回值
+
+无同步返回值。
+
+#### 成功回调参数
+
+`success` 回调的 **Object** 载荷：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `errMsg` | `string` | 成功时为 **`getStorage:ok`**。 |
+| `data` | `any` | 写入 **`setStorage`** 时保存的 **`data`**；若存储结构异常可能为 **`null`**。 |
+
+---
+### removeStorage
+
+#### 说明
+
+**异步 API**。删除一项。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `key` | `string` | 是 | 键。 |
+
+#### 返回值
+
+无同步返回值。
+
+---
+### removeStorageSync
+
+#### 说明
+
+同步删除一项。
+
+#### 入参
+
+参数如下。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `key` | `string` | 是 | 键。 |
+
+#### 返回值
+
+无。
+
+---
+### clearStorage
+
+#### 说明
+
+**异步 API**。异步清空缓存。
+
+#### 入参
+
+常规异步 API 回调。
+
+#### 返回值
+
+无同步返回值。
+
+---
+### clearStorageSync
+
+#### 说明
+
+同步清空缓存。
+
+#### 入参
+
+无。
+
+#### 返回值
+
+无。
+
+---
+### getStorageInfo
+
+#### 说明
+
+**异步 API**。异步获取缓存占用与键列表。
+
+#### 入参
+
+常规异步 API 回调。
+
+#### 返回值
+
+无同步返回值。
+
+#### 成功回调参数
+
+`success` 回调的 **Object** 载荷：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `errMsg` | `string` | 成功时为 **`getStorageInfo:ok`**。 |
+| `keys` | `string[]` | 当前已存键名列表。 |
+
+---
+## 媒体
+
+仅收录 RN 上可用的 **图片信息**、**相机上下文** 等相关接口；音频、预览、压缩、相册/相机选取等本文不列出。
+
+### getImageInfo
+
+#### 说明
+
+**异步 API**。获取远程或本地图片的宽高与路径信息。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `src` | `string` | 是 | 图片路径或 URL。 |
+
+#### 返回值
+
+无同步返回值。
+
+#### 成功回调参数
+
+`success` 回调的 **Object** 载荷：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `errMsg` | `string` | 成功时为 **`getImageInfo:ok`**。 |
+| `width` | `number` | 图片宽度 px。 |
+| `height` | `number` | 图片高度 px。 |
+| `path` | `string` | 与入参 **`src`** 一致。 |
+
+---
+### createCameraContext
+
+#### 说明
+
+工厂方法：创建 **`CameraContext`**（非 `success`/`fail` 工厂入参模型）。需当前页面提供可用的相机能力；未就绪时 **`setZoom`** 等会 **`fail`**，**`takePhoto`** / **`startRecord`** / **`stopRecord`** 可能无效果。
+
+#### 入参
+
+无。
+
+#### 返回值
+
+返回 **`CameraContext`** 实例。
+
+---
+## 位置
+
+### getLocation
+
+#### 说明
+
+**异步 API**。获取当前地理位置（单次读取）。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `isHighAccuracy` | `boolean` | 否 | 是否启用高精度定位。 |
+| （其它与小程序对齐的字段） | — | 否 | 当前未读取，可忽略。 |
+
+#### 返回值
+
+无同步返回值。
+
+---
+## 设备
+
+### getNetworkType
+
+#### 说明
+
+**异步 API**。获取网络类型。
+
+#### 入参
+
+常规异步 API 回调。
+
+#### 返回值
+
+无同步返回值。
+
+#### 成功回调参数
+
+`success` 回调的 **Object** 载荷：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `errMsg` | `string` | 成功时为 **`getNetworkType:ok`**。 |
+| `networkType` | `string` | 如 **`wifi`**、**`none`**、蜂窝代际 **`2g`/`3g`/`4g`** 等。 |
+
+---
+### onNetworkStatusChange
+
+#### 说明
+
+监听网络状态（监听 API）。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 网络变化时调用。 |
+
+#### 监听回调参数
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `isConnected` | `boolean` | 是否联网。 |
+| `networkType` | `string` | `wifi` / `2g` / `4g` 等。 |
+
+#### 返回值
+
+无。
+
+---
+### offNetworkStatusChange
+
+#### 说明
+
+取消网络状态监听。**不传 `callback`** 时清空全部监听并取消网络状态订阅。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 否 | 同一引用；省略则清空全部监听并取消订阅。 |
+
+#### 返回值
+
+无。
+
+---
+### hideKeyboard
+
+#### 说明
+
+**异步 API**。收起键盘。
+
+#### 入参
+
+常规异步 API 回调。
+
+#### 返回值
+
+无同步返回值。
+
+---
+### onKeyboardHeightChange
+
+#### 说明
+
+监听键盘高度（监听 API）。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 高度变化时调用。 |
+
+#### 监听回调参数
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `height` | `number` | 键盘高度；键盘弹出时为可见高度，收起时 iOS 上多为 **`0`**，Android 上可能仍带高度值。 |
+
+#### 返回值
+
+无。
+
+---
+### offKeyboardHeightChange
+
+#### 说明
+
+取消键盘高度监听：仅移除与注册时**同一引用**的 **`callback`**；**不传引用不会移除其它监听**。当监听列表为空时会移除键盘显示/隐藏相关订阅。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 与 **`onKeyboardHeightChange`** 注册时为同一函数引用。 |
+
+#### 返回值
+
+无。
+
+---
+### makePhoneCall
+
+#### 说明
+
+**异步 API**。调起拨号。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `phoneNumber` | `string` | 是 | 电话号码。 |
+
+#### 返回值
+
+无同步返回值。
+
+---
+### vibrateShort
+
+#### 说明
+
+**异步 API**。短触感反馈；**`type`** 档位与小程序一致，由系统触感能力承载。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `type` | `string` | 否 | 触感档位，默认 **`light`**，首字母大写后拼到 `impact` 前缀上参与触发。 |
+
+#### 返回值
+
+无同步返回值。
+
+---
+### vibrateLong
+
+#### 说明
+
+**异步 API**。长震动。
+
+#### 入参
+
+常规异步 API 回调。
+
+#### 返回值
+
+无同步返回值。
+
+---
+
+### 低功耗蓝牙
+
+与小程序 **低功耗蓝牙（中心设备）** 能力对齐；使用蓝牙需系统授权，并请按 **`@mpxjs/api-proxy`** 包说明安装所需可选依赖。
+
+| API | 说明 |
+| --- | --- |
+| `openBluetoothAdapter` | 打开蓝牙适配器。 |
+| `closeBluetoothAdapter` | 关闭蓝牙适配器。 |
+| `startBluetoothDevicesDiscovery` | 开始搜寻周边蓝牙设备。 |
+| `stopBluetoothDevicesDiscovery` | 停止搜寻。 |
+| `onBluetoothDeviceFound` | 发现设备时回调监听。 |
+| `offBluetoothDeviceFound` | 取消发现设备监听。 |
+| `getConnectedBluetoothDevices` | 获取已连接设备列表。 |
+| `getBluetoothAdapterState` | 获取适配器状态。 |
+| `onBluetoothAdapterStateChange` | 适配器状态变化监听。 |
+| `offBluetoothAdapterStateChange` | 取消适配器状态监听。 |
+| `getBluetoothDevices` | 获取已发现设备列表。 |
+| `createBLEConnection` | 建立与指定设备的 BLE 连接。 |
+| `closeBLEConnection` | 断开 BLE 连接。 |
+| `onBLEConnectionStateChange` | 连接状态变化监听。 |
+| `offBLEConnectionStateChange` | 取消连接状态监听（须传入与注册时同一 **`callback`** 引用）。 |
+| `writeBLECharacteristicValue` | 向特征值写入二进制数据。 |
+| `readBLECharacteristicValue` | 读取特征值。 |
+| `notifyBLECharacteristicValueChange` | 订阅特征值变化通知。 |
+| `onBLECharacteristicValueChange` | 特征值变化监听。 |
+| `offBLECharacteristicValueChange` | 取消特征值变化监听。 |
+| `setBLEMTU` | 协商 MTU。 |
+| `getBLEDeviceRSSI` | 读取设备信号强度。 |
+| `getBLEDeviceServices` | 获取设备服务 UUID 列表。 |
+| `getBLEDeviceCharacteristics` | 获取某服务下特征值列表。 |
+
+入参、回调与 **`errMsg`** 与小程序文档一致，单接口字段本文不逐项展开。
+
+#### 通过 mpx.config 扩展（权限）
+
+调用 **`openBluetoothAdapter`** 时，在初始化底层蓝牙模块之前会先执行「是否具备运行所需权限」的检查。未配置时由 **`@mpxjs/api-proxy`** 内置逻辑处理（**Android** 上按系统版本申请定位或蓝牙扫描/连接等权限；**iOS** 上默认视为前置条件已满足，实际仍依赖工程 **`Info.plist`** 与系统行为）。若需要与宿主 App 统一的权限申请、文案与多语言、或厂商定制流程，可在 **`mpx.config.rnConfig`** 上提供 **`bluetoothPermission`**，**完全替代**内置检查函数。
+
+| 配置项 | 类型 | 生效时机 | 说明 |
+| --- | --- | --- | --- |
+| `bluetoothPermission` | `() => Promise<boolean>` | 每次 **`openBluetoothAdapter`**，在蓝牙模块启动之前 | **`Promise`** 解析为 **`true`** 时继续；为 **`false`** 或 **`reject`** 时走失败回调（如 **`openBluetoothAdapter:fail no permission`**）。 |
+
+```js
+import mpx from "@mpxjs/core"
+
+// 在应用入口、调用任何 BLE API 之前完成赋值
+mpx.config.rnConfig.bluetoothPermission = () => {
+  // 示例：改为走宿主原生模块或统一封装
+  return nativeBridge.requestBlePermission().then((granted) => Boolean(granted))
+}
+```
+
+类型与更多 **`rnConfig`** 字段见 **`@mpxjs/core`** 中的 **`RnConfig`** 声明。
+
+---
+
+### Wi-Fi
+
+与小程序 **Wi‑Fi** 能力对齐；涉及系统 Wi‑Fi 与定位类权限，请按 **`@mpxjs/api-proxy`** 包说明处理依赖与权限。
+
+| API | 说明 |
+| --- | --- |
+| `startWifi` | 校验 Wi‑Fi 与权限并进入就绪态；在部分 **iOS** 编译目标下可能直接 **`fail`**（系统不支持系统级扫网等）。 |
+| `stopWifi` | 结束 Wi‑Fi 模块并清空列表监听；在部分 **iOS** 编译目标下可能 **`fail`**。 |
+| `getWifiList` | 在 **`startWifi`** 就绪后扫描热点并通过 **`onGetWifiList`** 回调列表；在部分 **iOS** 编译目标下可能 **`fail`**。 |
+| `onGetWifiList` | 注册接收热点列表的回调。 |
+| `offGetWifiList` | 移除热点列表回调。 |
+| `getConnectedWifi` | 读取当前已连接 Wi‑Fi（支持仅取 SSID 等简化入参）；需先 **`startWifi`** 成功就绪。 |
+
+成功时 **`errMsg`** 文案与微信文档字面可能略有差异，以实际返回为准。
+
+#### 通过 mpx.config 扩展（权限）
+
+调用 **`startWifi`** 时，在检查 Wi‑Fi 是否已打开之前会先执行「扫描热点所需权限」的检查。当前实现下，**RN 输出为 iOS** 时，**`startWifi` / `stopWifi` / `getWifiList`** 会直接 **`fail`**（系统级扫网等能力受限），**不涉及**下述配置。**RN 输出为 Android** 且使用内置 **`react-native-wifi-reborn`** 路径时，未配置 **`wifiPermission`** 则使用内置的 **`ACCESS_FINE_LOCATION`** 等申请逻辑；若需自定义（统一权限组件、补充说明文案等），可在 **`mpx.config.rnConfig`** 上提供 **`wifiPermission`**，**完全替代**内置函数。
+
+| 配置项 | 类型 | 生效时机 | 说明 |
+| --- | --- | --- | --- |
+| `wifiPermission` | `() => Promise<boolean>` | 每次 **`startWifi`**，在校验 Wi‑Fi 开关之前 | **`Promise`** 解析为 **`true`** 时继续后续流程；为 **`false`** 或 **`reject`** 时 **`startWifi`** 走 **`fail`**。 |
+
+```js
+import mpx from "@mpxjs/core"
+
+mpx.config.rnConfig.wifiPermission = () => {
+  // 示例：先展示说明再申请定位权限，或对接宿主统一权限 API
+  return showWifiScanRationale().then(() => requestAndroidFineLocation())
+}
+```
+
+类型与更多 **`rnConfig`** 字段见 **`@mpxjs/core`** 中的 **`RnConfig`** 声明。
+
+---
+
+## WXML
+
+### createIntersectionObserver
+
+#### 说明
+
+工厂方法：创建 **`IntersectionObserver`**（与小程序链式用法一致；非 `success` / `fail` 入参模型）。可与小程序相同传入 **组件实例** 作为首参，再传入配置 **Object**；或单参仅传配置 **Object**（以工程约定为准）。
+
+#### 入参
+
+配置 **Object** 常用字段如下（与小程序 `options` 对齐）。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `thresholds` | `number[]` | 否 | 相交比例阈值列表。 |
+| `initialRatio` | `number` | 否 | 初始相交比例。 |
+
+#### 返回值
+
+返回 **`IntersectionObserver`** 实例。
+
+---
+
+### createSelectorQuery
+
+#### 说明
+
+工厂方法：创建 **`SelectorQuery`**（非 `success` / `fail` 入参模型）。
+
+#### 入参
+
+无；若需组件作用域，与小程序一致传入 **组件实例**（以实现为准）。
+
+#### 返回值
+
+返回 **`SelectorQuery`** 实例。
+
+---
diff --git a/.agents/skills/mpx-rn-style-guide/references/rn-global-config.md b/.agents/skills/mpx-rn-style-guide/references/rn-extend-reference.md
similarity index 100%
rename from .agents/skills/mpx-rn-style-guide/references/rn-global-config.md
rename to .agents/skills/mpx-rn-style-guide/references/rn-extend-reference.md
diff --git a/.agents/skills/mpx-rn-style-guide/references/rn-json-reference.md b/.agents/skills/mpx-rn-style-guide/references/rn-json-reference.md
index b02750ed37..1639d4f35a 100644
--- a/.agents/skills/mpx-rn-style-guide/references/rn-json-reference.md
+++ b/.agents/skills/mpx-rn-style-guide/references/rn-json-reference.md
@@ -1,43 +1,49 @@
 # 跨端输出 RN JSON 配置参考
 
-本文档说明在 Mpx 输出 React Native（如 `mode` 为 `ios`、`android`、`harmony` 等 RN 目标）时，**小程序形态 JSON 配置**（`app.mpx` / 页面与组件 `.mpx` 中的 json 块）的支持范围与使用注意。写法上仍与微信小程序 `app.json`、页面/组件配置对齐；RN 端对部分字段仅有编译期处理或运行时等价能力，下文按层级说明。
+本文档说明在 Mpx 输出 React Native（如 `mode` 为 `ios`、`android`、`harmony` 等 RN 目标）时，**小程序形态 JSON 配置**（`app.mpx` / 页面与组件 `.mpx` 中的 JSON 块）的支持范围与使用注意。写法上仍与微信小程序 `app.json`、页面/组件配置对齐；RN 端对部分字段仅有编译期处理或运行时等价能力，下文按层级说明。
 
-## 目录
+## 索引
 
-- [应用级配置](#应用级配置)
-- [页面级配置](#页面级配置)
-- [组件级配置](#组件级配置)
+- [应用配置](#应用配置)
+- [页面配置](#页面配置)
+- [组件配置](#组件配置)
 - [分包与分包异步化](#分包与分包异步化)
+  - [使用 `packages` 定义分包](#使用-packages-定义分包)
+  - [异步分包组件](#异步分包组件)
+  - [异步分包 JS 模块](#异步分包-js-模块)
+  - [分包预下载](#分包预下载)
+  - [注册 `loadChunkAsync` 和 `downloadChunkAsync`](#注册-loadchunkasync-和-downloadchunkasync)
+  - [分包失败处理](#分包失败处理)
+- [抽象节点](#抽象节点)
+  - [声明 `componentGenerics`（定义方 JSON）](#定义方声明-componentgenerics)
+  - [定义方模板](#定义方模板)
+  - [使用方 `generic:` 绑定](#使用方-generic-绑定)
+  - [默认组件（可选）](#默认组件可选)
 
 ---
 
-## 应用级配置
+## 应用配置
 
-应用 json 用于注册页面、默认窗口样式、分包、预下载规则等。示例如下（字段可按需取舍）：
+应用 JSON 配置用于注册页面、默认窗口样式、分包、预下载规则等。示例如下（字段可按需取舍）：
 
-```json5
+```JSON5
 {
-  "pages": [
-    "pages/index",
-    { "src": "pages/other", "path": "custom/route-name" }
-  ],
-  "window": {
-    "navigationBarTitleText": "默认标题",
-    "navigationBarTextStyle": "white",
-    "navigationBarBackgroundColor": "#000000",
-    "navigationStyle": "default"
+  pages: ["pages/index", { src: "pages/other", path: "custom/route-name" }],
+  window: {
+    navigationBarTitleText: "默认标题",
+    navigationBarTextStyle: "white",
+    navigationBarBackgroundColor: "#000000",
+    navigationStyle: "default"
   },
   // 推荐：用 packages 引用子包入口，并在路径上带 ?root 声明分包名
-  "packages": [
-    "./packageA/app.mpx?root=packageA"
-  ],
+  packages: ["./packageA/app.mpx?root=packageA"],
   // subPackages 兼容微信等原生 app.json 写法，推荐优先使用 packages + ?root 进行分包定义
-  "usingComponents": {},
-  "networkTimeout": { "request": 60000 },
-  "preloadRule": {
-    "pages/index": { "network": "all", "packages": ["packageA"] }
+  usingComponents: {},
+  networkTimeout: { request: 60000 },
+  preloadRule: {
+    "pages/index": { network: "all", packages: ["packageA"] }
   },
-  "entryPagePath": "pages/index"
+  entryPagePath: "pages/index"
 }
 ```
 
@@ -46,10 +52,10 @@
 | 字段 | RN 侧支持说明 |
 | --- | --- |
 | `pages` | **必填**：注册页面，值可为页面路径字符串，或 `{ src, path? }` 对象（`path` 为路由别名）。 |
-| `packages` | **推荐**：声明分包时优先使用，值为分包入口路径（如分包子应用的 `app.mpx` 或 `app.json`），在路径上通过 **`?root`** 指定分包名，分包名 `root` 不得以 `.` 开头，详情查看[使用 `packages` 定义分包](#使用-packages-定义分包)。 |
+| `packages` | **推荐**：声明分包时优先使用，值为分包入口路径（分包目录或 npm 包内的 `app.mpx` 或 `app.json`），在路径上通过 **`?root`** 指定分包名，分包名 `root` 不得以 `.` 开头，详情查看[使用 `packages` 定义分包](#使用-packages-定义分包)。 |
 | `subPackages` / `subpackages` | **兼容**：与微信等原生 `app.json` 的 `subPackages` 写法对齐；Mpx 中推荐使用 **`packages` + `?root`** 定义分包 |
-| `window` | 作为**全局默认窗口配置**，与各页面 json 合并后参与导航栏与页面展示，详情查看[页面级配置](#页面级配置)。 |
-| `usingComponents` | 全局组件注册，仅支持同步组件。 |
+| `window` | 作为**全局默认窗口配置**，与各页面 JSON 合并后参与导航栏与页面展示，详情查看[页面配置](#页面配置)。 |
+| `usingComponents` | 全局组件注册。 |
 | `networkTimeout` | 定义请求相关能力的默认超时时长。 |
 | `preloadRule` | 定义在指定页面进入后的预下载分包规则，需在运行时注册 `Mpx.config.rnConfig.downloadChunkAsync`，否则不会触发实际下载。 |
 | `entryPagePath` | 应用初始页面路径，未定义时使用 `pages` 数组的首个元素作为初始页面路径 |
@@ -57,26 +63,24 @@
 
 ---
 
-## 页面级配置
+## 页面配置
 
-以下为页面 `.mpx` 中 **json 配置块** 示例（字段与小程序页面 `.json` 一致，可按需删减）：
+以下为页面的 JSON 配置示例：
 
-```json5
+```JSON5
 {
-  "navigationBarTitleText": "首页",
-  "navigationBarTextStyle": "black",
-  "navigationBarBackgroundColor": "#ffffff",
-  "navigationStyle": "default",
-  "backgroundColorContent": "#f5f5f5",
-  "disableScroll": true,
-  "usingComponents": {
+  navigationBarTitleText: "首页",
+  navigationBarTextStyle: "black",
+  navigationBarBackgroundColor: "#ffffff",
+  navigationStyle: "default",
+  backgroundColorContent: "#f5f5f5",
+  disableScroll: true,
+  usingComponents: {
     "list-item": "../components/list-item"
   }
 }
 ```
 
-跨端输出时 **`disableScroll` 宜为 `true`**，在 `<template>` 里用 **`scroll-y` 的 `scroll-view`** 包裹需要滚动的内容，与 RN 侧行为对齐。下拉刷新、触底等请结合 `scroll-view` 事件与业务逻辑实现。
-
 下表为跨端输出 RN 时支持的**页面级**配置项全集，未提到的配置项均不支持，跨端适配时需进行条件编译处理。
 
 | 字段 / 类别 | RN 侧说明 |
@@ -86,27 +90,29 @@
 | `navigationBarTextStyle` | 支持 `white` / `black`（及常见对应色值）映射为状态栏与标题前景色；其它值按实现回退为安全默认值。 |
 | `navigationBarBackgroundColor` | 导航栏背景色，默认值为 `#000`，可使用 `mpx.setNavigationBarColor` 在运行时进行更新。 |
 | `backgroundColorContent` | 页面容器背景色，默认值为 `#fff`。 |
-| `usingComponents` | 局部组件注册，可配合 `?root` 及 `componentPlaceholder` 声明异步分包组件，详情查看[异步分包组件](#异步分包组件)  |
+| `usingComponents` | 局部组件注册，可配合 `?root` 及 `componentPlaceholder` 声明异步分包组件，详情查看[异步分包组件](#异步分包组件) |
 | `componentPlaceholder` | **开启异步分包且组件为异步时**：必须配置占位组件，且占位须在 `usingComponents` 中可解析；占位组件本身不应再标记为异步，否则构建会告警或报错。 |
 | `disableScroll` | 跨端输出时应设置为 **`true`**，关闭页面默认滚动行为，**统一使用 `scroll-view` 包裹页面滚动内容**，作为跨端兼容方案。 |
 | `enablePullDownRefresh` | 输出 RN 时无效，应在模板中结合 `scroll-view` 相关能力进行跨端兼容实现。 |
 | `onReachBottomDistance` | 输出 RN 时无效，应在模板中结合 `scroll-view` 相关能力进行跨端兼容实现。 |
 | `disableKeyboardAvoiding` | 仅输出 RN 时有效，为 `true` 时关闭框架自带的键盘避让包裹，开发者自行处理键盘遮挡。 |
 
+**注意**：跨端输出时 **`disableScroll` 宜为 `true`**，在 `<template>` 里用 **`scroll-y` 的 `scroll-view`** 包裹需要滚动的内容，与 RN 侧行为对齐。下拉刷新、触底等请结合 `scroll-view` 事件与业务逻辑实现。
+
 ---
 
-## 组件级配置
+## 组件配置
 
-以下为自定义组件 `.mpx` 中 **json 配置块** 示例：
+以下为自定义组件的 JSON 配置示例：
 
-```json5
+```JSON5
 {
-  "usingComponents": {
-    "inner": "./inner"
+  usingComponents: {
+    inner: "./inner"
   },
-  "componentGenerics": {
-    "item": {
-      "default": "./default-item"
+  componentGenerics: {
+    item: {
+      default: "./default-item"
     }
   }
 }
@@ -118,17 +124,344 @@
 | --- | --- |
 | `usingComponents` | 局部组件注册，可配合 `?root` 及 `componentPlaceholder` 声明异步分包组件，详情查看[异步分包组件](#异步分包组件) |
 | `componentPlaceholder` | **开启异步分包且组件为异步时**：必须配置占位组件，且占位须在 `usingComponents` 中可解析；占位组件本身不应再标记为异步，否则构建会告警或报错。 |
-| `componentGenerics` | 抽象节点配置，带 `default` 的项会参与组件依赖收集，详情查看[抽象节点](#抽象节点)。|
+| `componentGenerics` | 抽象节点配置，带 `default` 的项会参与组件依赖收集，详情查看[抽象节点](#抽象节点)。 |
 
 ---
 
 ## 分包与分包异步化
 
+Mpx 跨端输出 RN 完整支持分包与分包异步化的构建能力，但需要在应用容器中自行实现分包 bundle 的下载与执行能力，并且在运行时注册到 `Mpx.config.rnConfig.loadChunkAsync` 和 `Mpx.config.rnConfig.downloadChunkAsync` 当中。
+
 ### 使用 `packages` 定义分包
 
+在应用 JSON 的 **`packages`** 数组中声明依赖的分包入口（分包目录或 npm 包内的 `app.mpx` / `app.json`），支持嵌套。编译时**只解析分别入口的 JSON 部分**，且主要消费其中的 **`pages`**、**`packages`** 域。这种写法在跨团队开发跨端应用时非常方便，分包的维护方能够自行维护分包内的页面列表，无需修改主应用配置。
+
+- **合并主包**：`packages` 路径上**不带** `root` query 时，分包入口内声明的 `pages` 会按原始路径合并到主包页面列表，与主包 `pages` 一起注册，这种方式当前已不再常用。
+- **注册分包**：在 `packages` 路径上增加 **`?root=分包名`**时，该入口下的 `pages` 会注册到对应分包中，分包名 `root` 不得以 `.` 开头。
+- **分包页面路径**：启用分包后，页面路径带有分包前缀，在分包配置发生变化时页面路径也会随之改变，建议使用资源 **`?resolve`** 动态获取正确的页面路径，避免写死。
+
+**分包使用示例**
+
+主应用的 app.mpx 中注册分包入口
+
+```JSON5
+// src/app.mpx 的 JSON 块（节选）
+{
+  pages: ["./pages/index"],
+  packages: ["./packageA/app.mpx?root=packageA"]
+}
+```
+
+分包入口的 app.mpx 中注册分包页面
+
+```JSON5
+// src/packageA/app.mpx 的 JSON 块（节选）
+{
+  pages: ["./pages/foo", "./pages/bar"]
+}
+```
+
+使用 `?resolve` 获取分包页面路径
+
+```js
+// 主包页面 src/pages/index.mpx 的 script（节选）
+import mpx from "@mpxjs/core"
+import fooPageUrl from "../../packageA/pages/foo.mpx?resolve"
+
+mpx.navigateTo({
+  url: fooPageUrl
+})
+```
+
+**`subPackages` / `subpackages`** 写法仍支持，用于兼容微信原生写法；日常更推荐 **`packages` + `?root`**。
+
 ### 异步分包组件
 
+跨分包使用其他分包内的自定义组件时，需在 **`usingComponents`** 的路径上声明 **`?root=对方分包名`**，并在 **`componentPlaceholder`** 中指定**已在本包 `usingComponents` 注册**的同步占位组件或基础组件（如 view / text 等）；占位组件本身不能再标记为异步。构建侧需开启 **`mpx.config.rnConfig.supportSubpackage`**，并可配置 `asyncChunk.loading` / `fallback` 等。
+
+概念与写法与官方 [分包异步化 - 跨分包自定义组件](https://mpxjs.cn/guide/advance/async-subpackage.html) 一致；**微信、支付宝、Web、RN** 等环境下框架对该能力有支持（非支持端会自动降级）。
+
+**示例：**
+
+```JSON5
+{
+  usingComponents: {
+    hello: "../../packageB/components/hello?root=packageB",
+    "simple-hello": "../components/hello"
+  },
+  componentPlaceholder: {
+    hello: "simple-hello"
+  }
+}
+```
+
 ### 异步分包 JS 模块
 
+在脚本中跨分包异步引用 JS 时，路径须带 **`?root=模块所在分包名`**，且使用 **`require.async('...').then(...)`** 的 Promise 风格（不能使用回调形式）。未带 `root` 时会触发构建告警。
+
+**示例：**
+
+```js
+// 当前脚本位于分包 A，异步引用分包 B 内的模块
+require
+  .async("../commonPackage/utils?root=packageB")
+  .then((mod) => {
+    mod.init()
+  })
+  .catch((err) => {
+    console.error("分包 JS 加载失败", err)
+  })
+```
+
+### 分包预下载
+
+通过应用配置中的 `preloadRule` 配置分包预下载规则，需在运行时注册实现 `downloadChunkAsync` 下载分包 bundle 能力。
+
+**示例（app JSON 节选）：**
+
+```JSON5
+{
+  pages: ["pages/index"],
+  packages: ["./packageImportant/app.mpx?root=important"],
+  preloadRule: {
+    "pages/index": {
+      network: "all",
+      packages: ["important"]
+    }
+  }
+}
+```
+
+### 注册 `loadChunkAsync` 和 `downloadChunkAsync`
+
+RN 官方不直接支持分包加载能力，需要在应用容器中自行实现，如需使用分包及分包异步化的核心功能需注册实现 `loadChunkAsync` 下载并执行分包 bundle 能力，如需使用分包预下载能力需注册实现 `downloadChunkAsync` 下载分包 bundle 能力。
+
+**示例（app script 节选）：**
+
+```js
+import mpx from "@mpxjs/core"
+
+// 异步分包页面 / require.async / 动态 chunk 加载时调用；config.package 为分包名
+mpx.config.rnConfig.loadChunkAsync = function (config) {
+  return yourNativeLoadChunk({ packageName: config.package }).then(() => {
+    /* 分包 bundle 已下载并执行完成 */
+  })
+}
+
+// 与 preloadRule 配合；入参为分包名数组
+mpx.config.rnConfig.downloadChunkAsync = function (packages) {
+  if (packages && packages.length) {
+    yourNativePrefetchPackages(packages)
+  }
+}
+```
+
+### 分包失败处理
+
+对于分包页面，用户可通过 `@mpxjs/webpack-plugin` 的编译配置 `rnConfig.asyncChunk.loading / fallback` 自定义的分包加载中和加载失败时的渲染组件，如无定义则渲染框架内置默认组件，其中自定义 `fallback` 组件可以通过向外发送 `reload` 事件触发分包页面的重新加载
+
+**构建配置示例（`mpx.config.js` 节选）：**
+
+```js
+const path = require("path")
+
+module.exports = defineConfig({
+  pluginOptions: {
+    mpx: {
+      plugin: {
+        rnConfig: {
+          asyncChunk: {
+            timeout: 10000,
+            loading: path.resolve(__dirname, "src/components/page-loading.mpx"),
+            fallback: path.resolve(
+              __dirname,
+              "src/components/page-fallback.mpx"
+            )
+          }
+        }
+      }
+    }
+  }
+})
+```
+
+**自定义 fallback 组件示例：**
+
+```html
+<template>
+  <view class="wrap">
+    <text>页面加载失败</text>
+    <view class="btn" bindtap="handleRetry">重试</view>
+  </view>
+</template>
+
+<script>
+  import { createComponent } from "@mpxjs/core"
+
+  createComponent({
+    methods: {
+      handleRetry() {
+        this.triggerEvent("reload")
+      }
+    }
+  })
+</script>
+```
+
+对于**分包页面**加载失败，还可注册 **`mpx.config.rnConfig.onLazyLoadPageError`** 监听，该配置仅在 RN 环境下生效。
+
+```js
+mpx.config.rnConfig.onLazyLoadPageError = (error) => {
+  console.error("异步页面加载失败", error.subpackage, error.errType) // errType: 'timeout' | 'fail' 等
+}
+```
+
+对于**异步分包组件**，可使用 **`mpx.onLazyLoadError`** 监听失败，回调入参中含 **`subpackage`** 分包名数组。若需重试，可在判断命中目标分包后，通过数据开关配合模板 **`wx:if`** 先卸载再挂载组件，以重新触发分包拉取与组件渲染。
+
+**示例：**
+
+```html
+<template>
+  <view class="heavy-slot">
+    <block wx:if="{{!loadFailed}}">
+      <async-heavy />
+    </block>
+    <view wx:else class="load-fail">
+      <text>组件加载失败</text>
+      <view class="btn" bindtap="retryHeavy">重试</view>
+    </view>
+  </view>
+</template>
+
+<script>
+  import mpx, { createComponent } from "@mpxjs/core"
+
+  const TARGET_SUBPACKAGE = "packageB"
+
+  createComponent({
+    data: {
+      loadFailed: false
+    },
+    attached() {
+      this._onLazyLoadError = (err) => {
+        const names = Array.isArray(err.subpackage) ? err.subpackage : []
+        if (names.indexOf(TARGET_SUBPACKAGE) === -1) return
+        console.error("异步分包组件加载失败", err.errMsg, names)
+        this.loadFailed = true
+      }
+      mpx.onLazyLoadError(this._onLazyLoadError)
+    },
+    detached() {
+      if (this._onLazyLoadError) {
+        mpx.offLazyLoadError(this._onLazyLoadError)
+      }
+    },
+    methods: {
+      retryHeavy() {
+        this.loadFailed = false
+      }
+    }
+  })
+</script>
+
+<script type="application/json">
+  {
+    "usingComponents": {
+      "async-heavy": "../../packageB/components/heavy?root=packageB"
+    },
+    "componentPlaceholder": {
+      "async-heavy": "view"
+    }
+  }
+</script>
+```
+
+对于**异步分包 JS**，在 **`require.async`** 返回的 Promise 上使用 **`.catch`** 监听失败，在回调中再次调用 **`require.async`** 即可重试。
+
+**示例：**
+
+```js
+function loadUtil() {
+  return require.async("../subpackage/util?root=packageB").catch((err) => {
+    console.warn("首次失败，重试", err)
+    return require.async("../subpackage/util?root=packageB")
+  })
+}
+
+loadUtil().then((mod) => {
+  mod.doSomething()
+})
+```
+
 ## 抽象节点
 
+输出 RN 支持与微信小程序一致的抽象节点能力，由组件定义方在 JSON 配置和模板中声明**占位标签**，由组件使用方从外部控制占位标签的具体实现。
+
+### 定义方声明 `componentGenerics`
+
+| 写法 | 说明 |
+| --- | --- |
+| `[name]: true` | 无默认实现，使用方必须写 `generic:[name]`。 |
+| `[name]: { "default": [path] }` | 使用方未指定时走默认组件；`default` 路径需存在。 |
+
+`名` 与模板里抽象标签名一致（注意短横线/驼峰与工程约定一致）。
+
+```JSON5
+{
+  "componentGenerics": {
+    "selectable": true
+  }
+}
+```
+
+### 定义方模板
+
+占位标签无需在本组件 `usingComponents` 里进行注册，标签名等于 `componentGenerics` 的键。
+
+```html
+<template>
+  <view wx:for="{{labels}}">
+    <label>
+      <selectable disabled="{{false}}" />
+      {{ item }}
+    </label>
+  </view>
+</template>
+```
+
+### 使用方 `generic:` 绑定
+
+引用带抽象节点的组件时写 **`generic:抽象名="组件名"`**；**`=` 右侧只能是静态字符串**，不能 `{{}}` 动态绑定组件类型。
+
+`generic:` 里出现的**组件名**必须在使用方 JSON 的 **`usingComponents`** 中注册。
+
+```html
+<template>
+  <selectable-group generic:selectable="custom-radio" />
+</template>
+```
+
+```JSON5
+{
+  "usingComponents": {
+    "selectable-group": "./selectable-group",
+    "custom-radio": "./custom-radio"
+  }
+}
+```
+
+换实现时改为 `generic:selectable="custom-checkbox"` 等，对应组件同样要进 `usingComponents`。
+
+### 默认组件（可选）
+
+无默认时（`true`）使用方**必须**传 `generic:`；有 `default` 时可省略 `generic:`，未省略则仍按传入为准。
+
+```JSON5
+{
+  "componentGenerics": {
+    "selectable": {
+      "default": "./default-selectable"
+    }
+  }
+}
+```
\ No newline at end of file
diff --git a/.agents/skills/mpx-rn-style-guide/references/rn-script-reference.md b/.agents/skills/mpx-rn-style-guide/references/rn-script-reference.md
index 4bac02d62c..4fc79c017f 100644
--- a/.agents/skills/mpx-rn-style-guide/references/rn-script-reference.md
+++ b/.agents/skills/mpx-rn-style-guide/references/rn-script-reference.md
@@ -1,6 +1,6 @@
 # 跨端输出 RN 逻辑能力参考
 
-本文档详细描述了 Mpx 跨端输出 RN 的逻辑能力支持情况，包括 `<script>` 中可用的构造选项、实例 API、数据响应与组合式 API等。
+本文档详细描述了 Mpx 跨端输出 RN 的逻辑能力支持情况，包括 `<script>` 中可用的构造选项、实例 API、数据响应与组合式 API 等。
 
 ## 目录
 
@@ -10,8 +10,15 @@
   - [页面 / 组件实例方法与属性](#页面--组件实例方法与属性)
 - [数据响应](#数据响应)
 - [组合式 API](#组合式-api)
+  - [`setup` 的第一个参数 `props`](#setup-的第一个参数-props)
+  - [`setup` 的第二个参数 `context`](#setup-的第二个参数-context)
+- [Mpx 运行时导出](#mpx-运行时导出)
+  - [默认导出](#默认导出)
+  - [命名导出](#命名导出)
 - [全局 API](#全局-api)
 - [Mpx.config.rnConfig](#mpxconfigrnConfig)
+- [环境 API](#环境-api)
+- [状态管理](#状态管理)
 
 ---
 
@@ -19,7 +26,6 @@
 
 ### App 构造选项
 
-
 `createApp(options)` 用于注册应用级逻辑与全局字段。**App 不支持数据响应式构造选项**（无 `data` / `computed` / `watch` 等），**也不使用 `provide` / `inject` / `setup`**；全局状态请通过挂载在 `getApp()` 返回对象上的普通字段（如 `globalData`）或业务层单例维护。
 
 页面或其它模块中读取全局数据：`const version = getApp().globalData.version`。
@@ -27,23 +33,23 @@
 ```html
 <!-- app.mpx：应用级生命周期与 globalData -->
 <script>
-  import { createApp } from '@mpxjs/core'
+  import { createApp } from "@mpxjs/core"
 
   createApp({
-    globalData: { version: '1.0.0' },
-    onLaunch (options) {
-      console.log('onLaunch', options.path, options.query, options.isLaunch)
+    globalData: { version: "1.0.0" },
+    onLaunch(options) {
+      console.log("onLaunch", options.path, options.query, options.isLaunch)
     },
-    onShow (options) {
-      console.log('onShow', options)
+    onShow(options) {
+      console.log("onShow", options)
     },
-    onHide (payload) {
-      console.log('onHide', payload.reason)
+    onHide(payload) {
+      console.log("onHide", payload.reason)
     },
-    onError (err) {
+    onError(err) {
       console.error(err)
     },
-    onUnhandledRejection (evt) {
+    onUnhandledRejection(evt) {
       console.warn(evt.reason)
     }
   })
@@ -71,18 +77,19 @@
 ```html
 <!-- 页面与组件共用一套选项模型（data、methods、生命周期等） -->
 <script>
-  import { createPage } from '@mpxjs/core'
+  import { createPage } from "@mpxjs/core"
 
   createPage({
-    data: { title: '首页' },
-    onLoad (rawQuery, decodedQuery) {
+    data: { title: "首页" },
+    onLoad(rawQuery, decodedQuery) {
       console.log(rawQuery, decodedQuery)
     },
     methods: {
-      go () { /* ... */ }
+      go() {
+        /* ... */
+      }
     }
   })
-
 </script>
 ```
 
@@ -133,46 +140,64 @@
 
 ### 页面 / 组件实例方法与属性
 
-```html
-<template>
-  <view id="box">内容</view>
-</template>
-<script>
-  import { createPage } from '@mpxjs/core'
-
-  createPage({
-    ready () {
-      this.createSelectorQuery().select('#box').boundingClientRect().exec((res) => {
-        console.log(res)
-      })
-    }
-  })
-</script>
-```
-
 | 名称 | 类型 | 适用 | 说明 |
 | --- | --- | --- | --- |
 | `route` | 属性 | 页面 | 当前路由名（screen name）。 |
 | `getPageId()` | 方法 | 共用 | 返回当前实例所在页的 pageId 字符串。 |
 | `getOpenerEventChannel()` | 方法 | 页面 | 打开当前页的 `EventChannel`，组件侧多为空实现占位。 |
 | `triggerEvent(name, detail?)` | 方法 | 组件 | 向父节点派发自定义事件。 |
-| `selectComponent(selector)` | 方法 | 共用 | 按选择器取第一个匹配实例（依赖 ref 注册）。 |
-| `selectAllComponents(selector)` | 方法 | 共用 | 取全部匹配实例数组。 |
-| `createSelectorQuery()` | 方法 | 共用 | 在实例作用域内创建查询对象。 |
-| `createIntersectionObserver(options?)` | 方法 | 共用 | 在实例作用域内创建交叉观察（依赖 RN 实现与上下文）。 |
-| `$refs` | 属性 | 共用 | 模板 `wx:ref` 对应的懒解析访问器集合。 |
+| `selectComponent(selector)` | 方法 | 共用 | 按选择器取第一个匹配实例。RN 不能像小程序一样按 selector 遍历视图树，须在模板目标节点声明 **空 wx:ref**，由编译期建立 **`#id` / `.class` 与节点**的映射后，本 API 才能按小程序写法解析。 |
+| `selectAllComponents(selector)` | 方法 | 共用 | 取全部匹配实例数组，**RN 侧与 `selectComponent` 相同**：依赖模板 **空 wx:ref** 与编译期 selector 映射，仅支持 **`#id` / `.class`**。 |
+| `createSelectorQuery()` | 方法 | 共用 | 在实例作用域内创建查询对象。后续 **`select(selector)`** 等链式调用在 RN 上同样依赖目标节点 **空 wx:ref**，通过编译映射将 `#id` / `.class` 落到真实视图，以兼容小程序用法。 |
+| `createIntersectionObserver(options?)` | 方法 | 共用 | 在实例作用域内创建交叉观察。若相对某一节点观察且传入 **`#id` / `.class`**（如 `relativeTo` 等），RN 侧同样要求该节点模板已声明 **空 wx:ref** 并完成编译期映射，其余行为依赖 `@mpxjs/api-proxy` 的 RN 实现。 |
+| `$refs` | 属性 | 共用 | 模板 **`wx:ref="refName"`** 对应的懒解析访问器（如 `this.$refs.refName`）；**空 wx:ref 不会注册具名 ref**，但与 selector 映射可并存——需按名取子实例时再写 **`wx:ref="refName"`**。 |
 | `$watch` | 方法 | 共用 | 动态创建对数据路径或表达式的侦听，返回用于停止侦听的函数，行为与选项式 `watch` 对齐。 |
 | `$forceUpdate` | 方法 | 共用 | 强制触发视图更新，可传入数据对象参与本次刷新，RN 侧由 `MpxProxy` 与 React 更新调度配合完成。 |
 | `$nextTick` | 方法 | 共用 | 在下一轮视图更新完成之后执行回调，用于在数据变更后读取更新后的视图状态。 |
 | `$set` | 方法 | 共用 | 向响应式对象添加新属性并保证其为响应式且触发视图更新，等价于对「无法被自动侦测的新增属性」的补充。 |
 | `$delete` | 方法 | 共用 | 删除响应式对象的属性并触发视图更新，用于需移除键且保持响应式一致性的场景。 |
-| `setData` | 方法 | 共用 | 兼容 API，内部走强制更新。 |
-| `__componentPath` | 属性 | 组件 | 编译注入的组件路径，供 relations 等内部逻辑使用。 |
+| `$t` | 方法 | 共用 | 文案翻译（占位符、命名参数等与 vue-i18n 相近），依赖工程 **`MpxWebpackPlugin` 的 `i18n` 配置**，用法可参考 [rn-template-reference - i18n 国际化](./rn-template-reference.md#i18n-国际化)。 |
+| `$tc` | 方法 | 共用 | 复数/数量相关翻译（`$tc(key, choice, ...)`）。 |
+| `$te` | 方法 | 共用 | 判断文案 key 在当前语言下是否存在。 |
+| `$tm` | 方法 | 共用 | 返回 key 在当前语言下的消息对象。 |
+| `setData` | 方法 | 共用 | 小程序原生兼容 API，内部通过 `$forceUpdate` 进行实现。 |
 
 #### 注意事项
 
-- **`selectComponent` / `selectAllComponents` / `$refs` 与模板 `wx:ref` 配套**：RN 上 ref 选择器仅支持 **`#id` 与 `.class`**，因为底层用 ref 映射而非完整小程序选择器引擎；复合选择器、深层选择器不可用。未在模板声明 `wx:ref` 的节点无法被上述 API 解析到实例。
-- `createSelectorQuery` 的能力边界以 `@mpxjs/api-proxy` 的 RN 实现为准；与真机布局、原生视图层级相关的行为需在设备上验证。
+- **`selectComponent`、`selectAllComponents`、`createSelectorQuery`（含 `select` 等链式入参）、`createIntersectionObserver`（`relativeTo` / `observe` 等涉及 selector 时）**在小程序中依赖视图层按 selector 查找节点，**RN 无同等原生能力**；须在**与 script 中 selector 对应**的节点上声明 **空 wx:ref**，可与 `id`、`class` 并存，由 **Mpx 编译期**根据 **`#id` / `.class` 建立映射**。若需 **`$refs` / `context.refs`** 按名访问，再使用 **`wx:ref="refName"`**。映射**仅支持 `#id` 与 `.class`**，不支持复合、后代等选择器；**未写 `wx:ref` 则无法解析**。`createSelectorQuery` / `createIntersectionObserver` 的测量与交叉等行为仍以 `@mpxjs/api-proxy` 的 RN 实现为准。
+
+**使用示例：**
+
+```html
+<template>
+  <!-- selector 相关 API：目标节点声明空 wx:ref；自定义组件须在 json 中注册后方可 selectComponent -->
+  <card id="chip" wx:ref />
+  <view id="box" class="block" wx:ref>内容</view>
+  <view class="cell" wx:ref>单元 1</view>
+  <view class="cell" wx:ref>单元 2</view>
+</template>
+<script>
+  import { createPage } from "@mpxjs/core"
+
+  createPage({
+    ready() {
+      this.selectComponent("#chip")
+      this.selectAllComponents(".cell")
+      this.createSelectorQuery()
+        .select("#box")
+        .boundingClientRect()
+        .exec((res) => {
+          console.log(res)
+        })
+      this.createIntersectionObserver()
+        .relativeTo("#box")
+        .observe(".cell", (res) => {
+          console.log(res)
+        })
+    }
+  })
+</script>
+```
 
 ---
 
@@ -181,18 +206,24 @@
 Mpx 在页面与组件上对 `data` 做响应式处理：**直接赋值** `this.field = value` 即可驱动 RN 视图更新，无需 `setData`。`computed` 基于依赖缓存；`watch` 可控制 `flush`（如 `post` 默认在视图更新后）。
 
 ```js
-import { createPage } from '@mpxjs/core'
+import { createPage } from "@mpxjs/core"
 
 createPage({
   data: { count: 0 },
   computed: {
-    double () { return this.count * 2 }
+    double() {
+      return this.count * 2
+    }
   },
   watch: {
-    count () { console.log('count changed') }
+    count() {
+      console.log("count changed")
+    }
   },
   methods: {
-    inc () { this.count++ }
+    inc() {
+      this.count++
+    }
   }
 })
 ```
@@ -214,145 +245,214 @@ createPage({
 
 ## 组合式 API
 
-在 **`setup(props, context)`** 或 **`script setup`** 中使用：从 `@mpxjs/core` 导入响应式 API、生命周期钩子、`provide` / `inject` 等。钩子须在 **`setup` 执行期间同步注册**，依赖当前正在创建的实例上下文。
+在 **`setup(props, context)`** 或 **`script setup`** 中编写逻辑时，需从 **`@mpxjs/core` 命名导出** 引入 `ref`、`computed`、生命周期钩子、`provide` / `inject` 等（**完整清单与 RN 侧要点**见 **[Mpx 运行时导出 — 命名导出](#命名导出)** 表内 **说明** 列）。组合式生命周期钩子 **须在 `setup` 执行期间同步注册**，否则会丢失当前实例上下文。
 
 ```js
-import { createComponent, ref, computed, onMounted, provide } from '@mpxjs/core'
+import { createComponent, ref, computed, onMounted, provide, toRefs } from "@mpxjs/core"
 
 createComponent({
-  setup (props, context) {
+  properties: {
+    title: String
+  },
+  setup(props, context) {
+    const { title } = toRefs(props)
     const n = ref(0)
     const doubled = computed(() => n.value * 2)
-    provide('token', 'demo')
+    provide("token", "demo")
     onMounted(() => {
-      console.log(n.value, context.refs)
+      console.log(n.value, title.value, context.refs)
     })
-    return { n, doubled }
+    return { n, doubled, title }
   }
 })
 ```
 
-| API | 参数 / 返回值概要 | RN 说明 |
+### `setup` 的第一个参数 `props`
+
+与选项式 **`properties`** 对应：为**只读**对象，字段与组件 / 页面在 `json` 或 `props` 选项中声明一致。不要在子组件内对 `props` 根对象整体赋值；需要可写副本时在 `setup` 内用 `ref` / `reactive` 承接。
+
+若要在 `setup` 内**按字段解构**使用，请对 **`toRefs(props)`**（或单个字段 **`toRef(props, 'key')`**）再解构，这样各字段仍是 **ref**，父组件传入变化时子侧会更新。不要写 **`const { foo } = props`**，也不要把形参写成 **`setup({ foo }, context)`**：`props` 在运行时是响应式代理，直接解构会丢掉响应式，与 Vue 3 行为一致。
+
+### `setup` 的第二个参数 `context`
+
+与选项式实例上暴露的部分能力等价，便于在纯函数 `setup` 内调用。**输出 RN** 时与 `select` / `refs` 相关的规则与选项式相同，下表仅强调 RN 侧注意点。
+
+| 字段 | 参数 / 返回值概要 | RN 说明 |
 | --- | --- | --- |
-| `setup(props, context)` | 组合式入口，返回对象会合并到实例 | 与 `docs-vitepress/api/composition-api.md` 一致，`context` 各字段见下列各行。 |
-| `context.triggerEvent` | `(name, detail?, options?) => void` | 语义同实例 `triggerEvent`，RN 上受 props 事件绑定方式约束。 |
-| `context.refs` | 与选项式 `$refs` 对应 | RN 上与模板 `wx:ref`、选择器限制一致，见「实例方法」注意事项。 |
-| `context.asyncRefs` | Promise 形式 refs | 字节等场景为主，RN 侧以实际导出与类型为准。 |
-| `context.nextTick` | `(fn) => void` | 同全局 `nextTick`，在视图更新后执行回调。 |
-| `context.forceUpdate` | 可带参数与回调 | 同实例强制更新路径，RN 由 `MpxProxy` 调度。 |
-| `context.selectComponent` | `(selector) => instance` | 同实例 `selectComponent`。 |
-| `context.selectAllComponents` | `(selector) => instance[]` | 同实例 `selectAllComponents`。 |
-| `context.createSelectorQuery` | `() => SelectorQuery` | 同实例 `createSelectorQuery`，能力边界见 api-proxy RN 实现。 |
-| `context.createIntersectionObserver` | `(options?) => IntersectionObserver` | 同实例 `createIntersectionObserver`。 |
-| `ref` | 基本引用容器 | 与 Vue 3 类似，可用于 `setup` 返回值驱动模板。 |
-| `shallowRef` | 浅层 `ref` | 与 Vue 3 类似，深层属性变更不自动触发依赖。 |
-| `unref` | 解包 `ref` | 与 Vue 3 类似。 |
-| `toRef` | 从响应式对象取单键为 `ref` | 与 Vue 3 类似。 |
-| `toRefs` | 对象各键转为 `ref` 集合 | 与 Vue 3 类似。 |
-| `reactive` | 深层响应式对象 | 由 `@mpxjs/core` 导出，行为见响应式文档。 |
-| `shallowReactive` | 浅层响应式对象 | 由 `@mpxjs/core` 导出。 |
-| `computed` | getter 或 `{ get, set }` | 与 Vue 3 类似，可用于 `setup`。 |
-| `watch` | 数据源 + 回调或选项对象 | 与 Vue 3 类似，支持 `flush` 等。 |
-| `watchEffect` | 自动追踪依赖的副作用 | 由 `@mpxjs/core` 导出。 |
-| `watchSyncEffect` | 同步 `flush` 的 `watchEffect` | 由 `@mpxjs/core` 导出。 |
-| `watchPostEffect` | 视图更新后执行的 `watchEffect` | 由 `@mpxjs/core` 导出。 |
-| `provide` | `provide(key, value)` | **仅在 `setup` 内** 调用，向子树提供依赖。 |
-| `inject` | `inject(key, default?, treatDefaultAsFactory?)` | **仅在 `setup` 内** 调用，解析父组件 `provide`。App 构造选项不使用 `provide`，本文不展开应用级注入。 |
-| `nextTick` | `(fn) => void` | 可在 `setup` 内外使用，与调度器一致。 |
-| `getCurrentInstance` | 返回内部代理相关对象 | 高级用途，慎用。 |
-| `onBeforeMount` | 布局完成前，refs 前置准备阶段 | RN 可用，语义对齐 Vue，与选项式映射见 `lifecycle.md`。 |
-| `onMounted` | 布局完成、refs 可用 | RN 可用。 |
-| `onBeforeUpdate` | 数据变更后、更新前 | RN 可用。 |
-| `onUpdated` | 更新完成后 | RN 可用。 |
-| `onBeforeUnmount` | 卸载前 | RN 可用。 |
-| `onUnmounted` | 卸载后 | RN 可用。 |
-| `onLoad` | 页面加载，可 `(rawQuery, decodedQuery)` | 仅页面 `setup`，RN 与选项式 `onLoad` 一致。 |
-| `onShow` | 页面展示 | 仅页面 `setup`，RN 与选项式一致。 |
-| `onHide` | 页面隐藏 | 仅页面 `setup`，RN 与选项式一致。 |
-| `onResize` | 页面尺寸变化 | 仅页面 `setup`，RN 与选项式一致。 |
-| `onPullDownRefresh` | 下拉刷新 | 与选项式相同，RN 无宿主自动触发，需自接 `scroll-view` 等能力。 |
-| `onReachBottom` | 触底 | 与选项式相同，RN 无宿主自动触发。 |
-| `onPageScroll` | 页面滚动 | 与选项式相同，RN 无宿主自动触发。 |
-| `onShareAppMessage` | 分享配置 | 与选项式相同，RN 需配合 `Mpx.config.rnConfig.openTypeHandler.onShareAppMessage` 与 `button` 的 `open-type="share"`。 |
-| `onShareTimeline` | 朋友圈分享 | 与选项式相同，RN 无效。 |
-| `onTabItemTap` | Tab 项点击 | 与选项式相同，RN 无效。 |
-| `onAddToFavorites` | 收藏 | 与选项式相同，RN 无效。 |
-| `onSaveExitState` | 退出态保存 | 与选项式相同，RN 无效。 |
-| `onServerPrefetch` | SSR 预取 | **RN 不使用**。 |
-| `onReactHooksExec` | 与 RN 渲染协同 | 框架内部使用为主。 |
-| `useI18n` | 见 i18n 文档 | 工程启用 i18n 时可用。 |
-
-#### setup script
+| `triggerEvent` | `(name, detail?, options?) => void` | 语义同实例 `triggerEvent`，RN 上受 props 事件绑定方式约束。 |
+| `refs` | 与选项式 `$refs` 对应 | 仅 **`wx:ref="refName"`** 会出现在 `refs` 上；**空 wx:ref** 只服务 selector 映射。详见「页面 / 组件实例方法与属性」注意事项。 |
+| `asyncRefs` | Promise 形式 refs | 字节等场景为主，RN 侧以实际导出与类型为准。 |
+| `nextTick` | `(fn) => void` | 同全局 `nextTick`，在视图更新后执行回调。 |
+| `forceUpdate` | 可带参数与回调 | 同实例强制更新路径，RN 由 `MpxProxy` 调度。 |
+| `selectComponent` | `(selector) => instance` | 同实例 `selectComponent`，RN 上 **selector 须由模板 `wx:ref` 参与编译映射**。 |
+| `selectAllComponents` | `(selector) => instance[]` | 同实例 `selectAllComponents`，规则同上。 |
+| `createSelectorQuery` | `() => SelectorQuery` | 同实例 `createSelectorQuery`，**`select` 等链式 selector** 在 RN 上同样依赖 **`wx:ref`** 映射。 |
+| `createIntersectionObserver` | `(options?) => IntersectionObserver` | 同实例 `createIntersectionObserver`，涉及 **selector 相对节点** 时在 RN 上同样依赖 **`wx:ref`** 映射。 |
 
 #### 注意事项
 
-- 组合式生命周期 **禁止在异步回调里再注册**，否则会丢失当前实例上下文。
-- `refs` 在 `onMounted` 及之后才可靠；与模板 `wx:ref` 的 RN 限制相同。
+- 组合式生命周期 **禁止在异步回调里注册**，否则会丢失当前实例上下文。
+- `context.refs` 及 **`selectComponent` / `selectAllComponents` / `createSelectorQuery` / `createIntersectionObserver`** 在 RN 上与选项式相同：`refs` 在 `onMounted` 及之后更可靠，**凡传入 `#id` / `.class` 的用法均须在模板对应节点声明空 wx:ref**（具名访问用 `wx:ref="refName"`），详见「页面 / 组件实例方法与属性」注意事项。
 
 ---
 
-## 全局 API
+## Mpx 运行时导出
 
-Mpx 输出 RN 时模拟实现了微信小程序中常用的全局 API。
+依据 **`packages/core/src/index.js`** 及其 **`export *`**（**`platform/export/index.js`**，以及可能对 **`@mpxjs/store`** 的再导出）整理；与版本不一致时以包内源码与类型声明为准。全局状态方案选型见 **[状态管理](#状态管理)**。
 
-```js
-const app = getApp()
-console.log(app.globalData)
+### 默认导出
 
-const stack = getCurrentPages()
-console.log(stack.length)
+`@mpxjs/core` 的**默认导出**为构造函数 **`Mpx`**。业务中通常写作 **`import Mpx from '@mpxjs/core'`**，并把它当作**命名空间对象**使用，而不是 `new Mpx()`。框架在初始化时会把平台 API 合并到 **`Mpx` 的静态属性**以及 **`Mpx.prototype`** 上，因此选项式页面 / 组件实例上的 `$wx`、`setData` 等能力，与这里的原型挂载一一对应。
 
-// 宿主或测试场景下可手动触发应用前后台逻辑
-setAppShow()
-setAppHide()
-```
+全局运行时配置集中在 **`Mpx.config`**（在 **`packages/core/src/index.js`** 里创建默认值，可按需改写）。其中 **`rnConfig`** 与输出 RN 关系最大，逐项说明见下文 **[Mpx.config.rnConfig](#mpxconfigrnconfig)**。
 
-| API | 说明 |
+#### `Mpx.config` 各字段
+
+| 属性 | 说明 |
 | --- | --- |
-| `getApp()` | 返回应用全局对象（包含用户在 `createApp` 中声明的自定义字段），在页面/组件脚本执行前已可用。 |
-| `getCurrentPages()` | 返回当前导航栈中已映射的页面实例列表（顺序与路由 state 相关）。 |
-| `setAppShow()` | 手动触发应用「进入前台」逻辑，驱动已注册的 `onShow`。 |
-| `setAppHide()` | 手动触发应用「进入后台」逻辑，驱动已注册的 `onHide`。 |
+| `useStrictDiff` | 是否启用更严格的 diff 策略（默认 `false`，以源码为准）。 |
+| `ignoreWarning` | 为 `true` 时忽略框架部分警告。 |
+| `ignoreProxyWhiteList` | 字符串数组，列出的路径不做响应式代理（默认含 `id`、`dataset`、`data`）。 |
+| `observeClassInstance` | 是否尝试将 class 实例变为响应式（默认 `false`，慎用）。 |
+| `errorHandler` | 全局错误处理函数，可为 `null`。 |
+| `warnHandler` | 全局警告处理函数，可为 `null`。 |
+| `proxyEventHandler` | 事件代理链路中的钩子，高级用途。 |
+| `setDataHandler` | `setData` 调用前后的钩子，高级用途。 |
+| `forceFlushSync` | 是否强制同步 flush 更新（默认 `false`）。 |
+| `webRouteConfig` | 输出 Web 时的路由相关配置对象。 |
+| `webConfig` | 输出 Web 时的通用配置对象。 |
+| `webviewConfig` | WebView 场景配置（如域名白名单、`apiImplementations` 等，见源码注释）。 |
+| `rnConfig` | 输出 React Native 时的扩展配置（导航、分包、`open-type` 容器实现、状态栏等），详见 [Mpx.config.rnConfig](#mpxconfigrnconfig)。 |
+
+#### `Mpx` 静态属性与方法
+
+| 符号 | 说明 |
+| --- | --- |
+| `injectMixins` | 注入 mixin，与 `mixin` 等价。 |
+| `mixin` | 同 `injectMixins`。 |
+| `observable` | `reactive` 的别名。 |
+| `watch` | 与命名导出 `watch` 同源。 |
+| `set` | 与命名导出 `set` 同源（响应式设值）。 |
+| `delete` | 与命名导出 `del` 同源（响应式删键）。 |
+| `isReactive` | 与命名导出 `isReactive` 同源。 |
+| `isRef` | 与命名导出 `isRef` 同源。 |
+| `use` | 安装插件：`Mpx.use(plugin, options?)`；`options.prefix` / `postfix` 可避免与已有 API 命名冲突。 |
+
+#### `Mpx.prototype` 实例方法
+
+| 符号 | 说明 |
+| --- | --- |
+| `$set` | 选项式实例上设值，语义与命名导出 `set` 一致。 |
+| `$delete` | 选项式实例上删键，语义与命名导出 `del` 一致。 |
 
-#### 注意事项
+### 命名导出
 
-- 勿在 App 构造函数执行完成前依赖 `getApp()` 内业务字段已赋值完毕；与路由相关的初始化宜放在 `onLaunch` / `onShow`。
-- `getCurrentPages()` 依赖 React Navigation 焦点与 `__mpxPagesMap`，与原生小程序栈细节不完全相同。
+| 导出名 | 说明 |
+| --- | --- |
+| `createApp` | **构造API**，创建应用实例。 |
+| `createPage` | **构造API**，创建页面。 |
+| `createComponent` | **构造API**，创建自定义组件。 |
+| `ref` | **组合式API：数据响应**，创建 ref。 |
+| `shallowRef` | **组合式API：数据响应**，创建浅层 ref。 |
+| `unref` | **组合式API：数据响应**，解包 ref。 |
+| `toRef` | **组合式API：数据响应**，自响应式对象取单键 ref。 |
+| `toRefs` | **组合式API：数据响应**，对象各键转 ref。 |
+| `isRef` | **组合式API：数据响应**，是否为 ref。 |
+| `customRef` | **组合式API：数据响应**，自定义 ref。 |
+| `triggerRef` | **组合式API：数据响应**，触发 shallowRef 更新。 |
+| `reactive` | **组合式API：数据响应**，深层响应式对象。 |
+| `shallowReactive` | **组合式API：数据响应**，浅层响应式对象。 |
+| `isReactive` | **组合式API：数据响应**，是否为 reactive。 |
+| `set` | **组合式API：数据响应**，响应式设键。 |
+| `del` | **组合式API：数据响应**，响应式删键；`Mpx` 静态为 `delete`。 |
+| `markRaw` | **组合式API：数据响应**，标记非响应式。 |
+| `computed` | **组合式API：数据响应**，计算属性。 |
+| `watch` | **组合式API：数据响应**，侦听数据源。 |
+| `watchEffect` | **组合式API：数据响应**，自动追踪依赖的副作用。 |
+| `watchSyncEffect` | **组合式API：数据响应**，同步 flush 的 `watchEffect`。 |
+| `watchPostEffect` | **组合式API：数据响应**，视图更新后的 `watchEffect`。 |
+| `effectScope` | **组合式API：数据响应**，创建 effect 作用域。 |
+| `getCurrentScope` | **组合式API：数据响应**，获取当前作用域。 |
+| `onScopeDispose` | **组合式API：数据响应**，作用域销毁回调。 |
+| `nextTick` | **组合式API：工具方法**，下一轮视图更新后执行。 |
+| `getCurrentInstance` | **组合式API：工具方法**，当前实例代理；慎用。 |
+| `provide` | **组合式API：工具方法**，向子树提供依赖；仅 `setup` 内同步调用，App 不支持 `provide`。 |
+| `inject` | **组合式API：工具方法**，解析父级 `provide`；仅 `setup` 内同步调用。 |
+| `useI18n` | **组合式API：工具方法**，国际化实例；依赖 `MpxWebpackPlugin` 的 `i18n`，模板见 [模版参考 · i18n](./rn-template-reference.md#i18n-国际化)。 |
+| `getMixin` | **选项式API**，mixin / `mergeOptions` 相关。 |
+| `BEFORECREATE` | **选项式API：内建生命周期常量**，组件初始化前，无组合式 API 对应钩子。 |
+| `CREATED` | **选项式API：内建生命周期常量**，组件初始化后，无组合式 API 对应钩子。 |
+| `BEFOREMOUNT` | **选项式API：内建生命周期常量**，组件挂载前，对应组合式 API `onBeforeMount`。 |
+| `MOUNTED` | **选项式API：内建生命周期常量**，组件挂载后，对应组合式 API `onMounted`（页面等价 `onReady`）。 |
+| `BEFOREUPDATE` | **选项式API：内建生命周期常量**，数据变更后视图更新前，对应组合式 API `onBeforeUpdate`。 |
+| `UPDATED` | **选项式API：内建生命周期常量**，视图更新后，对应组合式 API `onUpdated`。 |
+| `BEFOREUNMOUNT` | **选项式API：内建生命周期常量**，卸载前，对应组合式 API `onBeforeUnmount`。 |
+| `UNMOUNTED` | **选项式API：内建生命周期常量**，卸载后，对应组合式 API `onUnmounted`。 |
+| `ONLOAD` | **选项式API：内建生命周期常量**，页面 onLoad，对应组合式 API `onLoad`。 |
+| `ONSHOW` | **选项式API：内建生命周期常量**，页面 onShow，对应组合式 API `onShow`。 |
+| `ONHIDE` | **选项式API：内建生命周期常量**，页面 onHide，对应组合式 API `onHide`。 |
+| `ONRESIZE` | **选项式API：内建生命周期常量**，页面 onResize，对应组合式 API `onResize`。 |
+| `SERVERPREFETCH` | **选项式API：内建生命周期常量**，SSR 预取钩子名，对应组合式 API `onServerPrefetch`。 |
+| `REACTHOOKSEXEC` | **选项式API：内建生命周期常量**，RN 混编时执行 React hooks 使用，对应组合式 API `onReactHooksExec`。 |
+| `onBeforeMount` | **组合式API：生命周期钩子**，挂载前。 |
+| `onMounted` | **组合式API：生命周期钩子**，挂载后（页面等价 `onReady`）。 |
+| `onBeforeUpdate` | **组合式API：生命周期钩子**，更新前。 |
+| `onUpdated` | **组合式API：生命周期钩子**，更新后。 |
+| `onBeforeUnmount` | **组合式API：生命周期钩子**，卸载前。 |
+| `onUnmounted` | **组合式API：生命周期钩子**，卸载后。 |
+| `onLoad` | **组合式API：生命周期钩子**，页面 onLoad；可 `(rawQuery, decodedQuery)`。 |
+| `onShow` | **组合式API：生命周期钩子**，页面 onShow。 |
+| `onHide` | **组合式API：生命周期钩子**，页面 onHide。 |
+| `onResize` | **组合式API：生命周期钩子**，页面 onResize。 |
+| `onPullDownRefresh` | **组合式API：生命周期钩子**，下拉刷新；RN 无宿主自动触发，宜 `scroll-view` 等。 |
+| `onReachBottom` | **组合式API：生命周期钩子**，触底；RN 同上。 |
+| `onShareAppMessage` | **组合式API：生命周期钩子**，分享；RN 需 `rnConfig.openTypeHandler.onShareAppMessage` 与 `open-type="share"`。 |
+| `onShareTimeline` | **组合式API：生命周期钩子**，朋友圈；输出 RN 无效。 |
+| `onAddToFavorites` | **组合式API：生命周期钩子**，收藏；输出 RN 无效。 |
+| `onPageScroll` | **组合式API：生命周期钩子**，页滚动；输出 RN 无效，使用 `scroll-view` 替代方案。 |
+| `onTabItemTap` | **组合式API：生命周期钩子**，Tab 点击；输出 RN 无效。 |
+| `onSaveExitState` | **组合式API：生命周期钩子**，退出态；输出 RN 无效。 |
+| `onServerPrefetch` | **组合式API：生命周期钩子**，SSR 预取；输出 RN 不使用。 |
+| `onReactHooksExec` | **组合式API：生命周期钩子**，RN 混编时执行 React hooks 使用。 |
+| `implement` | **扩展API**，按 mode 注册或移除实现。 |
+| `toPureObject` | **工具API**，深拷贝为纯对象。 |
 
----
+#### 注意事项
 
-## mpx.config.rnConfig
+- **`Mpx.use`** 安装的插件会合并到 **`Mpx` 静态对象**与 **`Mpx.prototype`**，若与业务自定义全局名冲突，可为插件传入 **`prefix` / `postfix`** 选项。
+
+## Mpx.config.rnConfig
 
 运行时对象 **`Mpx.config.rnConfig`**（`Mpx` 为 `@mpxjs/core` 默认导出）用于扩展 RN 导航、分包、状态栏等行为。下列为脚本侧常见项（以源码为准，未列项可能随版本增加）。
 
 ```js
-import Mpx from '@mpxjs/core'
+import Mpx from "@mpxjs/core"
 
 // 须在 createApp 与页面脚本执行前完成赋值
 Mpx.config.rnConfig = {
-  parseAppProps (props) {
+  parseAppProps(props) {
     return {
-      initialRouteName: 'pages/index',
+      initialRouteName: "pages/index",
       initialParams: props || {}
     }
   },
-  onStateChange (state) {
-    console.log('navigation state', state)
+  onStateChange(state) {
+    console.log("navigation state", state)
   },
   openTypeHandler: {
-    onShareAppMessage (shareInfo) {
-      console.log('share', shareInfo)
+    onShareAppMessage(shareInfo) {
+      console.log("share", shareInfo)
     },
-    onUserInfo () {
-      return { userInfo: { nickName: 'RN' } }
+    onUserInfo() {
+      return { userInfo: { nickName: "RN" } }
     }
   }
 }
 ```
 
-
 | 配置项 | 说明 |
 | --- | --- |
+| `projectName` | 由构建注入到 RN 入口，与 `AppRegistry.registerComponent` 相关（偏构建侧）。 |
 | `parseAppProps` | `(props) => { initialRouteName?, initialParams? }`，解析外层传入 App 根组件的初始路由。 |
 | `onStateChange` | 导航 state 变化时回调。 |
 | `disableAppStateListener` | 为 `true` 时不注册 `AppState` 监听（避免与宿主 App 重复）。 |
@@ -360,10 +460,9 @@ Mpx.config.rnConfig = {
 | `openTypeHandler.onShareAppMessage` | 对应模板中 `open-type="share"`：框架会先取当前页 `onShareAppMessage` 的返回（含与默认 `title` / `path` 的合并及可选 `promise` 异步结果），再调用本回调，入参为 `{ title, path, imageUrl? }`，由宿主调起系统分享等能力。 |
 | `openTypeHandler.onUserInfo` | 对应模板中 `open-type="getUserInfo"`：由宿主实现获取用户信息的逻辑，结果需满足按钮侧对 `bindgetuserinfo` 的约定（以 `@mpxjs/webpack-plugin` 中 `mpx-button` 运行时为准）。 |
 | `statusBarTranslucent` | 影响 Stack `screenOptions` 中状态栏相关配置。 |
-| `downloadChunkAsync` | 分包预下载，与 `global.__preloadRule` 等配合。 |
 | `getBottomVirtualHeight` | Android 底部虚拟区域高度修正。 |
-| `loadChunkAsync` | 异步分包加载实现（webpack 插件运行时可能引用）。 |
-| `projectName` | 由构建注入到 RN 入口，与 `AppRegistry.registerComponent` 相关（偏构建侧）。 |
+| `loadChunkAsync` | 异步分包加载实现。 |
+| `downloadChunkAsync` | 分包下载实现，用于实现 preloadRule。 |
 | `supportSubpackage` | 是否启用分包相关异步加载能力，与页面 `json` 中 `async` 等配合。 |
 | `asyncChunk` | 异步页面的 `fallback`、`loading` 等组件路径配置，偏构建与运行时加载。 |
 
@@ -371,3 +470,325 @@ Mpx.config.rnConfig = {
 
 - `rnConfig` 为普通对象，应在 **任何页面 import 并执行 `createApp` 之前** 赋值，避免导航已初始化后配置未生效。
 - 具体键名以 `packages/core/src/index.js` 注释、`createApp.ios.js`、`LoadAsyncChunkModule.js` 等处的读取逻辑为准。
+
+## 全局 API
+
+Mpx 输出 RN 时模拟实现了微信小程序中常用的全局 API。
+
+```js
+const app = getApp()
+console.log(app.globalData)
+
+const stack = getCurrentPages()
+console.log(stack.length)
+
+// 宿主或测试场景下可手动触发应用前后台逻辑
+setAppShow()
+setAppHide()
+```
+
+| API | 说明 |
+| --- | --- |
+| `getApp()` | 返回应用全局对象（包含用户在 `createApp` 中声明的自定义字段），在页面/组件脚本执行前已可用。 |
+| `getCurrentPages()` | 返回当前导航栈中已映射的页面实例列表（顺序与路由 state 相关）。 |
+| `setAppShow()` | 手动触发应用「进入前台」逻辑，驱动已注册的 `onShow`。 |
+| `setAppHide()` | 手动触发应用「进入后台」逻辑，驱动已注册的 `onHide`。 |
+
+#### 注意事项
+
+- 勿在 App 构造函数执行完成前依赖 `getApp()` 内业务字段已赋值完毕；与路由相关的初始化宜放在 `onLaunch` / `onShow`。
+- `getCurrentPages()` 依赖 React Navigation 焦点与 `__mpxPagesMap`，与原生小程序栈细节不完全相同。
+
+## 环境 API
+
+Mpx 中通过 `@mpxjs/api-proxy` 提供了跨多端一致的环境 API 能力，详情查看[跨端输出 RN 环境 API 参考](./rn-api-reference.md) 
+
+## 状态管理
+
+跨端输出 RN 时，脚本侧可使用与小程序、Web 对齐的全局状态方案。**`@mpxjs/pinia`（Pinia 风格）为当前优先推荐**；新功能、新模块及与组合式 API 混编时，宜采用 Pinia 范式。若工程已深度使用 **`@mpxjs/store`（Vuex 风格）**，可继续维护，无需为 RN 单独换栈；同一业务域避免用两套方案重复建模。
+
+### `@mpxjs/pinia`（Pinia 风格，推荐）
+
+概念与 API 与 Pinia 对齐，与 Vuex 式 store 的主要差异包括：
+
+1. 无 **`mutations`**，同步与异步状态变更都通过 **`actions`** 完成。  
+2. 运行时通过 **`useXxxStore()`** 动态获取 store 实例。  
+3. **扁平**结构，无 `modules` 嵌套；多个 store 之间可组合使用。
+
+#### 创建 pinia
+
+在入口调用 **`createPinia()`** 即可：内部会注册**全局 active pinia**（`setActivePinia`），**无需再执行 `Mpx.use(pinia)`**；若需注册插件，在得到的实例上执行 **`pinia.use(plugin)`**。
+
+```js
+// app.mpx（节选）
+import { createPinia } from '@mpxjs/pinia'
+
+const pinia = createPinia()
+```
+
+**定义 store：`defineStore(id, setupFn | options)`**
+
+Setup Store 与组合式 **`setup`** 类似：`ref` 视为 state，`computed` 视为 getter，普通函数视为 action。
+
+```js
+// stores/setup.js
+import { defineStore } from '@mpxjs/pinia'
+import { ref, computed } from '@mpxjs/core'
+
+export const useSetupStore = defineStore('setup', () => {
+  const count = ref(0)
+  const name = ref('pinia')
+  const myName = computed(() => name.value)
+  function increment () {
+    count.value += 1
+  }
+  return { count, name, myName, increment }
+})
+```
+
+Options Store 示例：
+
+```js
+// stores/options.js
+import { defineStore } from '@mpxjs/pinia'
+
+export const useOptionsStore = defineStore('options', {
+  state: () => ({
+    count: 0,
+    name: 'pinia'
+  }),
+  getters: {
+    myName (state) {
+      return state.name
+    }
+  },
+  actions: {
+    increment () {
+      this.count += 1
+    }
+  }
+})
+```
+
+#### 使用 store（选项式 API）
+
+在 Pinia 中，**getter 同样通过 `mapState` 映射**（`mapGetters` 与 `mapState` 等价别名）。options / setup 两种 store 在选项式组件中的用法相同。
+
+```js
+import { createComponent } from '@mpxjs/core'
+import { mapState, mapActions } from '@mpxjs/pinia'
+import { useSetupStore } from '../stores/setup'
+
+createComponent({
+  computed: Object.assign(
+    {},
+    mapState(useSetupStore, ['name', 'count']),
+    mapState(useSetupStore, {
+      otherName: 'name',
+      double: (store) => store.count * 2,
+      magicValue () {
+        return this.count + this.double
+      }
+    }),
+    mapState(useSetupStore, ['myName'])
+  ),
+  methods: Object.assign(
+    {},
+    mapActions(useSetupStore, ['increment']),
+    mapActions(useSetupStore, {
+      setupIncrement: 'increment'
+    })
+  )
+})
+```
+
+#### 使用 store（组合式 API）
+
+直接解构 store 会丢失响应式，需用 **`storeToRefs`**；**`storeToRefs` 仅包含 state 与 getter**。
+
+```js
+import { createComponent } from '@mpxjs/core'
+import { storeToRefs } from '@mpxjs/pinia'
+import { useSetupStore } from '../stores/setup'
+
+createComponent({
+  setup (props, context) {
+    const setupStore = useSetupStore()
+    function onIncrementClick () {
+      setupStore.increment()
+    }
+    return Object.assign(
+      { onIncrementClick },
+      storeToRefs(setupStore)
+    )
+  }
+})
+```
+
+**插件**：在 **`createPinia()`** 得到实例后执行 **`pinia.use(plugin)`**；例如通过 **`store.$onAction`** 订阅 action 前后钩子。
+
+#### API 参考
+
+
+
+### `@mpxjs/store`（Vuex 风格）
+
+参考 Vuex：**`state` / `getters` / `mutations` / `actions`**。与随意挂到全局的普通对象相比：① store 内状态是 **响应式** 的；② **不能直接改 `state`**，须通过 **`commit` mutation** 变更，便于追溯。异步与组合逻辑放在 **`actions`** 中 **`dispatch`**。与「单一状态树 + `this.$store`」不同，Mpx 支持 **多实例 store**，组件内需 **显式引入** 实例，再用计算属性或 **`mapState` / `mapGetters` 等** 注入。
+
+#### 创建 store
+
+从 **`@mpxjs/core`** 引入（由 core 再导出 **`@mpxjs/store`**，与直接依赖 **`@mpxjs/store`** 等价）。
+
+**优先使用 `createStoreWithThis`**：getter / mutation / action 内通过 **`this.state`**、**`this.commit`** 等访问，与 **`createStateWithThis` / `createGettersWithThis` / `createMutationsWithThis` / `createActionsWithThis`** 等辅助声明配合时，**TypeScript 类型推导更完整**。**`createStore`** 仍为合法写法：getter、mutation 以 **`(state, …)`**、action 以 **`(context, …)`** 接收参数，在 TS 下推导通常弱于 **`createStoreWithThis`**。
+
+```js
+// store.js
+import { createStoreWithThis } from '@mpxjs/core'
+
+const store = createStoreWithThis({
+  state: {
+    count: 0
+  },
+  getters: {
+    doubled () {
+      return this.state.count * 2
+    }
+  },
+  mutations: {
+    increment () {
+      this.state.count += 1
+    },
+    subCount () {
+      this.state.count -= 1
+    }
+  },
+  actions: {
+    increment () {
+      this.commit('increment')
+    }
+  }
+})
+
+export default store
+```
+
+#### 多实例 store
+
+多个 store 可并列创建、并通过 **`deps`** 进行组合，`deps` 里的 **key** 即命名空间，依赖方的 **`state` / `mutations` 等** 会挂到当前 store 的 **`state[key]`**、**`commit('key.mutationName')`** 等路径下。
+
+```js
+import { createComponent, createStoreWithThis } from '@mpxjs/core'
+
+// 子模块：普通多实例之一，可被多个上层 store 复用
+const childStore = createStoreWithThis({
+  state: { n: 0 },
+  mutations: {
+    addN () {
+      this.state.n += 1
+    }
+  }
+})
+
+// 根模块：deps 写在 options 根；childStore 挂到 state.child（命名空间 = 键名 child）
+const rootStore = createStoreWithThis({
+  state: { local: 0 },
+  getters: {
+    sum () {
+      // this.state.child 与 childStore.state 同源，改任一侧都会联动
+      return this.state.local + this.state.child.n
+    }
+  },
+  mutations: {
+    addLocal () {
+      this.state.local += 1
+    },
+    // 触发依赖 store 的 mutation：'命名空间.mutation 名'
+    proxyAddChild () {
+      this.commit('child.addN')
+    }
+  },
+  deps: {
+    child: childStore
+  }
+})
+
+createComponent({
+  computed: Object.assign(
+    {},
+    // 第一个参数为 deps 里的命名空间，第二个为子 state 上的字段名
+    rootStore.mapState('child', ['n']),
+    rootStore.mapState(['local']),
+    rootStore.mapGetters(['sum'])
+  ),
+  methods: Object.assign(
+    {},
+    rootStore.mapMutations(['addLocal', 'proxyAddChild']),
+    // 也可把依赖 mutation 映射成本地方法名
+    rootStore.mapMutations({ addNFromChild: 'child.addN' })
+  )
+})
+```
+
+#### 使用 store（选项式 API）
+
+`mapState` 只映射 **`state` 路径**；派生状态用 **`mapGetters`**。
+
+```js
+import { createComponent } from '@mpxjs/core'
+import store from '../store'
+
+createComponent({
+  computed: Object.assign(
+    {},
+    store.mapState(['count']),
+    store.mapGetters(['doubled'])
+  ),
+  methods: Object.assign(
+    {},
+    store.mapMutations(['increment']),
+    store.mapActions(['increment'])
+  )
+})
+```
+
+#### 使用 store（组合式 API）
+
+组合式场景下更推荐 **`@mpxjs/pinia`**；沿用 Vuex 式 store 时，可用 **`mapStateToRefs` / `mapGettersToRefs`** 在 `setup` 里拿到 **state、getters 的 ref**。**`mutations` / `actions`** 可直接 **`store.commit` / `store.dispatch`**，也可继续用 **`mapMutations` / `mapActions`** 映射成函数（与主站「在组合式 API 中使用 store」一致）。**`createStore`** 与 **`createStoreWithThis`** 得到的实例均具备上述 **`map*ToRefs`** 与 **`map*`** 方法。
+
+```js
+import { createComponent, watchEffect } from '@mpxjs/core'
+import store from '../store'
+
+createComponent({
+  setup () {
+    const { count } = store.mapStateToRefs(['count'])
+    const { doubled } = store.mapGettersToRefs(['doubled'])
+    const { increment } = store.mapMutations(['increment'])
+
+    watchEffect(() => {
+      console.log(count.value, doubled.value)
+    })
+
+    return {
+      count,
+      doubled,
+      increment,
+      subCount () {
+        store.commit('subCount')
+      }
+    }
+  }
+})
+```
+
+上例中 **`increment`** 来自 **`mapMutations`**，**`subCount`** 直接 **`store.commit`**，演示两种提交 mutation 的方式（与主站「在组合式 API 中使用 store」一致）。
+
+#### 注意事项
+
+- **`action` 的返回值会被包装为 `Promise`**，便于 `then` / `async` 组合。  
+- 虽支持 **`modules`**，更推荐 **多实例 store + `deps` 组合** 做模块划分，灵活度更高。
+
+### 选型建议
+
+- **优先 `@mpxjs/pinia`**：新项目、新状态域、与 **`setup` / `script setup`** 协同、希望与 Pinia 生态一致时选用。  
+- **保留 `@mpxjs/store`**：已有 Vuex 式仓库、`mutations` 可追溯链路或团队规范仍以 Vuex 为主时继续沿用，按需渐进迁移即可。
diff --git a/.agents/skills/mpx-rn-style-guide/references/rn-style-practice.md b/.agents/skills/mpx-rn-style-guide/references/rn-style-practice.md
index 7454d7d238..55f9db4d36 100644
--- a/.agents/skills/mpx-rn-style-guide/references/rn-style-practice.md
+++ b/.agents/skills/mpx-rn-style-guide/references/rn-style-practice.md
@@ -10,7 +10,7 @@
 - [2. 样式单位使用建议](#2-样式单位使用建议)
   - [2.1 优先使用 px 和 rpx 单位](#21-优先使用-px-和-rpx-单位)
   - [2.2 百分比用于相对布局](#22-百分比用于相对布局)
-  - [2.3 1像素边框（极细线）](#23-1像素边框极细线)
+  - [2.3 1 像素边框（极细线）](#23-1像素边框极细线)
   - [2.4 避免使用不兼容的单位 (rem/em)](#24-避免使用不兼容的单位-remem)
   - [2.5 谨慎使用 font-weight 数值](#25-谨慎使用-font-weight-数值)
 - [3. 布局最佳实践](#3-布局最佳实践)
@@ -31,9 +31,10 @@ Mpx 输出 RN 时仅支持**单类选择器**、`page` 选择器和 `:host` 选
 
 Mpx 输出 RN 时通过类名样式映射模拟实现了 CSS 中定义样式的能力，从 RN 平台的技术限制和模拟实现的运行时开销考虑，当前主要支持了**单类选择器**，不支持复杂的复合选择器（如后代选择器 `.parent .child`、交集选择器 `.classA.classB` 等）。为了保证跨端样式表现一致，建议将复合选择器替换为等效的单类选择器。
 
-**注意：** 替换为单类选择器时，不仅需要更新 `<template>` 和 `<style>` 中的类名引用，还需要同步更新 `<script>` 中涉及的动态类名绑定的字面量，以及使用 `selector` 作为参数的相关 API（小程序中主要包括：`createSelectorQuery`、`createIntersectionObserver`、`selectComponent` 和 `selectAllComponents`）。
+**注意**：替换为单类选择器时，不仅需要更新 `<template>` 和 `<style>` 中的类名引用，还需要同步更新 `<script>` 中涉及的动态类名绑定的字面量，以及使用 `selector` 作为参数的相关 API（小程序中主要包括：`createSelectorQuery`、`createIntersectionObserver`、`selectComponent` 和 `selectAllComponents`）。
 
 **❌ 避免：**
+
 ```html
 <template>
   <view class="list">
@@ -45,40 +46,46 @@ Mpx 输出 RN 时通过类名样式映射模拟实现了 CSS 中定义样式的
 </template>
 
 <style>
-/* 避免使用后代选择器和交集选择器 */
-.list .item {
-  padding: 20rpx;
-}
-.item.active {
-  color: red;
-}
+  /* 避免使用后代选择器和交集选择器 */
+  .list .item {
+    padding: 20rpx;
+  }
+  .item.active {
+    color: red;
+  }
 </style>
 
 <script>
-import { createComponent } from '@mpxjs/core'
-
-createComponent({
-  data: {
-    isActive: true
-  },
-  computed: {
-    // script 中返回交集修饰类名
-    dynamicClass() {
-      return this.isActive ? 'active' : ''
+  import { createComponent } from "@mpxjs/core"
+
+  createComponent({
+    data: {
+      isActive: true
+    },
+    computed: {
+      // script 中返回交集修饰类名
+      dynamicClass() {
+        return this.isActive ? "active" : ""
+      }
+    },
+    ready() {
+      // 避免在 API 中使用复合选择器
+      this.createSelectorQuery()
+        .select(".list .item")
+        .boundingClientRect()
+        .exec()
+      this.createIntersectionObserver()
+        .relativeTo(".list")
+        .observe(".item.active", () => {})
+      this.selectComponent(".list .item")
+      this.selectAllComponents(".list .item")
     }
-  },
-  ready() {
-    // 避免在 API 中使用复合选择器
-    this.createSelectorQuery().select('.list .item').boundingClientRect().exec()
-    this.createIntersectionObserver().relativeTo('.list').observe('.item.active', () => {})
-    this.selectComponent('.list .item')
-    this.selectAllComponents('.list .item')
-  }
-})
+  })
 </script>
 ```
 
 **✅ 推荐：**
+
 ```html
 <template>
   <view class="list">
@@ -90,45 +97,50 @@ createComponent({
 </template>
 
 <style>
-/* 推荐使用单类选择器 */
-.list-item {
-  padding: 20rpx;
-}
-.list-item-active {
-  color: red;
-}
+  /* 推荐使用单类选择器 */
+  .list-item {
+    padding: 20rpx;
+  }
+  .list-item-active {
+    color: red;
+  }
 </style>
 
 <script>
-import { createComponent } from '@mpxjs/core'
-
-createComponent({
-  data: {
-    isActive: true
-  },
-  computed: {
-    // script 中的动态类名绑定也需要同步更新为完整的单类名
-    dynamicClass() {
-      return this.isActive ? 'list-item-active' : ''
+  import { createComponent } from "@mpxjs/core"
+
+  createComponent({
+    data: {
+      isActive: true
+    },
+    computed: {
+      // script 中的动态类名绑定也需要同步更新为完整的单类名
+      dynamicClass() {
+        return this.isActive ? "list-item-active" : ""
+      }
+    },
+    ready() {
+      // 使用 selector 作为参数的 API 也需要同步更新为单类名
+      this.createSelectorQuery()
+        .select(".list-item")
+        .boundingClientRect()
+        .exec()
+      this.createIntersectionObserver()
+        .relativeTo(".list")
+        .observe(".list-item-active", () => {})
+      this.selectComponent(".list-item")
+      this.selectAllComponents(".list-item")
     }
-  },
-  ready() {
-    // 使用 selector 作为参数的 API 也需要同步更新为单类名
-    this.createSelectorQuery().select('.list-item').boundingClientRect().exec()
-    this.createIntersectionObserver().relativeTo('.list').observe('.list-item-active', () => {})
-    this.selectComponent('.list-item')
-    this.selectAllComponents('.list-item')
-  }
-})
+  })
 </script>
 ```
 
-
 #### 1.2 子元素伪类替代方案 (:first-child / :last-child / :nth-child)
 
 RN 平台不支持 CSS 子元素伪类选择器（如 `:first-child`, `:last-child`, `:nth-child`）。建议在模版中通过数据下标 (`index`) 判断来动态应用样式类。
 
 **❌ 避免：**
+
 ```css
 /* RN 不支持结构伪类 */
 .item:first-child {
@@ -137,6 +149,7 @@ RN 平台不支持 CSS 子元素伪类选择器（如 `:first-child`, `:last-chi
 ```
 
 **✅ 推荐：**
+
 ```html
 <template>
   <!-- 建议使用 wx:class 进行动态样式绑定 -->
@@ -151,15 +164,15 @@ RN 平台不支持 CSS 子元素伪类选择器（如 `:first-child`, `:last-chi
 </template>
 
 <style>
-.item {
-  margin-top: 20rpx;
-  border-bottom-width: 1rpx;
-}
+  .item {
+    margin-top: 20rpx;
+    border-bottom-width: 1rpx;
+  }
 
-/* 单独定义首项样式 */
-.first-item {
-  margin-top: 0;
-}
+  /* 单独定义首项样式 */
+  .first-item {
+    margin-top: 0;
+  }
 </style>
 ```
 
@@ -168,10 +181,11 @@ RN 平台不支持 CSS 子元素伪类选择器（如 `:first-child`, `:last-chi
 RN 平台不支持 `::before` 和 `::after` 伪元素选择器。对于需要在元素前后添加装饰性内容的需求，应使用真实的组件节点进行等效替代。
 
 **❌ 避免：**
+
 ```css
 /* RN 不支持伪元素 */
 .title::before {
-  content: '';
+  content: "";
   width: 10rpx;
   height: 30rpx;
   background-color: blue;
@@ -179,6 +193,7 @@ RN 平台不支持 `::before` 和 `::after` 伪元素选择器。对于需要在
 ```
 
 **✅ 推荐：**
+
 ```html
 <template>
   <view class="title-container">
@@ -189,18 +204,18 @@ RN 平台不支持 `::before` 和 `::after` 伪元素选择器。对于需要在
 </template>
 
 <style>
-.title-container {
-  display: flex;
-  flex-direction: row;
-  align-items: center;
-}
+  .title-container {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+  }
 
-.title-decorator {
-  width: 10rpx;
-  height: 30rpx;
-  background-color: blue;
-  margin-right: 10rpx;
-}
+  .title-decorator {
+    width: 10rpx;
+    height: 30rpx;
+    background-color: blue;
+    margin-right: 10rpx;
+  }
 </style>
 ```
 
@@ -208,10 +223,10 @@ RN 平台不支持 `::before` 和 `::after` 伪元素选择器。对于需要在
 
 RN 平台不支持 `:active` 伪类选择器，如需实现点击态样式，可以使用 `hover-class` 组件属性进行跨端兼容实现。
 
-**支持组件：**
-`view`、`button`、`navigator`
+**支持组件：** `view`、`button`、`navigator`
 
 **❌ 避免：**
+
 ```css
 /* RN 不支持 :active 伪类 */
 .btn:active {
@@ -221,29 +236,26 @@ RN 平台不支持 `:active` 伪类选择器，如需实现点击态样式，可
 ```
 
 **✅ 推荐：**
+
 ```html
 <template>
   <!-- 使用 hover-class 指定点击态样式类 -->
   <!-- hover-stay-time 指定手指松开后点击态保留时间，单位毫秒 -->
-  <view
-    class="btn"
-    hover-class="btn-hover"
-    hover-stay-time="{{100}}"
-  >
+  <view class="btn" hover-class="btn-hover" hover-stay-time="{{100}}">
     点击我
   </view>
 </template>
 
 <style>
-.btn {
-  background-color: #ffffff;
-}
+  .btn {
+    background-color: #ffffff;
+  }
 
-/* 定义点击态样式 */
-.btn-hover {
-  opacity: 0.8;
-  background-color: #f5f5f5;
-}
+  /* 定义点击态样式 */
+  .btn-hover {
+    opacity: 0.8;
+    background-color: #f5f5f5;
+  }
 </style>
 ```
 
@@ -254,6 +266,7 @@ RN 平台不支持 `:active` 伪类选择器，如需实现点击态样式，可
 px 和 rpx 在 RN 与小程序平台都具备良好兼容性，建议优先使用；其中 rpx 适合响应式尺寸，px 适合固定尺寸。
 
 **✅ 推荐：**
+
 ```css
 .container {
   width: 750rpx;
@@ -280,7 +293,7 @@ px 和 rpx 在 RN 与小程序平台都具备良好兼容性，建议优先使
 
 /* 场景2：Flexbox 中的相对布局 */
 .item {
-  width: 50%;  /* 在 flex 容器中表现良好 */
+  width: 50%; /* 在 flex 容器中表现良好 */
 }
 ```
 
@@ -292,32 +305,25 @@ px 和 rpx 在 RN 与小程序平台都具备良好兼容性，建议优先使
 ```html
 <template>
   <!-- 场景1：font-size 百分比需要 parent-font-size -->
-  <view
-    parent-font-size="{{16}}"
-    class="text"
-  />
+  <view parent-font-size="{{16}}" class="text" />
 
   <!-- 场景2：calc() 中的百分比需要辅助属性 -->
-  <view
-    parent-width="{{750}}"
-    parent-height="{{1000}}"
-    class="box"
-  />
+  <view parent-width="{{750}}" parent-height="{{1000}}" class="box" />
 </template>
 
 <style>
-.text {
-  font-size: 120%;  /* 需要 parent-font-size */
-}
+  .text {
+    font-size: 120%; /* 需要 parent-font-size */
+  }
 
-.box {
-  /* calc() 中的百分比需要辅助属性 */
-  width: calc(50% - 20rpx);   /* 需要 parent-width */
-  height: calc(30% + 10rpx);  /* 需要 parent-height */
+  .box {
+    /* calc() 中的百分比需要辅助属性 */
+    width: calc(50% - 20rpx); /* 需要 parent-width */
+    height: calc(30% + 10rpx); /* 需要 parent-height */
 
-  /* calc() 中的 translateX/Y 百分比会自动测量 */
-  transform: translateX(calc(50% + 10rpx));  /* 自动测量元素 width */
-}
+    /* calc() 中的 translateX/Y 百分比会自动测量 */
+    transform: translateX(calc(50% + 10rpx)); /* 自动测量元素 width */
+  }
 </style>
 ```
 
@@ -326,7 +332,7 @@ px 和 rpx 在 RN 与小程序平台都具备良好兼容性，建议优先使
 ```css
 /* 避免：字体大小使用百分比 */
 .text {
-  font-size: 120%;  /* 需要 parent-font-size，容易出错 */
+  font-size: 120%; /* 需要 parent-font-size，容易出错 */
 }
 
 /* 推荐：使用 rpx */
@@ -336,7 +342,7 @@ px 和 rpx 在 RN 与小程序平台都具备良好兼容性，建议优先使
 
 /* 避免：calc() 中使用百分比但不传递辅助属性 */
 .box {
-  width: calc(50% - 20rpx);  /* 需要 parent-width，否则会报错 */
+  width: calc(50% - 20rpx); /* 需要 parent-width，否则会报错 */
 }
 
 /* 推荐：使用 rpx */
@@ -353,15 +359,13 @@ px 和 rpx 在 RN 与小程序平台都具备良好兼容性，建议优先使
 4. **谨慎使用 calc() 中的百分比**：`calc()` 是框架模拟支持的，其中的百分比需要辅助属性，建议在 `calc()` 中使用 rpx 代替百分比
 5. **使用 vh/vw**：对于视口相关的尺寸，vh/vw 是更好的选择
 
-#### 2.3 1像素边框（极细线）
+#### 2.3 1 像素边框（极细线）
 
 在移动端开发中，常需要实现物理像素为 1px 的极细边框。
 
-**原平台：**
-使用 `1rpx` 可以很好地在不同设备上呈现细边框。
+**原平台：** 使用 `1rpx` 可以很好地在不同设备上呈现细边框。
 
-**RN 平台：**
-使用 `hairlineWidth` 常量来实现平台最细边框。
+**RN 平台：** 使用 `hairlineWidth` 常量来实现平台最细边框。
 
 **✅ 推荐写法（使用条件编译）：**
 
@@ -381,22 +385,22 @@ px 和 rpx 在 RN 与小程序平台都具备良好兼容性，建议优先使
 
 RN 不支持 `rem` 和 `em` 单位。需将其转换为 `rpx` 以实现响应式布局。
 
-**转换说明：**
-`rpx` 是小程序和 Mpx RN 的响应式单位（规定屏幕宽为 750rpx）。
-若原项目使用 `rem` 进行响应式适配，通常存在固定的换算比例。
-例如：
+**转换说明：** `rpx` 是小程序和 Mpx RN 的响应式单位（规定屏幕宽为 750rpx）。若原项目使用 `rem` 进行响应式适配，通常存在固定的换算比例。例如：
+
 - 若设定 `1rem = 100px` (基于 750px 设计稿)，则 `1rem = 100rpx`。
 - 若基于浏览器默认字号 (`16px`)，则 `1rem = 32rpx` (1px = 2rpx)。
 
 **❌ 避免：**
+
 ```css
 .text {
-  width: 2rem;       /* RN 不支持 */
+  width: 2rem; /* RN 不支持 */
   font-size: 1.2rem; /* RN 不支持 */
 }
 ```
 
 **✅ 推荐（转换为 rpx）：**
+
 ```css
 .text {
   /* 假设转换比例 1rem = 100rpx */
@@ -409,20 +413,21 @@ RN 不支持 `rem` 和 `em` 单位。需将其转换为 `rpx` 以实现响应式
 
 由于 RN 平台数值类型的 `font-weight`（如 `400`, `500`, `700`）在不同系统和字体下的渲染表现，与小程序/Web 平台往往存在差异，容易导致跨端 UI 不一致。
 
-**建议：**
-尽量使用 `normal` 或 `bold` 关键字来控制字体粗细，以获得更稳定一致的跨平台表现。
+**建议：** 尽量使用 `normal` 或 `bold` 关键字来控制字体粗细，以获得更稳定一致的跨平台表现。
 
 **❌ 避免：**
+
 ```css
 .text-normal {
-  font-weight: 400;  /* 跨端表现可能不一致 */
+  font-weight: 400; /* 跨端表现可能不一致 */
 }
 .text-bold {
-  font-weight: 700;  /* 跨端表现可能不一致 */
+  font-weight: 700; /* 跨端表现可能不一致 */
 }
 ```
 
 **✅ 推荐：**
+
 ```css
 .text-normal {
   font-weight: normal;
@@ -439,6 +444,7 @@ RN 不支持 `rem` 和 `em` 单位。需将其转换为 `rpx` 以实现响应式
 Flexbox 是跨平台最可靠的布局方式。
 
 **✅ 推荐：**
+
 ```css
 .container {
   display: flex;
@@ -461,6 +467,7 @@ Flexbox 是跨平台最可靠的布局方式。
 Grid 布局在 RN 平台不支持。
 
 **❌ 避免：**
+
 ```css
 .container {
   display: grid;
@@ -469,6 +476,7 @@ Grid 布局在 RN 平台不支持。
 ```
 
 **替代方案：**
+
 ```css
 .container {
   display: flex;
@@ -485,6 +493,7 @@ Grid 布局在 RN 平台不支持。
 `float` 在 RN 平台不支持，不应作为布局方案使用。
 
 **❌ 避免：**
+
 ```css
 .left {
   float: left;
@@ -498,6 +507,7 @@ Grid 布局在 RN 平台不支持。
 ```
 
 **替代方案：**
+
 ```css
 .container {
   display: flex;
@@ -513,6 +523,7 @@ Grid 布局在 RN 平台不支持。
 ### 4. 文本溢出处理
 
 **原平台：**
+
 ```css
 .text {
   white-space: nowrap;
@@ -521,39 +532,31 @@ Grid 布局在 RN 平台不支持。
 ```
 
 **跨平台兼容方案：**
+
 ```html
 <style>
-/* 原平台内使用样式条件编译保留原有样式定义 */
-/* @mpx-if (__mpx_mode__ === 'wx' || __mpx_mode__ === 'ali' || __mpx_mode__ === 'web') */
-.text {
-  white-space: nowrap;
-  text-overflow: ellipsis;
-}
-/* @mpx-endif */
+  /* 原平台内使用样式条件编译保留原有样式定义 */
+  /* @mpx-if (__mpx_mode__ === 'wx' || __mpx_mode__ === 'ali' || __mpx_mode__ === 'web') */
+  .text {
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+  /* @mpx-endif */
 </style>
 
 <template>
   <!-- RN 平台内使用模板属性条件编译添加 numberOfLines 属性进行等效实现-->
-  <text
-    class="text"
-    numberOfLines@ios|android|harmony="{{1}}"
-  >
-    {{text}}
-  </text>
+  <text class="text" numberOfLines@ios|android|harmony="{{1}}"> {{text}} </text>
 
   <!-- numberOfLines 也可用于 view -->
-  <view
-    class="text"
-    numberOfLines@ios|android|harmony="{{1}}"
-  >
-    {{text}}
-  </view>
+  <view class="text" numberOfLines@ios|android|harmony="{{1}}"> {{text}} </view>
 </template>
 ```
 
 ### 5. 隐藏元素
 
 **原平台：**
+
 ```css
 .hidden {
   display: none;
@@ -570,7 +573,7 @@ Grid 布局在 RN 平台不支持。
   width: 0;
   padding: 0;
   margin: 0;
-  overflow: 'hidden';
+  overflow: "hidden";
 }
 ```
 
@@ -579,6 +582,7 @@ Grid 布局在 RN 平台不支持。
 在 Web 和小程序开发中，经常会使用设置 `line-height` 与容器 `height` 等高的方式来实现文本垂直居中，而在 RN 平台中，`line-height` 的实际表现存在差异，建议使用 `flex` 布局属性来实现文本垂直居中。
 
 **❌ 避免：**
+
 ```css
 .text-container {
   height: 100px;
@@ -587,6 +591,7 @@ Grid 布局在 RN 平台不支持。
 ```
 
 **✅ 推荐：**
+
 ```css
 .text-container {
   display: flex;
@@ -602,18 +607,30 @@ Grid 布局在 RN 平台不支持。
 因为 RN 中对 `transparent` 的实现是 `rgba(0,0,0,0)`（黑色透明）。当直接用 `transparent` 当做渐变色的色值时，会出现渐变区域发灰（Black Transition），而不是预期的颜色过渡。
 
 **❌ 避免：**
+
 ```css
 .gradient {
   /* transparent 会导致过渡区域发灰 */
-  background: linear-gradient(to left, transparent 0%, #fff 50%, transparent 100%);
+  background: linear-gradient(
+    to left,
+    transparent 0%,
+    #fff 50%,
+    transparent 100%
+  );
 }
 ```
 
 **✅ 推荐：**
+
 ```css
 .gradient {
   /* 使用 rgba(255,255,255,0) 确保过渡颜色正确 */
-  background: linear-gradient(to left, rgba(255,255,255,0) 0%, #fff 50%, rgba(255,255,255,0) 100%);
+  background: linear-gradient(
+    to left,
+    rgba(255, 255, 255, 0) 0%,
+    #fff 50%,
+    rgba(255, 255, 255, 0) 100%
+  );
 }
 ```
 
@@ -622,6 +639,7 @@ Grid 布局在 RN 平台不支持。
 对于多个组件复用的样式提取到公共样式文件中，减少包体积开销。
 
 创建公共样式文件：
+
 ```css
 /* common.css */
 .flex-center {
@@ -632,6 +650,7 @@ Grid 布局在 RN 平台不支持。
 ```
 
 引用公共样式：
+
 ```html
 <template>
   <view class="page flex-center">
@@ -640,10 +659,10 @@ Grid 布局在 RN 平台不支持。
 </template>
 
 <style>
-@import "./common.css";
+  @import "./common.css";
 
-.page {
-  min-height: 100vh;
-}
+  .page {
+    min-height: 100vh;
+  }
 </style>
 ```
diff --git a/.agents/skills/mpx-rn-style-guide/references/rn-style-reference.md b/.agents/skills/mpx-rn-style-guide/references/rn-style-reference.md
index 932168a77b..538cde805c 100644
--- a/.agents/skills/mpx-rn-style-guide/references/rn-style-reference.md
+++ b/.agents/skills/mpx-rn-style-guide/references/rn-style-reference.md
@@ -39,11 +39,11 @@ Mpx 在 RN 平台支持使用标准的 CSS 语法编写样式，与小程序平
 
 ```html
 <style>
-.container {
-  width: 750rpx;
-  padding: 20rpx;
-  background-color: #fff;
-}
+  .container {
+    width: 750rpx;
+    padding: 20rpx;
+    background-color: #fff;
+  }
 </style>
 ```
 
@@ -54,43 +54,55 @@ Mpx 在 RN 平台支持使用标准的 CSS 语法编写样式，与小程序平
 Mpx 在 RN 平台完整支持静态和动态的类名及样式绑定，与小程序平台保持一致。
 
 #### 静态类名和样式
+
 可以直接使用 `class` 和 `style` 属性：
 
 ```html
 <template>
-  <view class="container" style="color: red;">
-    静态样式
-  </view>
+  <view class="container" style="color: red;"> 静态样式 </view>
 </template>
 ```
 
 #### 动态类名绑定（wx:class）
+
 `wx:class` 支持对象语法和数组语法，可以与静态 `class` 属性同时使用。
 
 **对象语法：**
+
 ```html
-<view class="outer" wx:class="{{ {active: isActive, disabled: isDisabled} }}">
+<view
+  class="outer"
+  wx:class="{{ {active: isActive, disabled: isDisabled} }}"
+></view>
 ```
 
 **数组语法：**
+
 ```html
-<view class="outer" wx:class="{{ ['active', 'primary'] }}">
+<view class="outer" wx:class="{{ ['active', 'primary'] }}"></view>
 ```
 
 #### 动态样式绑定（wx:style）
+
 `wx:style` 支持对象语法和数组语法，可以与静态 `style` 属性同时使用。样式名支持驼峰写法。
 
 **对象语法：**
+
 ```html
-<view style="color: red;" wx:style="{{ {fontSize: '16px', fontWeight: 'bold'} }}">
+<view
+  style="color: red;"
+  wx:style="{{ {fontSize: '16px', fontWeight: 'bold'} }}"
+></view>
 ```
 
 **数组语法：**
+
 ```html
-<view wx:style="{{ [baseStyle, activeStyle] }}">
+<view wx:style="{{ [baseStyle, activeStyle] }}"></view>
 ```
 
 **注意事项：**
+
 - 样式名可以使用驼峰写法（如 `fontSize`）或横杠写法（如 `font-size`）
 - `wx:class` 和 `wx:style` 在运行时动态计算，性能优良
 - 支持与静态 `class` 和 `style` 属性同时使用，会自动合并
@@ -102,25 +114,43 @@ Mpx 在 RN 平台完整支持静态和动态的类名及样式绑定，与小程
 RN 环境下支持的选择器范围有限，主要是**单类选择器**、`page` 选择器和 `:host` 选择器。
 
 ✅ **支持的选择器：**
+
 ```css
-.container { }
-.button { }
-.text-primary { }
-.classA, .classB { } /* 逗号组合支持 */
-page { }
-:host { }
+.container {
+}
+.button {
+}
+.text-primary {
+}
+.classA,
+.classB {
+} /* 逗号组合支持 */
+page {
+}
+:host {
+}
 ```
 
 ❌ **不支持的选择器：**
+
 ```css
-view, text { }       /* 标签选择器 */
-.container .item { } /* 后代选择器 */
-.list > .item { }    /* 子选择器 */
-.item + .item { }    /* 相邻选择器 */
-.button:hover { }    /* 伪类选择器 */
-.text::before { }    /* 伪元素选择器 */
-[type="text"] { }    /* 属性选择器 */
-.button.primary { }  /* 组合选择器 */
+view,
+text {
+} /* 标签选择器 */
+.container .item {
+} /* 后代选择器 */
+.list > .item {
+} /* 子选择器 */
+.item + .item {
+} /* 相邻选择器 */
+.button:hover {
+} /* 伪类选择器 */
+.text::before {
+} /* 伪元素选择器 */
+[type="text"] {
+} /* 属性选择器 */
+.button.primary {
+} /* 组合选择器 */
 ```
 
 ### 2.2 样式单位与转换
@@ -130,7 +160,7 @@ Mpx 在 RN 平台支持多种 CSS 单位，并在运行时进行转换。
 #### 基础单位
 
 | 单位 | 说明 | 转换规则 |
-|------|------|----------|
+| --- | --- | --- |
 | `px` | 绝对像素 | 直接转换为 RN 的无单位数值 |
 | `rpx` | 响应式像素 | `rpx值 × 屏幕宽度 / 750` |
 | `%` | 百分比 | 转换为字符串形式（如 `'50%'`），由 RN 原生支持或框架处理 |
@@ -145,10 +175,10 @@ Mpx 在 RN 平台支持多种 CSS 单位，并在运行时进行转换。
 同时支持通过运行时配置 `Mpx.config.rnConfig.customDimensions` 自定义样式计算基准：
 
 ```javascript
-import mpx from '@mpxjs/core'
+import mpx from "@mpxjs/core"
 
 mpx.config.rnConfig = Object.assign({}, mpx.config.rnConfig, {
-  customDimensions (dimensions) {
+  customDimensions(dimensions) {
     const nextWindow = Object.assign({}, dimensions.window, {
       height: dimensions.window.height - 44
     })
@@ -169,24 +199,22 @@ mpx.config.rnConfig = Object.assign({}, mpx.config.rnConfig, {
 
 跨端输出 RN 时， 部分百分比单位原生支持，而部分百分比单位则由框架进行计算抹平实现，详情如下：
 
-1.  **原生支持（基于父节点宽高）**：
-    `width`、`height`、`left`、`right`、`top`、`bottom`、`margin`、`padding` 等属性。
+1.  **原生支持（基于父节点宽高）**： `width`、`height`、`left`、`right`、`top`、`bottom`、`margin`、`padding` 等属性。
+
+2.  **需辅助属性（基于父节点字体）**： `font-size` 的百分比计算依赖开发者传入的 `parent-font-size` 属性。
 
-2.  **需辅助属性（基于父节点字体）**：
-    `font-size` 的百分比计算依赖开发者传入的 `parent-font-size` 属性。
     ```html
     <text parent-font-size="16" style="font-size: 120%;">文本内容</text>
     ```
 
-3.  **基于自身宽高计算**：
-    `translateX`、`translateY`、`border-radius` 的百分比都是根据自身宽高来计算的（首次渲染不展示，在 `onLayout` 后计算生效）。
+3.  **基于自身宽高计算**： `translateX`、`translateY`、`border-radius` 的百分比都是根据自身宽高来计算的（首次渲染不展示，在 `onLayout` 后计算生效）。
 
-4.  **calc() 函数内的百分比**：
-    在 `calc()` 函数表达式内使用百分比时，需要开发者设置 `parent-width` 或 `parent-height` 属性。
+4.  **calc() 函数内的百分比**：在 `calc()` 函数表达式内使用百分比时，需要开发者设置 `parent-width` 或 `parent-height` 属性。
 
 ### 2.3 颜色值支持
 
 支持以下颜色值格式：
+
 - **Named Color**: 预定义颜色名称（如 `red`、`blue`）
 - **Hex Color**: 十六进制颜色（如 `#090`、`#009900`）
 - **RGB/RGBA**: `rgb(34, 12, 64)`、`rgba(34, 12, 64, 0.6)`
@@ -199,11 +227,13 @@ mpx.config.rnConfig = Object.assign({}, mpx.config.rnConfig, {
 Mpx 框架抹平了平台差异，使 `view` 节点可以直接包裹文本并继承样式。
 
 **继承规则：**
+
 1.  **view -> text 继承**：只有 `view` 节点下的**直接子** `text` 节点可以继承 `view` 节点上的文本样式。
 2.  **text 嵌套继承**：父级 `text` 节点的样式可以被嵌套的子 `text` 节点继承。
 3.  **自动包裹**：`view` 节点直接包裹文本时，Mpx 编译时会自动添加 `text` 节点包裹文本。
 
 **透传属性：**
+
 - Mpx 会从 `view` 上拆分文本组件属性并透传到直接子 `text` 节点，包括：`ellipsizeMode`、`numberOfLines`、`allowFontScaling`
 - Mpx 会从 `view` 的样式中拆分文本样式并透传到直接子 `text` 节点，包括：`color`、`font*`、`text*`、`letterSpacing`、`lineHeight`、`includeFontPadding`、`writingDirection`
 
@@ -211,15 +241,14 @@ Mpx 框架抹平了平台差异，使 `view` 节点可以直接包裹文本并
 
 RN 仅原生支持部分 CSS 简写属性，Mpx 会在**编译时**对其他简写属性进行展开，以兼容 RN。
 
-**RN 原生支持的简写属性：**
-以下属性在 RN 中原生支持，可以在 `style` 内联样式和 `class` 类样式中使用，无需编译转换：
+**RN 原生支持的简写属性：** 以下属性在 RN 中原生支持，可以在 `style` 内联样式和 `class` 类样式中使用，无需编译转换：
+
 - **布局**：`flex`（支持 `flex: 1` / `flex: 0` 等）
 - **间距**：`margin`、`padding`（**仅支持单值语法**，如 `margin: 10px`）
 - **边框**：`border-width`、`border-color`、`border-radius`（**仅支持单值语法**，如 `border-width: 1px`）
 - **阴影**：`box-shadow`（RN 0.76+ 原生支持）
 
-**Mpx 编译时增强的简写属性：**
-以下属性及其多值语法 RN 不原生支持，Mpx 会在编译时自动将其展开为 RN 支持的多属性结构：
+**Mpx 编译时增强的简写属性：** 以下属性及其多值语法 RN 不原生支持，Mpx 会在编译时自动将其展开为 RN 支持的多属性结构：
 
 - **间距多值语法**：`margin`、`padding` 的 2-4 值语法
   - 如 `margin: 10px 20px` → `marginTop: 10, marginRight: 20...`
@@ -235,6 +264,7 @@ RN 仅原生支持部分 CSS 简写属性，Mpx 会在**编译时**对其他简
 - **装饰简写**：`text-decoration`
 
 **使用限制：**
+
 - ✅ **class 类样式**：支持所有简写属性及其多值语法，Mpx 会在编译时自动展开。
 - ❌ **style 属性**：仅支持 RN 原生支持的简写属性（如 `margin`、`padding` 的单值语法）。**不支持** Mpx 编译增强的简写属性（如 `border`、多值 `margin` 等），在内联样式中使用这些属性会导致 RN 运行时报错或无效。
 - ❌ **CSS 变量**：编译增强的简写属性不支持单个 `var()` 函数（如 `margin: var(--spacing)`），但支持多值简写中使用多个 `var()`（如 `margin: var(--v) var(--h)`）。RN 原生支持的简写属性（如单值 `margin`）支持单个 `var()`。
@@ -242,15 +272,19 @@ RN 仅原生支持部分 CSS 简写属性，Mpx 会在**编译时**对其他简
 ### 2.6 CSS 变量与函数
 
 #### CSS 变量 (Custom Properties)
+
 支持定义和使用 CSS 变量，支持 fallback 值。
 
 ```css
-:root { --main-color: #3498db; }
-.comp { color: var(--main-color, blue); }
+:root {
+  --main-color: #3498db;
+}
+.comp {
+  color: var(--main-color, blue);
+}
 ```
 
-**自动检测与 enable-var：**
-框架会自动检测样式中的 CSS 变量使用。如果样式中一开始不存在变量定义或使用，但后续需要动态添加（如通过 `wx:style`），建议使用 `enable-var` 属性预先声明，以确保运行时正确处理变量。
+**自动检测与 enable-var：** 框架会自动检测样式中的 CSS 变量使用。如果样式中一开始不存在变量定义或使用，但后续需要动态添加（如通过 `wx:style`），建议使用 `enable-var` 属性预先声明，以确保运行时正确处理变量。
 
 ```html
 <template>
@@ -263,13 +297,14 @@ RN 仅原生支持部分 CSS 简写属性，Mpx 会在**编译时**对其他简
 <script>
   // ...
   this.dynamicStyle = {
-    '--text-color': 'red',
-    color: 'var(--text-color)'
+    "--text-color": "red",
+    color: "var(--text-color)"
   }
 </script>
 ```
 
 #### calc() 函数
+
 支持四则运算（`+`、`-`、`*`、`/`），支持混合单位。
 
 ```css
@@ -278,11 +313,13 @@ font-size: calc(16px / 2);
 ```
 
 #### env() 函数
+
 用于适配设备安全区域。
 
 ```css
 padding-top: env(safe-area-inset-top, 20px);
 ```
+
 支持的环境变量：`safe-area-inset-top`、`safe-area-inset-right`、`safe-area-inset-bottom`、`safe-area-inset-left`。
 
 ### 2.7 媒体查询
@@ -290,11 +327,13 @@ padding-top: env(safe-area-inset-top, 20px);
 Mpx 在 RN 平台支持 `@media` 规则，但能力受限。
 
 **支持特性：**
+
 - 媒体类型：`screen`、`all`
 - 媒体特性：`width`、`min-width`、`max-width`
 - 逻辑运算符：`and`
 
 **限制：**
+
 - 媒体查询中的宽度条件仅支持 `px` 单位。
 - 不支持 `height`、`orientation` 等其他特性。
 
@@ -307,11 +346,10 @@ Mpx 在 RN 平台支持以下动画方式：
 - **不支持**：CSS Keyframes (`@keyframes`) 动画。
 
 **使用限制：**
-- 仅 `view` 组件支持动画相关属性。
 
-**自动检测与 enable-animation：**
-框架会自动检测样式和属性中的动画定义来确定动画类型（如检测到 `transition` 样式或 `animation` 属性）。如果样式中一开始不存在动画定义，但后续需要动态添加（如通过 `wx:style` 动态添加 `transition`），建议使用 `enable-animation` 属性预先声明动画类型。
+- 仅 `view` 组件支持动画相关属性。
 
+**自动检测与 enable-animation：** 框架会自动检测样式和属性中的动画定义来确定动画类型（如检测到 `transition` 样式或 `animation` 属性）。如果样式中一开始不存在动画定义，但后续需要动态添加（如通过 `wx:style` 动态添加 `transition`），建议使用 `enable-animation` 属性预先声明动画类型。
 
 ```html
 <template>
@@ -322,7 +360,7 @@ Mpx 在 RN 平台支持以下动画方式：
 <script>
   // ...
   this.dynamicStyle = {
-    transition: 'opacity 0.3s ease',
+    transition: "opacity 0.3s ease",
     opacity: 0.5
   }
 </script>
@@ -333,19 +371,20 @@ Mpx 在 RN 平台支持以下动画方式：
 Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样式转换。
 
 **支持特性：**
+
 - **背景颜色**：RN 原生支持 `background-color`。
 - **背景图**：支持 `background-image: url()` 引用图片。
 - **渐变背景**：支持 `background-image: linear-gradient()` 线性渐变。
 - **相关属性**：完整支持 `background-size` 和 `background-position`。
 
 **限制与注意事项：**
+
 - **组件限制**：仅 `view` 组件支持除 `background-color` 外的背景相关属性。
 - **简写属性**：`background` 简写属性仅支持 `<background-color>`、`<background-image>` 和 `<background-repeat>`，不支持 `background-position` 和 `background-size` 简写。
 - **背景重复**：`background-repeat` 仅支持 `no-repeat`
 - **多重背景**：不支持多重背景。
 
-**自动检测与 enable-background：**
-框架会自动检测样式中的背景相关属性（如 `background-image`、`background-size` 等）。如果样式中一开始不存在背景定义，但后续需要动态添加（如通过 `wx:style`），建议使用 `enable-background` 属性预先声明，以确保运行时正确处理背景。
+**自动检测与 enable-background：** 框架会自动检测样式中的背景相关属性（如 `background-image`、`background-size` 等）。如果样式中一开始不存在背景定义，但后续需要动态添加（如通过 `wx:style`），建议使用 `enable-background` 属性预先声明，以确保运行时正确处理背景。
 
 ```html
 <template>
@@ -358,7 +397,7 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 <script>
   // ...
   this.dynamicStyle = {
-    backgroundImage: 'url(...)'
+    backgroundImage: "url(...)"
   }
 </script>
 ```
@@ -368,7 +407,7 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 ### 3.1 布局属性 (Flexbox)
 
 | 属性 | 值类型 | 默认值 | 说明 |
-|------|--------|--------|------|
+| --- | --- | --- | --- |
 | `display` | `flex` \| `none` | `flex` | RN 仅支持 Flex 布局 |
 | `flex-direction` | `row` \| `column` \| `row-reverse` \| `column-reverse` | `column` | 主轴方向（RN 默认为 column） |
 | `flex-wrap` | `nowrap` \| `wrap` \| `wrap-reverse` | `nowrap` | 换行控制 |
@@ -385,7 +424,7 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 ### 3.2 定位与层级
 
 | 属性 | 值类型 | 默认值 | 说明 |
-|------|--------|--------|------|
+| --- | --- | --- | --- |
 | `position` | `relative` \| `absolute` \| `fixed` | `relative` | 不支持 `sticky` |
 | `top` / `right` / `bottom` / `left` | `length` \| `%` | - | 偏移量 |
 | `z-index` | `number` | - | 层级控制 |
@@ -393,7 +432,7 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 ### 3.3 尺寸与溢出
 
 | 属性 | 值类型 | 默认值 | 说明 |
-|------|--------|--------|------|
+| --- | --- | --- | --- |
 | `width` / `height` | `auto` \| `length` \| `%` | `auto` | 宽高 |
 | `min-width` / `min-height` | `length` \| `%` | - | 最小尺寸 |
 | `max-width` / `max-height` | `length` \| `%` | - | 最大尺寸 |
@@ -403,17 +442,17 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 
 ### 3.4 间距 (Margin/Padding)
 
-| 属性 | 值类型 | 说明 |
-|------|--------|------|
-| `margin` | `auto` \| `length` \| `%` | 外边距简写（支持多值） |
-| `margin-*` | `auto` \| `length` \| `%` | 单边外边距 |
-| `padding` | `length` \| `%` | 内边距简写（支持多值） |
-| `padding-*` | `length` \| `%` | 单边内边距 |
+| 属性        | 值类型                    | 说明                   |
+| ----------- | ------------------------- | ---------------------- |
+| `margin`    | `auto` \| `length` \| `%` | 外边距简写（支持多值） |
+| `margin-*`  | `auto` \| `length` \| `%` | 单边外边距             |
+| `padding`   | `length` \| `%`           | 内边距简写（支持多值） |
+| `padding-*` | `length` \| `%`           | 单边内边距             |
 
 ### 3.5 边框 (Border)
 
 | 属性 | 值类型 | 说明 |
-|------|--------|------|
+| --- | --- | --- |
 | `border` | `width style color` | 边框简写 |
 | `border-width` | `length` | 边框宽度（支持多值） |
 | `border-color` | `color` | 边框颜色（支持多值） |
@@ -423,10 +462,10 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 
 ### 3.6 背景 (Background)
 
-> **注意**：仅 `view` 组件支持背景相关属性（除 `background-color` 外）。
+**注意**：仅 `view` 组件支持背景相关属性（除 `background-color` 外）。
 
 | 属性 | 值类型 | 说明 |
-|------|--------|------|
+| --- | --- | --- |
 | `background` | `<background-color>` \| `<background-image>` \| `<background-repeat>` | 背景简写，不支持 `background-position` 和 `background-size` 简写 |
 | `background-color` | `color` | 背景色 |
 | `background-image` | `url()` \| `linear-gradient()` | 背景图/渐变 |
@@ -436,10 +475,10 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 
 ### 3.7 文本与字体
 
-> **注意**：文本样式需遵循继承规则。
+**注意**：文本样式需遵循继承规则。
 
 | 属性 | 值类型 | 默认值 | 说明 |
-|------|--------|--------|------|
+| --- | --- | --- | --- |
 | `color` | `color` | - | 文本颜色 |
 | `font-family` | `string` | - | 字体（仅支持单字体） |
 | `font-size` | `length` | - | 字体大小 |
@@ -458,26 +497,26 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 
 ### 3.8 变换 (Transform)
 
-| 属性 | 值类型 | 说明 |
-|------|--------|------|
-| `transform` | `translate` \| `scale` \| `rotate`... | 变换函数列表 |
-| `transform-origin` | `length` \| `%` \| `keyword` | 变换原点 |
+| 属性               | 值类型                                | 说明         |
+| ------------------ | ------------------------------------- | ------------ |
+| `transform`        | `translate` \| `scale` \| `rotate`... | 变换函数列表 |
+| `transform-origin` | `length` \| `%` \| `keyword`          | 变换原点     |
 
 **不支持**：`translateZ`, `scaleZ`, `translate3d`, `scale3d`, `rotate3d`, `matrix3d`。
 
 ### 3.9 阴影与不透明度
 
 | 属性 | 值类型 | 说明 |
-|------|--------|------|
+| --- | --- | --- |
 | `box-shadow` | `<offset-x> <offset-y> <blur-radius> <spread-radius> <color>` | 阴影简写（RN 0.76+ 原生支持） |
 | `opacity` | `0-1` | 不透明度 |
 
 ### 3.10 动画 (Animation)
 
-> **注意**：仅 `view` 组件支持动画相关属性。
+**注意**：仅 `view` 组件支持动画相关属性。
 
 | 属性 | 值类型 | 说明 |
-|------|--------|------|
+| --- | --- | --- |
 | `transition` | `property duration timing-function delay` | 过渡简写 |
 | `transition-property` | `string` | 过渡属性（不支持 `all`） |
 | `transition-duration` | `time` | 过渡持续时间 |
@@ -487,7 +526,7 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 ### 3.11 其他属性
 
 | 属性 | 值类型 | 说明 |
-|------|--------|------|
+| --- | --- | --- |
 | `pointer-events` | `auto` \| `none` \| `box-none` \| `box-only` | 点击穿透控制 |
 | `backface-visibility` | `visible` \| `hidden` | 背面可见性 |
 | `object-fit` | `cover` \| `contain` \| `fill` \| `scale-down` | 图片填充模式 |
@@ -495,6 +534,7 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 ### 3.12 不支持的属性
 
 以下属性在 RN 平台不支持：
+
 - `white-space`
 - `text-overflow`
 - `animation` (CSS Keyframes)
@@ -506,4 +546,3 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 - `caret-color`
 - `float`
 - `clear`
-
diff --git a/.agents/skills/mpx-rn-style-guide/references/rn-template-reference.md b/.agents/skills/mpx-rn-style-guide/references/rn-template-reference.md
index 66b3aaf840..17b08ba24a 100644
--- a/.agents/skills/mpx-rn-style-guide/references/rn-template-reference.md
+++ b/.agents/skills/mpx-rn-style-guide/references/rn-template-reference.md
@@ -2,11 +2,22 @@
 
 ## 目录索引
 
+- [数据绑定](#数据绑定)
+  - [文本、属性与表达式](#文本属性与表达式)
 - [模板指令](#模板指令)
 - [事件处理](#事件处理)
-  - [基础通用事件](#基础通用事件)
+  - [通用事件](#通用事件)
   - [事件绑定语法](#事件绑定语法)
-  - [注意事项](#注意事项)
+  - [注意事项](#注意事项-1)
+- [i18n 国际化](#i18n-国际化)
+  - [工程配置示例](#工程配置示例)
+  - [模板中使用翻译函数](#模板中使用翻译函数)
+  - [JS 中使用翻译函数](#js-中使用翻译函数)
+  - [注意事项](#注意事项-2)
+- [无障碍访问](#无障碍访问)
+  - [模板属性](#模板属性)
+  - [示例](#示例)
+  - [注意事项](#注意事项-3)
 - [基础组件](#基础组件)
   - [通用属性](#通用属性)
   - [view](#view)
@@ -43,12 +54,66 @@
   - [cover-view](#cover-view)
   - [cover-image](#cover-image)
 
+
+## 数据绑定
+
+跨端输出 RN 时，模板数据绑定规则与微信小程序一致：在模板中使用 Mustache 语法 `{{}}` 将脚本中的响应式数据、计算属性等绑定到视图。编译后由 Mpx 在 RN 侧生成等价的数据流与属性传递，写法上与输出小程序、Web 保持同一套 `.mpx` 模板习惯即可。
+
+### 文本、属性与表达式
+
+- **文本节点**：在标签闭合内容中使用 Mustache 表达式插值，例如 `<text>{{ message }}</text>`。
+- **属性值**：属性值同样支持 Mustache 表达式插值，例如 `value="{{ inputValue }}"`、`placeholder="共 {{ total }} 条"`，同时支持在模版指令中使用，如 `wx:if`、`wx:for`、`wx:show` 等。
+- **表达式能力**：`{{}}` 内支持算术、三元、逻辑运算、属性访问等常见 JavaScript 表达式，可与 `data`、`computed`、`setup` 暴露的数据字段组合使用。`{{}}` 内支持**可选链** `?.`，例如 `{{ user?.name }}`、`wx:if="{{ list?.length }}"`。
+- **访问环境变量**：在 `{{}}` 中可直接访问 **`__mpx_mode__`**（当前目标平台，如 `wx`、`ali`、`ios`、`android` 等）、**`__mpx_env__`**（用户在编译配置中通过 `env` 定义的环境标识），以及用户在编译配置中通过 **`defs`** 定义的自定义环境变量。
+
+```html
+<template>
+  <!-- 不推荐：在 {{}} 中直接调用 methods 或任意函数 -->
+  <!-- <text>{{ formatTitle(title) }}</text> -->
+
+  <!-- 推荐：绑定 computed / data 字段 -->
+  <text>{{ displayTitle }}</text>
+
+  <!-- i18n：翻译方法由编译器改写，可按项目 i18n 文档使用 -->
+  <text>{{ $t('hello') }}</text>
+</template>
+
+<script>
+import { createComponent } from '@mpxjs/core'
+
+createComponent({
+  data () {
+    return {
+      title: 'demo'
+    }
+  },
+  computed: {
+    displayTitle () {
+      return this.formatTitle(this.title)
+    }
+  },
+  methods: {
+    formatTitle (str) {
+      return str ? str.toUpperCase() : ''
+    }
+  }
+})
+</script>
+```
+
+#### 注意事项
+
+1. 模板数据绑定中**不支持**对组件 `methods` 或任意函数的**一般方法调用**（例如 `{{ formatTitle(title) }}`）。
+2. 需要在模版中加工展示数据时，请使用 **`computed`** 替代，或改写为 **`wxs`** 函数，模版中支持调用 `wxs` 函数。
+3. **例外**：**i18n 翻译函数**（如 `$t`、`$tc` 等，组合式 API 中为 `t`、`tc` 等）会在**编译期**被 Mpx **改写为等效的 `computed` 或 `wxs` 实现**，因此模板中支持直接调用 i18n 翻译函数。
+
+
 ## 模板指令
 
 Mpx 跨端输出 RN 时，支持以下模板指令。
 
 | 指令 | 支持状态 | 说明 | 示例 |
-|------|---------|------|------|
+| --- | --- | --- | --- |
 | wx:if | ✅ | 条件渲染 | `<view wx:if="{{condition}}">...</view>` |
 | wx:else | ✅ | 条件渲染 | `<view wx:else>...</view>` |
 | wx:elif | ✅ | 条件渲染 | `<view wx:elif="{{condition}}">...</view>` |
@@ -71,29 +136,27 @@ Mpx 跨端输出 RN 时，支持以下模板指令。
 
 在跨端输出 RN 时，所有基础组件均支持以下基础通用事件，并且支持事件冒泡和捕获。
 
-| 事件名 | 说明 |
-| --- | --- |
-| tap | 手指触摸后马上离开 |
-| longpress | 手指触摸后，超过 350ms 再离开 |
-| touchstart | 手指触摸动作开始 |
-| touchmove | 手指触摸后移动 |
-| touchend | 手指触摸动作结束 |
+| 事件名      | 说明                                   |
+| ----------- | -------------------------------------- |
+| tap         | 手指触摸后马上离开                     |
+| longpress   | 手指触摸后，超过 350ms 再离开          |
+| touchstart  | 手指触摸动作开始                       |
+| touchmove   | 手指触摸后移动                         |
+| touchend    | 手指触摸动作结束                       |
 | touchcancel | 手指触摸动作被打断，如来电提醒，弹窗等 |
 
 ### 事件绑定语法
 
 **普通事件绑定**
+
 ```js
-<view bindtap="handleTap">
-    Click here!
-</view>
+<view bindtap="handleTap">Click here!</view>
 ```
 
 **绑定并阻止事件冒泡**
+
 ```js
-<view catchtap="handleTap">
-    Click here!
-</view>
+<view catchtap="handleTap">Click here!</view>
 ```
 
 **事件捕获**
@@ -101,18 +164,14 @@ Mpx 跨端输出 RN 时，支持以下模板指令。
 ```js
 <view capture-bind:touchstart="handleTap1">
   outer view
-  <view capture-bind:touchstart="handleTap2">
-    inner view
-  </view>
+  <view capture-bind:touchstart="handleTap2">inner view</view>
 </view>
 ```
 
 **中断捕获阶段和取消冒泡阶段**
 
 ```js
-<view capture-catch:touchstart="handleTap1">
-  outer view
-</view>
+<view capture-catch:touchstart="handleTap1">outer view</view>
 ```
 
 **事件内联传参**
@@ -124,12 +183,16 @@ Mpx 支持了事件内联传参机制。
   <!--Mpx增强语法，模板内联传参，方便简洁-->
   <view bindtap="handleTapInline('inline')">内联传参</view>
 </template>
-<script setup>
-  // 直接通过参数获取数据，直观方便
-  const handleTapInline = (params) => {
-    console.log('params:', params)
+<script>
+import { createComponent } from '@mpxjs/core'
+
+createComponent({
+  methods: {
+    handleTapInline (params) {
+      console.log('params:', params)
+    }
   }
-  // ...
+})
 </script>
 ```
 
@@ -140,26 +203,32 @@ Mpx 也支持使用 `{{}}` 插值进行动态事件绑定。
 ```html
 <template>
   <!--动态事件绑定-->
-  <view wx:for="{{items}}" bindtap="handleTap_{{index}}">
-    {{item}}
-  </view>
+  <view wx:for="{{items}}" bindtap="handleTap_{{index}}"> {{item}} </view>
 </template>
-<script setup>
-  import { ref } from '@mpxjs/core'
-  const items = ref(['Item 1', 'Item 2', 'Item 3', 'Item 4'])
-  const handleTap_0 = (event) => {
-    console.log('Tapped on item 1');
-  }
-  const handleTap_1 = (event) => {
-    console.log('Tapped on item 2');
-  }
-  const handleTap_2 = (event) => {
-    console.log('Tapped on item 3');
+<script>
+import { createComponent } from '@mpxjs/core'
+
+createComponent({
+  data () {
+    return {
+      items: ['Item 1', 'Item 2', 'Item 3', 'Item 4']
+    }
+  },
+  methods: {
+    handleTap_0 () {
+      console.log('Tapped on item 1')
+    },
+    handleTap_1 () {
+      console.log('Tapped on item 2')
+    },
+    handleTap_2 () {
+      console.log('Tapped on item 3')
+    },
+    handleTap_3 () {
+      console.log('Tapped on item 4')
+    }
   }
-  const handleTap_3 = (event) => {
-    console.log('Tapped on item 4');
-  }
-  // ...
+})
 </script>
 ```
 
@@ -170,6 +239,187 @@ Mpx 也支持使用 `{{}}` 插值进行动态事件绑定。
 3. 由于 `tap` 和 `longpress` 事件是由 `touchstart` / `touchend` 等底层触摸事件模拟实现，所以在 RN 环境，如果子组件绑定了 `catchtouchend`，那么父组件的 `tap` 事件将不会响应。
 4. 如果元素上设置了 `opacity: 0` 的样式，会导致 ios 事件无法响应。
 
+## i18n 国际化
+
+Mpx 跨端输出 RN 时完整支持 i18n，在模板 Mustache 表达式中可直接调用翻译函数，选项式 API 与组合式 API 均可使用。与输出小程序保持一致。**必须**在构建配置里为 **`MpxWebpackPlugin` 传入 `i18n` 选项**（如 `locale`、`messages` 或 `messagesPath` 等）；未配置时模板与脚本中的翻译调用均无法按预期工作。
+
+### 工程配置示例
+
+在接入 `MpxWebpackPlugin` 时传入 `i18n` 配置（具体挂在 `new MpxWebpackPlugin({...})`、`pluginOptions.mpx.plugin` 等位置以项目脚手架为准）：
+
+```js
+i18n: {
+  locale: 'zh-CN',
+  messages: {
+    'zh-CN': {
+      message: { hello: '{msg}，你好' }
+    },
+    'en-US': {
+      message: { hello: 'Hello, {msg}' }
+    }
+  }
+  // messagesPath: path.resolve(__dirname, '../src/i18n/messages.js')
+  // useComputed: false // 见下方「注意事项」
+}
+```
+
+### 模板中使用翻译函数
+
+| 场景 | 模板中常用写法 | 说明 |
+| --- | --- | --- |
+| 选项式 API | `$t`、`$tc`、`$te`、`$tm` | 与 vue-i18n 习惯一致，可在 `{{}}` 与指令属性中书写表达式。 |
+| 组合式 API | `t`、`tc`、`te`、`tm` | 须在 `setup` 中通过 **`useI18n()`** 解构，并 **原样名** 放入 `return`，供模板绑定；**禁止** `const { t: t1 } = useI18n()` 后再把 `t1` 交给模板，否则编译期无法正确解析。 |
+
+**选项式：模板 + 指令中的翻译**
+
+```html
+<template>
+  <view>
+    <text wx:if="{{ $te('message.hello') }}">{{ $t('message.hello', { msg: title }) }}</text>
+  </view>
+</template>
+
+<script>
+import { createComponent } from '@mpxjs/core'
+
+createComponent({
+  data () {
+    return { title: 'Mpx' }
+  }
+})
+</script>
+```
+
+**组合式：在模板中使用 `t`（翻译函数需在 `setup` 中导出，且不能随意变更函数名称）**
+
+```html
+<template>
+  <view>
+    <text>{{ t('message.hello', { msg: title }) }}</text>
+  </view>
+</template>
+
+<script>
+import { ref, createComponent, useI18n } from '@mpxjs/core'
+
+createComponent({
+  setup () {
+    const title = ref('Mpx')
+    const { t } = useI18n()
+    return {
+      title,
+      t
+    }
+  }
+})
+</script>
+```
+
+翻译函数参数、复数文案 `tc`、存在性判断 `te`、消息对象 `tm` 等用法与 vue-i18n 保持一致。
+
+### JS 中使用翻译函数
+
+- **选项式 API**：在 `methods`、`computed`、生命周期钩子等任意可访问组件实例处，使用 **`this.$t` / `this.$tc` / `this.$te` / `this.$tm`**，与 vue-i18n 相同。
+- **组合式 API**：在 **`setup`** 函数体内直接调用 **`useI18n()`** 返回的 **`t`/`tc`/`te`/`tm`**，用于拼 **`computed`**、**`watch`**、异步回调等；勿在 `setup` 外闭包中延迟首次调用 `useI18n`（须顶层同步调用）。
+
+**选项式：在逻辑层调用**
+
+```js
+import { createComponent } from '@mpxjs/core'
+
+createComponent({
+  data () {
+    return { userName: 'Lee' }
+  },
+  ready () {
+    const text = this.$t('message.hello', { msg: this.userName })
+    console.log(text)
+  },
+  computed: {
+    greeting () {
+      return this.$t('message.hello', { msg: this.userName })
+    }
+  }
+})
+```
+
+**组合式：列表文案建议在 JS 中先翻译再渲染（多端一致）**
+
+```html
+<template>
+  <view wx:for="{{ displayList }}" wx:key="id">
+    <text>{{ item.label }}</text>
+  </view>
+</template>
+
+<script>
+import { ref, computed, createComponent, useI18n } from '@mpxjs/core'
+
+createComponent({
+  setup () {
+    const { t } = useI18n()
+    const list = ref([
+      { id: 1, nameKey: 'apple' },
+      { id: 2, nameKey: 'banana' }
+    ])
+    const displayList = computed(function () {
+      return list.value.map(function (item) {
+        return {
+          id: item.id,
+          label: t('fruit.' + item.nameKey)
+        }
+      })
+    })
+    return {
+      displayList
+    }
+  }
+})
+</script>
+```
+
+### 注意事项
+
+1. **`useI18n` 须在 `setup` 顶层同步调用**；组合式下模板里出现的翻译函数名必须与 **`useI18n()` 解构名完全一致**（`t`、`tc`、`te`、`tm`），不可重命名后交给模板。
+2. 输出小程序且开启 **`i18n.useComputed`** 时，模板中的翻译函数走 computed 注入，**无法引用 `wx:for` 循环体内的 `item` / `index`**。输出 RN 虽不受该机制限制，为与小程序等行为对齐、避免同一模板在不同端表现不一致，**列表场景仍建议在 JS 中先完成翻译**（见上文 `displayList` 示例），避免依赖 `{{ t('key', { x: item }) }}` 仅在部分端可用的写法。
+3. **能力边界**：当前与主站一致，仅支持 **`$t` / `$tc` / `$te` / `$tm`（选项式）** 与 **`t` / `tc` / `te` / `tm`（组合式）**；**不支持** **`$d` / `$n`** 等日期、数字格式化 API。
+4. **组合式 + 模板**：模板里的 `t`/`tc`/`te`/`tm` 由编译器按 computed 类方式处理，除循环变量问题外，仍需保证 **`return` 中暴露**了模板所需翻译函数，否则对应翻译函数无法在模版中生效。
+
+## 无障碍访问
+
+跨端输出 RN 时，模板侧请**优先且统一**使用 **`aria-role`**、**`aria-label`**，与小程序侧写法对齐。**不推荐**在模板里直接书写 React Native 文档中的驼峰无障碍属性名（如 **`accessibilityLabel`**、**`accessibilityHint`**、**`accessibilityRole`**、**`accessibilityState`** 等）：这类写法不利于与其它端模板保持一致，也更容易在后续编译或组件封装变动时产生隐性差异。底层 RN 映射由框架与编译规则完成；若需了解语义对应关系，可对照 [React Native Accessibility](https://reactnative.dev/docs/accessibility) 作阅读参考，而不是在业务模板中手写 RN 属性名。
+
+### 模板属性
+
+| 模板属性 | 说明 |
+| --- | --- |
+| `aria-role` | 用于声明按钮、标题、图像等语义角色。 |
+| `aria-label` | 用于补充读屏文案。 |
+
+属性值支持 Mustache，例如 `aria-label="{{ desc }}"`。
+
+### 示例
+
+**语义角色 + 读屏文案（推荐写法）**
+
+```html
+<template>
+  <view
+    aria-role="button"
+    aria-label="{{ submitText }}"
+    bindtap="onSubmit"
+  >
+    <text>{{ submitText }}</text>
+  </view>
+</template>
+```
+
+### 注意事项
+
+1. **可点击区域**：除可见文案外，为图标按钮等补充 **`aria-label`**，避免读屏仅播报「按钮」而无含义。
+2. **与样式隐藏区分**：视觉上用 `wx:show` / 样式隐藏时，仍注意焦点与读屏顺序是否应与视觉一致；若需定义 RN 专有行为，放在 **仅 RN 的条件编译** 中处理，而不是在跨端模板中直接写 RN 无障碍属性名。
+3. **多端一致**：小程序与 RN 读屏实现不同，上线前应在 **iOS VoiceOver** 与 **Android TalkBack** 上各测一遍关键路径。
+
 ## 基础组件
 
 目前 Mpx 输出 React Native 支持的基础组件如下：
@@ -178,428 +428,437 @@ Mpx 也支持使用 `{{}}` 插值进行动态事件绑定。
 
 通用属性除了前述的[模板指令](#模板指令)和[通用事件](#通用事件)绑定外，还包括以下属性：
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| id		  | string  |         | 组件唯一标识 |
-| class	  | string  |         | 组件样式类名 |
-| style		  | string  |         | 组件内联样式 |
-| enable-offset		  | boolean  |     `false`    | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息|
-| enable-var	  | boolean  |     `true`    | 默认支持使用 css variable，若想关闭该功能可设置为 false |
-| parent-font-size		  | number |         | 父组件字体大小，主要用于百分比计算的场景，如 font-size: 100%|
-| parent-width		  | number  |         | 父组件宽度，主要用于百分比计算的场景，如 width: calc(100% - 20px)，需要在外部传递父组件的宽度|
-| parent-height		  | number  |         | 父组件高度，主要用于百分比计算的场景，如 height: calc(100% - 20px),需要在外部传递父组件的高度|
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| id | string |  | 组件唯一标识 |
+| class | string |  | 组件样式类名 |
+| style | string |  | 组件内联样式 |
+| enable-offset | boolean | `false` | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息 |
+| enable-var | boolean | `true` | 默认支持使用 css variable，若想关闭该功能可设置为 false |
+| parent-font-size | number |  | 父组件字体大小，主要用于百分比计算的场景，如 font-size: 100% |
+| parent-width | number |  | 父组件宽度，主要用于百分比计算的场景，如 width: calc(100% - 20px)，需要在外部传递父组件的宽度 |
+| parent-height | number |  | 父组件高度，主要用于百分比计算的场景，如 height: calc(100% - 20px),需要在外部传递父组件的高度 |
 
 以上基础组件的通用属性仅在 React Native 环境中支持。在跨平台输出到小程序或 Web 时，这些属性将无法使用。
 
 由于 view、text、scroll-view、image 和 input 组件都是基于 React Native 原生组件实现的，因此这些组件默认继承原生组件支持的属性。
 
 ### view
+
 视图容器。
 
 #### 属性
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| hover-class	             | string  |         | 指定按下去的样式类。 |
-| hover-start-time   | number  |     `50`    | 按住后多久出现点击态，单位毫秒|
-| hover-stay-time	  | number  |     `400`    | 手指松开后点击态保留时间，单位毫秒	 |
-| animation | object  |   | 传递动画的实例， 可配合mpx.createAnimation方法一起使用|
-| enable-background		  | boolean  |     `false `   |  RN环境特有属性，是否要开启background-image、background-size和background-position的相关计算或渲染，请根据实际情况开启 |
-| enable-animation | boolean  | `false`  | RN环境特有属性，开启要开启动画渲染，请根据实际情况开启 |
-| enable-fast-image | boolean  | `false`  | RN环境特有属性，开启后将使用 react-native-fast-image 进行图片渲染，请根据实际情况开启 |
-| is-simple | -  | -  | RN环境特有标记，设置后将使用简单版本的 view 组件渲染，该组件不包含 css var、calc、ref 等拓展功能，但性能更优，请根据实际情况设置 |
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| hover-class | string |  | 指定按下去的样式类。 |
+| hover-start-time | number | `50` | 按住后多久出现点击态，单位毫秒 |
+| hover-stay-time | number | `400` | 手指松开后点击态保留时间，单位毫秒 |
+| animation | object |  | 传递动画的实例， 可配合 mpx.createAnimation 方法一起使用 |
+| enable-background | boolean | `false ` | RN 环境特有属性，是否要开启 background-image、background-size 和 background-position 的相关计算或渲染，请根据实际情况开启 |
+| enable-animation | boolean | `false` | RN 环境特有属性，开启要开启动画渲染，请根据实际情况开启 |
+| enable-fast-image | boolean | `false` | RN 环境特有属性，开启后将使用 react-native-fast-image 进行图片渲染，请根据实际情况开启 |
+| is-simple | - | - | RN 环境特有标记，设置后将使用简单版本的 view 组件渲染，该组件不包含 css var、calc、ref 等拓展功能，但性能更优，请根据实际情况设置 |
 
 #### 事件
-| 事件名           | 说明                |
-| ----------------| ------------------ |
-| bindtransitionend| 动画结束时触发,`event.detail = { elapsedTime, finished, current }`     |
+
+| 事件名 | 说明 |
+| --- | --- |
+| bindtransitionend | 动画结束时触发,`event.detail = { elapsedTime, finished, current }` |
 
 #### 注意事项
+
 - 如果从未使用背景图、动图或动画，请不要开启`enable-background`、`enable-animation`或`enable-fast-image`属性，会有一定的性能消耗。
 - 若开启`enable-background`需要给当前 view 组件设置一个唯一 key。
 - `background-image`、`background-size`、`background-position` 等背景图相关 css 属性，仅 view 组件支持
 - 出于性能考虑，基础组件的样式增强能力（如 `enable-var`、`enable-background`、`enable-animation`）采用按需启用策略。view 组件仅在**首次**渲染时检测样式并决定是否开启对应能力。由于 React Hooks 的一致性约束，增强能力无法在后续更新阶段再动态启用，因此当组件生命周期内**可能**使用相关能力时，需在首次渲染时**显式声明**启用，比如 <span v-pre>`enable-animation="{{ true }}"`</span>。
 
 ### text
+
 文本。
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| user-select             | boolean  | `false`       | 文本是否可选。 |
-| selectable              | boolean  | `false`       | 文本是否可选。该属性已废弃，请使用 user-select |
-| decode                  | boolean  | `false`       | 是否解码 |
-| is-simple               | -  | -  | RN环境特有标记，设置后将使用简单版本的 text 组件渲染，该组件不包含 css var、calc、ref 等拓展功能，但性能更优，请根据实际情况设置 |
-
-
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| user-select | boolean | `false` | 文本是否可选。 |
+| selectable | boolean | `false` | 文本是否可选。该属性已废弃，请使用 user-select |
+| decode | boolean | `false` | 是否解码 |
+| is-simple | - | - | RN 环境特有标记，设置后将使用简单版本的 text 组件渲染，该组件不包含 css var、calc、ref 等拓展功能，但性能更优，请根据实际情况设置 |
 
 #### 注意事项
+
 - 未包裹 text 标签的文本，会自动包裹 text 标签。
 - text 组件开启 enable-offset 后，offsetLeft、offsetWidth 获取时机仅为组件首次渲染阶段
 
 ### scroll-view
+
 可滚动视图区域。
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值     | 说明                                               |
-| ----------------------- | ------- | --------- | -------------------------------------------------- |
-| scroll-x                | boolean | `false`   | 允许横向滚动 |
-| scroll-y                | boolean | `false`   | 允许纵向滚动  |
-| upper-threshold         | number  | `50`      | 距顶部/左边多远时(单位 px),触发 scrolltoupper 事件      |
-| lower-threshold         | number  | `50`      | 距底部/右边多远时(单位 px),触发 scrolltolower 事件      |
-| scroll-top              | number  | `0`       | 设置纵向滚动条位置                                    |
-| scroll-left             | number  | `0`       | 设置横向滚动条位置                                    |
-| scroll-with-animation   | boolean | `false`   | 在设置滚动条位置时使用动画过渡                          |
-| enable-back-to-top      | boolean | `false`   | 点击状态栏的时候视图会滚动到顶部，仅 iOS环境支持                      |
-| enhanced                | boolean | `false`   | scroll-view 组件功能增强                             |
-| bounces                | boolean | `true`   | iOS 下 scroll-view 边界弹性控制 (同时开启 enhanced 属性后生效)                          |
-| refresher-enabled       | boolean | `false`   | 开启自定义下拉刷新                                    |
-| refresher-threshold     | number  | `45`      | 设置自定义下拉刷新阈值                                  |
-| scroll-into-view	        | boolean | `false` | 值应为某子元素id（id不能以数字开头）    |  
-| scroll-into-view-offset	        | number | `0` | 跳转到 scroll-into-view 目标节点时的额外偏移                       |
-| refresher-default-style | string  | `'black'` | 设置下拉刷新默认样式,支持 `black`、`white`、`none`，仅安卓支持 |
-| refresher-background    | string  | `'#fff'`  | 设置自定义下拉刷新背景颜色，仅安卓支持                         |
-| refresher-triggered     | boolean | `false`   | 设置当前下拉刷新状态,true 表示已触发               |
-| paging-enabled          | number  | `false`   | 分页滑动效果 (同时开启 enhanced 属性后生效)，当值为 true 时，滚动条会停在滚动视图的尺寸的整数倍位置  |
-| show-scrollbar          | number  | `true`   | 滚动条显隐控制 (同时开启 enhanced 属性后生效)|
-| enable-trigger-intersection-observer  |  boolean   |  `false`    | RN环境特有属性，是否开启intersection-observer |
-| simultaneous-handlers  | array\<object>  |    `[]`    | RN环境特有属性，主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 scroll-view 组件 |
-| wait-for  |  array\<object>  |  `[]`    | RN环境特有属性，主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 scroll-view 组件 |
-| scroll-event-throttle  |  number   |  `0`   | RN环境特有属性，控制 scroll 事件触发频率 |
-| enable-sticky  |  boolean   |  `false`   | RN环境特有属性，当使用 sticky 组件时，需要手动将此属性设置为 true |
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| scroll-x | boolean | `false` | 允许横向滚动 |
+| scroll-y | boolean | `false` | 允许纵向滚动 |
+| upper-threshold | number | `50` | 距顶部/左边多远时(单位 px),触发 scrolltoupper 事件 |
+| lower-threshold | number | `50` | 距底部/右边多远时(单位 px),触发 scrolltolower 事件 |
+| scroll-top | number | `0` | 设置纵向滚动条位置 |
+| scroll-left | number | `0` | 设置横向滚动条位置 |
+| scroll-with-animation | boolean | `false` | 在设置滚动条位置时使用动画过渡 |
+| enable-back-to-top | boolean | `false` | 点击状态栏的时候视图会滚动到顶部，仅 iOS 环境支持 |
+| enhanced | boolean | `false` | scroll-view 组件功能增强 |
+| bounces | boolean | `true` | iOS 下 scroll-view 边界弹性控制 (同时开启 enhanced 属性后生效) |
+| refresher-enabled | boolean | `false` | 开启自定义下拉刷新 |
+| refresher-threshold | number | `45` | 设置自定义下拉刷新阈值 |
+| scroll-into-view | boolean | `false` | 值应为某子元素 id（id 不能以数字开头） |
+| scroll-into-view-offset | number | `0` | 跳转到 scroll-into-view 目标节点时的额外偏移 |
+| refresher-default-style | string | `'black'` | 设置下拉刷新默认样式,支持 `black`、`white`、`none`，仅安卓支持 |
+| refresher-background | string | `'#fff'` | 设置自定义下拉刷新背景颜色，仅安卓支持 |
+| refresher-triggered | boolean | `false` | 设置当前下拉刷新状态,true 表示已触发 |
+| paging-enabled | number | `false` | 分页滑动效果 (同时开启 enhanced 属性后生效)，当值为 true 时，滚动条会停在滚动视图的尺寸的整数倍位置 |
+| show-scrollbar | number | `true` | 滚动条显隐控制 (同时开启 enhanced 属性后生效) |
+| enable-trigger-intersection-observer | boolean | `false` | RN 环境特有属性，是否开启 intersection-observer |
+| simultaneous-handlers | array\<object> | `[]` | RN 环境特有属性，主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 scroll-view 组件 |
+| wait-for | array\<object> | `[]` | RN 环境特有属性，主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 scroll-view 组件 |
+| scroll-event-throttle | number | `0` | RN 环境特有属性，控制 scroll 事件触发频率 |
+| enable-sticky | boolean | `false` | RN 环境特有属性，当使用 sticky 组件时，需要手动将此属性设置为 true |
 
 #### 事件
 
-| 事件名           | 说明                |
-| ----------------| ------------------ |
-| binddragstart| 滑动开始事件，同时开启 enhanced 属性后生效|
-| binddragging| 滑动事件，同时开启 enhanced 属性后生效 |
-| binddragend| 滑动结束事件，同时开启 enhanced 属性后生效 |
-| bindscrolltoupper   | 滚动到顶部/左边触发 |
-| bindscrolltolower   | 滚动到底部/右边触发 |
-| bindscroll          | 滚动时触发         |
-| bindscrollend | 滚动结束时触发         |
-| bindrefresherrefresh| 自定义下拉刷新被触发 |
+| 事件名               | 说明                                       |
+| -------------------- | ------------------------------------------ |
+| binddragstart        | 滑动开始事件，同时开启 enhanced 属性后生效 |
+| binddragging         | 滑动事件，同时开启 enhanced 属性后生效     |
+| binddragend          | 滑动结束事件，同时开启 enhanced 属性后生效 |
+| bindscrolltoupper    | 滚动到顶部/左边触发                        |
+| bindscrolltolower    | 滚动到底部/右边触发                        |
+| bindscroll           | 滚动时触发                                 |
+| bindscrollend        | 滚动结束时触发                             |
+| bindrefresherrefresh | 自定义下拉刷新被触发                       |
 
 #### 注意事项
+
 - 若使用 scroll-into-view 属性，需要 id 对应的组件节点添加 wx:ref 标记，否则无法正常滚动。另外组件节点需要是内置基础组件，自定义组件暂不支持。
 - simultaneous-handlers 为 RN 环境特有属性，具体含义可参考[react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#simultaneouswithexternalgesture)
 - wait-for 为 RN 环境特有属性，具体含义可参考[react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#requireexternalgesturetofail)
 - scroll-view 组件在滚动过程中，不会触发其自身或子组件的 touchend 事件响应，这是 RN 底层实现导致的问题，手势系统识别当前是 scroll-view 的滚动，就会取消掉 touchend 事件的响应。
 - 安卓上如果触发了 scroll-view 组件默认的下拉刷新，binddragend 可能不触发，只会触发 binddragstart
 
-
 ### swiper
+
 滑块视图容器。
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值              | 说明                                 |
-| ----------------------- | ------- | ------------------  | ------------------------------------|
-| indicator-dots          | boolean | `false`             | 是否显示面板指示点                     |
-| indicator-color         | color   | `rgba(0, 0, 0, .3)` | 指示点颜色                            |
-| indicator-active-color  | color   | `#000000`           | 当前选中的指示点颜色                   |
-| indicator-width         | number  |                     | 指示点宽度             |
-| indicator-height        | number  |                     | 指示点高度             |
-| indicator-spacing       | number  |                     | 指示点间距             |
-| indicator-radius        | number  |                     | 指示点圆角             |
-| indicator-margin        | number  |                     | 指示点外边距           |
-| autoplay                | boolean | `false`             | 是否自动切换                          |
-| current                 | number  | `0`                 | 当前所在滑块的 index                  |
-| interval                | number  | `5000`              | 自动切换时间间隔                       |
-| duration                | number  | `500`               | 滑动动画时长                          |
-| circular                | boolean | `false`             | 是否采用衔接滑动                       |
-| vertical                | boolean | `false`             | 滑动方向是否为纵向                      |
-| previous-margin         | string  | `0`                 | 前边距，可用于露出前一项的一小部分，接受px |
-| next-margin             | string  | `0`                 | 后边距，可用于露出后一项的一小部分，接受px |
-| scale                   | boolean  | `false`            | 滑动时是否开启前后元素缩小,默认是缩放0.7倍, 暂不支持自定义 |
-| easing-function         | string  | `linear`      | 支持 linear、easeInCubic、easeOutCubic、easeInOutCubic|
-| simultaneous-handlers              | array\<object>|   `[]`          | RN环境特有属性，主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 swiper 组件|
-| wait-for              | array\<object>|   `[]`          | RN环境特有属性，主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 swiper 组件|
-| disableGesture              | boolean|   `false`       |  RN 环境特有属性，禁用 swiper 滑动手势。若开启用户无法通过手势滑动 swiper，只能通过开启 autoPlay 进行自动轮播|
-
-
-
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| indicator-dots | boolean | `false` | 是否显示面板指示点 |
+| indicator-color | color | `rgba(0, 0, 0, .3)` | 指示点颜色 |
+| indicator-active-color | color | `#000000` | 当前选中的指示点颜色 |
+| indicator-width | number |  | 指示点宽度 |
+| indicator-height | number |  | 指示点高度 |
+| indicator-spacing | number |  | 指示点间距 |
+| indicator-radius | number |  | 指示点圆角 |
+| indicator-margin | number |  | 指示点外边距 |
+| autoplay | boolean | `false` | 是否自动切换 |
+| current | number | `0` | 当前所在滑块的 index |
+| interval | number | `5000` | 自动切换时间间隔 |
+| duration | number | `500` | 滑动动画时长 |
+| circular | boolean | `false` | 是否采用衔接滑动 |
+| vertical | boolean | `false` | 滑动方向是否为纵向 |
+| previous-margin | string | `0` | 前边距，可用于露出前一项的一小部分，接受 px |
+| next-margin | string | `0` | 后边距，可用于露出后一项的一小部分，接受 px |
+| scale | boolean | `false` | 滑动时是否开启前后元素缩小,默认是缩放 0.7 倍, 暂不支持自定义 |
+| easing-function | string | `linear` | 支持 linear、easeInCubic、easeOutCubic、easeInOutCubic |
+| simultaneous-handlers | array\<object> | `[]` | RN 环境特有属性，主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 swiper 组件 |
+| wait-for | array\<object> | `[]` | RN 环境特有属性，主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 swiper 组件 |
+| disableGesture | boolean | `false` | RN 环境特有属性，禁用 swiper 滑动手势。若开启用户无法通过手势滑动 swiper，只能通过开启 autoPlay 进行自动轮播 |
 
 #### 事件
 
-| 事件名           | 说明                |
-| ----------------| ------------------ |
-| bindchange| current 改变时会触发 change 事件，`event.detail = {current, source}`|
+| 事件名 | 说明 |
+| --- | --- |
+| bindchange | current 改变时会触发 change 事件，`event.detail = {current, source}` |
 
 ### swiper-item
-仅可放置在swiper组件中，宽高自动设置为100%。
+
+仅可放置在 swiper 组件中，宽高自动设置为 100%。
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值              | 说明                                 |
-| ----------------------- | ------- | ------------------  | ------------------------------------|
-| item-id                 | string  |             | 该 swiper-item 的标识符                  |
+| 属性名  | 类型   | 默认值 | 说明                    |
+| ------- | ------ | ------ | ----------------------- |
+| item-id | string |        | 该 swiper-item 的标识符 |
 
 ### movable-area
-movable-view的可移动区域。
+
+movable-view 的可移动区域。
 
 ### movable-view
-可移动的视图容器，在页面中可以拖拽滑动。movable-view 必须在 movable-area 组件中，并且必须是直接子节点，否则不能移动。
 
+可移动的视图容器，在页面中可以拖拽滑动。movable-view 必须在 movable-area 组件中，并且必须是直接子节点，否则不能移动。
 
 #### 属性
 
-| 属性名 | 类型             | 默认值 | 说明                                                                                                  |
-| ------ | ---------------- | ------ | ----------------------------------------------------------------------------------------------------- |
-| direction   | string           |   `none`     | 目前支持 all、vertical、horizontal、none  |
-| inertia   | boolean          |   `false`     | movable-view是否带有惯性  |
-| out-of-bounds   | boolean          |   `false`     | 超过可移动区域后，movable-view是否还可以移动  |
-| x   | number |      | 定义x轴方向的偏移  |
-| y  | number  |        | 定义y轴方向的偏移 |
-| disabled  | boolean  |    `false`   | 是否禁用 |
-| animation  | boolean  |    `true`   | 是否使用动画	 |
-| damping   | number   |    `20`      | 阻尼系数，用于控制x或y改变时的动画和过界回弹的动画，值越大移动越快 |
-| friction  | number   |    `2`       | 摩擦系数，用于控制惯性滑动的动画，值越大摩擦力越大，滑动越快停止 |
-| simultaneous-handlers  | array\<object>  |   `[]`   | RN 环境特有属性，主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 movable-view 组件 |
-| wait-for  |  array\<object>  |  `[]`    |  RN 环境特有属性，主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 movable-view 组件 |
-| disable-event-passthrough | boolean  |  `false`   | RN 环境特有属性，有时候我们希望movable-view 在水平方向滑动，并且竖直方向的手势也希望被 movable-view 组件消费掉，不被其他组件响应，可以将这个属性设置为true） |
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| direction | string | `none` | 目前支持 all、vertical、horizontal、none |
+| inertia | boolean | `false` | movable-view 是否带有惯性 |
+| out-of-bounds | boolean | `false` | 超过可移动区域后，movable-view 是否还可以移动 |
+| x | number |  | 定义 x 轴方向的偏移 |
+| y | number |  | 定义 y 轴方向的偏移 |
+| disabled | boolean | `false` | 是否禁用 |
+| animation | boolean | `true` | 是否使用动画 |
+| damping | number | `20` | 阻尼系数，用于控制 x 或 y 改变时的动画和过界回弹的动画，值越大移动越快 |
+| friction | number | `2` | 摩擦系数，用于控制惯性滑动的动画，值越大摩擦力越大，滑动越快停止 |
+| simultaneous-handlers | array\<object> | `[]` | RN 环境特有属性，主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 movable-view 组件 |
+| wait-for | array\<object> | `[]` | RN 环境特有属性，主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 movable-view 组件 |
+| disable-event-passthrough | boolean | `false` | RN 环境特有属性，有时候我们希望 movable-view 在水平方向滑动，并且竖直方向的手势也希望被 movable-view 组件消费掉，不被其他组件响应，可以将这个属性设置为 true） |
 
 #### 事件
 
-| 事件名               | 说明                                       |
-| -------------------- | ------------------------------------------ |
-| bindchange        | 拖动过程中触发的事件，`event.detail = {x, y, source}` |
-| htouchmove          | 初次手指触摸后移动为横向的移动时触发 |
-| vtouchmove    | 初次手指触摸后移动为纵向的移动时触发                      |
-
+| 事件名     | 说明                                                  |
+| ---------- | ----------------------------------------------------- |
+| bindchange | 拖动过程中触发的事件，`event.detail = {x, y, source}` |
+| htouchmove | 初次手指触摸后移动为横向的移动时触发                  |
+| vtouchmove | 初次手指触摸后移动为纵向的移动时触发                  |
 
 #### 注意事项
+
 - simultaneous-handlers 为 RN 环境特有属性，具体含义可参考[react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#simultaneouswithexternalgesture)
 - wait-for 为 RN 环境特有属性，具体含义可参考[react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#requireexternalgesturetofail)
 - RN 环境 movable 相关组件暂不支持缩放能力
 
 ### image
+
 图片组件
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| src                     | string  | `false`       | 图片资源地址及 base64 格式数据 |
-| mode                    | string  | `scaleToFill` | 图片裁剪、缩放的模式，可选值为 `scaleToFill`、`aspectFit`、`aspectFill`、`widthFix`、`heightFix`、`top`、`bottom`、`center`、`left`、`right`、`top left`、`top right`、`bottom left`、`bottom right`             |
-| enable-fast-image          | boolean  | `false`   | RN环境特有属性，开启后将使用 react-native-fast-image 进行图片渲染，请根据实际情况开启 |
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| src | string | `false` | 图片资源地址及 base64 格式数据 |
+| mode | string | `scaleToFill` | 图片裁剪、缩放的模式，可选值为 `scaleToFill`、`aspectFit`、`aspectFill`、`widthFix`、`heightFix`、`top`、`bottom`、`center`、`left`、`right`、`top left`、`top right`、`bottom left`、`bottom right` |
+| enable-fast-image | boolean | `false` | RN 环境特有属性，开启后将使用 react-native-fast-image 进行图片渲染，请根据实际情况开启 |
 
 #### 事件
 
-| 事件名           | 说明                                                 |
-| ----------------| --------------------------------------------------- |
-| binderror       | 当错误发生时触发，`event.detail = { errMsg }`            |
-| bindload        | 当图片载入完毕时触发，`event.detail = { height, width }`  |
+| 事件名    | 说明                                                     |
+| --------- | -------------------------------------------------------- |
+| binderror | 当错误发生时触发，`event.detail = { errMsg }`            |
+| bindload  | 当图片载入完毕时触发，`event.detail = { height, width }` |
 
 #### 注意事项
+
 - image 组件默认宽度 320px、高度 240px
 - image 组件进行缩放时，计算出来的宽高可能带有小数，在不同 webview 内核下渲染可能会被抹去小数部分
 
 ### icon
+
 图标组件
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| type      | string  |               | icon 的类型，有效值：success、success_no_circle、info、warn、waiting、cancel、download、search、clear |
-| size      | string\|number  |     `23`    | icon 的大小 |
-| color		  | string  |         | icon 的颜色，同 css 的 color |
-
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| type | string |  | icon 的类型，有效值：success、success_no_circle、info、warn、waiting、cancel、download、search、clear |
+| size | string\|number | `23` | icon 的大小 |
+| color | string |  | icon 的颜色，同 css 的 color |
 
 ### button
+
 按钮。
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                      |
-| ----------------------- | ------- | ------------- | --------------------------------------------------------- |
-| size                    | string  | `default`     | 按钮的大小，`default`：默认大小，`mini`：小尺寸                                                  |
-| type                    | string  | `default`     | 按钮的样式类型，`primary`：绿色，`default`：白色，`warn`：红色                                               |
-| plain                   | boolean | `false`       | 按钮是否镂空，背景色透明                                       |
-| disabled                | boolean | `false`       | 是否禁用                                                    |
-| loading                 | boolean | `false`       | 名称前是否带 loading 图标                                     |
-| form-type               | string  |               | 用于 form 组件，点击分别会触发 form 组件的 submit/reset 事件，有效值为 `submit`、`reset` |
-| open-type               | string  |               | 微信开放能力，当前仅支持 `share` 和 `getUserInfo`                              |
-| hover-class             | string  |               | 指定按钮按下去的样式类。当 hover-class="none" 时，没有点击态效果  |
-| hover-start-time        | number  |  `20`         | 按住后多久出现点击态，单位毫秒                                  |
-| hover-stay-time         | number  |  `70`         | 手指松开后点击态保留时间，单位毫秒                               |
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| size | string | `default` | 按钮的大小，`default`：默认大小，`mini`：小尺寸 |
+| type | string | `default` | 按钮的样式类型，`primary`：绿色，`default`：白色，`warn`：红色 |
+| plain | boolean | `false` | 按钮是否镂空，背景色透明 |
+| disabled | boolean | `false` | 是否禁用 |
+| loading | boolean | `false` | 名称前是否带 loading 图标 |
+| form-type | string |  | 用于 form 组件，点击分别会触发 form 组件的 submit/reset 事件，有效值为 `submit`、`reset` |
+| open-type | string |  | 微信开放能力，当前仅支持 `share` 和 `getUserInfo` |
+| hover-class | string |  | 指定按钮按下去的样式类。当 hover-class="none" 时，没有点击态效果 |
+| hover-start-time | number | `20` | 按住后多久出现点击态，单位毫秒 |
+| hover-stay-time | number | `70` | 手指松开后点击态保留时间，单位毫秒 |
 
 #### 注意事项
+
 - openType 需要在 `mpx.config.rnConfig` 中注册对应能力如 `onShareAppMessage`、`onUserInfo` 来配合使用。
-   
+
 ### label
-用来改进表单组件的可用性
 
+用来改进表单组件的可用性
 
 #### 注意事项
+
 - 当前不支持使用 for 属性找到对应 id，仅支持将控件放在该标签内，目前可以绑定的控件有：checkbox、radio、switch。
 
 ### checkbox
-多选项目
 
+多选项目
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| value	    | string   |              | checkbox 标识，选中时触发 checkbox-group 的 change 事件，并携带 checkbox 的 value |
-| disabled  | boolean  |     `false`    | 是否禁用 |
-| checked	  | boolean  |     `false`    | 当前是否选中，可用来设置默认选中 |
-| color		  | string   |     `#09BB07` | checkbox的颜色，同css的color |
-
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| value | string |  | checkbox 标识，选中时触发 checkbox-group 的 change 事件，并携带 checkbox 的 value |
+| disabled | boolean | `false` | 是否禁用 |
+| checked | boolean | `false` | 当前是否选中，可用来设置默认选中 |
+| color | string | `#09BB07` | checkbox 的颜色，同 css 的 color |
 
 ### checkbox-group
-多项选择器，内部由多个checkbox组成。
 
+多项选择器，内部由多个 checkbox 组成。
 
 #### 事件
 
-| 事件名           | 说明                |
-| ----------------| ------------------ |
-| bindchange      | checkbox-group 中选中项发生改变时触发 change 事件，`detail = { value: [ 选中的 checkbox 的 value 的数组 ] } `|
-
+| 事件名 | 说明 |
+| --- | --- |
+| bindchange | checkbox-group 中选中项发生改变时触发 change 事件，`detail = { value: [ 选中的 checkbox 的 value 的数组 ] } ` |
 
 ### radio
-单选项目
 
+单选项目
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| value	    | string  |               | radio 标识，当该 radio 选中时，radio-group 的 change 事件会携带 radio 的 value |
-| disabled  | boolean  |     false    | 是否禁用 |
-| checked	  | boolean  |     false    | 当前是否选中，可用来设置默认选中 |
-| color		  | string   |     #09BB07  | checkbox 的颜色，同 css 的 color |
-
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| value | string |  | radio 标识，当该 radio 选中时，radio-group 的 change 事件会携带 radio 的 value |
+| disabled | boolean | false | 是否禁用 |
+| checked | boolean | false | 当前是否选中，可用来设置默认选中 |
+| color | string | #09BB07 | checkbox 的颜色，同 css 的 color |
 
 ### radio-group
-单项选择器，内部由多个 radio 组成
 
+单项选择器，内部由多个 radio 组成
 
 #### 事件
 
-| 事件名           | 说明                |
-| ----------------| ------------------ |
-| bindchange      | radio-group 中选中项发生改变时触发 change 事件，`detail = { value: [ 选中的 radio 的 value 的数组 ] }` |
-
+| 事件名 | 说明 |
+| --- | --- |
+| bindchange | radio-group 中选中项发生改变时触发 change 事件，`detail = { value: [ 选中的 radio 的 value 的数组 ] }` |
 
 ### form
+
 表单。
 
 当点击 form 表单中 form-type 为 submit 的 button 组件时，会将表单组件中的 value 值进行提交，需要在表单组件中加上 name 来作为 key。
 
 #### 事件
 
-| 事件名     | 说明                                                |
-| ---------- | --------------------------------------------------- |
+| 事件名 | 说明 |
+| --- | --- |
 | bindsubmit | 携带 form 中的数据触发 submit 事件，`event.detail = {value : {'name': 'value'} }` |
-| bindreset  | 表单重置时会触发 reset 事件 |
-
+| bindreset | 表单重置时会触发 reset 事件 |
 
 ### input
+
 输入框。
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| value                   | string  |               | 输入框的初始内容                                              |
-| type                    | string  | `text`        | input 的类型，可选值为 `text`、`number`、`idcard`、`digit`，不支持 `safe-password`、`nickname`              |
-| password                | boolean | `false`       | 是否是密码类型                                               |
-| placeholder             | string  |               | 输入框为空时占位符                                            |
-| placeholder-class       | string  |               | 指定 placeholder 的样式类，仅支持 color 属性                   |
-| placeholder-style       | string  |               | 指定 placeholder 的样式，仅支持 color 属性                    |
-| disabled                | boolean | `false`       | 是否禁用                                                    |
-| maxlength               | number  | `140`         | 最大输入长度，设置为 -1 的时候不限制最大长度                     |
-| cursor-spacing          | number  | `0`           | 指定光标与键盘的距离，单位 px。取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离 |
-| auto-focus              | boolean | `false`       | (即将废弃，请直接使用 focus )自动聚焦，拉起键盘                  |
-| focus                   | boolean | `false`       | 获取焦点                                                    |
-| confirm-type            | string  | `done`        | 设置键盘右下角按钮的文字，仅在 type='text' 时生效，可选值为 `send`、`search`、`next`、`go`、`done`、`return`              |
-| confirm-hold            | boolean | `false`       | 点击键盘右下角按钮时是否保持键盘不收起                           |
-| hold-keyboard           | boolean | `false`       | 输入框聚焦时，点击页面其他地方是否收起键盘 <badge type="tip" text="2.10.18+" />  |
-| cursor                  | number  |               | 指定 focus 时的光标位置                                      |
-| cursor-color            | string  |               | 光标颜色                                                    |
-| selection-start         | number  | `-1`          | 光标起始位置，自动聚集时有效，需与 selection-end 搭配使用         |
-| selection-end           | number  | `-1`          | 光标结束位置，自动聚集时有效，需与 selection-start 搭配使用       |
-| adjust-position         | boolean | `true`        | 键盘弹起时，是否自动上推页面                                  |
-| keyboard-type           | string  |               | RN环境特有属性，设置键盘类型                                  |
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| value | string |  | 输入框的初始内容 |
+| type | string | `text` | input 的类型，可选值为 `text`、`number`、`idcard`、`digit`，不支持 `safe-password`、`nickname` |
+| password | boolean | `false` | 是否是密码类型 |
+| placeholder | string |  | 输入框为空时占位符 |
+| placeholder-class | string |  | 指定 placeholder 的样式类，仅支持 color 属性 |
+| placeholder-style | string |  | 指定 placeholder 的样式，仅支持 color 属性 |
+| disabled | boolean | `false` | 是否禁用 |
+| maxlength | number | `140` | 最大输入长度，设置为 -1 的时候不限制最大长度 |
+| cursor-spacing | number | `0` | 指定光标与键盘的距离，单位 px。取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离 |
+| auto-focus | boolean | `false` | (即将废弃，请直接使用 focus )自动聚焦，拉起键盘 |
+| focus | boolean | `false` | 获取焦点 |
+| confirm-type | string | `done` | 设置键盘右下角按钮的文字，仅在 type='text' 时生效，可选值为 `send`、`search`、`next`、`go`、`done`、`return` |
+| confirm-hold | boolean | `false` | 点击键盘右下角按钮时是否保持键盘不收起 |
+| hold-keyboard | boolean | `false` | 输入框聚焦时，点击页面其他地方是否收起键盘 <badge type="tip" text="2.10.18+" /> |
+| cursor | number |  | 指定 focus 时的光标位置 |
+| cursor-color | string |  | 光标颜色 |
+| selection-start | number | `-1` | 光标起始位置，自动聚集时有效，需与 selection-end 搭配使用 |
+| selection-end | number | `-1` | 光标结束位置，自动聚集时有效，需与 selection-start 搭配使用 |
+| adjust-position | boolean | `true` | 键盘弹起时，是否自动上推页面 |
+| keyboard-type | string |  | RN 环境特有属性，设置键盘类型 |
 
 #### 事件
 
-| 事件名                | 说明                                                                               |
-| ---------------------| ---------------------------------------------------------------------------------- |
-| bindinput            | 键盘输入时触发，`event.detail = { value, cursor }`，不支持 `keyCode`                     |
-| bindfocus            | 输入框聚焦时触发，`event.detail = { value }`，不支持 `height`                            |
-| bindblur             | 输入框失去焦点时触发，`event.detail = { value }`，不支持 `encryptedValue`、`encryptError` |
-| bindconfirm          | 点击完成按钮时触发，`event.detail = { value }`                                         |
-| bind:selectionchange | 选区改变事件, `event.detail = { selectionStart, selectionEnd }`                      |
-
+| 事件名 | 说明 |
+| --- | --- |
+| bindinput | 键盘输入时触发，`event.detail = { value, cursor }`，不支持 `keyCode` |
+| bindfocus | 输入框聚焦时触发，`event.detail = { value }`，不支持 `height` |
+| bindblur | 输入框失去焦点时触发，`event.detail = { value }`，不支持 `encryptedValue`、`encryptError` |
+| bindconfirm | 点击完成按钮时触发，`event.detail = { value }` |
+| bind:selectionchange | 选区改变事件, `event.detail = { selectionStart, selectionEnd }` |
 
 ### textarea
+
 多行输入框。
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| value                   | string  |               | 输入框内容                                                   |
-| placeholder             | string  |               | 输入框为空时占位符                                            |
-| placeholder-class       | string  |               | 指定 placeholder 的样式类，仅支持 color 属性                   |
-| placeholder-style       | string  |               | 指定 placeholder 的样式，仅支持 color 属性                    |
-| disabled                | boolean | `false`       | 是否禁用                                                    |
-| maxlength               | number  | `140`         | 最大输入长度，设置为 -1 的时候不限制最大长度                     |
-| cursor-spacing          | number  | `0`           | 指定光标与键盘的距离，单位 px。取 textarea 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离 |
-| auto-focus              | boolean | `false`       | (即将废弃，请直接使用 focus )自动聚焦，拉起键盘                  |
-| focus                   | boolean | `false`       | 获取焦点                                                    |
-| auto-height             | boolean | `false`       | 是否自动增高，设置 auto-height 时，style.height不生效          |
-| confirm-type            | string  | `return`      | 设置键盘右下角按钮的文字，可选值为 `send`、`search`、`next`、`go`、`done`、`return`                       |
-| confirm-hold            | boolean | `false`       | 点击键盘右下角按钮时是否保持键盘不收起                           |
-| hold-keyboard           | boolean | `false`       | 输入框聚焦时，点击页面其他地方是否收起键盘 <badge type="tip" text="2.10.18+" /> |
-| cursor                  | number  |               | 指定 focus 时的光标位置                                      |
-| cursor-color            | string  |               | 光标颜色                                                    |
-| selection-start         | number  | `-1`          | 光标起始位置，自动聚集时有效，需与 selection-end 搭配使用         |
-| selection-end           | number  | `-1`          | 光标结束位置，自动聚集时有效，需与 selection-start 搭配使用       |
-| adjust-position         | boolean | `true`        | 键盘弹起时，是否自动上推页面                                  |
-| keyboard-type           | string  |               | RN环境特有属性，设置键盘类型                                  |
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| value | string |  | 输入框内容 |
+| placeholder | string |  | 输入框为空时占位符 |
+| placeholder-class | string |  | 指定 placeholder 的样式类，仅支持 color 属性 |
+| placeholder-style | string |  | 指定 placeholder 的样式，仅支持 color 属性 |
+| disabled | boolean | `false` | 是否禁用 |
+| maxlength | number | `140` | 最大输入长度，设置为 -1 的时候不限制最大长度 |
+| cursor-spacing | number | `0` | 指定光标与键盘的距离，单位 px。取 textarea 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离 |
+| auto-focus | boolean | `false` | (即将废弃，请直接使用 focus )自动聚焦，拉起键盘 |
+| focus | boolean | `false` | 获取焦点 |
+| auto-height | boolean | `false` | 是否自动增高，设置 auto-height 时，style.height 不生效 |
+| confirm-type | string | `return` | 设置键盘右下角按钮的文字，可选值为 `send`、`search`、`next`、`go`、`done`、`return` |
+| confirm-hold | boolean | `false` | 点击键盘右下角按钮时是否保持键盘不收起 |
+| hold-keyboard | boolean | `false` | 输入框聚焦时，点击页面其他地方是否收起键盘 <badge type="tip" text="2.10.18+" /> |
+| cursor | number |  | 指定 focus 时的光标位置 |
+| cursor-color | string |  | 光标颜色 |
+| selection-start | number | `-1` | 光标起始位置，自动聚集时有效，需与 selection-end 搭配使用 |
+| selection-end | number | `-1` | 光标结束位置，自动聚集时有效，需与 selection-start 搭配使用 |
+| adjust-position | boolean | `true` | 键盘弹起时，是否自动上推页面 |
+| keyboard-type | string |  | RN 环境特有属性，设置键盘类型 |
 
 #### 事件
 
-| 事件名                | 说明                                                                               |
-| ---------------------| ---------------------------------------------------------------------------------- |
-| bindinput            | 键盘输入时触发，`event.detail = { value, cursor }`，不支持 `keyCode`                     |
-| bindfocus            | 输入框聚焦时触发，`event.detail = { value }`，不支持 `height`                            |
-| bindblur             | 输入框失去焦点时触发，`event.detail = { value }`，不支持 `encryptedValue`、`encryptError` |
-| bindconfirm          | 点击完成按钮时触发，`event.detail = { value }`                                          |
-| bindlinechange       | 输入框行数变化时调用，`event.detail = { height: 0, lineCount: 0 }`，不支持 `heightRpx`    |
-| bind:selectionchange | 选区改变事件, `event.detail = {selectionStart, selectionEnd}`                                         |
+| 事件名 | 说明 |
+| --- | --- |
+| bindinput | 键盘输入时触发，`event.detail = { value, cursor }`，不支持 `keyCode` |
+| bindfocus | 输入框聚焦时触发，`event.detail = { value }`，不支持 `height` |
+| bindblur | 输入框失去焦点时触发，`event.detail = { value }`，不支持 `encryptedValue`、`encryptError` |
+| bindconfirm | 点击完成按钮时触发，`event.detail = { value }` |
+| bindlinechange | 输入框行数变化时调用，`event.detail = { height: 0, lineCount: 0 }`，不支持 `heightRpx` |
+| bind:selectionchange | 选区改变事件, `event.detail = {selectionStart, selectionEnd}` |
 
 ### progress
+
 进度条。
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| percent                 | number  | `0`           | 百分比进度，范围0-100                                         |
-| stroke-width            | number\|string | `6`   | 进度条线的宽度，单位px                                        |
-| color                   | string  |               | 进度条颜色（已废弃，请使用 activeColor）                        |
-| activeColor             | string  | `#09BB07`     | 已选择的进度条的颜色                                           |
-| backgroundColor         | string  | `#EBEBEB`     | 未选择的进度条的颜色                                           |
-| active                  | boolean | `false`       | 进度条从左往右的动画                                           |
-| active-mode             | string  | `backwards`   | 动画播放模式，`backwards`: 从头开始播放；`forwards`: 从上次结束点接着播放 |
-| duration                | number  | `30`          | 进度增加1%所需毫秒数                                          |
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| percent | number | `0` | 百分比进度，范围 0-100 |
+| stroke-width | number\|string | `6` | 进度条线的宽度，单位 px |
+| color | string |  | 进度条颜色（已废弃，请使用 activeColor） |
+| activeColor | string | `#09BB07` | 已选择的进度条的颜色 |
+| backgroundColor | string | `#EBEBEB` | 未选择的进度条的颜色 |
+| active | boolean | `false` | 进度条从左往右的动画 |
+| active-mode | string | `backwards` | 动画播放模式，`backwards`: 从头开始播放；`forwards`: 从上次结束点接着播放 |
+| duration | number | `30` | 进度增加 1%所需毫秒数 |
 
 #### 事件
 
-| 事件名           | 说明                                                 |
-| ----------------| --------------------------------------------------- |
-| bindactiveend   | 动画完成时触发，`event.detail = { percent }`            |
+| 事件名        | 说明                                         |
+| ------------- | -------------------------------------------- |
+| bindactiveend | 动画完成时触发，`event.detail = { percent }` |
 
 #### 注意事项
+
 - 不支持 `show-info` 属性，即不支持在进度条右侧显示百分比
 - 不支持 `border-radius` 属性自定义圆角大小
 - 不支持 `font-size` 属性设置右侧百分比字体大小
@@ -610,28 +869,28 @@ movable-view的可移动区域。
 
 #### 属性
 
-| 属性名                   | 类型              | 默认值              | 说明                                 |
-| ----------------------- | ------------------| ------------------ | ------------------------------------|
-| value                   | array\<number\>   | `[]`           | 数组中的数字依次表示 picker-view 内的 [picker-view-column](#picker-view-column) 选择的第几项（下标从 0 开始），数字大于 [picker-view-column](#picker-view-column) 可选项长度时，选择最后一项。|
-| indicator-style         | string          |                | 设置选择器中间选中框的样式 |
-| indicator-class         | string          |                | 设置选择器中间选中框的类名 |
-| mask-style              | string          |                | 设置蒙层的样式           |
-| mask-class              | string          |                | 设置蒙层的类名           |
-| enable-wheel-animation  | boolean         |   `true`       | RN环境特有属性，是否开启滚轮滚动动画效果 <badge type="tip" text="2.10.17+" />  |
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| value | array\<number\> | `[]` | 数组中的数字依次表示 picker-view 内的 [picker-view-column](#picker-view-column) 选择的第几项（下标从 0 开始），数字大于 [picker-view-column](#picker-view-column) 可选项长度时，选择最后一项。 |
+| indicator-style | string |  | 设置选择器中间选中框的样式 |
+| indicator-class | string |  | 设置选择器中间选中框的类名 |
+| mask-style | string |  | 设置蒙层的样式 |
+| mask-class | string |  | 设置蒙层的类名 |
+| enable-wheel-animation | boolean | `true` | RN 环境特有属性，是否开启滚轮滚动动画效果 <badge type="tip" text="2.10.17+" /> |
 
 #### 事件
 
-| 事件名           | 说明                |
-| ----------------| ------------------ |
-| bindchange      | 滚动选择时触发 change 事件，`event.detail = {value}`，其中 `value` 为数组，表示 picker-view 内的 [picker-view-column](#picker-view-column) 当前选择的是第几项（下标从 0 开始） |
+| 事件名 | 说明 |
+| --- | --- |
+| bindchange | 滚动选择时触发 change 事件，`event.detail = {value}`，其中 `value` 为数组，表示 picker-view 内的 [picker-view-column](#picker-view-column) 当前选择的是第几项（下标从 0 开始） |
 
 触感反馈回调方法
 
 通过在全局注册 `mpx.config.rnConfig.onPickerVibrate` 方法，在每次滚动选择时会调用该方法。
 
-| 注册触感方法名           | 类型          | 说明                |
-| ----------------------| --------------| ------------------- |
-| onPickerVibrate         | Function      | 注册自定义触感反馈方法。调用时机：在每次滚动选择时会调用该方法。可以在方法内自定义实现类似 iOS 端原生表盘的振动触感。    |
+| 注册触感方法名 | 类型 | 说明 |
+| --- | --- | --- |
+| onPickerVibrate | Function | 注册自定义触感反馈方法。调用时机：在每次滚动选择时会调用该方法。可以在方法内自定义实现类似 iOS 端原生表盘的振动触感。 |
 
 ### picker-view-column
 
@@ -643,263 +902,269 @@ movable-view的可移动区域。
 
 #### 属性
 
-| 属性名                  | 类型         | 默认值             | 说明                          |
-| -----------------------| ------------| ------------------ | -----------------------------|
-| mode                   | string      | `selector`         | 选择器类型，目前支持 `selector`、 `multiSelector`、 `time`、 `date`、  `region`   |
-| disabled               | boolean     | `false`            | 是否禁用                       |
-| header-text            | string      |                    | 头部标题                       |
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| mode | string | `selector` | 选择器类型，目前支持 `selector`、 `multiSelector`、 `time`、 `date`、 `region` |
+| disabled | boolean | `false` | 是否禁用 |
+| header-text | string |  | 头部标题 |
 
 #### 事件
 
-| 事件名           | 说明                                                 |
-| ----------------| ----------------------------------------------------|
-| bindcancel      | 取消选择时触发                                         |
-| bindchange      | value 改变时触发 change 事件，`event.detail = {value}` |
+| 事件名     | 说明                                                   |
+| ---------- | ------------------------------------------------------ |
+| bindcancel | 取消选择时触发                                         |
+| bindchange | value 改变时触发 change 事件，`event.detail = {value}` |
 
 #### 普通选择器：mode = selector
 
 ##### 属性
 
-| 属性名                  | 类型                     | 默认值         | 说明                           |
-| -----------------------| ------------------------| ------------- | -----------------------------|
-| range                  | array[object]/array     | `[]`          | mode 为 selector 或 multiSelector 时，range 有效 |
-| range-key              | string                  | `false`       | 当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容 |
-| value                  | number                  | 0             | 表示选择了 range 中的第几个（下标从 0 开始）|
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| range | array[object]/array | `[]` | mode 为 selector 或 multiSelector 时，range 有效 |
+| range-key | string | `false` | 当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容 |
+| value | number | 0 | 表示选择了 range 中的第几个（下标从 0 开始） |
 
 #### 多列选择器：mode = multiSelector
+
 ##### 属性与事件
 
-| 属性名                  | 类型                     | 默认值         | 说明                           |
-| -----------------------| ------------------------| ------------- | -----------------------------|
-| range                  | array[object]/array     | `[]`          | mode 为 selector 或 multiSelector 时，range 有效 |
-| range-key              | string                  | `false`       | 当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容 |
-| value                  | array                   | `[]`          | 表示选择了 range 中的第几个（下标从 0 开始）|
-| bindcolumnchange       |        function                 |               | 列改变时触发|
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| range | array[object]/array | `[]` | mode 为 selector 或 multiSelector 时，range 有效 |
+| range-key | string | `false` | 当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容 |
+| value | array | `[]` | 表示选择了 range 中的第几个（下标从 0 开始） |
+| bindcolumnchange | function |  | 列改变时触发 |
 
 #### 多列选择器：时间选择器：mode = time
+
 ##### 属性
 
-| 属性名                  | 类型                     | 默认值         | 说明                           |
-| -----------------------| ------------------------| ------------- | -----------------------------|
-| value                  | string                  | `[]`          | 表示选中的时间，格式为"hh:mm" |
-| start                  | string                  | `false`       | 表示有效时间范围的开始，字符串格式为"hh:mm" |
-| end                    | string                   | `[]`         | 表示有效时间范围的结束，字符串格式为"hh:mm"|
+| 属性名 | 类型   | 默认值  | 说明                                        |
+| ------ | ------ | ------- | ------------------------------------------- |
+| value  | string | `[]`    | 表示选中的时间，格式为"hh:mm"               |
+| start  | string | `false` | 表示有效时间范围的开始，字符串格式为"hh:mm" |
+| end    | string | `[]`    | 表示有效时间范围的结束，字符串格式为"hh:mm" |
 
 #### 多列选择器：时间选择器：mode = date
+
 ##### 属性
 
-| 属性名                  | 类型                     | 默认值         | 说明                                      |
-| -----------------------| ------------------------| ------------- | ------------------------------------------|
-| value                  | string                  | `当天`         | 表示选中的日期，格式为"YYYY-MM-DD"            |
-| start                  | string                  | `false`       | 表示有效日期范围的开始，字符串格式为"YYYY-MM-DD" |
-| end                    | string                   | `[]`         | 表示有效日期范围的结束，字符串格式为"YYYY-MM-DD" |
-| fields                 | string                   | `day`        | 有效值 year,month,day，表示选择器的粒度        |
+| 属性名 | 类型   | 默认值  | 说明                                             |
+| ------ | ------ | ------- | ------------------------------------------------ |
+| value  | string | `当天`  | 表示选中的日期，格式为"YYYY-MM-DD"               |
+| start  | string | `false` | 表示有效日期范围的开始，字符串格式为"YYYY-MM-DD" |
+| end    | string | `[]`    | 表示有效日期范围的结束，字符串格式为"YYYY-MM-DD" |
+| fields | string | `day`   | 有效值 year,month,day，表示选择器的粒度          |
 
-fields 有效值：
-| 属性名                  | 说明                     |
-| -----------------------| ------------------------ |
-| year                   | 选择器粒度为年             |
-| month                  | 选择器粒度为月份           |
-| day                   | 选择器粒度为天              |
+fields 有效值： | 属性名 | 说明 | | -----------------------| ------------------------ | | year | 选择器粒度为年 | | month | 选择器粒度为月份 | | day | 选择器粒度为天 |
 
 #### 省市区选择器：mode = region
+
 ##### 属性
 
-| 属性名                  | 类型                     | 默认值         | 说明                                      |
-| -----------------------| ------------------------| ------------- | ------------------------------------------|
-| value                  | array                   | `[]`          | 表示选中的省市区，默认选中每一列的第一个值       |
-| custom-item            | string                  |               | 可为每一列的顶部添加一个自定义的项              |
-| level                  | string                  | `region`      | 选择器层级                                  |
+| 属性名      | 类型   | 默认值   | 说明                                       |
+| ----------- | ------ | -------- | ------------------------------------------ |
+| value       | array  | `[]`     | 表示选中的省市区，默认选中每一列的第一个值 |
+| custom-item | string |          | 可为每一列的顶部添加一个自定义的项         |
+| level       | string | `region` | 选择器层级                                 |
 
 level 有效值：
 
-| 属性名                  | 说明                     |
-| -----------------------| ------------------------ |
-| province               | 选省级选择器               |
-| city                   | 市级选择器                 |
-| region                 | 区级选择器                 |
+| 属性名   | 说明         |
+| -------- | ------------ |
+| province | 选省级选择器 |
+| city     | 市级选择器   |
+| region   | 区级选择器   |
 
 ### switch
+
 开关选择器。
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| checked		             | boolean  |   `false`     | 是否选中 |
-| disabled   | boolean  |     `false`    | 是否禁用	|
-| type	  | string  |     `switch`    | 样式，有效值：switch, checkbox		 |
-| color		  | string  |     `#04BE02`    | switch 的颜色，同 css 的 color|
-
+| 属性名   | 类型    | 默认值    | 说明                           |
+| -------- | ------- | --------- | ------------------------------ |
+| checked  | boolean | `false`   | 是否选中                       |
+| disabled | boolean | `false`   | 是否禁用                       |
+| type     | string  | `switch`  | 样式，有效值：switch, checkbox |
+| color    | string  | `#04BE02` | switch 的颜色，同 css 的 color |
 
 #### 事件
 
-| 事件名           | 说明                                                 |
-| ----------------| --------------------------------------------------- |
-| bindchange       |  点击导致 checked 改变时会触发 change 事件，`event.detail = { value }`   |
+| 事件名 | 说明 |
+| --- | --- |
+| bindchange | 点击导致 checked 改变时会触发 change 事件，`event.detail = { value }` |
 
 ### navigator
+
 页面链接。
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| hover-class	             | string  |    `false`      | 指定按下去的样式类。 |
-| hover-start-time   | number  |     `50`    | 按住后多久出现点击态，单位毫秒|
-| hover-stay-time	  | number  |     `400`    | 手指松开后点击态保留时间，单位毫秒	 |
-| open-type		  | string  |     `navigate`    | 可支持`navigateBack`、`redirect`、`switchTab`、`reLaunch`、`navigateTo`|
-| url		  | string  |       |  跳转链接	|
-| delta		  | number  |       |  当 open-type 为 'navigateBack' 时有效，表示回退的层数	|
-
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| hover-class | string | `false` | 指定按下去的样式类。 |
+| hover-start-time | number | `50` | 按住后多久出现点击态，单位毫秒 |
+| hover-stay-time | number | `400` | 手指松开后点击态保留时间，单位毫秒 |
+| open-type | string | `navigate` | 可支持`navigateBack`、`redirect`、`switchTab`、`reLaunch`、`navigateTo` |
+| url | string |  | 跳转链接 |
+| delta | number |  | 当 open-type 为 'navigateBack' 时有效，表示回退的层数 |
 
 ### rich-text
-富文本。
 
+富文本。
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| nodes			             | array\|string  |    []     | 节点列表 |
-
+| 属性名 | 类型          | 默认值 | 说明     |
+| ------ | ------------- | ------ | -------- |
+| nodes  | array\|string | []     | 节点列表 |
 
 ### canvas
+
 画布。
 
 #### 事件
 
-| 事件名                   | 说明                                                       |
-| -----------------------| ---------------------------------------------------------- |
-| bindtouchstart	  | 手指触摸动作开始		|
-| bindtouchmove	   | 手指触摸后移动		|
-| bindtouchend	  | 手指触摸动作结束	|
-| bindtouchcancel	  | 手指触摸动作被打断	|
-| bindlongtap    | 手指长按 350ms 之后触发	|
-| binderror	    | 当发生错误时触发 error 事件， `detail = {errMsg}`	|
+| 事件名          | 说明                                              |
+| --------------- | ------------------------------------------------- |
+| bindtouchstart  | 手指触摸动作开始                                  |
+| bindtouchmove   | 手指触摸后移动                                    |
+| bindtouchend    | 手指触摸动作结束                                  |
+| bindtouchcancel | 手指触摸动作被打断                                |
+| bindlongtap     | 手指长按 350ms 之后触发                           |
+| binderror       | 当发生错误时触发 error 事件， `detail = {errMsg}` |
 
 #### API
 
-| 方法名                     | 说明  |
-| ----------------------- | ------- |
-| createImage	     |  创建一个图片对象。 仅支持在 2D Canvas 中使用	|
-| createImageData	      | 创建一个 ImageData 对象。仅支持在 2D Canvas 中使用		|
-| getContext	      | 该方法返回 Canvas 的绘图上下文。仅支持在 2D Canvas 中使用	|
-| toDataURL	      | 返回一个包含图片展示的 data URI	|
+| 方法名          | 说明                                                      |
+| --------------- | --------------------------------------------------------- |
+| createImage     | 创建一个图片对象。 仅支持在 2D Canvas 中使用              |
+| createImageData | 创建一个 ImageData 对象。仅支持在 2D Canvas 中使用        |
+| getContext      | 该方法返回 Canvas 的绘图上下文。仅支持在 2D Canvas 中使用 |
+| toDataURL       | 返回一个包含图片展示的 data URI                           |
 
 #### 注意事项
+
 - canvas 组件目前仅支持 2D 类型，不支持 webgl
 - 通过 Canvas.getContext('2d') 接口可以获取 CanvasRenderingContext2D 对象，具体接口可以参考 [HTML Canvas 2D Context](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D) 定义的属性、方法
 - canvas 的实现主要借助于 PostMessage 方式与 webview 容器通信进行绘制，所以对于严格依赖方法执行时机的场景，如调用 drawImage 绘图，再通过 getImageData 获取图片数据的场景，调用时需要使用 await 等方式来保证方法的执行时机
 - 通过 Canvas.createImage 画图，图片的链接不能有特殊字符，安卓手机可能会 load 失败
 
 ### video
-视频
 
+视频
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| src	    | string  |               | 要播放视频的资源地址|
-| controls	    | boolean  |     `true`         | 是否显示默认播放控件|
-| autoplay	    | boolean  |   `false`  | 是否自动播放|
-| loop	    | boolean  |       `false`        | 是否循环播放	|
-| muted	    | boolean  |        `false`       | 是否静音播放|
-| initial-time	    | number  |     `0`          | 指定视频初始播放位置|
-| object-fit  | string  |      `contain`         | 当视频大小与 video 容器大小不一致时，视频的表现形式|
-| poster	    | string  |               | 视频封面的图片地址|
-| enable-auto-rotation	    | boolean  |         `false`      | 是否开启手机横屏时自动全屏，当系统设置开启自动旋转时生效，仅 ios 支持|
-| preferred-peak-bit-rate	    | number  |        `0`      | 指定码率上界，单位为比特每秒|
-| is-drm	    | boolean  |         `false`      | 是否为 drm 视频|
-| provision-url	    | string  |               | android 环境特有属性，drm 视频的 provision url|
-| certificate-url	    | string  |               | ios 环境特有属性，drm 视频的 certificate url|
-| license-url	    | string  |               | drm 视频的 license url|
-
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| src | string |  | 要播放视频的资源地址 |
+| controls | boolean | `true` | 是否显示默认播放控件 |
+| autoplay | boolean | `false` | 是否自动播放 |
+| loop | boolean | `false` | 是否循环播放 |
+| muted | boolean | `false` | 是否静音播放 |
+| initial-time | number | `0` | 指定视频初始播放位置 |
+| object-fit | string | `contain` | 当视频大小与 video 容器大小不一致时，视频的表现形式 |
+| poster | string |  | 视频封面的图片地址 |
+| enable-auto-rotation | boolean | `false` | 是否开启手机横屏时自动全屏，当系统设置开启自动旋转时生效，仅 ios 支持 |
+| preferred-peak-bit-rate | number | `0` | 指定码率上界，单位为比特每秒 |
+| is-drm | boolean | `false` | 是否为 drm 视频 |
+| provision-url | string |  | android 环境特有属性，drm 视频的 provision url |
+| certificate-url | string |  | ios 环境特有属性，drm 视频的 certificate url |
+| license-url | string |  | drm 视频的 license url |
 
 #### 事件
 
-| 事件名           | 说明                                                 |
-| ----------------| --------------------------------------------------- |
-| bindplay       |  当开始/继续播放时触发play事件   |
-| bindpause       |  当暂停播放时触发 pause 事件	   |
-| bindended       |  当播放到末尾时触发 ended 事件   |
-| bindtimeupdate       |  播放进度变化时触发，`event.detail = {currentTime, duration}`   |
-| bindfullscreenchange       |  视频进入和退出全屏时触发，`event.detail = {fullScreen` }   |
-| bindwaiting       |  视频出现缓冲时触发   |
-| binderror       |  视频播放出错时触发	   |
-| bindloadedmetadata       |  视频元数据加载完成时触发。`event.detail = {width, height, duration}`   |
-| bindcontrolstoggle       |  切换 controls 显示隐藏时触发。`event.detail = {show}`	   |
-| bindseekcomplete       |  seek 完成时触发    |
+| 事件名 | 说明 |
+| --- | --- |
+| bindplay | 当开始/继续播放时触发 play 事件 |
+| bindpause | 当暂停播放时触发 pause 事件 |
+| bindended | 当播放到末尾时触发 ended 事件 |
+| bindtimeupdate | 播放进度变化时触发，`event.detail = {currentTime, duration}` |
+| bindfullscreenchange | 视频进入和退出全屏时触发，`event.detail = {fullScreen` } |
+| bindwaiting | 视频出现缓冲时触发 |
+| binderror | 视频播放出错时触发 |
+| bindloadedmetadata | 视频元数据加载完成时触发。`event.detail = {width, height, duration}` |
+| bindcontrolstoggle | 切换 controls 显示隐藏时触发。`event.detail = {show}` |
+| bindseekcomplete | seek 完成时触发 |
 
 #### 注意事项
+
 - 手动拖拽进度条场景，bindseekcomplete 事件，android 可以触发，ios 不支持
 - video 组件基于第三方库 `react-native-video` 来实现，需要容器中安装此依赖包
 
-
 ### web-view
-承载网页的容器。会自动铺满整个 RN 页面
 
+承载网页的容器。会自动铺满整个 RN 页面
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| src	    | string  |               | webview 指向网页的链接，如果需要对跳转的URL设定白名单可跳转，需要在业务跳转之前处理该逻辑
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| src | string |  | webview 指向网页的链接，如果需要对跳转的 URL 设定白名单可跳转，需要在业务跳转之前处理该逻辑 |
 
 #### 事件
 
-| 事件名                   | 说明                                                       |
-| ---------------------| ---------------------------------------------------------- |
-| bindmessage	   |  网页向RN通过 postMessage 传递数据
-| bindload	    |  网页加载成功时候触发此事件
-| binderror	     |  网页加载失败的时候触发此事件
-
+| 事件名      | 说明                                |
+| ----------- | ----------------------------------- |
+| bindmessage | 网页向 RN 通过 postMessage 传递数据 |
+| bindload    | 网页加载成功时候触发此事件          |
+| binderror   | 网页加载失败的时候触发此事件        |
 
 #### 注意事项
+
 - 被打开的 H5 页面需使用 `@mpxjs/webview-bridge@2.9.68` 及以上版本与 RN 容器进行通信，具体通信方式参见 [Webview API](#webview-api)
 
 ### root-portal
+
 使整个子树从页面中脱离出来，类似于在 CSS 中使用 position: fixed 的效果。主要用于制作弹窗、弹出层等。
+
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| enable   | boolean           |   `true`	     | 是否从页面中脱离出来 |
+| 属性名 | 类型    | 默认值 | 说明                 |
+| ------ | ------- | ------ | -------------------- |
+| enable | boolean | `true` | 是否从页面中脱离出来 |
 
 #### 注意事项
+
 - style 样式中不支持使用百分比计算、css variable
-   
+
 ### sticky-section
+
 吸顶布局容器，仅支持作为 `<scroll-view>` 的直接子节点
 
 #### 注意事项
+
 - sticky-section 目前仅支持 RN、web 以及微信小程序环境，其他环境暂不支持。微信小程序中使用需开启 skyline 渲染模式
 
 ### sticky-header
+
 吸顶布局容器，仅支持作为 `<scroll-view>` 的直接子节点或 `sticky-section` 组件直接子节点
 
 #### 属性
 
-| 属性名                   | 类型     | 默认值         | 说明                                                       |
-| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
-| offset-top	    | number  |    `0`      | 吸顶时与顶部的距离 |
-| padding	    | array  |     `[0, 0, 0, 0] `         | 长度为 4 的数组，按 top、right、bottom、left 顺序指定内边距 |
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| offset-top | number | `0` | 吸顶时与顶部的距离 |
+| padding | array | `[0, 0, 0, 0] ` | 长度为 4 的数组，按 top、right、bottom、left 顺序指定内边距 |
 
 #### 事件
 
-| 事件名           | 说明                                                 |
-| ----------------| --------------------------------------------------- |
-| bindstickontopchange      |  吸顶状态变化事件, `event.detail = { isStickOnTop }`，当 sticky-header 吸顶时为 true，否则为 false   |
+| 事件名 | 说明 |
+| --- | --- |
+| bindstickontopchange | 吸顶状态变化事件, `event.detail = { isStickOnTop }`，当 sticky-header 吸顶时为 true，否则为 false |
 
 #### 注意事项
+
 - sticky-header 目前仅支持 RN、web 以及微信小程序环境，其他环境暂不支持。微信小程序中使用需开启 skyline 渲染模式
 - RN 环境的 sticky-header 更适用于内容稳定、状态不常变更的场景使用，目前如果 sticky 还在动画过程中就触发组件更新（如在 bindstickontopchange 回调中立刻更新 state）、scroll-view 内容高度由多变少、通过修改 scroll-into-view、scroll-top 让 scroll-view 滚动，以上场景在安卓上都可能会导致闪烁或抖动
 
 ### cover-view
-视图容器。
-功能同 [view 组件](#view)，在 cover-view 中只能嵌套 cover-view 或 cover-image 组件。
+
+视图容器。功能同 [view 组件](#view)，在 cover-view 中只能嵌套 cover-view 或 cover-image 组件。
 
 ### cover-image
-视图容器。
-功能同 [image 组件](#image)
+
+视图容器。功能同 [image 组件](#image)
diff --git a/.agents/skills/mpx-rn-style-guide/references/single-file-component.md b/.agents/skills/mpx-rn-style-guide/references/single-file-component.md
index 463c1f8dc1..3396f3ac48 100644
--- a/.agents/skills/mpx-rn-style-guide/references/single-file-component.md
+++ b/.agents/skills/mpx-rn-style-guide/references/single-file-component.md
@@ -1,6 +1,6 @@
 # 单文件开发 {#single-file-development}
 
-小程序规范中每个页面和组件都是由四个文件描述组成的，wxml/js/wxss/json，分别描述了组件/页面的视图模板，执行逻辑，样式和配置，由于这四个部分彼此之间存在相关性，比如模板中的组件需要在json中注册，数据需要在js中定义，这种离散的文件结构在实际开发的时候体验并不理想；受Vue单文件开发的启发，Mpx也提供了类似的单文件开发模式，拓展名为.mpx。
+小程序规范中每个页面和组件都是由四个文件描述组成的，wxml/js/wxss/json，分别描述了组件/页面的视图模板，执行逻辑，样式和配置，由于这四个部分彼此之间存在相关性，比如模板中的组件需要在 json 中注册，数据需要在 js 中定义，这种离散的文件结构在实际开发的时候体验并不理想；受 Vue 单文件开发的启发，Mpx 也提供了类似的单文件开发模式，拓展名为.mpx。
 
 Mpx 单文件组件（SFC）格式 `.mpx` 是一种将组件的视图模板、组件逻辑、组件样式和组件配置封装在一个文件中的开发模式。每个 `.mpx` 文件都包含了以下几个部分：
 
@@ -9,35 +9,115 @@ Mpx 单文件组件（SFC）格式 `.mpx` 是一种将组件的视图模板、
 - style 区块：定义组件的样式，支持 CSS 预处理（如 Stylus、Sass、Less 等），跨端输出 RN 时存在较强约束限制，对应微信小程序的 `.wxss` 部分
 - json 区块：定义组件的配置，支持微信小程序的组件配置选项，对应微信小程序的 `.json` 部分
 
-简单示例如下：
+示例如下：
 
 ```html
-<!--对应.wxml文件-->
 <template>
-  <list></list>
+  <!--动态样式-->
+  <view class="container" wx:style="{{dynamicStyle}}">
+    <!--数据绑定-->
+    <view class="title">{{title}}</view>
+    <!--计算属性数据绑定-->
+    <view class="title">{{reversedTitle}}</view>
+    <view class="list">
+      <!--循环渲染，动态类名，事件处理内联传参-->
+      <view wx:for="{{list}}" wx:key="id" class="list-item" wx:class="{{ {active:item.active} }}"
+            bindtap="toggleActive(index)">
+        <view>{{item.content}}</view>
+      </view>
+    </view>
+    <!-- wx:ref 标记 ref 名；布局完成后在 setup 中用 context.refs.ci、选项式中用 this.$refs.ci 取自定义组件实例 -->
+    <custom-input wx:ref="ci" wx:model="{{customInfo}}" wx:model-prop="info" wx:model-event="change"/>
+    <!--动态组件，is传入组件名字符串，可使用的组件需要在json中注册，全局注册也生效-->
+    <component is="{{current}}"></component>
+    <!--显示/隐藏dom-->
+    <view class="bottom" wx:show="{{showBottom}}">
+      <!-- 模板节点条件编译，非目标平台的节点不会进入产物 -->
+      <view @wx>wx mode</view>
+      <view @ali>ali mode</view>
+    </view>
+  </view>
 </template>
-<!--对应.js文件-->
+
 <script>
-  import { createPage } from '@mpxjs/core'
+  import { createPage, ref, computed, watch, onMounted } from '@mpxjs/core'
 
   createPage({
-    onLoad () {
-    },
-    onReady () {
+    setup (props, context) {
+      const dynamicStyle = ref({
+        fontSize: '16px',
+        color: 'red'
+      })
+      const title = ref('hello world')
+      const list = ref([
+        {
+          content: '全军出击',
+          id: 0,
+          active: false
+        },
+        {
+          content: '猥琐发育，别浪',
+          id: 1,
+          active: false
+        }
+      ])
+      const customInfo = ref({
+        title: 'test',
+        content: 'test content'
+      })
+      const current = ref('com-a')
+      const showBottom = ref(false)
+
+      const reversedTitle = computed(() => title.value.split('').reverse().join(''))
+
+      watch(title, (val, oldVal) => {
+        console.log(val, oldVal)
+      }, { immediate: true })
+
+      function toggleActive (index) {
+        list.value[index].active = !list.value[index].active
+      }
+
+      // 页面下 onMounted 对应小程序页面的 onReady（组件对应 ready）；此时可安全读取 wx:ref
+      onMounted(() => {
+        const ciIns = context.refs.ci
+        if (ciIns) {
+          // 拿到 custom-input 组件实例，可调用其对外暴露的 methods 等（以子组件实际导出为准）
+          // 例如：ciIns.focus()
+          console.log('custom-input instance', ciIns)
+        }
+        setTimeout(() => {
+          title.value = '你好，世界'
+          current.value = 'com-b'
+        }, 1000)
+      })
+
+      return {
+        dynamicStyle,
+        title,
+        list,
+        customInfo,
+        current,
+        showBottom,
+        reversedTitle,
+        toggleActive
+      }
     }
   })
 </script>
-<!--对应.wxss文件-->
-<style lang="stylus">
-</style>
-<!--对应.json文件-->
+
 <script type="application/json">
   {
     "usingComponents": {
-      "list": "../components/list"
+      "custom-input": "../components/custom-input",
+      "com-a": "../components/com-a",
+      "com-b": "../components/com-b"
     }
   }
 </script>
-```
-
 
+<style lang="stylus">
+  .container
+    flex 1
+</style>
+```
diff --git a/AGENTS.md b/AGENTS.md
index f055b099a9..0d2ce9066d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,12 +6,17 @@
 
 ## 偏好指引
 
-- 开发新特性时尽量参考具有相似性的已有的流程实现，尽可能复用当前已有的流程实现，或者保持与已有流程实现的相似性
+- 设计技术方案时尽量参考具有相似性的已有流程实现，尽可能复用当前已有流程实现，或者保持与已有流程实现的相似性
+- 技术实现时尽可能复用现有流程与工具方法，追求最小的变动进行实现
 - 编写代码时尽可能保持简洁精炼，避免无效的冗余代码，例如：
   - 避免声明不必要的中间变量
   - 避免编写不必要的中间步骤
   - 避免添加不必要的兜底值
+  - 避免类似 `|| undefined` 的冗余兜底写法
+  - 兜底逻辑统一添加到实现侧而不是调用侧，避免多重兜底
   - 避免添加不必要的容错判断
+- 代码风格尽可能模仿当前仓库中现有的写法，例如：
+  - 遍历数组用.forEach而不是for()
 
 
 ## 强制约束
diff --git a/docs-vitepress/api-proxy/index.md b/docs-vitepress/api-proxy/index.md
index 4059f061ee..962131f886 100644
--- a/docs-vitepress/api-proxy/index.md
+++ b/docs-vitepress/api-proxy/index.md
@@ -25,7 +25,7 @@ mpx.use(apiProxy, options)
 | --------------- | ----------------- | ---------------------------------------------------------- | -------- | ------- | ----------------------------------------------------------- |
 | ~~platform~~    | ~~Object~~        | ~~各平台之间的转换~~                                       | ~~否~~   |         | 已删除                                                      |
 | ~~exclude~~     | ~~Array(String)~~ | ~~跨平台时不需要转换的 api~~                               | ~~否~~   | ~~[]~~  | 已删除                                                      |
-| usePromise      | Boolean           | 是否启用 Promise 化风格调用                                | 否       | `false` | 开启后，异步 API 将返回 Promise 对象                        |
+| usePromise      | Boolean           | 是否启用 Promise 化风格调用                                | 否       | `false` | 开启后，符合 Promise 化规则的异步 API 会返回 Promise 对象   |
 | whiteList       | Array(String)     | **强制启用** Promise 化的 API 名单                         | 否       | `[]`    | 仅在 usePromise: true 时有效，可覆盖 blackList              |
 | blackList       | Array(String)     | **强制禁用** Promise 化的 API 名单                         | 否       | `[]`    | 即使在 usePromise: true 时，名单内的 API 也不会返回 Promise |
 | ~~fallbackMap~~ | ~~Object~~        | ~~对于不支持的 API，允许配置一个映射表，接管不存在的 API~~ | ~~否~~   | ~~{}~~  | 已删除                                                      |
@@ -54,12 +54,12 @@ mpx.showModal({
 
 ### usePromise
 
-启用 `usePromise` 选项后，所有异步 `API` 将返回 `Promise` 对象。需要注意的是，部分小程序 `API`（如 `uploadFile`）的返回值本身具有特定意义（例如返回一个 `uploadTask` 对象用于监听上传进度或取消任务）。为了兼容这种情况，这些 `API` 的原始返回值会被挂载到返回的 `Promise` 对象的 `__returned` 属性上，开发者仍可正常访问和使用。
+启用 `usePromise` 选项后，在 Promise 化规则范围内的异步 `API` 会返回 `Promise` 对象。部分小程序 `API`（如 `uploadFile`）的返回值本身具有特定意义（例如返回一个 `uploadTask` 对象用于监听上传进度或取消任务）。为了兼容这种情况，这些 `API` 的原始返回值会被挂载到返回的 `Promise` 对象的 `__returned` 属性上，开发者仍可正常访问和使用。
 
 > [!important] ⚠️ 注意
 >
 > - **与原生微信小程序差异**
->   - 在 `Mpx` 中，开启 `usePromise` 后，**所有**接收 `success` 或 `fail` 参数的 `API` 都可返回 `Promise`，统一支持 `await` 或 `.then ()` 语法。
+>   - 在 `Mpx` 中，开启 `usePromise` 后，在 Promise 化规则范围内的异步 `API` 会返回 `Promise`，统一支持 `await` 或 `.then()` 语法（部分 API 因语义或命名规则默认不参与 Promise 化，见下文「whiteList 与 blackList」）。
 >   - 而微信小程序原生环境中则存在差异：大部分接收 `success` 和 `fail` 回调的 `API` 已支持 `Promise` 化写法，**但存在个别特例——** 这些 `API` 虽然同样接收 `success` 和 `fail` 参数，却不支持 `promisify` 风格调用。
 > - **混用风险**
 >   - API 调用同时支持 `success/fail` 回调与 `Promise` 的 `then/catch` 写法，且两者两种方式可以共存使用。虽然支持共存，但还是**强烈建议开启 `usePromise` 后，支持 `promisify` 风格的 `API` 都走 `then/catch` 写法**以避免产生下面提示的第三项的影响
@@ -74,6 +74,7 @@ import apiProxy from "@mpxjs/api-proxy"
 
 // 启用 Promise 风格
 mpx.use(apiProxy, {
+  usePromise: true,
   blackList: ["getSystemInfo"],
 })
 
@@ -90,7 +91,17 @@ mpx.getSystemInfo({
 
 ### whiteList 与 blackList {#whitelist-and-blacklist}
 
-当微信平台新增了某些 API，而 Mpx 框架暂未及时适配时，您可以通过配置 whiteList 或 blackList 来明确指定这些 API 是否应被 Promise 化，从而避免因框架未及时更新而导致的调用异常或兼容性问题。
+在 `usePromise: true` 时，除你在 `whiteList` / `blackList` 中的配置外，实现里还会按命名与语义过滤一部分 **默认不** 做 Promise 化的方法，例如：
+
+- 名称以 `Sync` 结尾的同步风格 API；
+- 名称以 `on`、`off` 开头的监听类 API；
+- 名称匹配 `get*Manager` 的 API；
+- 名称匹配 `create*` 的 API（`createBLEConnection`、`createBLEPeripheralServer` 等少数例外会参与 Promise 化）；
+- 另有少量特殊 API（如 `nextTick`、`canIUse`、部分信息获取类方法等）在实现中固定不参与 Promise 化。
+
+`whiteList` 中的名称会 **强制** 参与 Promise 化（可覆盖上述默认规则）；`blackList` 中的名称会与上述内置规则 **合并**，用于强制保持回调风格。
+
+当平台侧新增了带 `success` / `fail` 的 API，而本地 `@mpxjs/api-proxy` 版本尚未跟进时，也可通过 `whiteList` / `blackList` 显式控制是否 Promise 化，减少行为不确定带来的问题。
 
 ### custom
 
@@ -129,8 +140,8 @@ if (__mpx_mode__ === "ali" || __mpx_mode__ === "ios") {
 作为 Mpx 框架的内置能力，也支持独立调用，无需显式挂载在 Mpx 实例上
 
 ```js
-import apiProxy from "@mpxjs/api-proxy"
-// 获取代理实例，底层仍基于 Mpx 框架的转换机制
+import { getProxy } from "@mpxjs/api-proxy"
+// 获取代理实例，与 mpx.use(apiProxy, options) 使用相同的 install 逻辑
 const proxy = getProxy(options)
 
 // 调用方式与原生 API 一致，代理层会自动处理跨平台转换
@@ -144,7 +155,7 @@ proxy.navigateTo({
 
 ### 按需导入单个 API {#import-single-api}
 
-除了使用完整的代理实例，你也可以直接从 `@mpxjs/api-proxy` 中按需导入特定的 API 方法
+除了使用完整的代理实例，也可以从 `@mpxjs/api-proxy` 中按需 **具名导入** 包内已实现并导出的 API（导出集合与 `getProxy()` 挂到目标上的方法一致）。未导出或未在本文档子页中出现的接口，通常表示尚未做跨端适配或需直接使用各端原生对象。
 
 ```js
 // 直接导入所需的 API 方法
diff --git a/docs-vitepress/api/compile.md b/docs-vitepress/api/compile.md
index 85a5b5a617..0986ea4e16 100644
--- a/docs-vitepress/api/compile.md
+++ b/docs-vitepress/api/compile.md
@@ -818,20 +818,49 @@ module.exports = defineConfig({
 })
 ```
 
-### webConfig
+### webConfig {#web-config}
 
-`{transRpxFn(match:string, $1:number): string}`
+**`mode === 'web'`** 输出时使用的编译期配置对象，在 `plugin.webConfig`（如 `vue.config.js` / `mpx.config.js` 的 `pluginOptions.mpx.plugin` 下）中传入，由 `MpxWebpackPlugin` 读取并参与 Web 侧 rpx 转换、SSR、页面切换动画与内建组件等编译逻辑。
 
-transRpxFn 配置用于自定义输出 web 时对于 rpx 样式单位的转换逻辑，常见的方式有转换为 vw 或转换为 rem
+#### webConfig.transRpxFn {#webconfig-transrpxfn}
 
-`{useSSR: boolean}`
+`(match: string, $1: number) => string`
 
-useSSR 默认值为 `false`，当 SSR 模式下使用异步分包时，需要将 useSSR 设置为 `true`, 其他场景不需要。
+自定义 Web 输出时对 **rpx** 单位的转换规则，常见写法为转为 **vw** 或 **rem**。
 
-`{disablePageTransition: boolean}`
+#### webConfig.useSSR {#webconfig-usessr}
 
-用于配置禁用/开启页面切换动画，默认禁用
+`boolean = false`
+
+在 **SSR** 模式下若使用 **异步分包**，需将 `useSSR` 设为 **`true`**；其它场景保持默认即可。
+
+#### webConfig.disablePageTransition {#webconfig-disablepagetransition}
+
+`boolean = true`
+
+为 `true` 时 **禁用** 页面切换动画；设为 **`false`** 可 **开启** 切换过渡效果。
+
+#### webConfig.customBuiltInComponents {#webconfig-custombuiltincomponents}
+
+`Record<string, string> | undefined`
+
+在 **Web 输出**（**`mode === 'web'`**）、且 **非 app 入口**（存在参与编译的用户模版）时生效，用于 **替换或扩展** 框架对某一微信基础标签在 Web 侧的内建实现。
+
+**key**
+
+- 须为 **微信小程序侧基础标签名**（如 `view`、`text`、`scroll-view`），与模版中写的标签一致。
+- **不要** 使用 **`mpx-*`** 作为 key。
+
+**value**（文档约定，插件 **不在编译期校验** 格式）
+
+- 建议使用 **绝对路径**（POSIX 以 **`/`** 开头，或 Windows 下 **`path.isAbsolute` 为真**），或 **以 npm 包名开头的模块路径**（如 **`@scope/pkg/...`**、**`my-pkg/...`**，首段须为合法包名，避免写成易被误认为工程相对路径的 **`src/...`**）。
+- **不要** 使用 **`./`、`../`** 及 **`~`** 前缀；不符合约定时一般由 **webpack 解析** 等环节报错。
 
+**注意事项**
+
+- 某标签一旦在配置中声明，Web 侧将 **优先使用你提供的模块** 作为该基础标签的实现；**属性、事件、子节点等与微信文档的差异** 需在你的组件内 **自行对齐**。
+- **app 入口** 仅内置 **`mpx-keep-alive`**，**不使用** 本配置项。
+- **小程序等其它输出形态** 不读取 `webConfig.customBuiltInComponents`；仅在 **Web / RN** 输出下配置有效。RN 侧请使用 **`rnConfig.customBuiltInComponents`**，约定与本节相同，见 [rnConfig.customBuiltInComponents](#rnconfig-custombuiltincomponents)。
 
 ```js
 // mpx.config.js
@@ -847,7 +876,78 @@ module.exports = defineConfig({
           // 当 SSR 模式下使用异步分包时
           useSSR: true,
           // 开启页面切换动画
-          disablePageTransition: false
+          disablePageTransition: false,
+          customBuiltInComponents: {
+            view: require('path').resolve(__dirname, 'src/builtin/MpxView.vue')
+          }
+        }
+      }
+    }
+  }
+})
+```
+
+### rnConfig {#rn-config}
+
+**`mode` 为输出 React Native（如 `react`）时**使用的编译期配置对象，由 `MpxWebpackPlugin` 传入 loader 上下文，并会挂到运行时的 `mpx.config.rnConfig` 上供 RN 逻辑读取（与小程序 / Web 无关）。
+
+#### rnConfig.projectName
+
+`string | undefined`
+
+若配置，则在入口脚本中调用 `AppRegistry.registerComponent(projectName, () => app)`，用于注册 RN 根组件名称。
+
+#### rnConfig.supportSubpackage
+
+`boolean = true`
+
+为 `true` 时，RN 输出下页面与组件可走异步分包与 `import()` 等逻辑；为 `false` 时关闭相关能力。插件初始化时若未传入则默认为 `true`。
+
+#### rnConfig.asyncChunk
+
+`{ timeout?: number, fallback?: string, loading?: string } | undefined`
+
+异步分包相关：
+
+- **timeout**：传给内部 `LoadAsyncChunkModule` 的超时时间（毫秒级用途，见 `@mpxjs/webpack-plugin` 实现）。
+- **fallback** / **loading**：异步页面/组件的占位与 loading 组件资源路径（经 `addQuery(..., { isComponent: true })` 参与打包），在 `react/script-helper.js` 中生成异步包装代码时使用。
+
+#### rnConfig.customBuiltInComponents {#rnconfig-custombuiltincomponents}
+
+`Record<string, string> | undefined`
+
+在 **RN 输出**（**`mode`** 为 **`ios` / `android` / `harmony`** 等）时生效。与 [webConfig.customBuiltInComponents](#webconfig-custombuiltincomponents) 的 **key、value 约定及注意事项** 相同，仅在 **`rnConfig`** 中配置，便于与 Web 使用不同的模块路径。
+
+**注意事项**
+
+- 页面/组件 **主模版** 以及 **子模版**（如通过 import 引入的模版）均会应用本配置。
+- **key / value** 及路径书写要求与 Web 一节一致，此处不再重复；详见 [webConfig.customBuiltInComponents](#webconfig-custombuiltincomponents)。
+
+#### rnConfig.loadChunkAsync（运行时）
+
+编译插件不会在选项里“实现”该函数；异步分包下载 chunk 时，运行时代码会调用 **`mpx.config.rnConfig.loadChunkAsync`**（若存在）。需在 RN 应用启动后自行挂载，例如与原生下载、热更新方案对接。与 **asyncChunk** 编译配置配合使用。
+
+```js
+// vue.config.js / mpx.config.js 片段
+const path = require('path')
+
+module.exports = defineConfig({
+  pluginOptions: {
+    mpx: {
+      plugin: {
+        mode: 'react',
+        rnConfig: {
+          projectName: 'MyMpxApp',
+          supportSubpackage: true,
+          asyncChunk: {
+            timeout: 10000,
+            fallback: path.resolve(__dirname, 'src/rn/PageFallback.mpx'),
+            loading: path.resolve(__dirname, 'src/rn/PageLoading.mpx')
+          },
+          customBuiltInComponents: {
+            view: '@your-org/mpx-rn-builtin/MpxView.mpx',
+            text: path.resolve(__dirname, 'src/builtin/MpxText.mpx')
+          }
         }
       }
     }
diff --git a/docs-vitepress/guide/advance/pinia.md b/docs-vitepress/guide/advance/pinia.md
index f57c34f744..9bbf8e2d47 100644
--- a/docs-vitepress/guide/advance/pinia.md
+++ b/docs-vitepress/guide/advance/pinia.md
@@ -24,7 +24,7 @@ import { createPinia } from '@mpxjs/pinia'
 const pinia = createPinia()
 ```
 
-如果你的应用想使用 SSR 渲染模式，请将 pinia 的创建放在 `onAppInit` 钩子中执行
+如果你的应用需要输出 Web 并使用 SSR 渲染模式，请将 pinia 的创建放在 `onAppInit` 钩子中执行并返回。
 ```js
 // app.mpx
 
diff --git a/packages/api-proxy/src/platform/api/system/index.ios.js b/packages/api-proxy/src/platform/api/system/index.ios.js
index 18cf06973d..ee56b8a408 100644
--- a/packages/api-proxy/src/platform/api/system/index.ios.js
+++ b/packages/api-proxy/src/platform/api/system/index.ios.js
@@ -46,7 +46,7 @@ const getSystemInfo = function (options = {}) {
   try {
     const systemInfo = getSystemInfoSync()
     Object.assign(systemInfo, {
-      errMsg: 'setStorage:ok'
+      errMsg: 'getSystemInfo:ok'
     })
     successHandle(systemInfo, success, complete)
   } catch (err) {
diff --git a/packages/webpack-plugin/lib/platform/run-rules.js b/packages/webpack-plugin/lib/platform/run-rules.js
index 81abff8cbb..da4c31d7e5 100644
--- a/packages/webpack-plugin/lib/platform/run-rules.js
+++ b/packages/webpack-plugin/lib/platform/run-rules.js
@@ -26,7 +26,7 @@ module.exports = function runRules (rules = [], input, options = {}) {
     Object.assign(data, {
       mode
     })
-    if (tester(testInput, meta) && processor) {
+    if (tester(testInput, meta, data) && processor) {
       const result = processor.call(rule, input, data, meta)
       meta.processed = true
       if (result !== undefined) {
diff --git a/packages/webpack-plugin/lib/platform/template/wx/component-config/custom-built-in-component.js b/packages/webpack-plugin/lib/platform/template/wx/component-config/custom-built-in-component.js
new file mode 100644
index 0000000000..d6b64491e0
--- /dev/null
+++ b/packages/webpack-plugin/lib/platform/template/wx/component-config/custom-built-in-component.js
@@ -0,0 +1,34 @@
+const CUSTOM_BUILTIN_MODES = ['web', 'ios', 'android', 'harmony']
+
+function testCustomBuiltInTag (tag, meta, data) {
+  const map = data && data.customBuiltInComponents
+  return !!(map && map[tag])
+}
+
+/**
+ * 命中后不再走后续常规 component-config（无 waterfall，run-rules 直接 break）。
+ * 从 runRules 的 data.customBuiltInComponents 读取配置；先写入 originalTag，再 mpx- 前缀。
+ */
+function applyCustomBuiltin (el, data) {
+  const map = data && data.customBuiltInComponents
+  if (!map || !map[el.tag]) return el
+  el.originalTag = el.tag
+  el.isBuiltIn = true
+  el.tag = 'mpx-' + el.originalTag
+  return el
+}
+
+/**
+ * @returns {object}
+ */
+module.exports = function customBuiltInComponent () {
+  return {
+    skipNormalize: true,
+    supportedModes: CUSTOM_BUILTIN_MODES,
+    test: testCustomBuiltInTag,
+    web: applyCustomBuiltin,
+    ios: applyCustomBuiltin,
+    android: applyCustomBuiltin,
+    harmony: applyCustomBuiltin
+  }
+}
diff --git a/packages/webpack-plugin/lib/platform/template/wx/component-config/index.js b/packages/webpack-plugin/lib/platform/template/wx/component-config/index.js
index 1535a9a4f1..b5a65229fb 100644
--- a/packages/webpack-plugin/lib/platform/template/wx/component-config/index.js
+++ b/packages/webpack-plugin/lib/platform/template/wx/component-config/index.js
@@ -40,10 +40,25 @@ const webView = require('./web-view')
 const label = require('./label')
 const wxs = require('./wxs')
 const fixComponentName = require('./fix-component-name')
+const customBuiltInComponent = require('./custom-built-in-component')
 const rootPortal = require('./root-portal')
 const stickyHeader = require('./sticky-header')
 const stickySection = require('./sticky-section')
 
+/**
+ * 未命中上方任一组件 test 的标签，仍须走 normalizeComponentRules 中的通用
+ * 指令 / 属性 / 事件链路（如 wx 源码输出 ali 时 bindtap → onTap）。
+ * 历史上在 template/wx/index.js 里通过 normalizeComponentRules(cfgs.concat({}), spec)
+ * 末尾塞入空对象，由 run-rules 对缺省 test 退化为恒 true；此处改为显式配置且必须排在最后。
+ */
+function defaultCatchAllComponentConfig () {
+  return {
+    test () {
+      return true
+    }
+  }
+}
+
 module.exports = function getComponentConfigs ({ warn, error }) {
   /**
    * universal print for detail component warn or error
@@ -84,6 +99,7 @@ module.exports = function getComponentConfigs ({ warn, error }) {
   // 转换规则只需以微信为基准配置微信和支付宝的差异部分，比如微信和支付宝都支持但是写法不一致，或者微信支持而支付宝不支持的部分(抛出错误或警告)
   return [
     fixComponentName({ print }),
+    customBuiltInComponent(),
     ...unsupported({ print }),
     ad({ print }),
     view({ print }),
@@ -127,6 +143,7 @@ module.exports = function getComponentConfigs ({ warn, error }) {
     label({ print }),
     rootPortal({ print }),
     stickyHeader({ print }),
-    stickySection({ print })
+    stickySection({ print }),
+    defaultCatchAllComponentConfig()
   ]
 }
diff --git a/packages/webpack-plugin/lib/platform/template/wx/index.js b/packages/webpack-plugin/lib/platform/template/wx/index.js
index b74f4c638e..c187ba5c27 100644
--- a/packages/webpack-plugin/lib/platform/template/wx/index.js
+++ b/packages/webpack-plugin/lib/platform/template/wx/index.js
@@ -590,6 +590,6 @@ module.exports = function getSpec ({ warn, error }) {
       ]
     }
   }
-  spec.rules = normalizeComponentRules(getComponentConfigs({ warn, error }).concat({}), spec)
+  spec.rules = normalizeComponentRules(getComponentConfigs({ warn, error }), spec)
   return spec
 }
diff --git a/packages/webpack-plugin/lib/react/processTemplate.js b/packages/webpack-plugin/lib/react/processTemplate.js
index 1f9eb21f38..fc617b040c 100644
--- a/packages/webpack-plugin/lib/react/processTemplate.js
+++ b/packages/webpack-plugin/lib/react/processTemplate.js
@@ -1,4 +1,3 @@
-const addQuery = require('../utils/add-query')
 const normalize = require('../utils/normalize')
 const parseRequest = require('../utils/parse-request')
 const { matchCondition } = require('../utils/match-condition')
@@ -8,6 +7,7 @@ const { genNode, genTemplate } = require('../template-compiler/gen-node-react')
 const bindThis = require('../template-compiler/bind-this')
 const isEmptyObject = require('../utils/is-empty-object')
 const dash2hump = require('../utils/hump-dash').dash2hump
+const addQuery = require('../utils/add-query')
 
 function transformCode (code, wxsModuleMap, error) {
   try {
@@ -52,7 +52,8 @@ module.exports = function (template, {
     forceProxyEventRules,
     checkUsingComponentsRules,
     globalComponents,
-    customTextRules
+    customTextRules,
+    rnConfig
   } = mpx
   const { resourcePath, rawResourcePath } = parseRequest(loaderContext.resource)
   const builtInComponentsMap = {}
@@ -111,7 +112,8 @@ module.exports = function (template, {
         hasVirtualHost: matchCondition(resourcePath, autoVirtualHostRules),
         forceProxyEvent: matchCondition(resourcePath, forceProxyEventRules),
         checkUsingComponents: matchCondition(resourcePath, checkUsingComponentsRules),
-        isCustomText: matchCondition(resourcePath, customTextRules)
+        isCustomText: matchCondition(resourcePath, customTextRules),
+        customBuiltInComponents: rnConfig && rnConfig.customBuiltInComponents
       }
       const { root, meta } = templateCompiler.parse(template.content, parseOptions)
 
@@ -147,13 +149,12 @@ module.exports = function (template, {
         }
       }
 
-      if (meta.builtInComponentsMap) {
-        Object.keys(meta.builtInComponentsMap).forEach((name) => {
-          builtInComponentsMap[name] = {
-            resource: addQuery(meta.builtInComponentsMap[name], { isComponent: true })
-          }
-        })
-      }
+      const builtInPaths = meta.builtInComponentsMap || {}
+      Object.keys(builtInPaths).forEach((name) => {
+        builtInComponentsMap[name] = {
+          resource: addQuery(builtInPaths[name], { isComponent: true })
+        }
+      })
       if (meta.genericsInfo) {
         genericsInfo = meta.genericsInfo
       }
diff --git a/packages/webpack-plugin/lib/react/template-loader.js b/packages/webpack-plugin/lib/react/template-loader.js
index 136fd0b5f7..2e2a65b495 100644
--- a/packages/webpack-plugin/lib/react/template-loader.js
+++ b/packages/webpack-plugin/lib/react/template-loader.js
@@ -21,7 +21,8 @@ module.exports = function (content) {
     decodeHTMLText,
     externalClasses,
     forceProxyEventRules,
-    getModuleId
+    getModuleId,
+    rnConfig
   } = mpx
 
   const { resourcePath, rawResourcePath, queryObj } = parseRequest(loaderContext.resource)
@@ -48,7 +49,8 @@ module.exports = function (content) {
     externalClasses,
     moduleId,
     filePath: rawResourcePath,
-    forceProxyEvent: matchCondition(resourcePath, forceProxyEventRules)
+    forceProxyEvent: matchCondition(resourcePath, forceProxyEventRules),
+    customBuiltInComponents: rnConfig && rnConfig.customBuiltInComponents
   }
 
   // Parse the template
@@ -69,13 +71,12 @@ module.exports = function (content) {
     })
   }
 
+  const builtInPaths = meta.builtInComponentsMap || {}
   const builtInComponents = []
-  if (meta.builtInComponentsMap) {
-    Object.keys(meta.builtInComponentsMap).forEach((componentName) => {
-      const componentRequest = loaderUtils.stringifyRequest(loaderContext, addQuery(meta.builtInComponentsMap[componentName], { isComponent: true }))
-      builtInComponents.push(`"${componentName}": function () { return getBuiltInBaseComponent(require(${componentRequest}), { __mpxBuiltIn: true }) }`)
-    })
-  }
+  Object.keys(builtInPaths).forEach((componentName) => {
+    const componentRequest = loaderUtils.stringifyRequest(loaderContext, addQuery(builtInPaths[componentName], { isComponent: true }))
+    builtInComponents.push(`"${componentName}": function () { return getBuiltInBaseComponent(require(${componentRequest}), { __mpxBuiltIn: true }) }`)
+  })
 
   // Generate local templates
   let localTemplatesCode = 'var localTemplates = {\n'
diff --git a/packages/webpack-plugin/lib/template-compiler/compiler.js b/packages/webpack-plugin/lib/template-compiler/compiler.js
index 61b0360e97..04780f1585 100644
--- a/packages/webpack-plugin/lib/template-compiler/compiler.js
+++ b/packages/webpack-plugin/lib/template-compiler/compiler.js
@@ -106,6 +106,7 @@ let hasVirtualHost
 let isCustomText
 let runtimeCompile
 let rulesRunner
+let customBuiltInComponentsOpt
 let currentEl
 let injectNodes = []
 let forScopes = []
@@ -643,6 +644,7 @@ function parse (template, options) {
   componentGenerics = options.componentGenerics || {}
   usingComponentsInfo = options.usingComponentsInfo || {}
   usingComponents = Object.keys(usingComponentsInfo)
+  customBuiltInComponentsOpt = options.customBuiltInComponents || null
 
   // 初始化跨平台语法检测配置（每次解析时只初始化一次）
   crossPlatformConfig = initCrossPlatformConfig()
@@ -668,7 +670,8 @@ function parse (template, options) {
     type: 'template',
     testKey: 'tag',
     data: {
-      usingComponents
+      usingComponents,
+      customBuiltInComponents: customBuiltInComponentsOpt
     },
     warn: _warn,
     error: _error
@@ -2538,19 +2541,25 @@ function processScoped (el) {
 
 const builtInComponentsPrefix = '@mpxjs/webpack-plugin/lib/runtime/components'
 
+function resolveCustomBuiltinResource (el) {
+  if (!customBuiltInComponentsOpt || !el.isBuiltIn) return null
+  if (el.originalTag != null && customBuiltInComponentsOpt[el.originalTag]) {
+    return customBuiltInComponentsOpt[el.originalTag]
+  }
+  return null
+}
+
 function processBuiltInComponents (el, meta) {
   if (el.isBuiltIn) {
     if (!meta.builtInComponentsMap) {
       meta.builtInComponentsMap = {}
     }
     const tag = el.tag
-    if (!meta.builtInComponentsMap[tag]) {
-      if (isReact(mode)) {
-        meta.builtInComponentsMap[tag] = `${builtInComponentsPrefix}/react/dist/${tag}`
-      } else {
-        meta.builtInComponentsMap[tag] = `${builtInComponentsPrefix}/${mode}/${tag}`
-      }
-    }
+    const customResource = resolveCustomBuiltinResource(el)
+    const defaultResource = isReact(mode)
+      ? `${builtInComponentsPrefix}/react/dist/${tag}`
+      : `${builtInComponentsPrefix}/${mode}/${tag}`
+    meta.builtInComponentsMap[tag] = customResource != null ? customResource : defaultResource
   }
 }
 
diff --git a/packages/webpack-plugin/lib/web/processTemplate.js b/packages/webpack-plugin/lib/web/processTemplate.js
index c66ee30839..a10a1549c7 100644
--- a/packages/webpack-plugin/lib/web/processTemplate.js
+++ b/packages/webpack-plugin/lib/web/processTemplate.js
@@ -99,7 +99,8 @@ module.exports = function (template, {
           componentGenerics,
           hasVirtualHost: matchCondition(resourcePath, autoVirtualHostRules),
           forceProxyEvent: matchCondition(resourcePath, forceProxyEventRules),
-          checkUsingComponents: matchCondition(resourcePath, checkUsingComponentsRules)
+          checkUsingComponents: matchCondition(resourcePath, checkUsingComponentsRules),
+          customBuiltInComponents: webConfig && webConfig.customBuiltInComponents
         })
         if (meta.wxsModuleMap) {
           wxsModuleMap = meta.wxsModuleMap
@@ -109,13 +110,12 @@ module.exports = function (template, {
             wxsContentMap[`${rawResourcePath}~${module}`] = meta.wxsContentMap[module]
           }
         }
-        if (meta.builtInComponentsMap) {
-          Object.keys(meta.builtInComponentsMap).forEach((name) => {
-            builtInComponentsMap[name] = {
-              resource: addQuery(meta.builtInComponentsMap[name], { isComponent: true })
-            }
-          })
-        }
+        const builtInPaths = meta.builtInComponentsMap || {}
+        Object.keys(builtInPaths).forEach((name) => {
+          builtInComponentsMap[name] = {
+            resource: addQuery(builtInPaths[name], { isComponent: true })
+          }
+        })
         if (meta.genericsInfo) {
           genericsInfo = meta.genericsInfo
         }
diff --git a/packages/webpack-plugin/test/template-compiler/custom-built-in-components.spec.js b/packages/webpack-plugin/test/template-compiler/custom-built-in-components.spec.js
new file mode 100644
index 0000000000..4568555a99
--- /dev/null
+++ b/packages/webpack-plugin/test/template-compiler/custom-built-in-components.spec.js
@@ -0,0 +1,45 @@
+const compiler = require('../../lib/template-compiler/compiler')
+
+const baseParseOpts = {
+  usingComponents: [],
+  usingComponentsInfo: {},
+  externalClasses: [],
+  srcMode: 'wx',
+  warn: jest.fn(),
+  error: jest.fn(),
+  defs: {
+    __mpx_mode__: 'web',
+    __mpx_src_mode__: 'wx',
+    __mpx_env__: ''
+  }
+}
+
+describe('customBuiltInComponents in processBuiltInComponents', () => {
+  it('wx key maps user path onto runtime tag in meta.builtInComponentsMap (web)', () => {
+    const { meta } = compiler.parse('<view></view>', Object.assign({}, baseParseOpts, {
+      mode: 'web',
+      customBuiltInComponents: { view: '/abs/CustomView.vue' }
+    }))
+    expect(meta.builtInComponentsMap['mpx-view']).toBe('/abs/CustomView.vue')
+  })
+
+  it('uses default path when no custom (web)', () => {
+    const { meta } = compiler.parse('<scroll-view></scroll-view>', Object.assign({}, baseParseOpts, {
+      mode: 'web'
+    }))
+    expect(meta.builtInComponentsMap['mpx-scroll-view']).toMatch(/mpx-scroll-view/)
+  })
+
+  it('wx key on RN mode', () => {
+    const { meta } = compiler.parse('<view></view>', Object.assign({}, baseParseOpts, {
+      mode: 'ios',
+      defs: {
+        __mpx_mode__: 'ios',
+        __mpx_src_mode__: 'wx',
+        __mpx_env__: ''
+      },
+      customBuiltInComponents: { view: '@pkg/MyView.mpx' }
+    }))
+    expect(meta.builtInComponentsMap['mpx-view']).toBe('@pkg/MyView.mpx')
+  })
+})
diff --git a/solutions/register-custom-builtin.md b/solutions/register-custom-builtin.md
new file mode 100644
index 0000000000..3ec91ec70d
--- /dev/null
+++ b/solutions/register-custom-builtin.md
@@ -0,0 +1,144 @@
+# 输出 Web 和 RN 时支持用户注册自定义的内建基础组件
+
+## 需求描述
+
+Mpx 在 Web/RN 输出时将微信侧基础组件映射为框架内建实现（如模版里写 `view`，经跨平台规则变为 `mpx-view` 等）。希望通过 **`webConfig` / `rnConfig` 下的 `customBuiltInComponents`**，让用户用 **自定义模块** **替换** 已有内建实现，并 **扩展** 框架尚未提供默认实现的基础组件能力。
+
+**目标形态（技术方案口径）**：
+
+- **`customBuiltInComponents` 的 key 使用微信小程序侧的原始基础组件标签名**（如 `view`、`text`、`scroll-view`），表示「用户对该基础标签的自定义拓展/替换」；**不再**要求用户直接配置运行时 `mpx-*` 名称。
+- **`el.isBuiltIn` 与标签名（tag）的跨平台转换** 统一在现有 **`rulesRunner`** 链路中完成；**将 `customBuiltInComponents` 放在 `getRulesRunner` 的 `data` 上**（**不**经 **`getSpec` / `getComponentConfigs`** 传入）。**`component-config/custom-built-in-component.js`** 注册单条规则，**`test` / `processor` 从 `run-rules` 传入的 `data.customBuiltInComponents` 读取**；顺序紧接 **`fix-component-name`** 之后，**命中后 `run-rules` 即结束**，不再执行后续 `view.js` 等常规转换；**无 `waterfall`**，由自定义实现自行与源平台（微信）语义对齐。
+- **value** 仍为自定义实现模块路径（约定见 §2.3）；**插件可对 value 不做格式校验**（以文档与构建期解析为准）。
+
+**说明**：下文 **§1.2 / §3.2** 中「当前已落地」描述的是 **过渡实现**（key 曾为运行时名、合并未经 rulesRunner 扩展）；**§3.3 及以后** 为 **与上述目标对齐** 的修订方向，**不写具体代码**。
+
+## 1. 现状与数据流
+
+### 1.1 编译侧（概念）
+
+- 模版 AST 上各基础组件的规则集中在 **`packages/webpack-plugin/lib/platform/template/wx/component-config/*.js`**，由 **`getRulesRunner`** 汇总，在 **`template-compiler/compiler.js`** 解析过程中对节点执行（**rulesRunner(el)**），完成 **`el.isBuiltIn`**、**`el.tag` 跨平台改名**（如 Web 下 `view` → `mpx-view`）等。
+- **`processBuiltInComponents`** 在 **`el.isBuiltIn`** 为真时，用 **当前（已转换后）的 `el.tag`** 作为 key，写入 **`meta.builtInComponentsMap`** → 框架默认资源路径。
+- **`web/processTemplate.js`、`react/processTemplate.js`** 将 **`meta.builtInComponentsMap`**（已在 **`processBuiltInComponents`** 中含用户或默认路径）经 **`addQuery`** 写入 **`builtInComponentsMap`**，再经 **`buildComponentsMap`** 生成 **`getComponent(require(...), { __mpxBuiltIn: true })`**。
+- **`react/template-loader.js`** 子模版链路须与主模版 **一致**（同样经过带 **rulesRunner** 的 `parse` 与合并逻辑）。
+
+### 1.2 当前实现与目标的差距
+
+| 维度 | 当前已落地（过渡） | 目标方案 |
+|------|-------------------|----------|
+| **配置 key** | 多为 **运行时标签名**（如 `mpx-view`），与 **`meta.builtInComponentsMap` 的 key** 一致才生效 | **微信原始基础标签名**（如 `view`），与用户模版写法一致 |
+| **内建打标与改名** | 依赖既有 **component-config**；**未覆盖** 的标签难以进内建链路 | **`customBuiltInComponents` 作为数据进入 rulesRunner**，在 **跨平台转换** 中与内置规则 **统一** 处理 **`isBuiltIn` + `tag`** |
+| **仅配置、无框架默认文件** | 旧方案在 **processTemplate** 二次 merge 时易遗漏 | **`processBuiltInComponents`** 在 **parse** 内直接写入 **用户 path 或默认 path** |
+
+### 1.3 RN 子模版
+
+- 与主链路共用同一套 **parse + rulesRunner 选项**（含 **`customBuiltInComponents` 数据**），保证 **import 模版** 与 **页面/组件模版** 行为一致。
+
+## 2. 配置设计
+
+### 2.1 字段位置与类型
+
+```ts
+/** key：微信侧基础组件标签名；value：自定义实现模块路径 */
+customBuiltInComponents?: Record<string, string>
+```
+
+- **Web**：`webConfig.customBuiltInComponents`
+- **RN**：`rnConfig.customBuiltInComponents`（可与 Web 分端配置不同模块）
+
+**与运行时 `mpx.config` 区分**：此处为 **webpack 插件编译期** 配置。
+
+### 2.2 Key 的约定（目标）
+
+- **统一为微信小程序基础组件命名空间下的标签名**（与 **`srcMode` 为 wx 时模版中写的标签** 一致），例如：`view`、`text`、`image`、`scroll-view`；用户 **拓展** 的组件若在微信体系中也按 **基础组件标签** 使用，则同样使用该 **原始 tag 字符串** 作为 key。
+- **不负责** 在配置里写 **`mpx-*`**：命中 **`custom-built-in-component`** 时，运行时名统一为 **`mpx-` + 微信 tag**（与常规内置里多数命名一致；**不再**单独区分 RN 的 `mpx-simple-view` 等分支，由自定义实现按需处理）。
+
+### 2.3 Value（文档约定）
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| 绝对路径 | POSIX **`/`** 开头；Windows **`path.isAbsolute` 为真** | `/abs/MyView.vue` |
+| npm 模块路径 | **`@scope/pkg/...`** 或 **`my-pkg/...`**（首段为合法包名） | `@acme/ui/MpxView.mpx` |
+
+**不支持**：**`~`** 前缀；**`./`、`../`**（及 `.\`、`..\`）等相对路径。
+
+### 2.4 与 `meta.builtInComponentsMap` / `builtInComponentsMap` 的衔接（目标）
+
+- **`meta.builtInComponentsMap`** 的 key 为 **跨平台转换完成后的 `el.tag`**（如 `mpx-view`），在 **`processBuiltInComponents`** 中一次性写入 **用户 path 或框架默认 path**，**不再**在 `processTemplate` 等处以 **`Object.assign`** 二次合并，也 **不需要** `builtInWxToRuntimeMap`。
+
+## 3. 实现方案（修订方向，不写代码）
+
+### 3.1 核心原则
+
+1. **`customBuiltInComponents` 作为 `data` 注入跨平台层**  
+   在 **`getRulesRunner`** 的 **`data`** 对象上挂载 **`customBuiltInComponents`**（与 **`usingComponents`** 并列），由 **`compiler.parse`** 创建 rulesRunner 时 **从 `webConfig` / `rnConfig` 填入**（按 **mode** 取对应端配置）；**`getRulesRunner` 顶层不再单独增加参数**。
+
+2. **在 rulesRunner 规则链路中扩展行为**  
+   - 对 **命中 `customBuiltInComponents` 的 wx 标签** 的节点：与 **`component-config`** 中已有基础组件类似地设置 **`el.isBuiltIn`**（若需与原生内置共存，需约定 **仅 Web/RN 输出** 下生效或与现有规则 **合并优先级**：通常 **用户拓展/替换优先** 或 **仅当框架未声明时补充**，具体以产品约定为准，文档建议 **custom 覆盖同名内置的默认实现路径，但不改变平台分支下的 tag 命名规则**）。  
+   - **标签名转换** 在 **rulesRunner**（含 **`custom-built-in-component`** 与常规 **`component-config`**）中完成。
+
+3. **`processBuiltInComponents`**  
+   在 **`el.isBuiltIn`** 之后按 **`el.tag`** 写入 **`meta.builtInComponentsMap[tag]`**：若 **`el.originalTag`** 在 **`customBuiltInComponents`** 中有配置（由 **`custom-built-in-component`** 规则写入）则用 **用户 path**，否则用 **框架默认 path**；**不支持**以 **`mpx-*`** 为配置 key。
+
+4. **Web app**  
+   维持 **不参与** `customBuiltInComponents`（仅固定 **`mpx-keep-alive`**），除非产品明确要求 app 壳也消费该配置。
+
+### 3.2 已实现（processTemplate）
+
+- **`web/processTemplate.js`、`react/processTemplate.js`、`react/template-loader.js`** 仅消费 **`parse` 产出的 `meta.builtInComponentsMap`**（已由 **`processBuiltInComponents`** 写入最终 path），**不再**二次 merge。
+
+### 3.3 待实现清单（与 rulesRunner 相关）
+
+| 项 | 说明 |
+|----|------|
+| **plugin → compiler** | `parse` 将 **`webConfig.customBuiltInComponents` / `rnConfig.customBuiltInComponents`**（随 **mode**）放入 **`getRulesRunner` 的 `data`**。 |
+| **component-config** | **`custom-built-in-component.js`**：单规则、`skipNormalize`；**`test(tag, meta, data)`** 查 **`data.customBuiltInComponents`**；**`processor(el, data)`** 同上；顺序在 **`fix-component-name`** 之下。 |
+| **processBuiltInComponents** | 无需改为认 wx tag；保持 **转换后 tag** 为 key。 |
+| **processTemplate** | 仅 **`addQuery(meta.builtInComponentsMap)`** 写入 **`builtInComponentsMap`**。 |
+| **文档与示例** | 对外文档 **`compile.md` 等** 中示例 key 改为 **`view`/`text`** 等 wx 名，并说明 **经 rulesRunner 转为 `mpx-*`**。 |
+
+### 3.4 自定义实现组件契约
+
+用户模块仍须满足 **`getComponent(..., { __mpxBuiltIn: true })`** 所需导出与行为；**拓展** 组件需与 **微信基础组件能力**（或团队自定义基础能力）在 props/事件上对齐。
+
+## 4. 错误处理
+
+- **value** 可不强制插件校验，由 **webpack** 报错。  
+- **wx 标签配置了 custom，但 rulesRunner 未注入或未命中**：应 **开发态可观测**（warning 或构建失败），避免 **静默不注册**。  
+- **key 与 `srcMode` 模版标签不一致**（如 ali 下标签名不同）：需在文档中说明 **以当前 `srcMode` 下模版实际标签名为准**，或后续 **增加 srcMode 维度配置**（本方案暂不展开）。
+
+## 5. 测试建议
+
+- **替换**：配置 `view` → 自定义 path，断言 **rulesRunner 后** `el.isBuiltIn` / **运行时 tag** 与 **无 custom 时一致**，且 **require** 指向用户模块。  
+- **扩展**：配置框架 **无静态 component-config** 的 wx 基础标签（或团队约定拓展名），断言 **经 rulesRunner** 进入 **meta** 与 **`builtInComponentsMap`**。  
+- **RN**：**template-loader** 与 **主模版** 各一条。
+
+## 6. 用户示例（目标配置形态）
+
+```js
+const path = require('path')
+
+new MpxWebpackPlugin({
+  mode: 'web',
+  webConfig: {
+    customBuiltInComponents: {
+      view: path.resolve(__dirname, 'src/builtin/web/MyView.vue'),
+      text: '/abs/path/to/MyText.vue'
+    }
+  },
+  rnConfig: {
+    customBuiltInComponents: {
+      view: '@your-org/mpx-rn-builtin/MpxView.mpx',
+      'scroll-view': '@your-org/mpx-rn-builtin/MpxScrollView.mpx'
+    }
+  }
+})
+```
+
+（实际运行时组件名仍为 **`mpx-view`** 等，由 **rulesRunner** 转换，用户 **无需** 在配置里写 `mpx-view`。）
+
+## 7. 风险与后续扩展
+
+- **与现有 `component-config` 重复**：同一 wx 标签 **框架已有** 且 **用户也配置** 时，需约定 **仅替换资源路径** 还是 **整条规则覆盖**；建议 **保留框架 tag 转换规则，仅覆盖默认 module 路径**。  
+- **与常规内置 RN 命名差异**：`custom-built-in-component` 路径下 **一律 `mpx-` + 微信 tag**；若业务仍依赖 `mpx-simple-view` 等，勿对该 wx tag 配置 custom，或自行在自定义组件内适配。  
+- **`mode` 为小程序原生**：不走 Web/RN 内建合并；**rulesRunner 数据** 是否传入需单独约定（通常 **不生效**）。  
+- **srcMode 非 wx**：key 命名是否仍采用「微信基础标签名」需在文档或配置中 **明确**（本方案默认 **仍以 wx 基础组件名为语义锚点**，与 Mpx 主流 **srcMode: wx** 一致）。