Mpx2rn

Mpx 跨端输出 RN 开发与适配指南

背景介绍

Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展支持的跨端开发框架，支持将同一套代码输出到小程序（微信、支付宝、百度等）、Web 和 React Native 平台。Mpx2RN 在编译时和运行时对模板、脚本、样式与 JSON 配置四大维度的开发能力进行了全面抹平，但与小程序、Web 平台仍存在一定能力差异。

适用场景

本 SKILL 是 Mpx2RN 开发适配的统一指南，覆盖模板、脚本、样式、JSON 配置四大维度。涉及 Mpx2RN 的任务均应在动笔前阅读本 SKILL 的 Mpx2RN 跨端开发约束，包括但不限于：

• 技术方案设计：评估需求在 RN 平台的可行性、跨端兼容方案选型、是否需要文件级条件编译或混合开发等;
• 旧项目跨端适配改造：对已基于小程序规范编写、未适配 RN 的存量组件进行兼容性补齐（参见下文任务一）;
• 页面 / 组件开发迭代：从零编写或迭代符合 RN 跨端兼容规范的 .mpx 页面与组件（参见下文任务二）;
• 编译和运行时报错排查：定位 RN 平台特有的编译错误（如样式空选择器、保留关键字、缩进敏感预处理器报错等）与运行时差异;
• Code Review：以本 SKILL 的 Mpx2RN 跨端开发约束为标准对照检查跨端兼容性。

不适用场景

以下场景与 Mpx2RN 无关，不应调用本 SKILL：

• 仅面向小程序平台（微信、支付宝、百度等）的 Mpx 开发问题;
• React Native 原生开发问题（不经 Mpx 编译的纯 RN 项目）;
• Mpx 跨端输出 Web（Mpx2Web）相关问题。

知识库索引

知识库使用建议

参考文档体量较大，不要一次性预读全部参考，按需取用即可：

1. 固定入口：完整读取本 SKILL.md；不要在动笔前预读 references 目录，完成实现后重新按本 SKILL 的跨端开发约束逐项核实。
2. 触发式读取：只在任务流程或跨端开发约束中明确指向某份参考时读取，且仅读取与当前问题相关的小节（参考文档均含目录与章节锚点，使用 grep / 锚点跳读，不要整文件 Read）。
3. 典型任务的最小阅读集（仅当本 SKILL 已无法判断时再补充）：
   • 已有组件 RN 跨端适配改造：识别问题维度后再读对应能力参考的相关小节，通常 1–2 份足够（如样式改造主要查 rn-style-practice.md）。
   • 新建 RN 跨端兼容组件：先按本 SKILL 的跨端开发约束起手，遇到能力存疑（某属性是否支持、某 API 是否存在）时再点查对应参考。
   • 排查特定编译报错：直接定位到报错维度的能力参考相关小节。
   • 使用或排查原子类：读取 rn-atomic-css.md；仅需核对底层样式属性时再补读 rn-style-reference.md，不要预读全部样式参考。
4. 样式参考的读取顺序：样式适配或开发时，优先读取 rn-style-practice.md 的相关小节，存在命中场景则直接应用；未命中相关内容时，再读取 rn-style-reference.md 的相关小节获取更广泛的知识参考。只有当任务明确查询某项样式能力是否支持时，才直接读取 rn-style-reference.md。
5. 何时读取 project-structure-and-single-file-component.md：仅当不熟悉 Mpx 项目结构、页面与组件注册关系或 SFC 基本结构时读取；已熟悉相关写法可跳过。

Mpx2RN 跨端开发约束

无论是适配改造、新建组件还是 Code Review，都应遵循以下约束。开始实现前以本节指导开发，完成实现后再按本节逐项核实。

跨平台兼容约束

产物代码须在原平台与 RN 平台均能正常运行。引入 numberOfLines@ios|android|harmony、hairlineWidth 等仅 RN 生效的写法时，通过条件编译限定在 RN 输出，并同步保留原平台原有写法，避免 RN 适配造成原平台行为退化。

模板开发约束

