From f42051b8b84585761c3add09688cabe5ec921234 Mon Sep 17 00:00:00 2001
From: hiyuki <674883329@qq.com>
Date: Thu, 2 Apr 2026 22:31:57 +0800
Subject: [PATCH 1/4] update skills & support register custom builtin
 components

---
 .../references/rn-json-reference.md           | 433 ++++++++-
 .../references/rn-script-reference.md         | 125 +--
 .../references/rn-style-practice.md           | 323 ++++---
 .../references/rn-style-reference.md          | 193 ++--
 .../references/rn-template-reference.md       | 885 +++++++++---------
 .../references/single-file-component.md       |  15 +-
 AGENTS.md                                     |   4 +-
 docs-vitepress/api/compile.md                 |  80 +-
 .../lib/react/processTemplate.js              |  18 +-
 .../lib/react/template-loader.js              |  14 +-
 .../webpack-plugin/lib/web/processTemplate.js |  13 +-
 solutions/register-custom-builtin.md          | 111 +++
 12 files changed, 1402 insertions(+), 812 deletions(-)
 create mode 100644 solutions/register-custom-builtin.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..9ded9b7d77 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 等。
 
 ## 目录
 
@@ -19,7 +19,6 @@
 
 ### App 构造选项
 
-
 `createApp(options)` 用于注册应用级逻辑与全局字段。**App 不支持数据响应式构造选项**（无 `data` / `computed` / `watch` 等），**也不使用 `provide` / `inject` / `setup`**；全局状态请通过挂载在 `getApp()` 返回对象上的普通字段（如 `globalData`）或业务层单例维护。
 
 页面或其它模块中读取全局数据：`const version = getApp().globalData.version`。
@@ -27,23 +26,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 +70,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>
 ```
 
@@ -135,16 +135,20 @@
 
 ```html
 <template>
-  <view id="box">内容</view>
+  <!-- RN：script 里传给 select* / SelectorQuery / IntersectionObserver 的 #id、.class 须在对应节点上写 wx:ref，编译期建 ref 并与 selector 映射 -->
+  <view id="box" wx:ref="boxRef">内容</view>
 </template>
 <script>
-  import { createPage } from '@mpxjs/core'
+  import { createPage } from "@mpxjs/core"
 
   createPage({
-    ready () {
-      this.createSelectorQuery().select('#box').boundingClientRect().exec((res) => {
-        console.log(res)
-      })
+    ready() {
+      this.createSelectorQuery()
+        .select("#box")
+        .boundingClientRect()
+        .exec((res) => {
+          console.log(res)
+        })
     }
   })
 </script>
@@ -156,11 +160,11 @@
 | `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`**，由编译期创建 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` 对应的懒解析访问器集合，与上述基于 selector 的 API 共用同一套编译期 ref 信息。 |
 | `$watch` | 方法 | 共用 | 动态创建对数据路径或表达式的侦听，返回用于停止侦听的函数，行为与选项式 `watch` 对齐。 |
 | `$forceUpdate` | 方法 | 共用 | 强制触发视图更新，可传入数据对象参与本次刷新，RN 侧由 `MpxProxy` 与 React 更新调度配合完成。 |
 | `$nextTick` | 方法 | 共用 | 在下一轮视图更新完成之后执行回调，用于在数据变更后读取更新后的视图状态。 |
@@ -171,8 +175,10 @@
 
 #### 注意事项
 
-- **`selectComponent` / `selectAllComponents` / `$refs` 与模板 `wx:ref` 配套**：RN 上 ref 选择器仅支持 **`#id` 与 `.class`**，因为底层用 ref 映射而非完整小程序选择器引擎；复合选择器、深层选择器不可用。未在模板声明 `wx:ref` 的节点无法被上述 API 解析到实例。
-- `createSelectorQuery` 的能力边界以 `@mpxjs/api-proxy` 的 RN 实现为准；与真机布局、原生视图层级相关的行为需在设备上验证。
+- **RN 无原生 selector 视图查询**：`selectComponent`、`selectAllComponents`、`createSelectorQuery`（及其 `select` 等链式入参）、`createIntersectionObserver`（涉及相对节点的 selector 时）在小程序里依赖视图层按 selector 查找节点，**RN 底层不支持同等能力**。
+- **须配合模板 `wx:ref`**：在**与 script 中 selector 对应**的节点上添加 **`wx:ref`**（指令名固定为 `wx:ref`，值为 ref 名，可与 `id` / `class` 并存），由 **Mpx 在编译期创建 ref**，并**建立 `#id` 与 `.class` 和 ref / 节点的映射**，从而在 RN 上**兼容**上述 API 在小程序中的写法。
+- **选择器形态受限**：映射仅覆盖 **`#id` 与 `.class`**，不支持复合选择器、后代 / 子代等小程序其它选择器语法；未声明 `wx:ref` 的节点无法被这些 API 解析。
+- **`createSelectorQuery` / `createIntersectionObserver` 的其余行为**（字段类型、布局测量、交叉比例等）仍以 `@mpxjs/api-proxy` 的 RN 实现为准，与真机布局、原生视图层级相关的能力请在设备上验证。
 
 ---
 
@@ -181,18 +187,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++
+    }
   }
 })
 ```
@@ -217,13 +229,13 @@ createPage({
 在 **`setup(props, context)`** 或 **`script setup`** 中使用：从 `@mpxjs/core` 导入响应式 API、生命周期钩子、`provide` / `inject` 等。钩子须在 **`setup` 执行期间同步注册**，依赖当前正在创建的实例上下文。
 
 ```js
