didi · xiao19880917lu · Oct 29, 2025 · Oct 30, 2025 · Oct 30, 2025 · Nov 6, 2025
diff --git a/docs-vitepress/api-proxy/interface/menu/getMenuButtonBoundingClientRect.md b/docs-vitepress/api-proxy/interface/menu/getMenuButtonBoundingClientRect.md
@@ -2,7 +2,9 @@
 
 获取菜单按钮（右上角胶囊按钮）的布局位置信息。坐标信息以屏幕左上角为原点。
 
-支持情况： 微信、支付宝
+支持情况: 微信、支付宝、React Native
+
+> **React Native 说明**: 由于 RN 应用没有微信的右上角胶囊按钮,该 API 会基于屏幕尺寸和安全区返回一个模拟的胶囊位置,可用于获取顶部导航区域的参考尺寸,保持代码兼容性。
 
 [参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/menu/wx.getMenuButtonBoundingClientRect.html)
 

diff --git a/docs-vitepress/api/compile.md b/docs-vitepress/api/compile.md
@@ -2092,27 +2092,4 @@ module.exports = defineConfig({
   }
 </script>
 
-```
-## useExtendComponents
-`object`
-
-除基础组件外，Mpx 还提供了一些扩展组件。这些组件需要开发者根据运行环境进行按需注册。注册成功后，即可作为全局自定义组件使用。
-```js
-// mpx.config.js
-defineConfig({
-  pluginOptions: {
-    mpx: {
-      plugin: {
-        useExtendComponents: {
-          wx: ["recycle-view"],
-          ali: ["recycle-view"],
-          web: ["recycle-view"],
-          ios: ["recycle-view"],
-          android: ["recycle-view"],
-          harmony: ["recycle-view"]
-        }
-      }
-    }
-  }
-})
 ```
diff --git a/docs-vitepress/guide/basic/component.md b/docs-vitepress/guide/basic/component.md
@@ -712,13 +712,27 @@ Mpx中提供了使用方法类似于 Vue 的动态组件能力，这是一个基
 ```html
 <!-- 组件模板 -->
 <!-- components/mySlot.mpx -->
-<view>
-  <view>这是组件模板</view>
-  <slot name="slot1"></slot>
-  <slot name="slot2"></slot>
-</view>
+<template>
+  <view>
+    <view>这是组件模板</view>
+    <slot name="slot1"></slot>
+    <slot name="slot2"></slot>
+  </view>
+<template>
+
+<script>
+import { createComponent } from '@mpxjs/core'
+
+createComponent({
+  options: {
+    multipleSlots: true // 启用多slot支持
+  }
+})
+</script>
 ```
 
+> 注意：使用多个slot时，需要在组件选项中开启 `multipleSlots: true`。
+
 使用组件时：
 
 ```html
@@ -732,16 +746,6 @@ Mpx中提供了使用方法类似于 Vue 的动态组件能力，这是一个基
   </view>
 </template>
 
-<script>
-import { createComponent } from '@mpxjs/core'
-
-createComponent({
-  options: {
-    multipleSlots: true // 启用多slot支持
-  }
-})
-</script>
-
 <script type="application/json">
   {
     "usingComponents": {
@@ -751,6 +755,4 @@ createComponent({
 </script>
 ```
 
-> 注意：使用多个slot时，需要在组件选项中开启 `multipleSlots: true`。
-
 更多关于插槽的使用细节可查看[微信小程序官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html)。
diff --git a/docs-vitepress/guide/extend/extend-component.md b/docs-vitepress/guide/extend/extend-component.md
@@ -1,28 +1,21 @@
 # Mpx 扩展组件
 
-除基础组件外，Mpx 额外提供一些扩展组件。扩展组件需开发者在 `mpx.config.js`中通过编译配置`useExtendComponents`按需注册，注册成功后即可作为全局自定义组件使用。
-```js
-// mpx.config.js
-defineConfig({
-  pluginOptions: {
-    mpx: {
-      plugin: {
-        useExtendComponents: {
-          wx: ["recycle-view"],
-          ali: ["recycle-view"],
-          web: ["recycle-view"],
-          ios: ["recycle-view"],
-          android: ["recycle-view"],
-          harmony: ["recycle-view"]
-        }
-      }
-    }
+除基础组件外，Mpx 额外提供一些扩展组件。扩展组件需要在页面或组件的 `usingComponents` 中注册后使用。
+
+```html
+<script type="application/json">
+{
+  "usingComponents": {
+    "section-list": "@mpxjs/webpack-plugin/lib/runtime/components/extends/section-list"
   }
-})
+}
+</script>
 ```
 
+Mpx 会根据当前编译的目标平台（wx/ali/web/ios/android/harmony），自动解析到对应平台的扩展组件实现。
+
 
-## recycle-view 
+## section-list
 
 跨端虚拟列表组件，可自定义分组头、列表头、列表项，自动分段渲染兼容各端。
 
@@ -32,19 +25,22 @@ defineConfig({
 
 | 属性名                  | 类型         | 默认值   | 说明                   | 支持平台  |
 |-----------------------|-------------|----------|------------------------|-----------|
-| height                | String/Number | 100%    | 组件高度                | 全平台    |
-| width                 | String/Number | 100%    | 组件宽度                | 全平台    |
-| listData              | Array       | []       | 列表数据，如需使用列表分组头 `section-header`，对应 item 的数据需要包含 `isSectionHeader: true` 标识    | 全平台    |
-| enable-sticky          | Boolean     | false    | 启用分组吸顶            | 全平台<br>⚠️微信小程序环境，需要使用 skyline 渲染模式，webview 模式不支持；web 环境仅支持移动端，不支持 pc 端   |
-| scroll-with-animation   | Boolean     | false    | 滚动动画                | 全平台    |
-| generic:recycle-item         | string      |       | 列表项，抽象节点组件名，对应组件需要通过 usingComponents 注册               | 全平台  |
-| generic:section-header    | string      |       | 列表分组头，抽象节点组件名，对应组件需要通过 usingComponents 注册          | 全平台  |
-| generic:list-header     | string      |       | 列表头，抽象节点组件名，对应组件需要通过 usingComponents 注册       | 全平台  |
-| useListHeader         | Boolean     | false     | 使用自定义列表头        | 全平台    |
-| listHeaderData        | Object      | {}       | 列表头数据              | 全平台    |
-| itemHeight            | Object      | {}       | 列表项高度配置（支持 getter/value），必须配置    | 全平台      |
-| sectionHeaderHeight   | Object      | {}       | 分组头部高度配置（getter/value），若使用了自定义分组头必须配置      | 全平台      |
-| listHeaderHeight      | Object      | {}       | 列表头部高度配置（getter/value），若使用了列表头必须配置      | 全平台      |
+| height                | String/Number | 100%    | 组件高度                | 微信小程序、支付宝小程序、Web、RN    |
+| width                 | String/Number | 100%    | 组件宽度                | 微信小程序、支付宝小程序、Web、RN    |
+| listData              | Array       | []       | 列表数据，如需使用列表分组头 `section-header`，对应 item 的数据需要包含 `isSectionHeader: true` 标识    | 微信小程序、支付宝小程序、Web、RN    |
+| enable-sticky          | Boolean     | false    | 启用分组吸顶            | 微信小程序、支付宝小程序、Web、RN<br>⚠️微信小程序环境，需要使用 skyline 渲染模式，webview 模式不支持；web 环境仅支持移动端，不支持 pc 端   |
+| scroll-with-animation   | Boolean     | false    | 滚动动画                | 微信小程序、支付宝小程序、Web、RN    |
+| useListHeader         | Boolean     | false     | 使用自定义列表头        | 微信小程序、支付宝小程序、Web、RN    |
+| listHeaderData        | Object      | {}       | 列表头数据              | 微信小程序、支付宝小程序、Web、RN    |
+| useListFooter       | Boolean     | false     | 使用自定义列表页脚        | 微信小程序、支付宝小程序、Web、RN    |
+| listFooterData        | Object      | {}       | 列表头数据              | 微信小程序、支付宝小程序、Web、RN    |
+| generic:recycle-item         | String      |       | 列表项，抽象节点组件名，对应组件需要通过 usingComponents 注册               | 微信小程序、支付宝小程序、Web、RN  |
+| generic:section-header    | String      |       | 列表分组头，抽象节点组件名，对应组件需要通过 usingComponents 注册          | 微信小程序、支付宝小程序、Web、RN  |
+| generic:list-header     | String      |       | 列表头，抽象节点组件名，对应组件需要通过 usingComponents 注册       | 微信小程序、支付宝小程序、Web、RN  |
+| generic:list-footer     | String      |       | 列表页脚，抽象节点组件名，对应组件需要通过 usingComponents 注册       | 微信小程序、支付宝小程序、Web、RN  |
+| itemHeight            | Object      | {}       | 列表项高度配置（支持 getter/value），必须配置    | 微信小程序、支付宝小程序、Web、RN      |
+| sectionHeaderHeight   | Object      | {}       | 分组头部高度配置（getter/value），若使用了自定义分组头必须配置      | 微信小程序、支付宝小程序、Web、RN      |
+| listHeaderHeight      | Object      | {}       | 列表头部高度配置（getter/value），若使用了列表头必须配置      | 微信小程序、支付宝小程序、Web、RN      |
 | bufferScale           | Number      | 1        | 渲染缓冲区行数（虚拟滚动优化）    | 仅支付宝小程序/web支持 |
 | minRenderCount        | Number      | 10       | 最小渲染项目数                 | 仅支付宝小程序/web支持 |
 
@@ -74,19 +70,20 @@ height: {
 
 | 事件名                 | 说明                             | 支持平台     |
 |-----------------------|-----------------------------------|--------------|
-| bindscroll                | 滚动时触发，返回滚动信息            | 全平台       |
-| bindscrolltolower         | 滚动到底部/触底通知                 | 全平台       |
-| bindscrollToIndex         | 组件方法，滚动到指定索引             | 全平台       |
+| bindscroll                | 滚动时触发，返回滚动信息            | 微信小程序、支付宝小程序、Web、RN       |
+| bindscrolltolower         | 滚动到底部/触底通知                 | 微信小程序、支付宝小程序、Web、RN       |
+| bindscrollToIndex         | 组件方法，滚动到指定索引             | 微信小程序、支付宝小程序、Web、RN       |
 
 `scrollToIndex({ index, animated, viewPosition })` 参数说明：
 - `index`：目标索引
 - `animated`：是否滚动动画
+- `viewOffset`：滚动偏移量
 - `viewPosition`：滚动定位，0:顶部, 0.5:中间, 1:底部
 
 ### 用法示例
 
 ```js
-<recycle-view
+<section-list
   generic:recycle-item="normal-recycle-item"
   generic:section-header="section-header"
   generic:list-header="list-header"
@@ -154,6 +151,7 @@ height: {
   <script type="application/json">
   {
     "usingComponents": {
+      "section-list": "@mpxjs/webpack-plugin/lib/runtime/components/extends/section-list",
       "normal-recycle-item": "@/components/recycle-item",
       "section-header": "@/components/section-header",
       "list-header": "@/components/list"
@@ -168,6 +166,89 @@ height: {
 - 可直接调用 ref 实例执行 `scrollToIndex` 方法实现滚动。
 - 如果用户滑动的速度超过渲染的速度，则会先看到空白的内容，这是为了长列表优化不得不作出的妥协。
 - 当某行滑出渲染区域之外后，其内部状态将不会保留。
-- 在 RN 环境，recycle-view 通过 RN 提供的 SectionList 实现分组吸顶。受 RN 底层实现机制限制，开启 `enable-sticky` 且快速滑动时，自定义分组头有时会出现闪烁现象。此问题需要等待 RN 官方修复，我们会持续关注并跟进。
+- 在 RN 环境，section-list 通过 RN 提供的 SectionList 实现分组吸顶。受 RN 底层实现机制限制，开启 `enable-sticky` 且快速滑动时，自定义分组头有时会出现闪烁现象。此问题需要等待 RN 官方修复，我们会持续关注并跟进。
 - 若某行需要使用 `section-header` 对应的抽象节点渲染，则该行数据必须包含 `isSectionHeader: true` 字段；否则默认使用 `recycle-item` 对应的抽象节点渲染
 
+
+## sticky-section
+
+吸顶布局容器，仅支持作为 `<scroll-view>` 的直接子节点
+
+支持平台：微信小程序（仅 skyline 支持）、支付宝小程序、Web、RN
+
+### 用法示例
+
+```html
+<template>
+  <scroll-view>
+    <sticky-section>
+      <sticky-header>这是会吸顶的内容</sticky-header>
+    </sticky-section>
+  </scroll-view>
+</template>
+
+<script type="application/json">
+{
+  "usingComponents": {
+    "sticky-section": "@mpxjs/webpack-plugin/lib/runtime/components/extends/sticky-section"
+  }
+}
+</script>
+```
+
+
+## sticky-header
+
+吸顶头部组件，支持在滚动容器中实现元素吸顶效果。仅支持作为 `<scroll-view>` 的直接子节点或 `sticky-section` 组件直接子节点
+
+支持平台：微信小程序（仅 skyline 支持）、支付宝小程序、Web、RN
+
+### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 | 支持平台 |
+|-------|------|--------|------|---------|
+| offsetTop | Number | 0 | 吸顶距离顶部的偏移量 | 微信小程序、支付宝小程序、Web、RN |
+| padding | Array | - | 内边距配置 [top, right, bottom, left] | 微信小程序、支付宝小程序、Web、RN |
+| scrollViewId | String | '' | 滚动容器的 id, 支付宝环境必传, 值与选择器 id 值一致 | 支付宝小程序 |
+| stickyId | String | '' | 吸顶元素的唯一标识，支付宝环境必传，值与选择器 id 值一致 | 支付宝小程序 |
+| enablePolling | Boolean | false | 启用轮询刷新 | 支付宝小程序 |
+| pollingDuration | Number | 300 | 轮询间隔时间（毫秒） | 支付宝小程序 |
+
+### 事件
+
+| 事件名 | 说明 | 支持平台 |
+|-------|------|---------|
+| stickontopchange | 吸顶状态改变时触发，返回 { isStickOnTop, id } | 微信小程序、支付宝小程序、Web、RN |
+
+**注意**：
+- 支付宝小程序中该功能基于 IntersectionObserver 实现，但在支付宝平台上，IntersectionObserver 的回调可能存在触发不及时或不触发的情况，进而导致 stickontopchange 事件无法及时触发，或 sticky-header 吸附位置异常。
+
+为此我们提供了 enablePolling 属性。开启后将通过定时轮询的方式校验 sticky-header 当前吸附状态是否正确，若发现异常会自动进行修正。建议在支付宝平台根据实际情况按需开启该配置。
+
+- RN 环境的 sticky-header 更适用于内容稳定，状态不常变更的场景使用，目前如果 sticky-header 还在动画过程中就触发组件更新（如在bindstickontopchange 回调中立刻更新 state）、scroll-view 内容高度由多变少、通过修改 scroll-into-view、scroll-top 让 scroll-view 滚动，以上场景在安卓上都可能会导致闪烁或抖动
+
+
+### 用法示例
+
+```html
+<template>
+  <scroll-view id="scrollViewContainer" scroll-y>
+    <sticky-header 
+      scroll-view-id="scrollViewContainer"
+      sticky-id="header1"
+      offset-top="0"
+      bind:stickontopchange="handleStickyChange">
+      <view>这是会吸顶的内容</view>
+    </sticky-header>
+  </scroll-view>
+</template>
+
+<script type="application/json">
+{
+  "usingComponents": {
+    "sticky-header": "@mpxjs/webpack-plugin/lib/runtime/components/extends/sticky-header"
+  }
+}
+</script>
+```
+
diff --git a/docs-vitepress/guide/rn/application-api.md b/docs-vitepress/guide/rn/application-api.md
@@ -476,3 +476,24 @@ boolean
 Mpx 框架默认会使用 `ReactNative.AppState.addEventListener('change', callback)` 作为 Mpx 应用切换切换台的驱动，从而触发对于的钩子（如onhide/onshow）
 
 在需要将 RN 应用嵌入到现有的 NA 应用中时，可能会出现AppState触发时机异常的情况（例如从 RN 页面跳转到 NA 页面时），此时可以将 disableAppStateListener 设置为 true 来禁用框架内部对 AppState 的监听。但需要在合适的时机手动调用 setAppShow() 与 setAppHide() 方法来进行驱动以确保对于的钩子能正常触发。
+
+
+### 自定义设置底部虚拟按键区高度
+
+#### mpx.config.rnConfig.getBottomVirtualHeight
+
+```ts
+() => number
+```
+Android的不同系统或者手机的虚拟按键区高度可能存在不同的情况，框架内部统一使用了initialWindowMetrics.insets.bottom，如存在需要单独调整的场景可自定义设置虚拟按键区高度。
+
+```javascript
+// 例子
+import ReactNative from 'react-native'
+import { initialWindowMetrics } from 'react-native-safe-area-context'
+mpx.config.rnConfig.getBottomVirtualHeight = (bottomHeight) => {
+  const screenDimensions = ReactNative.Dimensions.get('screen')
+  const windowDimensions = ReactNative.Dimensions.get('window')
+  return Math.max(initialWindowMetrics?.insets?.bottom || 0 , (screenDimensions.height - windowDimensions.height - ReactNative.StatusBar.currentHeight) || 0, 0)
+}vscode 如何打开markdown
+```