1. 基础组件优先：仅使用模板能力参考 · 基础组件中标注 RN 支持的基础组件、属性与事件；不支持项通过模板条件编译隔离。若用户通过 rnConfig.customBuiltInComponents 扩展了能力，以用户说明为准。
2. 页面滚动：RN 页面默认不可滚动，onPullDownRefresh / onReachBottom / onPageScroll 不会触发；需要滚动时使用 scroll-view 及其等效能力。
3. 事件冒泡与捕获：仅对基础通用事件 tap / longpress / touchstart / touchmove / touchend / touchcancel 使用冒泡和捕获语义。
4. 模板内方法调用：模板 Mustache 表达式不调用普通方法，相关逻辑使用 computed / wxs 实现；i18n 翻译函数除外。
5. i18n 函数命名：组合式 API 中 useI18n() 解构出的翻译函数以原名 t / tc / te / tm 暴露给模板，不要重命名。
6. 事件传参：自定义参数优先通过内联传参语法（如 bindtap="handleTap('param')"）传递，不要使用 data- dataset 属性绕行传参。
7. 文字节点：文字内容优先由 text 显式包裹，避免依赖框架为 view 中的裸文字补节点；跨平台布局对齐方案见样式开发最佳实践 · text 跨平台布局对齐。
8. 动态样式绑定：动态 class / style 使用 wx:class / wx:style 指令，不要在属性值内使用 {{}} 拼接。
9. selector 映射：selector 类 API 引用的模板节点须声明空 wx:ref，完成编译期映射。

脚本开发约束

1. 生命周期与构造选项：仅使用逻辑能力参考中标注 RN 支持的生命周期、构造选项和实例方法；onShareTimeline / onTabItemTap / onAddToFavorites / onSaveExitState 等无默认驱动的声明须由业务提供适配并通过 implement 登记，或使用 remove: true 移除，不得仅登记便视为能力已实现。
2. 环境 API：统一通过 @mpxjs/api-proxy 提供的 mpx.xxx 调用环境能力，不要直接使用 wx.xxx / my.xxx；具体支持范围以环境 API 参考为准。若用户通过 custom 配置扩展了能力，以用户说明为准。
3. Promise 化调用：@mpxjs/api-proxy 开启 usePromise 时，参与 Promise 化的异步 API 必须使用 await 或 .then() / .catch()，不得传入 success / fail 回调。详见环境 API 参考 · Promise 化。
4. selector API：selectComponent / selectAllComponents / createSelectorQuery / createIntersectionObserver 等 selector API 仅使用 #id / .class，且对应模板节点须声明空 wx:ref。详见逻辑能力参考 · 页面 / 组件实例方法与属性。
5. 保留关键字：挂载到实例上的数据 key（包括 props / data / computed / methods / setup return / inject 等）不得使用 id / dataset / data，避免触发 reserved keyword of miniprogram 错误。
6. <script setup> 显式暴露：模板引用的数据与方法须通过 defineExpose() 显式声明，不要暴露模板未使用的大型 store、RN 原生对象等无 UI 数据。

样式开发约束