-import { createComponent, ref, computed, onMounted, provide } from '@mpxjs/core'
+import { createComponent, ref, computed, onMounted, provide } from "@mpxjs/core"
 
 createComponent({
-  setup (props, context) {
+  setup(props, context) {
     const n = ref(0)
     const doubled = computed(() => n.value * 2)
-    provide('token', 'demo')
+    provide("token", "demo")
     onMounted(() => {
       console.log(n.value, context.refs)
     })
@@ -236,14 +248,14 @@ createComponent({
 | --- | --- | --- |
 | `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.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`。 |
+| `context.selectComponent` | `(selector) => instance` | 同实例 `selectComponent`，RN 上 **selector 须由模板 `wx:ref` 参与编译映射**。 |
+| `context.selectAllComponents` | `(selector) => instance[]` | 同实例 `selectAllComponents`，规则同上。 |
+| `context.createSelectorQuery` | `() => SelectorQuery` | 同实例 `createSelectorQuery`，**`select` 等链式 selector** 在 RN 上同样依赖 **`wx:ref`** 映射。 |
+| `context.createIntersectionObserver` | `(options?) => IntersectionObserver` | 同实例 `createIntersectionObserver`，涉及 **selector 相对节点** 时在 RN 上同样依赖 **`wx:ref`** 映射。 |
 | `ref` | 基本引用容器 | 与 Vue 3 类似，可用于 `setup` 返回值驱动模板。 |
 | `shallowRef` | 浅层 `ref` | 与 Vue 3 类似，深层属性变更不自动触发依赖。 |
 | `unref` | 解包 `ref` | 与 Vue 3 类似。 |
@@ -282,12 +294,10 @@ createComponent({
 | `onReactHooksExec` | 与 RN 渲染协同 | 框架内部使用为主。 |
 | `useI18n` | 见 i18n 文档 | 工程启用 i18n 时可用。 |
 
-#### setup script
-
 #### 注意事项
 
 - 组合式生命周期 **禁止在异步回调里再注册**，否则会丢失当前实例上下文。
-- `refs` 在 `onMounted` 及之后才可靠；与模板 `wx:ref` 的 RN 限制相同。
+- `context.refs` 及 **`selectComponent` / `selectAllComponents` / `createSelectorQuery` / `createIntersectionObserver`** 在 RN 上与选项式相同：`refs` 在 `onMounted` 及之后更可靠，**凡传入 `#id` / `.class` 的用法均须在模板对应节点声明 `wx:ref`**，详见「页面 / 组件实例方法与属性」注意事项。
 
 ---
 
@@ -326,33 +336,33 @@ setAppHide()
 运行时对象 **`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 +370,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` 等组件路径配置，偏构建与运行时加载。 |
 
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..d6fbf39116 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
@@ -48,7 +48,7 @@
 Mpx 跨端输出 RN 时，支持以下模板指令。
 
 | 指令 | 支持状态 | 说明 | 示例 |
-|------|---------|------|------|
+| --- | --- | --- | --- |
 | wx:if | ✅ | 条件渲染 | `<view wx:if="{{condition}}">...</view>` |
 | wx:else | ✅ | 条件渲染 | `<view wx:else>...</view>` |
 | wx:elif | ✅ | 条件渲染 | `<view wx:elif="{{condition}}">...</view>` |
@@ -71,29 +71,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 +99,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>
 ```
 
 **事件内联传参**
@@ -127,7 +121,7 @@ Mpx 支持了事件内联传参机制。
 <script setup>
   // 直接通过参数获取数据，直观方便
   const handleTapInline = (params) => {
-    console.log('params:', params)
+    console.log("params:", params)
   }
   // ...
 </script>
@@ -140,24 +134,22 @@ 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'])
+  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');
+    console.log("Tapped on item 1")
   }
   const handleTap_1 = (event) => {
-    console.log('Tapped on item 2');
+    console.log("Tapped on item 2")
   }
   const handleTap_2 = (event) => {
-    console.log('Tapped on item 3');
+    console.log("Tapped on item 3")
   }
   const handleTap_3 = (event) => {
-    console.log('Tapped on item 4');
+    console.log("Tapped on item 4")
   }
   // ...
 </script>
@@ -178,428 +170,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 +611,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 +644,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..79af2b1a04 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` 文件都包含了以下几个部分：
 
@@ -18,18 +18,15 @@ Mpx 单文件组件（SFC）格式 `.mpx` 是一种将组件的视图模板、
 </template>
 <!--对应.js文件-->
 <script>
-  import { createPage } from '@mpxjs/core'
+  import { createPage } from "@mpxjs/core"
 
   createPage({
-    onLoad () {
-    },
-    onReady () {
-    }
+    onLoad() {},
+    onReady() {}
   })
 </script>
 <!--对应.wxss文件-->
-<style lang="stylus">
-</style>
+<style lang="stylus"></style>
 <!--对应.json文件-->
 <script type="application/json">
   {
@@ -39,5 +36,3 @@ Mpx 单文件组件（SFC）格式 `.mpx` 是一种将组件的视图模板、
   }
 </script>
 ```
-
-
diff --git a/AGENTS.md b/AGENTS.md
index f055b099a9..079712f824 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,12 +6,14 @@
 
 ## 偏好指引
 
-- 开发新特性时尽量参考具有相似性的已有的流程实现，尽可能复用当前已有的流程实现，或者保持与已有流程实现的相似性
+- 开发新特性时尽量参考具有相似性的已有流程实现，尽可能复用当前已有流程实现，或者保持与已有流程实现的相似性
 - 编写代码时尽可能保持简洁精炼，避免无效的冗余代码，例如：
   - 避免声明不必要的中间变量
   - 避免编写不必要的中间步骤
   - 避免添加不必要的兜底值
   - 避免添加不必要的容错判断
+- 代码风格尽可能模仿当前仓库中现有的写法，例如：
+  - 遍历数组用.forEach而不是for()
 
 
 ## 强制约束
diff --git a/docs-vitepress/api/compile.md b/docs-vitepress/api/compile.md
index 85a5b5a617..8e7ba984ab 100644
--- a/docs-vitepress/api/compile.md
+++ b/docs-vitepress/api/compile.md
@@ -818,7 +818,7 @@ module.exports = defineConfig({
 })
 ```
 
-### webConfig
+### webConfig {#web-config}
 
 `{transRpxFn(match:string, $1:number): string}`
 
@@ -832,6 +832,14 @@ useSSR 默认值为 `false`，当 SSR 模式下使用异步分包时，需要将
 
 用于配置禁用/开启页面切换动画，默认禁用
 
+`{customBuiltInComponents?: Record<string, string>}`
+
+仅 **`mode === 'web'`** 且 **非 app 入口**（存在用户模版并参与 `parse`）时生效，用于覆盖框架默认的内建基础组件实现。
+
+- **key**：运行时内建标签名（如 `mpx-view`、`mpx-text`），与编译产物中的内建 tag 一致，而非微信侧的 `view`、`text`。
+- **value**（**文档约定**，插件 **不做格式校验**）：须为 **绝对路径**（POSIX 下以 **`/`** 开头的路径，或 Windows 下 **`path.isAbsolute` 为真的路径**），或 **以 npm 包名开头的模块路径**（作用域包如 **`@scope/pkg/...`**；无作用域包如 **`my-pkg/...`**，首段须为合法包名，避免使用 `src/` 等易被误认为工程相对路径的写法）。**不要使用** **`./`、`../`** 等相对路径；**不要使用**以 **`~`** 开头的 webpack 模块前缀。不符合约定时由 **webpack 解析**等环节报错。
+
+合并规则：`Object.assign({}, meta.builtInComponentsMap, customBuiltInComponents || {})`，同 key 时用户配置覆盖框架默认。**app** 入口仅注入固定的 `mpx-keep-alive`，不参与 `customBuiltInComponents` 合并。
 
 ```js
 // mpx.config.js
@@ -847,7 +855,75 @@ module.exports = defineConfig({
           // 当 SSR 模式下使用异步分包时
           useSSR: true,
           // 开启页面切换动画
-          disablePageTransition: false
+          disablePageTransition: false,
+          customBuiltInComponents: {
+            'mpx-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
+
+`Record<string, string> | undefined`
+
+与 [webConfig.customBuiltInComponents](#web-config) 类似，但作用于 **RN 输出**：在 `react/processTemplate.js` 与 `react/template-loader.js` 中，于 `templateCompiler.parse` 得到 `meta.builtInComponentsMap` 之后，与 **`Object.assign`** 合并再 `addQuery`。
+
+**value 约定与 Web 一致**（插件不校验）：仅 **绝对路径** 或 **以 npm 包名开头的路径**（`@scope/pkg/...` 或 `my-pkg/...`）；**禁止** `./`、`../` 及 **`~`** 前缀；详见 [webConfig.customBuiltInComponents](#web-config)。
+
+#### 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: {
+            'mpx-view': '@your-org/mpx-rn-builtin/MpxView.mpx',
+            'mpx-text': path.resolve(__dirname, 'src/builtin/MpxText.mpx')
+          }
         }
       }
     }
diff --git a/packages/webpack-plugin/lib/react/processTemplate.js b/packages/webpack-plugin/lib/react/processTemplate.js
index 1f9eb21f38..5374a65ae3 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 = {}
@@ -147,13 +148,12 @@ module.exports = function (template, {
         }
       }
 
-      if (meta.builtInComponentsMap) {
-        Object.keys(meta.builtInComponentsMap).forEach((name) => {
-          builtInComponentsMap[name] = {
-            resource: addQuery(meta.builtInComponentsMap[name], { isComponent: true })
-          }
-        })
-      }
+      const mergedPaths = Object.assign({}, meta.builtInComponentsMap || {}, (rnConfig && rnConfig.customBuiltInComponents) || {})
+      Object.keys(mergedPaths).forEach((name) => {
+        builtInComponentsMap[name] = {
+          resource: addQuery(mergedPaths[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..8596e507fe 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)
@@ -69,13 +70,12 @@ module.exports = function (content) {
     })
   }
 
+  const mergedPaths = Object.assign({}, meta.builtInComponentsMap || {}, (rnConfig && rnConfig.customBuiltInComponents) || {})
   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(mergedPaths).forEach((componentName) => {
+    const componentRequest = loaderUtils.stringifyRequest(loaderContext, addQuery(mergedPaths[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/web/processTemplate.js b/packages/webpack-plugin/lib/web/processTemplate.js
index c66ee30839..700c262944 100644
--- a/packages/webpack-plugin/lib/web/processTemplate.js
+++ b/packages/webpack-plugin/lib/web/processTemplate.js
@@ -109,13 +109,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 mergedPaths = Object.assign({}, meta.builtInComponentsMap || {}, (webConfig && webConfig.customBuiltInComponents) || {})
+        Object.keys(mergedPaths).forEach((name) => {
+          builtInComponentsMap[name] = {
+            resource: addQuery(mergedPaths[name], { isComponent: true })
+          }
+        })
         if (meta.genericsInfo) {
           genericsInfo = meta.genericsInfo
         }
diff --git a/solutions/register-custom-builtin.md b/solutions/register-custom-builtin.md
new file mode 100644
index 0000000000..8e34962335
--- /dev/null
+++ b/solutions/register-custom-builtin.md
@@ -0,0 +1,111 @@
+# 输出 Web 和 RN 时支持用户注册自定义的内建基础组件
+
+## 需求描述
+
+当前 Mpx 框架内在 `webpack-plugin/lib/runtime/components/react|web` 中维护了同微信小程序基础组件一致的内建组件，在编译时将模版中的用户编写的基础组件映射转换为框架内建组件实现（如 `view` → `mpx-view`），现在希望通过开放 `webpack-plugin` 中的配置，提供用户注册自定义内建组件的能力，对应配置可以提供到 `webpack-plugin` 的 `webConfig` 和 `rnConfig` 中，配置名为 `customBuiltInComponents`，key 为基础组件 tag 名，value 为自定义内建实现路径（约定见下文 **Value（文档约定）**，插件侧不做校验）。
+
+## 1. 现状与数据流
+
+### 1.1 编译侧
+
+- 各基础组件在 `packages/webpack-plugin/lib/platform/template/wx/component-config/*.js` 中通过 `el.isBuiltIn = true` 及 `web` / `ios` / `android` 等钩子把源码标签（如 `view`）转换为输出端标签（Web 下多为 `mpx-view`，RN 下为 `mpx-view` / `mpx-simple-view` 等）。
+- `packages/webpack-plugin/lib/template-compiler/compiler.js` 中 `processBuiltInComponents` 在遇到 `el.isBuiltIn` 时，向 `meta.builtInComponentsMap` 写入 **当前节点上的 `el.tag`（已是转换后的标签名）** 到默认实现路径的映射：
+  - RN：`@mpxjs/webpack-plugin/lib/runtime/components/react/dist/${tag}`
+  - Web：`@mpxjs/webpack-plugin/lib/runtime/components/${mode}/${tag}`
+- `packages/webpack-plugin/lib/web/processTemplate.js` 与 `packages/webpack-plugin/lib/react/processTemplate.js` 在 `parse` 完成后，把 `meta.builtInComponentsMap` 与用户 `customBuiltInComponents` 合并后写入 `builtInComponentsMap`（经 `addQuery(..., { isComponent: true })`），再交给 `processScript` → `buildComponentsMap`，生成 `getComponent(require(...), { __mpxBuiltIn: true })` 形式的注册代码。
+
+### 1.2 RN 子模版
+
+- `packages/webpack-plugin/lib/react/template-loader.js` 对内联/引入的 `.wxml` 模版再次调用 `templateCompiler.parse`，并单独生成内建映射。自定义内建必须在 **主链路 processTemplate 与 template-loader** 两处一并处理。
+
+## 2. 配置设计
+
+### 2.1 字段位置与类型
+
+在 **`MpxWebpackPlugin` 插件选项**（编译期）中已有 `webConfig`、`rnConfig`（见 `packages/webpack-plugin/lib/index.js` 初始化）。在其上增加可选字段：
+
+```ts
+customBuiltInComponents?: Record<string, string>
+```
+
+- **Web**：`webConfig.customBuiltInComponents`
+- **RN**：`rnConfig.customBuiltInComponents`
+
+**与运行时配置区分**：`mpx.config.webConfig` / `mpx.config.rnConfig` 为运行时使用；插件选项里的 `webConfig` / `rnConfig` 为编译期对象，二者不是同一引用。`customBuiltInComponents` **仅**在插件侧读取。
+
+### 2.2 Key 的约定
+
+配置 key 为 **运行时内建标签名**（如 `mpx-view`、`mpx-text`），与 `meta.builtInComponentsMap` 及 `processBuiltInComponents` 中 `el.tag` 一致，而非微信侧 `view`、`text`。
+
+### 2.3 Value（文档约定，插件不校验）
+
+**约定**（由业务与文档遵守；**`@mpxjs/webpack-plugin` 不对 value 做格式校验**，错误配置由 webpack 解析失败等方式暴露）：
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| 绝对路径 | POSIX 下以 **`/`** 开头的绝对路径；Windows 下 **`path.isAbsolute` 为真**的路径（盘符路径等） | `/Users/proj/src/a.vue`、`C:\proj\src\a.vue` |
+| npm 包路径 | **作用域包**：以 **`@scope/pkg/`** 形式开头（`@` + scope + `/` + 包名 + `/` + 子路径） | `@acme/ui-rn/MpxView.mpx` |
+| npm 包路径 | **无作用域包**：字符串以 **npm 包名** 开头，即首段为合法包名片段，后可跟 `/子路径`；避免写成易被误认为工程目录相对路径的形式（如不要用 `src/...` 冒充包名） | `my-builtin-pkg/MpxText.mpx` |
+
+**明确不支持 / 禁止写入约定**：
+
+- **不支持**以 **`~`** 开头的 webpack 模块前缀（不要使用 `~pkg/...`）。
+- **不要使用** **`./`、`../`**（及 **`.\\`、`..\\`**）等相对路径。
+
+合并方式：**`Object.assign({}, meta.builtInComponentsMap, customBuiltInComponents || {})`**，再对合并结果逐项 **`addQuery(..., { isComponent: true })`**。
+
+## 3. 实现方案（已落地）
+
+### 3.1 总体策略
+
+- **不改变** `compiler.js` 中默认 `meta.builtInComponentsMap` 的生成。
+- **Web app**（`ctorType === 'app'`）：仅注入固定的 **`mpx-keep-alive`**，**不**读取 **`webConfig.customBuiltInComponents`**。
+- **Web 非 app / RN**：在拿到 **`meta`** 后（Web 在 `parse` 回调内；RN 主链路与 `template-loader` 各一处）做上述合并并写入产物。
+
+### 3.2 修改文件
+
+| 文件 | 行为 |
+|------|------|
+| `packages/webpack-plugin/lib/web/processTemplate.js` | app 只写 keep-alive；非 app 在 parse 后 `Object.assign` + `addQuery`。 |
+| `packages/webpack-plugin/lib/react/processTemplate.js` | 有 `template.content` 且 parse 后同上（`rnConfig.customBuiltInComponents`）。 |
+| `packages/webpack-plugin/lib/react/template-loader.js` | parse 后同上。 |
+
+### 3.3 自定义实现组件契约
+
+替换实现应尽可能与被替换内建在 props、事件、子节点等行为上一致；导出形态需与 web/vue 或 react 内建兼容，以便 `getComponent(..., { __mpxBuiltIn: true })` 与样式、事件代理正常工作。
+
+## 4. 错误处理
+
+- 插件 **不对** `customBuiltInComponents` 的 value 做合法性校验；路径无法解析等问题由 **webpack 构建**暴露。
+
+## 5. 测试建议
+
+- Web / RN：按 §2.3 约定配置绝对路径、`@scope/pkg/...`、无作用域包名路径，断言产物 `require` 目标正确。
+
+## 6. 用户示例
+
+```js
+const path = require('path')
+
+new MpxWebpackPlugin({
+  mode: 'web',
+  webConfig: {
+    customBuiltInComponents: {
+      'mpx-view': path.resolve(__dirname, 'src/builtin/web/MpxView.vue'),
+      'mpx-text': '/abs/path/to/MpxText.vue'
+    }
+  },
+  rnConfig: {
+    customBuiltInComponents: {
+      'mpx-view': '@your-org/mpx-rn-builtin/MpxView.mpx',
+      'mpx-scroll-view': '@your-org/mpx-rn-builtin/MpxScrollView.mpx'
+    }
+  }
+})
+```
+
+## 7. 风险与后续扩展
+
+- RN 上同一微信标签可能对应 `mpx-simple-view` 等，需按实际 AST 中的 tag 配置。
+- `mode` 为小程序原生输出时不走上述 Web/RN 合并逻辑。
+- 若需支持「微信 tag 为 key」的别名，需另做映射层。

From 81276044f2d46a6bf76665867f5e6f3ad4542b71 Mon Sep 17 00:00:00 2001
From: hiyuki <674883329@qq.com>
Date: Wed, 15 Apr 2026 20:52:16 +0800
Subject: [PATCH 2/4] support rn&web customBuiltInComponents & update skills

---
 .../references/rn-api-reference.md            | 1581 +++++++++++++++++
 .../references/rn-global-config.md            |    0
 .../references/rn-script-reference.md         |  618 +++++--
 .../references/rn-template-reference.md       |  302 +++-
 .../references/single-file-component.md       |  107 +-
 AGENTS.md                                     |    5 +-
 docs-vitepress/api-proxy/index.md             |   25 +-
 docs-vitepress/api/compile.md                 |   58 +-
 docs-vitepress/guide/advance/pinia.md         |    2 +-
 .../src/platform/api/system/index.ios.js      |    2 +-
 .../webpack-plugin/lib/platform/run-rules.js  |    2 +-
 .../template/wx/component-config/index.js     |    2 +
 .../lib/platform/template/wx/index.js         |    2 +-
 .../lib/react/processTemplate.js              |    9 +-
 .../lib/react/template-loader.js              |    9 +-
 .../lib/template-compiler/compiler.js         |   25 +-
 .../webpack-plugin/lib/web/processTemplate.js |    9 +-
 solutions/register-custom-builtin.md          |  129 +-
 18 files changed, 2654 insertions(+), 233 deletions(-)
 delete mode 100644 .agents/skills/mpx-rn-style-guide/references/rn-global-config.md

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-global-config.md
deleted file mode 100644
index e69de29bb2..0000000000
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 9ded9b7d77..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
@@ -10,8 +10,15 @@
   - [页面 / 组件实例方法与属性](#页面--组件实例方法与属性)
 - [数据响应](#数据响应)
 - [组合式 API](#组合式-api)
+  - [`setup` 的第一个参数 `props`](#setup-的第一个参数-props)
+  - [`setup` 的第二个参数 `context`](#setup-的第二个参数-context)
+- [Mpx 运行时导出](#mpx-运行时导出)
+  - [默认导出](#默认导出)
+  - [命名导出](#命名导出)
 - [全局 API](#全局-api)
 - [Mpx.config.rnConfig](#mpxconfigrnConfig)
+- [环境 API](#环境-api)
+- [状态管理](#状态管理)
 
 ---
 
@@ -133,53 +140,65 @@
 
 ### 页面 / 组件实例方法与属性
 
+| 名称 | 类型 | 适用 | 说明 |
+| --- | --- | --- | --- |
+| `route` | 属性 | 页面 | 当前路由名（screen name）。 |
+| `getPageId()` | 方法 | 共用 | 返回当前实例所在页的 pageId 字符串。 |
+| `getOpenerEventChannel()` | 方法 | 页面 | 打开当前页的 `EventChannel`，组件侧多为空实现占位。 |
+| `triggerEvent(name, detail?)` | 方法 | 组件 | 向父节点派发自定义事件。 |
+| `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` | 方法 | 共用 | 删除响应式对象的属性并触发视图更新，用于需移除键且保持响应式一致性的场景。 |
+| `$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`、`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>
-  <!-- RN：script 里传给 select* / SelectorQuery / IntersectionObserver 的 #id、.class 须在对应节点上写 wx:ref，编译期建 ref 并与 selector 映射 -->
-  <view id="box" wx:ref="boxRef">内容</view>
+  <!-- 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>
 ```
 
-| 名称 | 类型 | 适用 | 说明 |
-| --- | --- | --- | --- |
-| `route` | 属性 | 页面 | 当前路由名（screen name）。 |
-| `getPageId()` | 方法 | 共用 | 返回当前实例所在页的 pageId 字符串。 |
-| `getOpenerEventChannel()` | 方法 | 页面 | 打开当前页的 `EventChannel`，组件侧多为空实现占位。 |
-| `triggerEvent(name, detail?)` | 方法 | 组件 | 向父节点派发自定义事件。 |
-| `selectComponent(selector)` | 方法 | 共用 | 按选择器取第一个匹配实例。RN 不能像小程序一样按 selector 遍历视图树，须在模板目标节点上声明 **`wx:ref`**，由编译期创建 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` 对应的懒解析访问器集合，与上述基于 selector 的 API 共用同一套编译期 ref 信息。 |
-| `$watch` | 方法 | 共用 | 动态创建对数据路径或表达式的侦听，返回用于停止侦听的函数，行为与选项式 `watch` 对齐。 |
-| `$forceUpdate` | 方法 | 共用 | 强制触发视图更新，可传入数据对象参与本次刷新，RN 侧由 `MpxProxy` 与 React 更新调度配合完成。 |
-| `$nextTick` | 方法 | 共用 | 在下一轮视图更新完成之后执行回调，用于在数据变更后读取更新后的视图状态。 |
-| `$set` | 方法 | 共用 | 向响应式对象添加新属性并保证其为响应式且触发视图更新，等价于对「无法被自动侦测的新增属性」的补充。 |
-| `$delete` | 方法 | 共用 | 删除响应式对象的属性并触发视图更新，用于需移除键且保持响应式一致性的场景。 |
-| `setData` | 方法 | 共用 | 兼容 API，内部走强制更新。 |
-| `__componentPath` | 属性 | 组件 | 编译注入的组件路径，供 relations 等内部逻辑使用。 |
-
-#### 注意事项
-
-- **RN 无原生 selector 视图查询**：`selectComponent`、`selectAllComponents`、`createSelectorQuery`（及其 `select` 等链式入参）、`createIntersectionObserver`（涉及相对节点的 selector 时）在小程序里依赖视图层按 selector 查找节点，**RN 底层不支持同等能力**。
-- **须配合模板 `wx:ref`**：在**与 script 中 selector 对应**的节点上添加 **`wx:ref`**（指令名固定为 `wx:ref`，值为 ref 名，可与 `id` / `class` 并存），由 **Mpx 在编译期创建 ref**，并**建立 `#id` 与 `.class` 和 ref / 节点的映射**，从而在 RN 上**兼容**上述 API 在小程序中的写法。
-- **选择器形态受限**：映射仅覆盖 **`#id` 与 `.class`**，不支持复合选择器、后代 / 子代等小程序其它选择器语法；未声明 `wx:ref` 的节点无法被这些 API 解析。
-- **`createSelectorQuery` / `createIntersectionObserver` 的其余行为**（字段类型、布局测量、交叉比例等）仍以 `@mpxjs/api-proxy` 的 RN 实现为准，与真机布局、原生视图层级相关的能力请在设备上验证。
-
 ---
 
 ## 数据响应
@@ -226,112 +245,183 @@ 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({
+  properties: {
+    title: String
+  },
   setup(props, context) {
+    const { title } = toRefs(props)
     const n = ref(0)
     const doubled = computed(() => n.value * 2)
     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`，RN 上 **selector 须由模板 `wx:ref` 参与编译映射**。 |
-| `context.selectAllComponents` | `(selector) => instance[]` | 同实例 `selectAllComponents`，规则同上。 |
-| `context.createSelectorQuery` | `() => SelectorQuery` | 同实例 `createSelectorQuery`，**`select` 等链式 selector** 在 RN 上同样依赖 **`wx:ref`** 映射。 |
-| `context.createIntersectionObserver` | `(options?) => IntersectionObserver` | 同实例 `createIntersectionObserver`，涉及 **selector 相对节点** 时在 RN 上同样依赖 **`wx:ref`** 映射。 |
-| `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 时可用。 |
+| `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`** 映射。 |
 
 #### 注意事项
 
-- 组合式生命周期 **禁止在异步回调里再注册**，否则会丢失当前实例上下文。
-- `context.refs` 及 **`selectComponent` / `selectAllComponents` / `createSelectorQuery` / `createIntersectionObserver`** 在 RN 上与选项式相同：`refs` 在 `onMounted` 及之后更可靠，**凡传入 `#id` / `.class` 的用法均须在模板对应节点声明 `wx:ref`**，详见「页面 / 组件实例方法与属性」注意事项。
+- 组合式生命周期 **禁止在异步回调里注册**，否则会丢失当前实例上下文。
+- `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.use`** 安装的插件会合并到 **`Mpx` 静态对象**与 **`Mpx.prototype`**，若与业务自定义全局名冲突，可为插件传入 **`prefix` / `postfix`** 选项。
 
-## mpx.config.rnConfig
+## Mpx.config.rnConfig
 
 运行时对象 **`Mpx.config.rnConfig`**（`Mpx` 为 `@mpxjs/core` 默认导出）用于扩展 RN 导航、分包、状态栏等行为。下列为脚本侧常见项（以源码为准，未列项可能随版本增加）。
 
@@ -380,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-template-reference.md b/.agents/skills/mpx-rn-style-guide/references/rn-template-reference.md
index d6fbf39116..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,6 +54,60 @@
   - [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 时，支持以下模板指令。
@@ -118,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>
 ```
 
@@ -136,22 +205,30 @@ Mpx 也支持使用 `{{}}` 插值进行动态事件绑定。
   <!--动态事件绑定-->
   <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")
-  }
-  const handleTap_3 = (event) => {
-    console.log("Tapped on item 4")
+<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')
+    }
   }
-  // ...
+})
 </script>
 ```
 
@@ -162,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 支持的基础组件如下：
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 79af2b1a04..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
@@ -9,30 +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 079712f824..0d2ce9066d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,11 +6,14 @@
 
 ## 偏好指引
 
-- 开发新特性时尽量参考具有相似性的已有流程实现，尽可能复用当前已有流程实现，或者保持与已有流程实现的相似性
+- 设计技术方案时尽量参考具有相似性的已有流程实现，尽可能复用当前已有流程实现，或者保持与已有流程实现的相似性
+- 技术实现时尽可能复用现有流程与工具方法，追求最小的变动进行实现
 - 编写代码时尽可能保持简洁精炼，避免无效的冗余代码，例如：
   - 避免声明不必要的中间变量
   - 避免编写不必要的中间步骤
   - 避免添加不必要的兜底值
+  - 避免类似 `|| 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 8e7ba984ab..0986ea4e16 100644
--- a/docs-vitepress/api/compile.md
+++ b/docs-vitepress/api/compile.md
@@ -820,26 +820,47 @@ module.exports = defineConfig({
 
 ### 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`**；其它场景保持默认即可。
 
-`{customBuiltInComponents?: Record<string, string>}`
+#### webConfig.disablePageTransition {#webconfig-disablepagetransition}
+
+`boolean = true`
 
-仅 **`mode === 'web'`** 且 **非 app 入口**（存在用户模版并参与 `parse`）时生效，用于覆盖框架默认的内建基础组件实现。
+为 `true` 时 **禁用** 页面切换动画；设为 **`false`** 可 **开启** 切换过渡效果。
+
+#### webConfig.customBuiltInComponents {#webconfig-custombuiltincomponents}
+
+`Record<string, string> | undefined`
 
-- **key**：运行时内建标签名（如 `mpx-view`、`mpx-text`），与编译产物中的内建 tag 一致，而非微信侧的 `view`、`text`。
-- **value**（**文档约定**，插件 **不做格式校验**）：须为 **绝对路径**（POSIX 下以 **`/`** 开头的路径，或 Windows 下 **`path.isAbsolute` 为真的路径**），或 **以 npm 包名开头的模块路径**（作用域包如 **`@scope/pkg/...`**；无作用域包如 **`my-pkg/...`**，首段须为合法包名，避免使用 `src/` 等易被误认为工程相对路径的写法）。**不要使用** **`./`、`../`** 等相对路径；**不要使用**以 **`~`** 开头的 webpack 模块前缀。不符合约定时由 **webpack 解析**等环节报错。
+在 **Web 输出**（**`mode === 'web'`**）、且 **非 app 入口**（存在参与编译的用户模版）时生效，用于 **替换或扩展** 框架对某一微信基础标签在 Web 侧的内建实现。
 
-合并规则：`Object.assign({}, meta.builtInComponentsMap, customBuiltInComponents || {})`，同 key 时用户配置覆盖框架默认。**app** 入口仅注入固定的 `mpx-keep-alive`，不参与 `customBuiltInComponents` 合并。
+**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
@@ -857,7 +878,7 @@ module.exports = defineConfig({
           // 开启页面切换动画
           disablePageTransition: false,
           customBuiltInComponents: {
-            'mpx-view': require('path').resolve(__dirname, 'src/builtin/MpxView.vue')
+            view: require('path').resolve(__dirname, 'src/builtin/MpxView.vue')
           }
         }
       }
@@ -891,13 +912,16 @@ module.exports = defineConfig({
 - **timeout**：传给内部 `LoadAsyncChunkModule` 的超时时间（毫秒级用途，见 `@mpxjs/webpack-plugin` 实现）。
 - **fallback** / **loading**：异步页面/组件的占位与 loading 组件资源路径（经 `addQuery(..., { isComponent: true })` 参与打包），在 `react/script-helper.js` 中生成异步包装代码时使用。
 
-#### rnConfig.customBuiltInComponents
+#### rnConfig.customBuiltInComponents {#rnconfig-custombuiltincomponents}
 
 `Record<string, string> | undefined`
 
-与 [webConfig.customBuiltInComponents](#web-config) 类似，但作用于 **RN 输出**：在 `react/processTemplate.js` 与 `react/template-loader.js` 中，于 `templateCompiler.parse` 得到 `meta.builtInComponentsMap` 之后，与 **`Object.assign`** 合并再 `addQuery`。
+在 **RN 输出**（**`mode`** 为 **`ios` / `android` / `harmony`** 等）时生效。与 [webConfig.customBuiltInComponents](#webconfig-custombuiltincomponents) 的 **key、value 约定及注意事项** 相同，仅在 **`rnConfig`** 中配置，便于与 Web 使用不同的模块路径。
+
+**注意事项**
 
-**value 约定与 Web 一致**（插件不校验）：仅 **绝对路径** 或 **以 npm 包名开头的路径**（`@scope/pkg/...` 或 `my-pkg/...`）；**禁止** `./`、`../` 及 **`~`** 前缀；详见 [webConfig.customBuiltInComponents](#web-config)。
+- 页面/组件 **主模版** 以及 **子模版**（如通过 import 引入的模版）均会应用本配置。
+- **key / value** 及路径书写要求与 Web 一节一致，此处不再重复；详见 [webConfig.customBuiltInComponents](#webconfig-custombuiltincomponents)。
 
 #### rnConfig.loadChunkAsync（运行时）
 
@@ -921,8 +945,8 @@ module.exports = defineConfig({
             loading: path.resolve(__dirname, 'src/rn/PageLoading.mpx')
           },
           customBuiltInComponents: {
-            'mpx-view': '@your-org/mpx-rn-builtin/MpxView.mpx',
-            'mpx-text': path.resolve(__dirname, 'src/builtin/MpxText.mpx')
+            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/index.js b/packages/webpack-plugin/lib/platform/template/wx/component-config/index.js
index 1535a9a4f1..33565bbf24 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,6 +40,7 @@ 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')
@@ -84,6 +85,7 @@ module.exports = function getComponentConfigs ({ warn, error }) {
   // 转换规则只需以微信为基准配置微信和支付宝的差异部分，比如微信和支付宝都支持但是写法不一致，或者微信支持而支付宝不支持的部分(抛出错误或警告)
   return [
     fixComponentName({ print }),
+    customBuiltInComponent(),
     ...unsupported({ print }),
     ad({ print }),
     view({ print }),
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 5374a65ae3..fc617b040c 100644
--- a/packages/webpack-plugin/lib/react/processTemplate.js
+++ b/packages/webpack-plugin/lib/react/processTemplate.js
@@ -112,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)
 
@@ -148,10 +149,10 @@ module.exports = function (template, {
         }
       }
 
-      const mergedPaths = Object.assign({}, meta.builtInComponentsMap || {}, (rnConfig && rnConfig.customBuiltInComponents) || {})
-      Object.keys(mergedPaths).forEach((name) => {
+      const builtInPaths = meta.builtInComponentsMap || {}
+      Object.keys(builtInPaths).forEach((name) => {
         builtInComponentsMap[name] = {
-          resource: addQuery(mergedPaths[name], { isComponent: true })
+          resource: addQuery(builtInPaths[name], { isComponent: true })
         }
       })
       if (meta.genericsInfo) {
diff --git a/packages/webpack-plugin/lib/react/template-loader.js b/packages/webpack-plugin/lib/react/template-loader.js
index 8596e507fe..2e2a65b495 100644
--- a/packages/webpack-plugin/lib/react/template-loader.js
+++ b/packages/webpack-plugin/lib/react/template-loader.js
@@ -49,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
@@ -70,10 +71,10 @@ module.exports = function (content) {
     })
   }
 
-  const mergedPaths = Object.assign({}, meta.builtInComponentsMap || {}, (rnConfig && rnConfig.customBuiltInComponents) || {})
+  const builtInPaths = meta.builtInComponentsMap || {}
   const builtInComponents = []
-  Object.keys(mergedPaths).forEach((componentName) => {
-    const componentRequest = loaderUtils.stringifyRequest(loaderContext, addQuery(mergedPaths[componentName], { isComponent: 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 }) }`)
   })
 
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 700c262944..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,10 +110,10 @@ module.exports = function (template, {
             wxsContentMap[`${rawResourcePath}~${module}`] = meta.wxsContentMap[module]
           }
         }
-        const mergedPaths = Object.assign({}, meta.builtInComponentsMap || {}, (webConfig && webConfig.customBuiltInComponents) || {})
-        Object.keys(mergedPaths).forEach((name) => {
+        const builtInPaths = meta.builtInComponentsMap || {}
+        Object.keys(builtInPaths).forEach((name) => {
           builtInComponentsMap[name] = {
-            resource: addQuery(mergedPaths[name], { isComponent: true })
+            resource: addQuery(builtInPaths[name], { isComponent: true })
           }
         })
         if (meta.genericsInfo) {
diff --git a/solutions/register-custom-builtin.md b/solutions/register-custom-builtin.md
index 8e34962335..3ec91ec70d 100644
--- a/solutions/register-custom-builtin.md
+++ b/solutions/register-custom-builtin.md
@@ -2,87 +2,117 @@
 
 ## 需求描述
 
-当前 Mpx 框架内在 `webpack-plugin/lib/runtime/components/react|web` 中维护了同微信小程序基础组件一致的内建组件，在编译时将模版中的用户编写的基础组件映射转换为框架内建组件实现（如 `view` → `mpx-view`），现在希望通过开放 `webpack-plugin` 中的配置，提供用户注册自定义内建组件的能力，对应配置可以提供到 `webpack-plugin` 的 `webConfig` 和 `rnConfig` 中，配置名为 `customBuiltInComponents`，key 为基础组件 tag 名，value 为自定义内建实现路径（约定见下文 **Value（文档约定）**，插件侧不做校验）。
+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 编译侧
+### 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` 与合并逻辑）。
 
-- 各基础组件在 `packages/webpack-plugin/lib/platform/template/wx/component-config/*.js` 中通过 `el.isBuiltIn = true` 及 `web` / `ios` / `android` 等钩子把源码标签（如 `view`）转换为输出端标签（Web 下多为 `mpx-view`，RN 下为 `mpx-view` / `mpx-simple-view` 等）。
-- `packages/webpack-plugin/lib/template-compiler/compiler.js` 中 `processBuiltInComponents` 在遇到 `el.isBuiltIn` 时，向 `meta.builtInComponentsMap` 写入 **当前节点上的 `el.tag`（已是转换后的标签名）** 到默认实现路径的映射：
-  - RN：`@mpxjs/webpack-plugin/lib/runtime/components/react/dist/${tag}`
-  - Web：`@mpxjs/webpack-plugin/lib/runtime/components/${mode}/${tag}`
-- `packages/webpack-plugin/lib/web/processTemplate.js` 与 `packages/webpack-plugin/lib/react/processTemplate.js` 在 `parse` 完成后，把 `meta.builtInComponentsMap` 与用户 `customBuiltInComponents` 合并后写入 `builtInComponentsMap`（经 `addQuery(..., { isComponent: true })`），再交给 `processScript` → `buildComponentsMap`，生成 `getComponent(require(...), { __mpxBuiltIn: true })` 形式的注册代码。
+### 1.2 当前实现与目标的差距
 
-### 1.2 RN 子模版
+| 维度 | 当前已落地（过渡） | 目标方案 |
+|------|-------------------|----------|
+| **配置 key** | 多为 **运行时标签名**（如 `mpx-view`），与 **`meta.builtInComponentsMap` 的 key** 一致才生效 | **微信原始基础标签名**（如 `view`），与用户模版写法一致 |
+| **内建打标与改名** | 依赖既有 **component-config**；**未覆盖** 的标签难以进内建链路 | **`customBuiltInComponents` 作为数据进入 rulesRunner**，在 **跨平台转换** 中与内置规则 **统一** 处理 **`isBuiltIn` + `tag`** |
+| **仅配置、无框架默认文件** | 旧方案在 **processTemplate** 二次 merge 时易遗漏 | **`processBuiltInComponents`** 在 **parse** 内直接写入 **用户 path 或默认 path** |
 
-- `packages/webpack-plugin/lib/react/template-loader.js` 对内联/引入的 `.wxml` 模版再次调用 `templateCompiler.parse`，并单独生成内建映射。自定义内建必须在 **主链路 processTemplate 与 template-loader** 两处一并处理。
+### 1.3 RN 子模版
+
+- 与主链路共用同一套 **parse + rulesRunner 选项**（含 **`customBuiltInComponents` 数据**），保证 **import 模版** 与 **页面/组件模版** 行为一致。
 
 ## 2. 配置设计
 
 ### 2.1 字段位置与类型
 
-在 **`MpxWebpackPlugin` 插件选项**（编译期）中已有 `webConfig`、`rnConfig`（见 `packages/webpack-plugin/lib/index.js` 初始化）。在其上增加可选字段：
-
 ```ts
+/** key：微信侧基础组件标签名；value：自定义实现模块路径 */
 customBuiltInComponents?: Record<string, string>
 ```
 
 - **Web**：`webConfig.customBuiltInComponents`
-- **RN**：`rnConfig.customBuiltInComponents`
-
-**与运行时配置区分**：`mpx.config.webConfig` / `mpx.config.rnConfig` 为运行时使用；插件选项里的 `webConfig` / `rnConfig` 为编译期对象，二者不是同一引用。`customBuiltInComponents` **仅**在插件侧读取。
+- **RN**：`rnConfig.customBuiltInComponents`（可与 Web 分端配置不同模块）
 
-### 2.2 Key 的约定
+**与运行时 `mpx.config` 区分**：此处为 **webpack 插件编译期** 配置。
 
-配置 key 为 **运行时内建标签名**（如 `mpx-view`、`mpx-text`），与 `meta.builtInComponentsMap` 及 `processBuiltInComponents` 中 `el.tag` 一致，而非微信侧 `view`、`text`。
+### 2.2 Key 的约定（目标）
 
-### 2.3 Value（文档约定，插件不校验）
+- **统一为微信小程序基础组件命名空间下的标签名**（与 **`srcMode` 为 wx 时模版中写的标签** 一致），例如：`view`、`text`、`image`、`scroll-view`；用户 **拓展** 的组件若在微信体系中也按 **基础组件标签** 使用，则同样使用该 **原始 tag 字符串** 作为 key。
+- **不负责** 在配置里写 **`mpx-*`**：命中 **`custom-built-in-component`** 时，运行时名统一为 **`mpx-` + 微信 tag**（与常规内置里多数命名一致；**不再**单独区分 RN 的 `mpx-simple-view` 等分支，由自定义实现按需处理）。
 
-**约定**（由业务与文档遵守；**`@mpxjs/webpack-plugin` 不对 value 做格式校验**，错误配置由 webpack 解析失败等方式暴露）：
+### 2.3 Value（文档约定）
 
 | 类型 | 说明 | 示例 |
 |------|------|------|
-| 绝对路径 | POSIX 下以 **`/`** 开头的绝对路径；Windows 下 **`path.isAbsolute` 为真**的路径（盘符路径等） | `/Users/proj/src/a.vue`、`C:\proj\src\a.vue` |
-| npm 包路径 | **作用域包**：以 **`@scope/pkg/`** 形式开头（`@` + scope + `/` + 包名 + `/` + 子路径） | `@acme/ui-rn/MpxView.mpx` |
-| npm 包路径 | **无作用域包**：字符串以 **npm 包名** 开头，即首段为合法包名片段，后可跟 `/子路径`；避免写成易被误认为工程目录相对路径的形式（如不要用 `src/...` 冒充包名） | `my-builtin-pkg/MpxText.mpx` |
+| 绝对路径 | POSIX **`/`** 开头；Windows **`path.isAbsolute` 为真** | `/abs/MyView.vue` |
+| npm 模块路径 | **`@scope/pkg/...`** 或 **`my-pkg/...`**（首段为合法包名） | `@acme/ui/MpxView.mpx` |
 
-**明确不支持 / 禁止写入约定**：
+**不支持**：**`~`** 前缀；**`./`、`../`**（及 `.\`、`..\`）等相对路径。
 
-- **不支持**以 **`~`** 开头的 webpack 模块前缀（不要使用 `~pkg/...`）。
-- **不要使用** **`./`、`../`**（及 **`.\\`、`..\\`**）等相对路径。
+### 2.4 与 `meta.builtInComponentsMap` / `builtInComponentsMap` 的衔接（目标）
 
-合并方式：**`Object.assign({}, meta.builtInComponentsMap, customBuiltInComponents || {})`**，再对合并结果逐项 **`addQuery(..., { isComponent: true })`**。
+- **`meta.builtInComponentsMap`** 的 key 为 **跨平台转换完成后的 `el.tag`**（如 `mpx-view`），在 **`processBuiltInComponents`** 中一次性写入 **用户 path 或框架默认 path**，**不再**在 `processTemplate` 等处以 **`Object.assign`** 二次合并，也 **不需要** `builtInWxToRuntimeMap`。
 
-## 3. 实现方案（已落地）
+## 3. 实现方案（修订方向，不写代码）
 
-### 3.1 总体策略
+### 3.1 核心原则
 
-- **不改变** `compiler.js` 中默认 `meta.builtInComponentsMap` 的生成。
-- **Web app**（`ctorType === 'app'`）：仅注入固定的 **`mpx-keep-alive`**，**不**读取 **`webConfig.customBuiltInComponents`**。
-- **Web 非 app / RN**：在拿到 **`meta`** 后（Web 在 `parse` 回调内；RN 主链路与 `template-loader` 各一处）做上述合并并写入产物。
+1. **`customBuiltInComponents` 作为 `data` 注入跨平台层**  
+   在 **`getRulesRunner`** 的 **`data`** 对象上挂载 **`customBuiltInComponents`**（与 **`usingComponents`** 并列），由 **`compiler.parse`** 创建 rulesRunner 时 **从 `webConfig` / `rnConfig` 填入**（按 **mode** 取对应端配置）；**`getRulesRunner` 顶层不再单独增加参数**。
 
-### 3.2 修改文件
+2. **在 rulesRunner 规则链路中扩展行为**  
+   - 对 **命中 `customBuiltInComponents` 的 wx 标签** 的节点：与 **`component-config`** 中已有基础组件类似地设置 **`el.isBuiltIn`**（若需与原生内置共存，需约定 **仅 Web/RN 输出** 下生效或与现有规则 **合并优先级**：通常 **用户拓展/替换优先** 或 **仅当框架未声明时补充**，具体以产品约定为准，文档建议 **custom 覆盖同名内置的默认实现路径，但不改变平台分支下的 tag 命名规则**）。  
+   - **标签名转换** 在 **rulesRunner**（含 **`custom-built-in-component`** 与常规 **`component-config`**）中完成。
 
-| 文件 | 行为 |
-|------|------|
-| `packages/webpack-plugin/lib/web/processTemplate.js` | app 只写 keep-alive；非 app 在 parse 后 `Object.assign` + `addQuery`。 |
-| `packages/webpack-plugin/lib/react/processTemplate.js` | 有 `template.content` 且 parse 后同上（`rnConfig.customBuiltInComponents`）。 |
-| `packages/webpack-plugin/lib/react/template-loader.js` | parse 后同上。 |
+3. **`processBuiltInComponents`**  
+   在 **`el.isBuiltIn`** 之后按 **`el.tag`** 写入 **`meta.builtInComponentsMap[tag]`**：若 **`el.originalTag`** 在 **`customBuiltInComponents`** 中有配置（由 **`custom-built-in-component`** 规则写入）则用 **用户 path**，否则用 **框架默认 path**；**不支持**以 **`mpx-*`** 为配置 key。
 
-### 3.3 自定义实现组件契约
+4. **Web app**  
+   维持 **不参与** `customBuiltInComponents`（仅固定 **`mpx-keep-alive`**），除非产品明确要求 app 壳也消费该配置。
 
-替换实现应尽可能与被替换内建在 props、事件、子节点等行为上一致；导出形态需与 web/vue 或 react 内建兼容，以便 `getComponent(..., { __mpxBuiltIn: true })` 与样式、事件代理正常工作。
+### 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. 错误处理
 
-- 插件 **不对** `customBuiltInComponents` 的 value 做合法性校验；路径无法解析等问题由 **webpack 构建**暴露。
+- **value** 可不强制插件校验，由 **webpack** 报错。  
+- **wx 标签配置了 custom，但 rulesRunner 未注入或未命中**：应 **开发态可观测**（warning 或构建失败），避免 **静默不注册**。  
+- **key 与 `srcMode` 模版标签不一致**（如 ali 下标签名不同）：需在文档中说明 **以当前 `srcMode` 下模版实际标签名为准**，或后续 **增加 srcMode 维度配置**（本方案暂不展开）。
 
 ## 5. 测试建议
 
-- Web / RN：按 §2.3 约定配置绝对路径、`@scope/pkg/...`、无作用域包名路径，断言产物 `require` 目标正确。
+- **替换**：配置 `view` → 自定义 path，断言 **rulesRunner 后** `el.isBuiltIn` / **运行时 tag** 与 **无 custom 时一致**，且 **require** 指向用户模块。  
+- **扩展**：配置框架 **无静态 component-config** 的 wx 基础标签（或团队约定拓展名），断言 **经 rulesRunner** 进入 **meta** 与 **`builtInComponentsMap`**。  
+- **RN**：**template-loader** 与 **主模版** 各一条。
 
-## 6. 用户示例
+## 6. 用户示例（目标配置形态）
 
 ```js
 const path = require('path')
@@ -91,21 +121,24 @@ new MpxWebpackPlugin({
   mode: 'web',
   webConfig: {
     customBuiltInComponents: {
-      'mpx-view': path.resolve(__dirname, 'src/builtin/web/MpxView.vue'),
-      'mpx-text': '/abs/path/to/MpxText.vue'
+      view: path.resolve(__dirname, 'src/builtin/web/MyView.vue'),
+      text: '/abs/path/to/MyText.vue'
     }
   },
   rnConfig: {
     customBuiltInComponents: {
-      'mpx-view': '@your-org/mpx-rn-builtin/MpxView.mpx',
-      'mpx-scroll-view': '@your-org/mpx-rn-builtin/MpxScrollView.mpx'
+      view: '@your-org/mpx-rn-builtin/MpxView.mpx',
+      'scroll-view': '@your-org/mpx-rn-builtin/MpxScrollView.mpx'
     }
   }
 })
 ```
 
+（实际运行时组件名仍为 **`mpx-view`** 等，由 **rulesRunner** 转换，用户 **无需** 在配置里写 `mpx-view`。）
+
 ## 7. 风险与后续扩展
 
-- RN 上同一微信标签可能对应 `mpx-simple-view` 等，需按实际 AST 中的 tag 配置。
-- `mode` 为小程序原生输出时不走上述 Web/RN 合并逻辑。
-- 若需支持「微信 tag 为 key」的别名，需另做映射层。
+- **与现有 `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** 一致）。

From 89ab6e96715916e33fecf6cca747b6a265d48568 Mon Sep 17 00:00:00 2001
From: hiyuki <674883329@qq.com>
Date: Wed, 15 Apr 2026 21:15:48 +0800
Subject: [PATCH 3/4] fix test

---
 .../references/rn-extend-reference.md         |  0
 .../custom-built-in-component.js              | 34 ++++++++++++++
 .../custom-built-in-components.spec.js        | 45 +++++++++++++++++++
 3 files changed, 79 insertions(+)
 create mode 100644 .agents/skills/mpx-rn-style-guide/references/rn-extend-reference.md
 create mode 100644 packages/webpack-plugin/lib/platform/template/wx/component-config/custom-built-in-component.js
 create mode 100644 packages/webpack-plugin/test/template-compiler/custom-built-in-components.spec.js

diff --git a/.agents/skills/mpx-rn-style-guide/references/rn-extend-reference.md b/.agents/skills/mpx-rn-style-guide/references/rn-extend-reference.md
new file mode 100644
index 0000000000..e69de29bb2
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/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')
+  })
+})

From d0e38154297c3dab26ead7ed0e7ca49382362282 Mon Sep 17 00:00:00 2001
From: hiyuki <674883329@qq.com>
Date: Fri, 17 Apr 2026 16:09:47 +0800
Subject: [PATCH 4/4] fix unit

---
 .../template/wx/component-config/index.js       | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

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 33565bbf24..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
@@ -45,6 +45,20 @@ 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
@@ -129,6 +143,7 @@ module.exports = function getComponentConfigs ({ warn, error }) {
     label({ print }),
     rootPortal({ print }),
     stickyHeader({ print }),
-    stickySection({ print })
+    stickySection({ print }),
+    defaultCatchAllComponentConfig()
   ]
 }