fix(rn): 修复响应式样式尺寸更新并支持配置计算基准

.agents/skills/mpx2rn/SKILL.md

@@ -2,7 +2,7 @@
 name: mpx2rn
 description: Mpx 跨端输出 RN（简称 Mpx2RN 或 Mpx2DRN）的开发适配指南，覆盖模板、脚本、样式、JSON 配置四大维度。当用户进行 Mpx2RN 相关任务时强制调用，包括但不限于：技术方案设计、页面 / 组件的开发迭代、旧项目跨端适配改造、编译和运行时报错排查、Code Review 等。当用户问题不涉及 Mpx2RN 时不应调用，如 Mpx 小程序开发问题，RN 原生开发问题、Mpx2Web 相关问题等。
 metadata:
-  version: "2.12.7"
+  version: "2.12.10"
   author: donghongping
 ---
 

.agents/skills/mpx2rn/references/rn-api-reference.md

@@ -263,6 +263,8 @@ mpx.use(apiProxy, {
 
 同步获取窗口、屏幕与安全区信息，常用于布局与刘海区域避让。
 
+可通过 `Mpx.config.rnConfig.customDimensions` 自定义尺寸，`getWindowInfo`、`getSystemInfo` 和 `getSystemInfoSync` 会基于处理后的尺寸计算相关字段。
+
 #### 入参
 
 无。

.agents/skills/mpx2rn/references/rn-script-reference.md

@@ -693,6 +693,7 @@ import Mpx from "@mpxjs/core"
 
 // 须在 createApp 与页面脚本执行前完成赋值
 Mpx.config.rnConfig = {
+  dimensionsBase: "window",
   parseAppProps(props) {
     return {
       initialRouteName: "pages/index",
@@ -721,6 +722,7 @@ Mpx.config.rnConfig = {
 | `onStateChange` | 导航 state 变化时回调。 |
 | `disablePageTransition` | 为 `true` 时禁用 RN 页面转场动画，框架内部映射为 `animation: "none"`。 |
 | `disableAppStateListener` | 为 `true` 时不注册 `AppState` 监听（避免与宿主 App 重复）。 |
+| `dimensionsBase` | `rpx` / `vw` / `vh`、媒体查询与 `onResize` 使用的尺寸基准，可选 `"window"` 或 `"screen"`，默认为 `"window"`。 |
 | `openTypeHandler` | 对象，注册 `button` 组件在 RN 上 `open-type` 的容器侧实现，未注册对应键时点击会告警。 |
 | `openTypeHandler.onShareAppMessage` | 对应模板中 `open-type="share"`：框架会先取当前页 `onShareAppMessage` 的返回（含与默认 `title` / `path` 的合并及可选 `promise` 异步结果），再调用本回调，入参为 `{ title, path, imageUrl? }`，由宿主调起系统分享等能力。 |
 | `openTypeHandler.onUserInfo` | 对应模板中 `open-type="getUserInfo"`：由宿主实现获取用户信息的逻辑，结果需满足按钮侧对 `bindgetuserinfo` 的约定（以 `@mpxjs/webpack-plugin` 中 `mpx-button` 运行时为准）。 |
@@ -751,6 +753,9 @@ console.log(stack.length)
 // 宿主或测试场景下可手动触发应用前后台逻辑
 setAppShow()
 setAppHide()
+
+// 宿主容器尺寸变化后，手动通知响应式样式重新计算
+notifyDimensionsChange()
 ```
 
 | API | 说明 |
@@ -759,6 +764,7 @@ setAppHide()
 | `getCurrentPages()` | 返回当前导航栈中已映射的页面实例列表（顺序与路由 state 相关）。 |
 | `setAppShow()` | 手动触发应用「进入前台」逻辑，驱动已注册的 `onShow`。 |
 | `setAppHide()` | 手动触发应用「进入后台」逻辑，驱动已注册的 `onHide`。 |
+| `notifyDimensionsChange(dimensions?)` | 主动通知框架 Dimensions 发生变化，触发 `rpx`、`vw`、`vh`、媒体查询和 `onResize` 等能力重新计算。不传参数时通过 `Dimensions.get` 读取当前原始尺寸；两种调用方式都会重新执行 `customDimensions`，并按 `dimensionsBase` 指定的尺寸判断是否刷新。运行期间修改 `dimensionsBase` 或 `customDimensions` 后需要调用此方法使配置生效。 |
 
 #### 注意事项
 

.agents/skills/mpx2rn/references/rn-style-reference.md

@@ -168,15 +168,23 @@ Mpx 在 RN 平台支持多种 CSS 单位，并在运行时进行转换。
 | 单位 | 说明 | 转换规则 |
 | --- | --- | --- |
 | `px` | 绝对像素 | 直接转换为 RN 的无单位数值 |
-| `rpx` | 响应式像素 | `rpx值 × 屏幕宽度 / 750` |
+| `rpx` | 响应式像素 | 按 `rpx值 × 视口基准宽度 / 750` 转换 |
 | `%` | 百分比 | 转换为字符串形式（如 `'50%'`），由 RN 原生支持或框架处理 |
-| `vw` | 视口宽度百分比 | `vw值 × 屏幕宽度 / 100` |
-| `vh` | 视口高度百分比 | `vh值 × 屏幕高度 / 100` |
+| `vw` | 视口宽度百分比 | 按 `vw值 × 视口基准宽度 / 100` 转换 |
+| `vh` | 视口高度百分比 | 按 `vh值 × 视口基准高度 / 100` 转换 |
 | `hairlineWidth` | RN 特有极细线 | `StyleSheet.hairlineWidth` |
 
 #### 样式计算基准与自定义
 
-`rpx`、`vw`、`vh` 的计算默认基于运行时的 `screen.width` 和 `screen.height`。
+`rpx`、`vw`、`vh` 与媒体查询的计算默认基于运行时的 `window.width` 和 `window.height`。如需保持旧版本基于 Screen 尺寸计算的效果，可将 `Mpx.config.rnConfig.dimensionsBase` 设置为 `"screen"`：
+
+运行期间修改 `dimensionsBase` 或 `customDimensions` 后，需要调用 `notifyDimensionsChange()` 使配置生效。
+
+```javascript
+Mpx.config.rnConfig.dimensionsBase = "screen"
+```
+
+该配置支持 `"window"` 和 `"screen"`，默认值为 `"window"`。所选尺寸发生变化时，依赖响应式单位或媒体查询的组件会重新计算样式。
 
 同时支持通过运行时配置 `Mpx.config.rnConfig.customDimensions` 自定义样式计算基准：
 
@@ -188,18 +196,17 @@ mpx.config.rnConfig = Object.assign({}, mpx.config.rnConfig, {
     const nextWindow = Object.assign({}, dimensions.window, {
       height: dimensions.window.height - 44
     })
-    const nextScreen = Object.assign({}, dimensions.screen, {
-      height: dimensions.screen.height - 44
-    })
     return {
       window: nextWindow,
-      screen: nextScreen
+      screen: dimensions.screen
     }
   }
 })
 ```
 
-配置生效后，`rpx`、`vw`、`vh` 会按自定义后的 `screen` 宽高进行计算。
+配置生效后，`rpx`、`vw`、`vh` 与媒体查询会按自定义后的 `dimensionsBase` 对应尺寸进行计算。
+
+宿主容器尺寸变化但 React Native 未派发 Dimensions change 事件，或需要基于外部状态重新执行 `customDimensions` 时，可调用全局方法 `notifyDimensionsChange(dimensions?)` 主动通知框架。省略参数时会通过 `Dimensions.get` 重新读取当前原始尺寸。
 
 #### 百分比计算规则
 
@@ -408,7 +415,7 @@ Mpx 在 RN 平台支持 `@media` 规则，但能力受限。
 
 **限制：**
 
-- 媒体查询中的宽度条件仅支持 `px` 单位，并基于运行时 `screen.width` 判断。
+- 媒体查询中的宽度条件仅支持 `px` 单位，并基于 `dimensionsBase` 选中尺寸的运行时 `width` 判断，默认使用 `window.width`。
 - 不支持 `width` 精确匹配、`height`、`orientation`、`all` 等其他特性。
 
 ### 动画支持

docs-vitepress/api-proxy/base/system/getWindowInfo.md

@@ -4,6 +4,8 @@
 
 支持情况： 微信、支付宝、web、RN
 
+> RN 下可通过 `Mpx.config.rnConfig.customDimensions` 自定义尺寸，`getWindowInfo`、`getSystemInfo` 和 `getSystemInfoSync` 会基于处理后的尺寸计算相关字段。
+
 [参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/system/wx.getWindowInfo.html)
 
 ### 参数 {#parameters}
@@ -60,4 +62,4 @@ console.log(deviceInfo.brand)
 console.log(deviceInfo.model)
 console.log(deviceInfo.platform)
 console.log(deviceInfo.system)
-```
+```

docs-vitepress/guide/rn/application-api.md

@@ -468,17 +468,70 @@ mpx.config.rnConfig.disablePageTransition = true
 
 ### 折叠屏适配 {#foldable-screen-adaption}
 
+#### mpx.config.rnConfig.dimensionsBase
+
+```ts
+'window' | 'screen'
+```
+
+控制 `rpx` / `vw` / `vh`、媒体查询与 `onResize` 使用的尺寸基准，默认值为 `'window'`。
+
+如果需要保持旧版本基于屏幕尺寸计算的效果，可配置为 `'screen'`：
+
+```js
+mpx.config.rnConfig.dimensionsBase = 'screen'
+```
+
+配置后，响应式单位和媒体查询将使用 `Dimensions.get('screen')` 的宽高，并在 Screen 尺寸变化时重新计算相关样式及触发 `onResize`。
+
 #### mpx.config.rnConfig.customDimensions
 
 ```ts
 (dimensions: { window: ScaledSize; screen: ScaledSize }) => { window: ScaledSize; screen: ScaledSize } | void
 ```
 
-在某些情况下，我们可能不希望当前应用全屏展示，Mpx 内部基于 ScreenWidth 与 ScreenHeight 作为 rpx、vh、vw、媒体查询、onResize等特性的依赖内容，此时可在 `mpx.config.rnConfig.customDimensions` 中自定义 screen 尺寸信息来得到想要的渲染效果。
+在某些情况下，我们可能不希望当前应用全屏展示。此时可在 `mpx.config.rnConfig.customDimensions` 中自定义 window 或 screen 尺寸信息，`rpx` / `vh` / `vw`、媒体查询与 `onResize` 会使用 `dimensionsBase` 指定的尺寸，并在该尺寸变化时触发相关更新。
+
+可在此方法中返回修改后的 dimensions，如果无返回或返回 `undefined`，则使用原始入参。
+
+例如，使用默认的 `dimensionsBase: 'window'` 时，折叠屏展开后如果期望应用只在一半窗口中展示，可在 `customDimensions` 中将 `window.width` 设为原来的一半。
+
+运行期间修改 `dimensionsBase` 或 `customDimensions` 后，需要调用 `notifyDimensionsChange()` 使配置生效。可以同时修改两项配置，再统一通知一次。
+
+#### notifyDimensionsChange
+
+```ts
+(dimensions?: { window: ScaledSize; screen: ScaledSize }) => void
+```
+
+主动通知框架 Dimensions 发生变化，使 `rpx` / `vw` / `vh`、媒体查询和 `onResize` 等依赖尺寸的能力重新计算。传入 `dimensions` 时使用传入值；不传参数时通过 `Dimensions.get('window')` 与 `Dimensions.get('screen')` 获取当前原始尺寸。两种方式都会重新执行 `rnConfig.customDimensions`，并根据 `dimensionsBase` 指定的尺寸判断是否触发刷新。
+
+```js
+// 宿主容器尺寸发生变化后，重新读取当前 Dimensions
+notifyDimensionsChange()
+
+// 也可以显式传入尺寸
+notifyDimensionsChange({
+  window: nextWindow,
+  screen: nextScreen
+})
+```
 
-可在此方法中返回修改后的 dimensions，如果无返回或返回 undefined，则以入参作为返回值
+框架会复制原始 Dimensions 后再交给 `customDimensions`，避免自定义逻辑直接修改 React Native 返回的原对象。
 
-例如: 在折叠屏中我们期望只在其中一半屏上展示，可在 customDimensions 中判断当前是否为折叠屏展开状态，如果是则将 ScreenWidth 设置为原来的一半。
+#### getStyleDimensions
+
+```ts
+(dimensionsBase?: 'window' | 'screen') => ScaledSize
+```
+
+返回最近一次初始化或 `notifyDimensionsChange()` 后生效的尺寸副本。可传入 `'window'` 或 `'screen'` 指定本次获取的尺寸；不传时使用最近一次生效的 `rnConfig.dimensionsBase`，传参不会修改该配置。修改返回值不会影响框架内部缓存。该方法只读取尺寸，不会使运行期间修改的 `dimensionsBase` 或 `customDimensions` 生效。
+
+```js
+const dimensions = getStyleDimensions()
+console.log(dimensions.width, dimensions.height)
+const screenDimensions = getStyleDimensions('screen')
+```
 
 
 ### 前后台切换 {#app-state-change}

docs-vitepress/guide/rn/style.md

@@ -103,19 +103,14 @@ Mpx 转 RN 支持以下单位，部分单位在特定情况下存在使用限制
 |------|---------|----------|
 | `%` | ✅ 支持 | 百分比单位参考 [百分比单位说明](#percentage-unit-explanation) |
 | `px` | ✅ 支持 | 绝对像素单位 |
-| `rpx` | ✅ 支持 | 响应式像素，根据屏幕宽度动态计算 |
-| `vh` | ✅ 支持 | 相对于视口的高度 |
-| `vw` | ✅ 支持 | 相对视口的宽度 |
+| `rpx` | ✅ 支持 | 响应式像素，默认根据 Window 宽度动态计算 |
+| `vh` | ✅ 支持 | 默认使用 Window 高度计算 |
+| `vw` | ✅ 支持 | 默认使用 Window 宽度计算 |
 
-> [!tip] vh 单位使用注意
+> [!tip] 尺寸基准说明
 >
-> - **问题**：使用系统默认导航栏时，`vh` 的计算基准可能会发生变化
->   - 页面首次加载：`100vh = 屏幕总高度`
->   - 状态更新后：`100vh = 屏幕高度 - 导航栏高度`
->
-> - **影响**：可能导致布局在运行时突然变化
->
-> - **建议**：如需使用 `vh` 单位，推荐配合自定义导航栏使用，以确保计算基准始终一致
+> `rpx` / `vw` / `vh` 和媒体查询默认使用 React Native `Dimensions.get('window')` 的尺寸。可将 `mpx.config.rnConfig.dimensionsBase` 设置为 `'screen'`，恢复基于 Screen 尺寸计算的旧版本效果。所选尺寸变化时，依赖这些能力的组件会重新计算样式。
+
 ### 百分比单位说明 {#percentage-unit-explanation}
 
 RN 原生较多属性不支持百分比，或对百分比的支持存在 bug（如 `font-size`、`translate` 等），但这些属性在编写 Web/小程序代码时使用较多，所以框架进行了抹平支持。

packages/api-proxy/src/platform/api/system/rnSystem.js

@@ -3,7 +3,7 @@ import { initialWindowMetrics } from 'react-native-safe-area-context'
 import { getFocusedNavigation } from '../../../common/js'
 
 const getWindowInfo = function () {
-  const dimensionsScreen = Dimensions.get('screen')
+  const dimensionsScreen = global.getStyleDimensions?.('screen') || Dimensions.get('screen')
   const navigation = getFocusedNavigation() || {}
   const initialWindowMetricsInset = initialWindowMetrics?.insets || {}
   const navigationInsets = navigation.insets || {}

packages/core/@types/global.d.ts

@@ -14,3 +14,10 @@ declare module '*?resolve' {
 
 declare let setAppShow: () => void
 declare let setAppHide: () => void
+
+declare let notifyDimensionsChange: (dimensions?: {
+  window: import('react-native').ScaledSize
+  screen: import('react-native').ScaledSize
+}) => void
+
+declare let getStyleDimensions: (dimensionsBase?: 'window' | 'screen') => Readonly<import('react-native').ScaledSize>

packages/core/@types/index.d.ts

@@ -476,14 +476,22 @@ export interface RnConfig {
   }) => void
 
   /**
-   * 自定义屏幕尺寸信息，用于 mpx style 渲染等依赖尺寸的功能。
+   * 自定义窗口和屏幕尺寸信息，用于 mpx style 渲染等依赖尺寸的功能。
+   * 运行期间修改后需调用 notifyDimensionsChange() 使配置生效。
    *
    * @param dimensions 包含 window 和 screen 的尺寸信息
    * @returns 返回修改后的尺寸对象，或 void 表示不修改
    */
-  customDimensions?: <T extends { window: ScaledSize; screen: ScaledSize }>(
-    dimensions: T
-  ) => T | void
+  customDimensions?: (
+    dimensions: { window: ScaledSize; screen: ScaledSize }
+  ) => { window: ScaledSize; screen: ScaledSize } | void
+
+  /**
+   * rpx、vw、vh、媒体查询与 onResize 使用的尺寸基准。
+   * 运行期间修改后需调用 notifyDimensionsChange() 使配置生效。
+   * @default 'window'
+   */
+  dimensionsBase?: 'window' | 'screen'
 
   /**
    * 加载并执行异步分包的方法。