Merge pull request #2474 from didi/inner-master

Inner master

Author: hiyuki

.agents/skills/mpx-rn-dev-guide/SKILL.md

@@ -44,6 +44,15 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展
 
 无论是适配改造还是新建组件，跨端兼容均需严格遵循以下通用约束：
 
+### 跨平台兼容约束
+
+产物代码须在原平台与 RN 平台均能正常运行。引入「RN 支持但原平台不支持」的写法（如 `numberOfLines@ios|android|harmony` / `hairlineWidth` 等 RN 等效实现）时，**不要替换原平台已有写法**，而应：
+
+- 用条件编译将该 RN 写法限定在 RN 平台输出（模板属性后缀 `@ios|android|harmony`、样式与脚本 `@mpx-if` 包裹等）；
+- 同步用条件编译保留原平台原有写法，避免改造引入原平台行为退化。
+
+该原则贯穿模板 / 脚本 / 样式 / JSON 四个维度，下方各约束与样式约束 #3 的「双轨」条目即此原则的具体落地。
+
 ### 模板（template）约束
 
 1. **基础组件优先**：使用 [模板能力参考 · 基础组件](./references/rn-template-reference.md#基础组件) 中标注 RN 支持的基础组件与其支持属性/事件，不要使用 RN 不支持的属性或事件；如用户通过 `rnConfig.customBuiltInComponents` 编译配置扩充拓展了基础组件能力，以用户说明为准。
@@ -67,17 +76,20 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展
 2. **优先使用模板指令进行动态样式绑定**：使用 `wx:class` / `wx:style` 指令，避免在 `class` / `style` 属性内拼接 `{{}}` 插值表达式。
    - **Bad Example**: `<view class="item {{isActive ? 'active' : ''}}">`
    - **Good Example**: `<view class="item" wx:class="{{ {active: isActive} }}">`
-3. **优先使用跨端兼容方案**：常见样式属性的跨端兼容方案见 [样式开发最佳实践](./references/rn-style-practice.md)，包括：
-   - 复合选择器 → 等效单类选择器
-   - 子元素伪类（`:first-child` 等）→ `wx:class` + `index` 判断
-   - 伪元素（`::before` / `::after`）→ 真实节点替代
-   - 点击态伪类（`:active`）→ `hover-class` / `hover-stay-time`
-   - 1rpx 极细线 → `hairlineWidth` 条件编译
-   - `rem` / `em` → `rpx`
-   - 数值型 `font-weight` → `normal` / `bold`
-   - 文本溢出 → 模板属性 `numberOfLines` 条件编译
-   - 隐藏元素 → 尺寸归零 + `overflow: hidden`，避免 `display: none`
-   - `grid` / `float` → Flex 布局
+3. **优先使用跨端兼容方案**：常见样式属性的跨端兼容方案见 [样式开发最佳实践](./references/rn-style-practice.md)。下表区分两类处理方式：
+   - **等效替换**（替换后写法在原平台与 RN 平台均生效，可直接全平台使用）
+     - 复合选择器 → 等效单类选择器
+     - 子元素伪类（`:first-child` 等）→ `wx:class` + `index` 判断
+     - 伪元素（`::before` / `::after`）→ 真实节点替代
+     - 点击态伪类（`:active`）→ `hover-class` / `hover-stay-time`
+     - `rem` / `em` → `rpx`
+     - 数值型 `font-weight` → `normal` / `bold`
+     - 隐藏元素：避免 `display: none`，使用尺寸归零 + `overflow: hidden`
+     - `grid` / `float` → Flex 布局
+   - **双轨保留**（原平台原写法用条件编译保留，RN 侧新增等效实现，**禁止只保留 RN 一侧**）
+     - 文本溢出：原平台保留 `white-space` / `text-overflow` / `overflow: hidden` 样式（用样式条件编译包裹整条规则），RN 侧通过模板属性 `numberOfLines@ios|android|harmony` 等效实现
+     - 1rpx 极细线：原平台保留 `1rpx` 边框写法（用样式条件编译），RN 侧用 `hairlineWidth` 等效
+     
 4. **保留单位注释**：保留原始样式中的 `/*use rpx*/` 与 `/*use px*/` 注释，编译期会据此批量切换样式单位。
 
 ### JSON 配置约束
@@ -160,12 +172,15 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展
 
 #### 5. 编译校验
 
-完成上述改造后，使用 `scripts/compile-validate.js` 对修改后的 `.mpx` 文件进行真实编译校验，参见下文 [编译校验脚本](#编译校验脚本)。若校验失败，按错误分类回到对应步骤进行修正。
+完成上述改造后，使用本 skill 自带的编译校验脚本对修改后的 `.mpx` 文件进行真实编译校验（位于 skill 目录下的 `scripts/compile-validate.js`，**不在宿主项目根目录下**），参见下文 [编译校验脚本](#编译校验脚本)。若校验失败，按错误分类回到对应步骤进行修正。
 
 #### 6. 检查与确认
 
 按 SFC 各区块逐项核对，并确认条件编译与编译校验已收尾：
 
+**跨平台兼容**
+- [ ] 引入的「RN 支持但原平台不支持」的写法均已通过条件编译限定在 RN 输出；原平台原有写法已用条件编译保留，未因 RN 适配而被替换或删除。
+
 **模板（template）**
 - [ ] `<template>` 中使用的基础组件、属性、事件均在 [模板能力参考](./references/rn-template-reference.md) 标注为 RN 支持，或已通过模板条件编译进行平台隔离；如用户通过 `rnConfig.customBuiltInComponents` 编译配置扩充拓展了基础组件能力，以用户说明为准。
 - [ ] 动态 `class` / `style` 已改造为 `wx:class` / `wx:style` 指令，未在属性值内使用 `{{}}` 拼接。
@@ -223,15 +238,17 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展
 
 #### 3. 编译校验
 
-使用 `scripts/compile-validate.js` 校验新建组件，参见下文 [编译校验脚本](#编译校验脚本)。建议同时校验所有目标平台（如 `--target=wx,ios,web`），确保跨端兼容。
+使用本 skill 自带的编译校验脚本（位于 skill 目录下的 `scripts/compile-validate.js`，**不在宿主项目根目录下**）校验新建组件，参见下文 [编译校验脚本](#编译校验脚本)。建议同时校验所有目标平台（如 `--target=wx,ios,web`），确保跨端兼容。
 
 #### 4. 检查与确认
 
 复用 [任务一 · 检查与确认](#6-检查与确认) 的清单，确认新建组件不引入任何 RN 不兼容写法。
 
 ## 编译校验脚本
 
-`scripts/compile-validate.js` 是基于宿主项目 `@mpxjs/mpx-cli-service` 的真实编译校验工具，会自动从输入文件向上探测项目根目录、加载工程编译配置、按指定 `target` 进行编译，并按 `style / template / script / json / dependency / other` 分类聚合错误与警告。改造或新建组件后建议作为强制环节运行。
+> **脚本位置**：编译校验脚本随本 skill 一同分发，位于 **skill 目录下** 的 `scripts/compile-validate.js`（即 `<skill-root>/scripts/compile-validate.js`），下文所有命令示例均使用 **指向 skill 目录的路径**调用该脚本，不要尝试在宿主项目根目录或 `node_modules` 中查找它。
+
+该脚本基于宿主项目内安装的 `@mpxjs/mpx-cli-service` 进行真实编译校验：会自动从输入 `.mpx` 文件向上探测宿主项目根目录、加载工程编译配置、按指定 `target` 进行编译，并按 `style / template / script / json / dependency / other` 分类聚合错误与警告。改造或新建组件后建议作为强制环节运行。
 
 子组件忽略策略按宿主项目 `@mpxjs/webpack-plugin` 版本自动切换：
 
@@ -253,21 +270,23 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展
 
 ### 使用示例
 
+> 下方示例中的 `<skill-root>` 表示本 skill 在宿主环境中的实际安装路径（例如 `.agents/skills/mpx-rn-dev-guide`、`.claude/skills/mpx-rn-dev-guide` 或 `~/.claude/skills/mpx-rn-dev-guide` 等，以实际安装位置为准）；调用时使用该绝对路径，不要在宿主项目根目录下查找 `scripts/compile-validate.js`。
+
 ```bash
 # 单组件、默认 target=ios
-node .agents/skills/mpx-rn-dev-guide/scripts/compile-validate.js src/components/foo.mpx
+node <skill-root>/scripts/compile-validate.js src/components/foo.mpx
 
 # 显式指定为页面（影响 entry 与 partialCompileRules 形态）
-node .agents/skills/mpx-rn-dev-guide/scripts/compile-validate.js src/pages/index.mpx --type=page --target=ios
+node <skill-root>/scripts/compile-validate.js src/pages/index.mpx --type=page --target=ios
 
 # 跨端多目标校验
-node .agents/skills/mpx-rn-dev-guide/scripts/compile-validate.js src/components/foo.mpx --target=wx,ios,web
+node <skill-root>/scripts/compile-validate.js src/components/foo.mpx --target=wx,ios,web
 
 # 输出结构化 JSON 便于二次处理
-node .agents/skills/mpx-rn-dev-guide/scripts/compile-validate.js src/components/foo.mpx --target=ios --json
+node <skill-root>/scripts/compile-validate.js src/components/foo.mpx --target=ios --json
 
 # 同时递归校验子组件（默认行为是仅校验目标自身）
-node .agents/skills/mpx-rn-dev-guide/scripts/compile-validate.js src/components/foo.mpx --target=ios --no-ignore-sub-components
+node <skill-root>/scripts/compile-validate.js src/components/foo.mpx --target=ios --no-ignore-sub-components
 ```
 
 校验失败时按错误的 `category` 字段回到对应任务步骤定位与修正问题，再次运行直至通过。

.agents/skills/mpx-rn-dev-guide/references/rn-style-practice.md

@@ -9,7 +9,7 @@
   - [点击态处理 (:active)](#点击态处理-active)
 - [样式单位使用建议](#样式单位使用建议)
   - [优先使用 px 和 rpx 单位](#优先使用-px-和-rpx-单位)
-  - [百分比用于相对布局](#百分比用于相对布局)
+  - [使用百分比](#使用百分比)
   - [1 像素边框（极细线）](#1-像素边框极细线)
   - [避免使用不兼容的单位 (rem/em)](#避免使用不兼容的单位-remem)
   - [谨慎使用 font-weight 数值](#谨慎使用-font-weight-数值)
@@ -426,7 +426,7 @@ px 和 rpx 在 RN 与小程序平台都具备良好兼容性，建议优先使
 </style>
 ```
 
-### 百分比用于相对布局
+### 使用百分比
 
 百分比单位在 RN 平台的处理分为两类：**React Native 原生支持的百分比**和**框架特殊处理的百分比**。
 
@@ -468,76 +468,80 @@ px 和 rpx 在 RN 与小程序平台都具备良好兼容性，建议优先使
 **⚠️ 需要辅助属性的场景：**
 
 1. **`font-size` 的百分比**需要传递 `parent-font-size` 辅助属性
-2. **`calc()` 中的百分比**需要传递相应的辅助属性（`calc()` 是框架模拟支持的特性）
+2. **`calc()` 中出现的任何百分比**都需要传递相应的 `parent-width` / `parent-height` 辅助属性（`calc()` 是框架模拟支持的特性）
 
 ```html
 <template>
   <!-- 场景1：font-size 百分比需要 parent-font-size -->
   <view parent-font-size="{{16}}" class="text" />
 
-  <!-- 场景2：calc() 中的百分比需要辅助属性 -->
-  <view parent-width="{{750}}" parent-height="{{1000}}" class="box" />
+  <!-- 场景2：仅在无法替代时，calc() 中的百分比需要父级布局宽高辅助计算 -->
+  <view id="calc-parent" class="calc-parent" wx:ref>
+    <view
+      wx:if="{{layoutReady}}"
+      class="box"
+      parent-width="{{parentWidth}}"
+      parent-height="{{parentHeight}}"
+    />
+  </view>
 </template>
 
+<script>
+export default {
+  data () {
+    return {
+      parentWidth: 0,
+      parentHeight: 0,
+      layoutReady: false
+    }
+  },
+  ready() {
+    this.createSelectorQuery()
+      .select('#calc-parent')
+      .boundingClientRect()
+      .exec((res) => {
+        const rect = res && res[0]
+        if (rect) {
+          this.parentWidth = rect.width
+          this.parentHeight = rect.height
+          this.layoutReady = true
+        }
+      })
+  }
+}
+</script>
+
 <style>
   .text {
     font-size: 120%; /* 需要 parent-font-size */
   }
 
+  .calc-parent {
+    width: 100%;
+    height: 400rpx;
+  }
+
   .box {
-    /* calc() 中的百分比需要辅助属性 */
+    /* calc() 中的百分比需要辅助属性参与计算 */
     width: calc(50% - 20rpx); /* 需要 parent-width */
     height: calc(30% + 10rpx); /* 需要 parent-height */
-
-    /* calc() 中的 translateX/Y 百分比会自动测量 */
-    transform: translateX(calc(50% + 10rpx)); /* 自动测量元素 width */
+    transform: translateX(calc(50% + 10rpx)); /* calc 内含百分比，同样需要 parent-width */
   }
 </style>
 ```
 
-**❌ 避免的场景：**
+如需使用 `calc() + 百分比`，父级宽高写死时可以直接传入固定的 `parent-width` / `parent-height`。更常见的场景，是使用 `createSelectorQuery()` 等布局查询 API 获取父级真实布局宽高后再传递给使用 `calc()` 的节点；在宽高信息获取完成前，建议先隐藏该节点展示（如使用 `wx:if` 延迟渲染，或使用 `opacity: 0` 隐藏），避免未完成辅助计算时出现闪动或错误布局。
 
-```html
-<template>
-  <text class="text-bad">不推荐：字号用百分比（易漏 parent-font-size）</text>
-  <text class="text-good">推荐：字号用 rpx</text>
-  <view class="box-bad">不推荐：calc 内百分比缺辅助属性</view>
-  <view class="box-good">推荐：calc 内用 rpx</view>
-</template>
-
-<style>
-  /* 避免：字体大小使用百分比 */
-  .text-bad {
-    font-size: 120%; /* 需要 parent-font-size，容易出错 */
-  }
-
-  /* 推荐：使用 rpx */
-  .text-good {
-    font-size: 32rpx;
-  }
-
-  /* 避免：calc() 中使用百分比但不传递辅助属性 */
-  .box-bad {
-    width: calc(50% - 20rpx); /* 需要 parent-width，否则会报错 */
-  }
-
-  /* 推荐：使用 rpx */
-  .box-good {
-    width: calc(375rpx - 20rpx);
-  }
-</style>
-```
+这种兼容写法会带来一定的性能与体验开销。一般不建议使用 `calc() + 百分比`，优先考虑 RN 原生支持的百分比布局、Flex 布局、rpx / vw / vh 或固定尺寸表达；仅在确实无法替代时使用该兼容写法。
 
 **最佳实践：**
 
 1. **优先使用 rpx**：对于固定尺寸，rpx 是最可靠的选择
 2. **放心使用百分比**：`width`, `height`, `padding`, `margin` 等属性的百分比由 RN 原生支持，可以放心使用
-3. **避免字体百分比**：`font-size` 的百分比需要辅助属性，建议使用 rpx 代替
-4. **谨慎使用 calc() 中的百分比**：`calc()` 是框架模拟支持的，其中的百分比需要辅助属性，建议在 `calc()` 中使用 rpx 代替百分比
+3. **谨慎使用字体百分比**：`font-size` 的百分比需要 `parent-font-size` 辅助属性，建议使用 rpx 代替
+4. **谨慎使用 calc() 中的百分比**：该写法需要 `parent-width` / `parent-height` 辅助计算，通常还要查询父级布局并延迟展示，存在性能与体验开销；优先使用原生百分比、Flex、rpx / vw / vh 或固定尺寸替代
 5. **使用 vh/vw**：对于视口相关的尺寸，vh/vw 是更好的选择
 
-<span id="1像素边框极细线"></span>
-
 ### 1 像素边框（极细线）
 
 在移动端开发中，常需要实现物理像素为 1px 的极细边框。

packages/webpack-plugin/lib/platform/json/wx/index.js

@@ -6,6 +6,8 @@ const { isOriginTag, isBuildInWebTag, isBuildInReactTag } = require('../../../ut
 const getBuildInTagComponent = require('../../../utils/get-build-tag-component')
 
 module.exports = function getSpec ({ warn, error }) {
+  const reactModes = ['ios', 'android', 'harmony']
+
   function print (mode, path, value, isError) {
     const msg = `Json path <${path}> is not supported in ${mode} environment!`
     isError ? error(msg, { path, value }) : warn(msg, { path, value })
@@ -32,6 +34,14 @@ module.exports = function getSpec ({ warn, error }) {
     }
   }
 
+  function createReactRule (test, processor) {
+    const rule = { test }
+    reactModes.forEach(mode => {
+      rule[mode] = processor
+    })
+    return rule
+  }
+
   /**
    * @desc 在app.mpx里配置usingComponents作为全局组件
    */
@@ -220,6 +230,7 @@ module.exports = function getSpec ({ warn, error }) {
       },
       jd: deletePath()
     },
+    createReactRule('enablePullDownRefresh|onReachBottomDistance', deletePath()),
     {
       test: 'navigationBarBackgroundColor',
       ali (input) {
@@ -247,8 +258,13 @@ module.exports = function getSpec ({ warn, error }) {
     {
       test: 'backgroundColorTop|backgroundColorBottom',
       ali: deletePath(),
-      swan: deletePath()
+      swan: deletePath(),
+      ios: deletePath(),
+      android: deletePath(),
+      harmony: deletePath()
     },
+    createReactRule('backgroundColor|backgroundTextStyle', deletePath()),
+    createReactRule('pageOrientation', deletePath()),
     {
       test: 'navigationBarTextStyle|navigationStyle|backgroundTextStyle',
       ali: deletePath()
@@ -382,7 +398,10 @@ module.exports = function getSpec ({ warn, error }) {
         qq: deletePath(),
         swan: deletePath(),
         tt: deletePath(),
-        jd: deletePath()
+        jd: deletePath(),
+        ios: deletePath(),
+        android: deletePath(),
+        harmony: deletePath()
       },
       {
         test: 'preloadRule',
@@ -394,14 +413,20 @@ module.exports = function getSpec ({ warn, error }) {
         qq: deletePath(true),
         swan: deletePath(true),
         tt: deletePath(),
-        jd: deletePath(true)
+        jd: deletePath(true),
+        ios: deletePath(true),
+        android: deletePath(true),
+        harmony: deletePath(true)
       },
       {
         test: 'plugins',
         qq: deletePath(true),
         swan: deletePath(true),
         tt: deletePath(),
-        jd: deletePath(true)
+        jd: deletePath(true),
+        ios: deletePath(true),
+        android: deletePath(true),
+        harmony: deletePath(true)
       },
       {
         test: 'usingComponents',
@@ -427,19 +452,28 @@ module.exports = function getSpec ({ warn, error }) {
       {
         test: 'debug',
         ali: deletePath(),
-        swan: deletePath()
+        swan: deletePath(),
+        ios: deletePath(),
+        android: deletePath(),
+        harmony: deletePath()
       },
       {
         test: 'requiredBackgroundModes',
         ali: deletePath(),
-        tt: deletePath()
+        tt: deletePath(),
+        ios: deletePath(),
+        android: deletePath(),
+        harmony: deletePath()
       },
       {
         test: 'workers',
         jd: deletePath(),
         ali: deletePath(),
         swan: deletePath(),
-        tt: deletePath()
+        tt: deletePath(),
+        ios: deletePath(),
+        android: deletePath(),
+        harmony: deletePath()
       },
       {
         test: 'subpackages|subPackages',
@@ -454,6 +488,8 @@ module.exports = function getSpec ({ warn, error }) {
         ali: deletePath(),
         jd: deletePath()
       },
+      createReactRule('navigateToMiniProgramAppIdList', deletePath()),
+      createReactRule('tabBar', deletePath(true)),
       {
         test: 'tabBar',
         ali: getTabBarRule(),
@@ -470,7 +506,10 @@ module.exports = function getSpec ({ warn, error }) {
         swan: getWindowRule(),
         tt: getWindowRule(),
         ks: getWindowRule(),
-        jd: getWindowRule()
+        jd: getWindowRule(),
+        ios: getWindowRule(),
+        android: getWindowRule(),
+        harmony: getWindowRule()
       }
     ]
   }