Merge pull request #2476 from didi/inner-master

update skills & rules

Author: yandadaFreedom

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

@@ -106,7 +106,7 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展
 
 需遵循以下约束：
 
-1. **最小化使用**：非必要时减少使用条件编译，避免大面积连续的条件编译破坏代码可读性与后期维护性；条件编译应仅最小包裹不兼容的片段。
+1. **最小化使用**：条件编译是处理跨端不兼容的**最后手段**，不是首选方案。使用条件编译之前，应先确认是否存在无需条件编译的跨端兼容写法（参见[样式开发最佳实践](./references/rn-style-practice.md)与各能力参考）。需要用条件编译时，仅最小包裹真正不兼容的片段，不要整段代码都用条件编译分叉。
 2. **避免空选择器**：样式条件编译产物中不得留下空选择器（无样式内容的选择器），整条规则（含选择器与花括号内容）须一并被条件编译包裹。详见 [条件编译 · 避免产物中出现空选择器](./references/conditional-compile.md#避免产物中出现空选择器)。
 
 完整语法（样式 `@mpx-if` / 模板 `@mode` & `@_mode` & `mpxTagName@mode` / 脚本 `__mpx_mode__` / JSON 配置）参考 [条件编译](./references/conditional-compile.md)。

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

@@ -211,7 +211,7 @@ mpx.config.rnConfig = Object.assign({}, mpx.config.rnConfig, {
     <text parent-font-size="16" style="font-size: 120%;">文本内容</text>
     ```
 
-3.  **基于自身宽高计算**： `translateX`、`translateY`、`border-radius` 的百分比都是根据自身宽高来计算的（首次渲染不展示，在 `onLayout` 后计算生效）。
+3.  **基于自身宽高计算**： `translateX`、`translateY`、`border-radius` 的百分比都是根据自身宽高来计算的（首次渲染不展示，在 `onLayout` 后计算生效）。其中 `translateX` / `translateY` 的百分比计算依赖 class 样式的编译转换；内联 `style` 中的字符串 transform 不会触发该计算。
 
 4.  **calc() 函数内的百分比**：在 `calc()` 函数表达式内使用百分比时，需要开发者设置 `parent-width` 或 `parent-height` 属性。
 
@@ -228,18 +228,18 @@ mpx.config.rnConfig = Object.assign({}, mpx.config.rnConfig, {
 
 ### 文本样式继承
 
-Mpx 框架抹平了平台差异，使 `view` 节点可以直接包裹文本并继承样式。
+Mpx 框架抹平了平台差异，使 `view` 等容器节点可以直接包裹文本并向直接子级文本组件透传文本样式。
 
 **继承规则：**
 
-1.  **view -> text 继承**：只有 `view` 节点下的**直接子** `text` 节点可以继承 `view` 节点上的文本样式。
+1.  **容器 -> text 继承**：只有容器节点下的**直接子** `text` 节点可以继承容器节点上的文本样式；中间存在非 text 节点时不会继续透传。
 2.  **text 嵌套继承**：父级 `text` 节点的样式可以被嵌套的子 `text` 节点继承。
 3.  **自动包裹**：`view` 节点直接包裹文本时，Mpx 编译时会自动添加 `text` 节点包裹文本。
 
 **透传属性：**
 
-- Mpx 会从 `view` 上拆分文本组件属性并透传到直接子 `text` 节点，包括：`ellipsizeMode`、`numberOfLines`、`allowFontScaling`
-- Mpx 会从 `view` 的样式中拆分文本样式并透传到直接子 `text` 节点，包括：`color`、`font*`、`text*`、`letterSpacing`、`lineHeight`、`includeFontPadding`、`writingDirection`
+- Mpx 会从容器上拆分文本组件属性并透传到直接子 `text` 节点，包括：`ellipsizeMode`、`numberOfLines`、`allowFontScaling`
+- Mpx 会从容器的样式中拆分文本样式并透传到直接子 `text` 节点，包括：`color`、`font*`、`text*`、`letterSpacing`、`lineHeight`、`includeFontPadding`、`writingDirection`
 
 ### 简写属性支持
 
@@ -332,14 +332,14 @@ Mpx 在 RN 平台支持 `@media` 规则，但能力受限。
 
 **支持特性：**
 
-- 媒体类型：`screen`、`all`
-- 媒体特性：`width`、`min-width`、`max-width`
+- 媒体类型：可书写 `screen`
+- 媒体特性：`min-width`、`max-width`
 - 逻辑运算符：`and`
 
 **限制：**
 
-- 媒体查询中的宽度条件仅支持 `px` 单位。
-- 不支持 `height`、`orientation` 等其他特性。
+- 媒体查询中的宽度条件仅支持 `px` 单位，并基于运行时 `screen.width` 判断。
+- 不支持 `width` 精确匹配、`height`、`orientation`、`all` 等其他特性。
 
 ### 动画支持
 
@@ -377,7 +377,7 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 **支持特性：**
 
 - **背景颜色**：RN 原生支持 `background-color`。
-- **背景图**：支持 `background-image: url()` 引用图片。
+- **背景图**：支持 `background-image: url()` 引用图片，也支持 `background-image: none` 清空背景图。
 - **渐变背景**：支持 `background-image: linear-gradient()` 线性渐变。
 - **相关属性**：完整支持 `background-size` 和 `background-position`。
 
@@ -474,7 +474,7 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 | --- | --- | --- |
 | `background` | `<background-color>` \| `<background-image>` \| `<background-repeat>` | 背景简写，不支持 `background-position` 和 `background-size` 简写 |
 | `background-color` | `color` | 背景色 |
-| `background-image` | `url()` \| `linear-gradient()` | 背景图/渐变 |
+| `background-image` | `url()` \| `linear-gradient()` \| `none` | 背景图/渐变 |
 | `background-size` | `cover` \| `contain` \| `auto` \| `length` \| `%` | 背景尺寸 |
 | `background-repeat` | `no-repeat` | 仅支持不重复 |
 | `background-position` | `center` \| `left` \| `right` \| `top` \| `bottom` \| `number` \| `%` | 背景位置 |
@@ -491,9 +491,9 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 | `font-weight` | `normal` \| `bold` \| `100-900` | `normal` | 字体粗细 |
 | `font-style` | `normal` \| `italic` | `normal` | 字体样式 |
 | `line-height` | `length` \| `number` \| `%` | - | 行高 |
-| `text-align` | `auto` \| `left` \| `right` \| `center` \| `justify` | `auto` | 文本对齐 |
-| `vertical-align` | `auto` \| `top` \| `bottom` \| `middle` | - | 垂直对齐（仅 Android） |
-| `text-decoration` | `line style color` | - | 装饰线简写 |
+| `text-align` | `left` \| `right` \| `center` \| `justify` | `auto` | 文本对齐；`auto` 是 RN 默认值，不支持在用户源码中显式书写 |
+| `vertical-align` | `auto` \| `top` \| `bottom` \| `middle` | - | 垂直对齐（Android / Harmony 支持，iOS 不支持） |
+| `text-decoration` | `line style color` | - | 装饰线简写；`text-decoration-style` / `text-decoration-color` 仅 iOS 支持 |
 | `text-transform` | `none` \| `uppercase` \| `lowercase` \| `capitalize` | `none` | 大小写转换 |
 | `letter-spacing` | `length` | - | 字符间距 |
 | `text-shadow` | `offset-x offset-y blur color` | - | 文本阴影（Mpx 增强） |
@@ -514,7 +514,7 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 
 | 属性 | 值类型 | 说明 |
 | --- | --- | --- |
-| `box-shadow` | `<offset-x> <offset-y> <blur-radius> <spread-radius> <color>` | 阴影简写（RN 0.76+ 原生支持） |
+| `box-shadow` | `<offset-x> <offset-y> <blur-radius> <spread-radius> <color>` | 阴影简写（依赖宿主 RN/DRN 版本原生支持） |
 | `opacity` | `0-1` | 不透明度 |
 
 ### 动画 (Animation)
@@ -552,3 +552,8 @@ Mpx 在 RN 平台支持 CSS 背景图及渐变背景，框架会自动处理样
 - `caret-color`
 - `float`
 - `clear`
+
+以下属性存在平台差异：
+
+- iOS 不支持 `vertical-align`
+- Android / Harmony 不支持 `text-decoration-style`、`text-decoration-color`、`shadow-offset`、`shadow-opacity`、`shadow-radius`

.agents/skills/mpx-rn-dev-guide/references/rn-template-reference.md

@@ -49,10 +49,12 @@
   - [picker-view](#picker-view)
   - [picker-view-column](#picker-view-column)
   - [picker](#picker)
+  - [slider](#slider)
   - [switch](#switch)
   - [navigator](#navigator)
   - [rich-text](#rich-text)
   - [canvas](#canvas)
+  - [camera](#camera)
   - [video](#video)
   - [web-view](#web-view)
   - [root-portal](#root-portal)
@@ -650,13 +652,13 @@ Mpx 输出 RN 内置支持了大部分常用的基础组件，详情见下方文
 | 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 | string |  | 值应为某子元素 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 属性后生效) |
+| paging-enabled | boolean | `false` | 分页滑动效果 (同时开启 enhanced 属性后生效)，当值为 true 时，滚动条会停在滚动视图的尺寸的整数倍位置 |
+| show-scrollbar | boolean | `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 组件 |
@@ -915,7 +917,6 @@ movable-view 的可移动区域。
 | 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 |  | 光标颜色 |
@@ -973,6 +974,10 @@ movable-view 的可移动区域。
 | bindlinechange | 输入框行数变化时调用，`event.detail = { height: 0, lineCount: 0 }`，不支持 `heightRpx` |
 | bind:selectionchange | 选区改变事件, `event.detail = {selectionStart, selectionEnd}` |
 
+#### 注意事项
+
+- textarea 组件不支持 `confirm-hold` 属性。
+
 ### progress
 
 进度条。
@@ -1116,6 +1121,37 @@ level 有效值：
 | city     | 市级选择器   |
 | region   | 区级选择器   |
 
+### slider
+
+滑动选择器。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| min | number | `0` | 最小值 |
+| max | number | `100` | 最大值 |
+| step | number | `1` | 步长 |
+| disabled | boolean | `false` | 是否禁用 |
+| value | number | `min` | 当前取值 |
+| color | string |  | 背景条颜色（已废弃，请使用 backgroundColor） |
+| selected-color | string |  | 已选择颜色（已废弃，请使用 activeColor） |
+| activeColor | string | `#1aad19` | 已选择颜色 |
+| backgroundColor | string | `#e9e9e9` | 背景条颜色 |
+| block-size | number | `28` | 滑块大小，RN 侧会限制在 12 到 28 之间 |
+| block-color | string | `#ffffff` | 滑块颜色 |
+
+#### 事件
+
+| 事件名 | 说明 |
+| --- | --- |
+| bindchange | 完成一次拖动后触发，`event.detail = { value }` |
+| bindchanging | 拖动过程中触发，`event.detail = { value }` |
+
+#### 注意事项
+
+- 不支持 `show-value` 属性，即不支持在滑动条右侧显示当前 value。
+
 ### switch
 
 开关选择器。
@@ -1191,6 +1227,42 @@ level 有效值：
 - canvas 的实现主要借助于 PostMessage 方式与 webview 容器通信进行绘制，所以对于严格依赖方法执行时机的场景，如调用 drawImage 绘图，再通过 getImageData 获取图片数据的场景，调用时需要使用 await 等方式来保证方法的执行时机
 - 通过 Canvas.createImage 画图，图片的链接不能有特殊字符，安卓手机可能会 load 失败
 
+### camera
+
+系统相机。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| mode | string | `normal` | 应用模式，可选值为 `normal`、`scanCode` |
+| resolution | string | `medium` | 分辨率，可选值为 `low`、`medium`、`high` |
+| device-position | string | `back` | 摄像头朝向，可选值为 `front`、`back` |
+| flash | string | `auto` | 闪光灯，可选值为 `auto`、`on`、`off` |
+| frame-size | string | `medium` | 指定期望的相机帧数据尺寸，可选值为 `small`、`medium`、`large` |
+
+#### 事件
+
+| 事件名 | 说明 |
+| --- | --- |
+| bindinitdone | 相机初始化完成时触发，`event.detail = { maxZoom }` |
+| bindstop | 摄像头在非正常终止时触发 |
+| binderror | 相机发生错误时触发 |
+| bindscancode | 在 `scanCode` 模式下识别到二维码时触发，`event.detail = { result, type, scanArea }` |
+
+#### API
+
+| 方法名 | 说明 |
+| --- | --- |
+| setZoom | 设置缩放级别 |
+| takePhoto | 拍照，仅支持在 `normal` 模式中使用 |
+| startRecord | 开始录像 |
+| stopRecord | 结束录像 |
+
+#### 注意事项
+
+- camera 组件基于第三方库 `react-native-vision-camera` 来实现，需要容器中安装此依赖包并完成相机权限配置。
+
 ### video
 
 视频

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

@@ -3,7 +3,7 @@ const { parseValues } = require('../../../utils/string')
 
 module.exports = function getSpec({ warn, error }) {
   // React Native 双端都不支持的 CSS property
-  const unsupportedPropExp = /^(white-space|text-overflow|animation|font-variant-caps|font-variant-numeric|font-variant-east-asian|font-variant-alternates|font-variant-ligatures|caret-color)$/
+  const unsupportedPropExp = /^(white-space|text-overflow|animation|font-variant-caps|font-variant-numeric|font-variant-east-asian|font-variant-alternates|font-variant-ligatures|caret-color|float|clear)$/
   const unsupportedPropMode = {
     // React Native ios 不支持的 CSS property
     ios: /^(vertical-align)$/,
@@ -50,7 +50,7 @@ module.exports = function getSpec({ warn, error }) {
     'flex-direction': ['row', 'row-reverse', 'column', 'column-reverse'],
     'flex-wrap': ['wrap', 'nowrap', 'wrap-reverse'],
     'pointer-events': ['auto', 'box-none', 'box-only', 'none'],
-    'vertical-align': ['auto', 'top', 'bottom', 'center'],
+    'vertical-align': ['auto', 'top', 'bottom', 'middle'],
     position: ['relative', 'absolute', 'fixed'],
     'font-variant': ['small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums'],
     'text-align': ['left', 'right', 'center', 'justify'],

packages/webpack-plugin/lib/platform/template/wx/component-config/input.js

@@ -101,7 +101,7 @@ module.exports = function ({ print }) {
         qa: qaPropLog
       },
       {
-        test: /^(always-embed|hold-keyboard|safe-password-.+)$/,
+        test: /^(always-embed|safe-password-.+)$/,
         ios: iosPropLog,
         android: androidPropLog,
         harmony: harmonyPropLog

packages/webpack-plugin/lib/platform/template/wx/component-config/movable-view.js

@@ -33,20 +33,14 @@ module.exports = function ({ print }) {
     props: [
       {
         test: /^(out-of-bounds)$/,
-        ali: qaPropLog,
-        ios: iosPropLog,
-        android: androidPropLog,
-        harmony: harmonyPropLog
+        ali: qaPropLog
       },
       {
         test: /^(inertia)$/,
         ks: ksPropLog
       },
       {
         test: /^(damping|friction)$/,
-        ios: iosPropLog,
-        android: androidPropLog,
-        harmony: harmonyPropLog,
         ks: ksPropLog
       },
       {

packages/webpack-plugin/lib/platform/template/wx/component-config/text.js

@@ -49,7 +49,7 @@ module.exports = function ({ print }) {
         qa: qaPropLog
       },
       {
-        test: /^(space|decode)$/,
+        test: /^(space)$/,
         ios: iosPropLog,
         android: androidPropLog,
         harmony: harmonyPropLog

packages/webpack-plugin/lib/platform/template/wx/component-config/textarea.js

@@ -14,13 +14,10 @@ module.exports = function ({ print }) {
   const qqEventLog = print({ platform: 'qq', tag: TAG_NAME, isError: false, type: 'event' })
   const qqPropLog = print({ platform: 'qq', tag: TAG_NAME, isError: false })
   const baiduPropLog = print({ platform: 'baidu', tag: TAG_NAME, isError: false })
-  const iosValueLogError = print({ platform: 'ios', tag: TAG_NAME, isError: true, type: 'value' })
   const iosPropLog = print({ platform: 'ios', tag: TAG_NAME, isError: false })
   const iosEventLog = print({ platform: 'ios', tag: TAG_NAME, isError: false, type: 'event' })
-  const androidValueLogError = print({ platform: 'android', tag: TAG_NAME, isError: true, type: 'value' })
   const androidPropLog = print({ platform: 'android', tag: TAG_NAME, isError: false })
   const androidEventLog = print({ platform: 'android', tag: TAG_NAME, isError: false, type: 'event' })
-  const harmonyValueLogError = print({ platform: 'harmony', tag: TAG_NAME, isError: true, type: 'value' })
   const harmonyPropLog = print({ platform: 'harmony', tag: TAG_NAME, isError: false })
   const harmonyEventLog = print({ platform: 'harmony', tag: TAG_NAME, isError: false, type: 'event' })
   const ksPropLog = print({ platform: 'ks', tag: TAG_NAME, isError: false })
@@ -72,28 +69,7 @@ module.exports = function ({ print }) {
         qa: qaPropLog
       },
       {
-        test: 'confirm-type',
-        ios ({ name, value }) {
-          const notSupported = ['return']
-          if (notSupported.includes(value)) {
-            iosValueLogError({ name, value })
-          }
-        },
-        android ({ name, value }) {
-          const notSupported = ['return']
-          if (notSupported.includes(value)) {
-            androidValueLogError({ name, value })
-          }
-        },
-        harmony ({ name, value }) {
-          const notSupported = ['return']
-          if (notSupported.includes(value)) {
-            harmonyValueLogError({ name, value })
-          }
-        }
-      },
-      {
-        test: /^(always-embed|hold-keyboard|disable-default-padding|adjust-keyboard-to|fixed|show-confirm-bar)$/,
+        test: /^(always-embed|confirm-hold|disable-default-padding|adjust-keyboard-to|fixed|show-confirm-bar)$/,
         ios: iosPropLog,
         android: androidPropLog,
         harmony: harmonyPropLog