1. 能力判断口径：样式属性是否支持以样式能力参考为准，不要以 RN 原生样式能力为准；Mpx2RN 已抹平支持的简写属性、CSS 变量、calc()、媒体查询、rpx、颜色格式和文本继承等能力无需额外替换或条件编译。
2. 选择器单类化：展开预处理语言中的嵌套选择器，不要使用复合选择器、伪类或伪元素等 RN 不支持的选择器；改为单类等效实现后，同步更新 <template> 与 <script> 中的引用。逗号分隔的并列单类选择器可以直接使用。
3. 动态样式绑定：优先使用 wx:class / wx:style 指令，不要在 class / style 属性中拼接 {{}} 插值表达式。
4. 按需样式能力预声明：基础组件的 CSS 变量、文本样式与文本属性透传、背景图像、API 动画或 transition 可能在首次渲染后由动态样式或属性引入时，分别通过 enable-var / enable-text-pass-through / enable-background / enable-animation 在首次渲染时预声明；hover-class 的存在状态和 enable-animation 的动画类型在同一组件实例生命周期内保持稳定。仅普通值变化且能力类型始终存在时无需冗余预声明。详见样式开发最佳实践 · 按需样式能力预声明。
5. 节点复用与 Hook 稳定性：条件分支或列表渲染可能复用同一基础组件节点，且各分支或列表项使用的按需样式能力不一致时，优先提供独立且稳定的 key / wx:key；无法提供时，按所有可能能力的并集在每个可能复用的节点上添加 enable-* 预声明，避免复用前后改变 Hook 调用。
6. 跨端兼容方案优先：优先采用样式开发最佳实践中的跨端兼容方案，根据具体方案的平台兼容性选择处理方式：
   • 等效替换：适配方案在原平台与 RN 平台均生效时，直接在全平台应用；例如将复合选择器改为等效单类选择器、将伪元素改为真实节点、将 grid / float 改为 Flex 布局。
   • 双轨保留：适配方案仅在 RN 侧生效无法在原平台生效时，通过条件编译保留原平台原写法，禁止只保留 RN 侧。例如文本溢出在原平台保留原样式、RN 侧使用 numberOfLines@ios|android|harmony；1rpx 极细线在原平台保留 1rpx 边框、RN 侧使用 hairlineWidth。
7. 保留单位注释：保留原始样式中的 /*use rpx*/ 与 /*use px*/ 注释，编译期会据此批量切换样式单位。
8. 原子 CSS：项目启用 UnoCSS 或模板使用原子类时，仅使用Mpx2RN 原子 CSS 能力参考中标注 RN 支持的工具类与 variants；动态类须可被静态提取或加入 safelist；颜色透明度使用 bg-red-500/50 等斜杠 alpha 语法，不要使用独立 *-opacity-* 组合。
9. 垂直 margin 折叠：按模板中的实际节点关系审计垂直 margin，并展开理解 margin 简写与长写。仅对确认在原平台发生折叠且同一间距由两侧共同表达的节点，将折叠后的有效间距归到单侧；先排除 Flex / Grid、浮动、position: absolute/fixed、clearance、父子关系中的 BFC 与分隔条件、空块阻断条件等不折叠场景，无法确认时保持原样。详见样式开发最佳实践 · 处理垂直 margin 折叠。

JSON 配置开发约束

1. 支持范围：应用、页面与组件配置字段须在JSON 配置参考标注的 RN 支持范围内；tabBar 等不支持字段通过条件编译隔离。
2. 动态生成配置：需要分平台或分环境定义配置时，使用 <script name="json"> 并通过 __mpx_mode__ / __mpx_env__ 动态生成。
3. 页面滚动：页面 JSON 将 disableScroll 设为 true，样式声明 page { height: 100%; }，并使用开启 scroll-y 的 scroll-view 承载滚动内容。

条件编译开发约束

• 原平台条件根据用户项目配置确定，一般为 __mpx_mode__ === 'wx' || __mpx_mode__ === 'ali' || __mpx_mode__ === 'web'。
• RN 平台条件根据用户项目配置确定，一般为 __mpx_mode__ === 'ios' || __mpx_mode__ === 'android' || __mpx_mode__ === 'harmony'。

1. 最小化使用：条件编译只作为没有跨端兼容写法时的最后手段，仅包裹真正不兼容的最小片段，不要大面积连续分叉。
2. 避免空选择器：样式条件编译优先只包裹不兼容属性；仅当整条规则均不兼容或某个平台会留下空规则时，才将选择器与声明块整体包裹。详见条件编译 · 避免产物中出现空选择器。
3. 保持预处理器缩进：stylus / sass 等缩进敏感预处理器中的条件编译注释与所在块体同级缩进，避免占位注释截断块上下文并触发 expected "indent", got "outdent" 等错误。
4. 使用区块对应语法：样式使用 /* @mpx-if (...) */，模板使用 wx:if="{{...}}" 或 @mode 属性后缀，脚本和 JSON 使用 if (__mpx_mode__ === ...)；新增代码不要使用历史兼容语法 @_mode。详见条件编译。