feat: ✨ 新增 root-portal 组件支持从页面中脱离出来，用于解决各种 fixed 失效问题 (#1155)

docs/.vitepress/config.mts

@@ -1,7 +1,7 @@
 /*
  * @Author: weisheng
  * @Date: 2023-07-27 10:26:09
- * @LastEditTime: 2025-06-29 17:05:24
+ * @LastEditTime: 2025-07-07 20:46:21
  * @LastEditors: weisheng
  * @Description:
  * @FilePath: /wot-design-uni/docs/.vitepress/config.mts
@@ -119,386 +119,6 @@ export default defineConfig({
       message: `Released under the MIT License.`,
       copyright: 'Copyright © 2023-present weisheng',
     },
-    nav: [
-      {
-        text: '指南', activeMatch: '/guide/', items: [
-          {
-            text: '介绍',
-            link: '/guide/introduction',
-          },
-          {
-            text: '快速上手',
-            link: '/guide/quick-use',
-          },
-          {
-            text: '定制主题',
-            link: '/guide/custom-theme',
-          },
-          {
-            text: '常见问题',
-            link: '/guide/common-problems',
-          },
-          {
-            text: '国际化',
-            link: '/guide/locale',
-          }, {
-            text: '更新日志',
-            link: '/guide/changelog',
-          }, {
-            text: '⭐ 案例',
-            link: '/guide/cases',
-          }, {
-            text: '加群沟通',
-            link: '/guide/join-group',
-          }
-        ]
-      },
-      {
-        text: '组件', activeMatch: '/component/', items: [
-          {
-            text: '基础组件',
-            link: "/component/button",
-          },
-          {
-            text: "导航组件",
-            link: "/component/pagination"
-          }, {
-            text: "数据输入",
-            link: "/component/calendar",
-          }, {
-            text: "反馈组件",
-            link: "/component/action-sheet",
-          }, {
-            text: "数据展示",
-            link: "/component/badge",
-          }
-
-        ]
-      },
-      { text: '🥤一杯咖啡', link: '/reward/reward', activeMatch: '/reward/' },
-      { text: '快速上手项目', link: 'https://github.com/Moonofweisheng/wot-demo' },
-      {
-        text: '周边生态',
-        items: [
-          { text: 'Vue3 uni-app路由库', link: 'https://moonofweisheng.github.io/uni-mini-router/' },
-          { text: '多平台小程序CI工具', link: 'https://github.com/Moonofweisheng/uni-mini-ci' },
-          { text: 'Uni Helper', link: 'https://uni-helper.js.org/' },
-          { text: 'uni-ku', link: 'https://github.com/uni-ku' },
-        ],
-      },
-    ],
-    sidebar: {
-      '/guide/': [
-        {
-          text: '介绍',
-          link: '/guide/introduction',
-        },
-        {
-          text: '快速上手',
-          link: '/guide/quick-use',
-        },
-        {
-          text: '定制主题',
-          link: '/guide/custom-theme',
-        },
-        {
-          text: '国际化',
-          link: '/guide/locale',
-        },
-        {
-          text: '常见问题',
-          link: '/guide/common-problems',
-        },
-        {
-          text: '更新日志',
-          link: '/guide/changelog',
-        }, {
-          text: '⭐ 案例',
-          link: '/guide/cases',
-        }, {
-          text: '加群沟通',
-          link: '/guide/join-group',
-        }
-      ],
-      '/reward/': [
-        {
-          text: '🥤一杯咖啡',
-          link: '/reward/reward',
-        },
-        {
-          text: '榜上有名',
-          link: '/reward/donor',
-        }
-      ],
-
-      '/component/': [
-        {
-          text: '基础',
-          collapsed: false,
-          items: [
-            {
-              link: "/component/button",
-              text: "Button 按钮"
-            }, {
-              link: "/component/icon",
-              text: "Icon 图标"
-            }, {
-              link: "/component/layout",
-              text: "Layout 布局"
-            }, {
-              link: "/component/config-provider",
-              text: "ConfigProvider 全局配置"
-            }, {
-              link: "/component/popup",
-              text: "Popup 弹出层"
-            }, {
-              link: "/component/resize",
-              text: "Resize 监听元素尺寸变化"
-            }, {
-              link: "/component/transition",
-              text: "Transition 动画"
-            }, {
-              link: "/component/fab",
-              text: "Fab 悬浮按钮"
-            }, {
-              link: "/component/text",
-              text: "Text 文本"
-            }
-          ]
-        },
-        {
-
-          text: "导航",
-          collapsed: false,
-          items: [{
-            link: "/component/pagination",
-            text: "Pagination 分页"
-          }, {
-            link: "/component/popover",
-            text: "Popover 气泡"
-          }, {
-            link: "/component/tabs",
-            text: "Tabs 标签页"
-          }, {
-            link: "/component/segmented",
-            text: "Segmented 分段器"
-          }, {
-            link: "/component/tabbar",
-            text: "Tabbar 标签栏"
-          }, {
-            link: "/component/navbar",
-            text: "Navbar 导航栏"
-          }, {
-            link: "/component/sidebar",
-            text: "Sidebar 侧边栏"
-          }, {
-            link: "/component/backtop",
-            text: "Backtop 回到顶部"
-          }, {
-            link: "/component/index-bar",
-            text: "IndexBar 索引栏"
-          }]
-        }, {
-
-          text: "数据输入",
-          collapsed: false,
-          items: [{
-            link: "/component/calendar",
-            text: "Calendar 日历选择器"
-          }, {
-            link: "/component/calendar-view",
-            text: "CalendarView 日历面板"
-          }, {
-            link: "/component/checkbox",
-            text: "Checkbox 复选框"
-          }, {
-            link: "/component/col-picker",
-            text: "ColPicker 多列选择器"
-          }, {
-            link: "/component/datetime-picker",
-            text: "DatetimePicker 时间选择器"
-          }, {
-            link: "/component/datetime-picker-view",
-            text: "DatetimePickerView 时间选择器视图"
-          }, {
-            link: "/component/form",
-            text: "Form 表单"
-          }, {
-            link: "/component/input",
-            text: "Input 输入框"
-          }, {
-            link: "/component/textarea",
-            text: "Textarea 文本域"
-          }, {
-            link: "/component/input-number",
-            text: "InputNumber 计数器"
-          }, {
-            link: "/component/picker",
-            text: "Picker 选择器"
-          }, {
-            link: "/component/picker-view",
-            text: "PickerView 选择器视图"
-          }, {
-            link: "/component/radio",
-            text: "Radio 单选框"
-          }, {
-            link: "/component/rate",
-            text: "Rate 评分"
-          }, {
-            link: "/component/search",
-            text: "Search 搜索框"
-          }, {
-            link: "/component/select-picker",
-            text: "SelectPicker 单复选选择器"
-          }, {
-            link: "/component/slider",
-            text: "Slider 滑块"
-          }, {
-            link: "/component/switch",
-            text: "Switch 开关"
-          }, {
-            link: "/component/upload",
-            text: "Upload 上传"
-          }, {
-            link: "/component/password-input",
-            text: "PasswordInput 密码输入框"
-          }, {
-            link: "/component/signature",
-            text: "Signature 签名"
-          }]
-        }, {
-          text: "反馈",
-          collapsed: false,
-          items: [{
-            link: "/component/action-sheet",
-            text: "ActionSheet 动作面板"
-          }, {
-            link: "/component/drop-menu",
-            text: "DropMenu 下拉菜单"
-          }, {
-            link: "/component/floating-panel",
-            text: "FloatingPanel 浮动面板"
-          }, {
-            link: "/component/loading",
-            text: "Loading 加载"
-          }, {
-            link: "/component/message-box",
-            text: "MessageBox 弹框"
-          }, {
-            link: "/component/notice-bar",
-            text: "NoticeBar 通知栏"
-          }, {
-            link: "/component/overlay",
-            text: "Overlay 遮罩层"
-          }, {
-            link: "/component/progress",
-            text: "Progress 进度条"
-          }, {
-            link: "/component/circle",
-            text: "Circle 环形进度条"
-          }, {
-            link: "/component/sort-button",
-            text: "SortButton 排序按钮"
-          }, {
-            link: "/component/status-tip",
-            text: "StatusTip 缺省提示"
-          }, {
-            link: "/component/swipe-action",
-            text: "SwipeAction 滑动操作"
-          }, {
-            link: "/component/toast",
-            text: "Toast 轻提示"
-          }, {
-            link: "/component/notify",
-            text: "Notify 消息通知"
-          }, {
-            link: "/component/tooltip",
-            text: "Tooltip 文字提示"
-          }, {
-            link: "/component/count-down",
-            text: "CountDown 倒计时"
-          }, {
-            link: "/component/count-to",
-            text: "CountTo 数字滚动"
-          }, {
-            link: "/component/keyboard",
-            text: "Keyboard 虚拟键盘"
-          }, {
-            link: "/component/number-keyboard",
-            text: "NumberKeyboard 数字键盘"
-          }]
-        },
-        {
-          text: "数据展示",
-          collapsed: false,
-          items: [{
-            link: "/component/badge",
-            text: "Badge 徽标"
-          }, {
-            link: "/component/card",
-            text: "Card 卡片"
-          }, {
-            link: "/component/cell",
-            text: "Cell 单元格"
-          }, {
-            link: "/component/collapse",
-            text: "Collapse 折叠面板"
-          }, {
-            link: "/component/curtain",
-            text: "Curtain 幕帘"
-          }, {
-            link: "/component/divider",
-            text: "Divider 分割线"
-          }, {
-            link: "/component/gap",
-            text: "Gap 间隔槽"
-          }, {
-            link: "/component/img",
-            text: "Img 图片"
-          }, {
-            link: "/component/img-cropper",
-            text: "ImgCropper 图片裁剪"
-          }, {
-            link: "/component/grid",
-            text: "Grid 宫格"
-          }, {
-            link: "/component/loadmore",
-            text: "Loadmore 加载更多"
-          }, {
-            link: "/component/skeleton",
-            text: "Skeleton 骨架屏"
-          }, {
-            link: "/component/steps",
-            text: "Steps 步骤条"
-          }, {
-            link: "/component/sticky",
-            text: "Sticky 粘性布局"
-          }, {
-            link: "/component/tag",
-            text: "Tag 标签"
-          }, {
-            link: "/component/watermark",
-            text: "Watermark 水印"
-          }, {
-            link: "/component/swiper",
-            text: "Swiper 轮播图"
-          }, {
-            link: "/component/table",
-            text: "Table 表格"
-          }]
-        },
-        {
-          text: '组合式API',
-          items: [
-            { text: 'useUpload', link: '/component/use-upload' },
-            { text: 'useCountDown', link: '/component/use-count-down' },
-            { text: 'useToast', link: '/component/use-toast' },
-            { text: 'useMessage', link: '/component/use-message' }
-          ]
-        }
-      ]
-    }
-
   },
 
 })

docs/.vitepress/locales/en-US.ts

@@ -173,6 +173,10 @@ export default defineConfig({
             {
               link: '/en-US/component/text',
               text: 'Text'
+            },
+            {
+              link: '/en-US/component/root-portal',
+              text: 'RootPortal'
             }
           ]
         },

docs/.vitepress/locales/zh-CN.ts

@@ -173,6 +173,10 @@ export default defineConfig({
             {
               link: '/component/text',
               text: 'Text 文本'
+            },
+            {
+              link: '/component/root-portal',
+              text: 'RootPortal 根节点'
             }
           ]
         },

docs/component/calendar.md

@@ -438,6 +438,7 @@ function handleConfirm({ value }) {
 | rules                   | 表单验证规则，结合`wd-form`组件使用                                                                                                                                                                | `FormItemRule []`     | -                                                                                           | `[]`                  | -                |
 | immediate-change        | type 为 'datetime' 或 'datetimerange' 时有，是否在手指松开时立即触发 picker-view 的 change 事件。若不开启则会在滚动动画结束后触发 change 事件，1.2.25 版本起提供，仅微信小程序和支付宝小程序支持。 | boolean               | -                                                                                           | false                 | 1.2.25           |
 | with-cell               | 是否使用内置 cell 选择器                                                                                                                                                                           | boolean               | -                                                                                           | true                  | 1.5.0 |
+| root-portal             | 是否从页面中脱离出来，用于解决各种 fixed 失效问题                                                                                                                                                   | boolean               | -                                                                                           | false                 | $LOWEST_VERSION$ |
 
 ### FormItemRule 数据结构
 

docs/component/col-picker.md

@@ -652,6 +652,7 @@ const columnChange = ({ selectedItem, resolve, finish }) => {
 | rules                  | 表单验证规则，结合`wd-form`组件使用                                                                                            | `FormItemRule []` | -      | `[]`    | -        |
 | lineWidth              | 底部条宽度，单位像素                                                                                                           | number            | -      | -       | 1.3.7    |
 | lineHeight             | 底部条高度，单位像素                                                                                                           | number            | -      | -       | 1.3.7    |
+| root-portal            | 是否从页面中脱离出来，用于解决各种 fixed 失效问题                                                                             | boolean           | -      | false   | $LOWEST_VERSION$ |
 
 ### FormItemRule 数据结构
 

docs/component/curtain.md

@@ -95,6 +95,7 @@ function handleClick() {
 | close-on-click-modal | 点击遮罩是否关闭                                   | boolean | -                                                                        | false  | -        |
 | hide-when-close      | 是否当关闭时将弹出层隐藏（display: none）          | boolean | -                                                                        | true   | -        |
 | z-index              | 设置层级                                           | number  | -                                                                        | 10     | 1.4.0    |
+| root-portal          | 是否从页面中脱离出来，用于解决各种 fixed 失效问题 | boolean | -                                                                        | false  | $LOWEST_VERSION$ |
 
 ## Events
 

docs/component/datetime-picker.md

@@ -318,6 +318,7 @@ const displayFormatTabLabel = (items) => {
 | rules | 表单验证规则，结合`wd-form`组件使用	 | `FormItemRule []`	 | - | `[]` | - |
 | immediate-change | 是否在手指松开时立即触发picker-view的 change 事件。若不开启则会在滚动动画结束后触发 change 事件，1.2.25版本起提供，仅微信小程序和支付宝小程序支持。 | boolean | - | false | 1.2.25 |
 | use-second | 是否显示秒选择，仅在 time 和 datetime 类型下生效 | boolean | - | false | 1.10.0 |
+| root-portal | 是否从页面中脱离出来，用于解决各种 fixed 失效问题 | boolean | - | false | $LOWEST_VERSION$ |
 
 ### FormItemRule 数据结构
 

docs/component/drop-menu.md

@@ -207,6 +207,7 @@ const handleBeforeToggle: DropMenuItemBeforeToggle = ({ status, resolve }) => {
 | value-key     | 选项对象中，value 对应的 key                                           | string                        | -      | value      | -        |
 | label-key     | 选项对象中，展示的文本对应的 key                                       | string                        | -      | label      | -        |
 | tip-key       | 选项对象中，选项说明对应的 key                                         | string                        | -      | tip        | -        |
+| root-portal    | 是否从页面中脱离出来，用于解决各种 fixed 失效问题                     | boolean                       | -      | false      | $LOWEST_VERSION$ |
 
 ## DropdownItem Events
 

docs/component/keyboard.md

@@ -254,9 +254,10 @@ const onDelete = () => showToast('删除')
 | closeButtonLoading  | 关闭按钮是否显示加载状态 | `boolean`             | -                          | `false`    | 1.3.10           |
 | modal               | 是否显示蒙层遮罩         | `boolean`             | -                          | `false`    | 1.3.10           |
 | hideOnClickOutside  | 是否在点击外部时收起键盘 | `boolean`             | -                          | `true`     | 1.3.10           |
-| lockScroll          | 是否锁定滚动             | `boolean`             | -                          | `true`     | 1.3.10           |
+| lockScroll          | 是否锁定背景滚动，锁定时蒙层里的内容也将无法滚动 | `boolean`             | -                          | `true`     | 1.3.10           |
 | safeAreaInsetBottom | 是否在底部安全区域内     | `boolean`             | -                          | `true`     | 1.3.10           |
 | extraKey            | 额外按键                 | `string` / `string[]` | -                          | -          | 1.3.10           |
+| root-portal         | 是否从页面中脱离出来，用于解决各种 fixed 失效问题 | `boolean`             | -                          | `false`    | $LOWEST_VERSION$ |
 
 ## Slot
 

docs/component/message-box.md

@@ -274,6 +274,7 @@ MessageBox.prompt(options)
 | 参数          | 说明     | 类型    | 可选值 | 默认值 | 最低版本 |
 | ------------- | -------- | ------- | ------ | ------ | -------- |
 | selector      | 指定唯一标识 | string  | -      | -     | -   |
+| root-portal   | 是否从页面中脱离出来，用于解决各种 fixed 失效问题 | boolean | -      | false | $LOWEST_VERSION$ |
 
 ## 外部样式类
 

docs/component/notify.md

@@ -193,6 +193,7 @@ export default {
 | background   | 背景颜色                                                          | string | -     | -            | -        |
 | safeHeight   | 顶部安全高度                                                       | number / string | -     | -            | -        |
 | selector   | 指定唯一标识                                                       | number | -     | -            | -        |
+| root-portal | 是否从页面中脱离出来，用于解决各种 fixed 失效问题 | boolean | - | false | $LOWEST_VERSION$ |
 
 ## Events
 | 事件名 | 说明                                      | 参数    | 最低版本 |

docs/component/number-keyboard.md

@@ -236,9 +236,10 @@ const onDelete = () => showToast('删除')
 | closeButtonLoading  | 关闭按钮是否显示加载状态 | `boolean`             | -                   | `false`    | 0.1.65   |
 | modal               | 是否显示蒙层遮罩         | `boolean`             | -                   | `false`    | 0.1.65   |
 | hideOnClickOutside  | 是否在点击外部时收起键盘 | `boolean`             | -                   | `true`     | 0.1.65   |
-| lockScroll          | 是否锁定滚动             | `boolean`             | -                   | `true`     | 0.1.65   |
+| lockScroll          | 是否锁定背景滚动，锁定时蒙层里的内容也将无法滚动 | `boolean`             | -                   | `true`     | 0.1.65   |
 | safeAreaInsetBottom | 是否在底部安全区域内     | `boolean`             | -                   | `true`     | 0.1.65   |
 | extraKey            | 额外按键                 | `string` / `string[]` | -                   | -          | 0.1.65   |
+| root-portal         | 是否从页面中脱离出来，用于解决各种 fixed 失效问题 | `boolean`             | -                   | `false`    | $LOWEST_VERSION$ |
 
 ## Slot
 

docs/component/picker.md

@@ -272,6 +272,7 @@ function handleConfirm({ value }) {
 | rules                  | 表单验证规则，结合`wd-form`组件使用                                                                                                                                   | `FormItemRule []`                 | -      | `[]`    | -                |
 | immediate-change       | 是否在手指松开时立即触发picker-view的 change 事件。若不开启则会在滚动动画结束后触发 change 事件，1.2.25版本起提供，仅微信小程序和支付宝小程序支持。                   | boolean                           | -      | false   | 1.2.25           |
 | clearable              | 显示清空按钮                                                                                                                                                          | boolean                           | -      | false   | 1.3.13 |
+| root-portal            | 是否从页面中脱离出来，用于解决各种 fixed 失效问题                                                                                                                     | boolean                           | -      | false   | $LOWEST_VERSION$ |
 
 ### FormItemRule 数据结构
 

docs/component/popup.md

@@ -66,6 +66,26 @@
 <wd-popup v-model="show" position="bottom" :safe-area-inset-bottom="true" custom-style="height: 200px;" @close="handleClose"></wd-popup>
 ```
 
+## root-portal
+
+当使用 `root-portal` 属性为 `true` 时，弹出层会从页面中脱离出来，这可以避免父组件的 transform、filter 等 CSS 属性影响弹出层的 fixed 定位。
+
+不同平台采用不同的实现方案：
+- **H5端**：使用 Vue 3 的 teleport 特性
+- **APP端**：使用 renderjs 将元素移动到 uni-app 根节点
+- **微信小程序/支付宝小程序**：使用 root-portal 组件
+- **其他平台**：不支持此功能
+
+```html
+<wd-popup v-model="show" root-portal position="center" custom-style="height: 200px;" @close="handleClose">
+  <text class="custom-txt">我被传送到了根节点中</text>
+</wd-popup>
+```
+
+:::tip 提示
+该功能主要用于解决复杂布局中弹窗的层级和定位问题，在需要时才建议开启。
+:::
+
 ## 禁止滚动穿透
 
 使用组件时，会发现内容部分滚动到底时，继续划动会导致底层页面的滚动，这就是滚动穿透。
@@ -103,7 +123,8 @@ h5 滚动穿透不需要处理，组件已默认开启 `lock-scroll`。
 | lazy-render | 弹层内容懒渲染，触发展示时才渲染内容 | boolean | - | true | - |
 | safe-area-inset-bottom | 弹出面板是否设置底部安全距离（iphone X 类型的机型） | boolean | - | false | - |
 | transition | 动画类型，参见 wd-transition 组件的name | string | fade / fade-up / fade-down / fade-left / fade-right / slide-up / slide-down / slide-left / slide-right / zoom-in | - | - |
-| lockScroll | 是否锁定背景滚动 | boolean | - | true | 0.1.30 |
+| lockScroll | 是否锁定背景滚动，锁定时蒙层里的内容也将无法滚动 | boolean | - | true | 0.1.30 |
+| root-portal | 是否从页面中脱离出来，用于解决各种 fixed 失效问题 | boolean | - | false | $LOWEST_VERSION$ |
 
 ## Events
 

docs/component/root-portal.md

@@ -0,0 +1,61 @@
+# Root Portal 根节点传送<el-tag text style="vertical-align: middle;margin-left:8px;" effect="plain">$LOWEST_VERSION$</el-tag>
+
+是否从页面中脱离出来，用于解决各种 fixed 失效问题，主要用于制作弹窗、弹出层等。
+
+:::tip 提示
+根节点传送组件仅支持`微信小程序`、`支付宝小程序`、`APP`和`H5`平台，组件会自动根据平台选择合适的实现方式：
+
+- **H5 端**：使用 `teleport` 特性
+- **微信小程序和支付宝小程序**：使用 `root-portal` 组件
+- **App 端**：使用 renderjs 实现
+- **其他平台**：不支持此功能
+
+该功能主要用于解决复杂布局中弹窗的层级和定位问题，在需要时才建议使用。
+:::
+
+
+
+## 基本用法
+
+使用 `wd-root-portal` 将内容渲染到根节点，避免被父组件的样式影响。
+
+```html
+<wd-button type="primary" @click="show = true">显示弹窗</wd-button>
+<wd-root-portal v-if="show">
+  <view class="modal">
+    <view class="modal-content">
+      <text>这是一个全局弹窗</text>
+      <wd-button @click="show = false">关闭</wd-button>
+    </view>
+  </view>
+</wd-root-portal>
+```
+
+```scss
+.modal {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background-color: rgba(0, 0, 0, 0.5);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+}
+
+.modal-content {
+  background-color: #fff;
+  padding: 20px;
+  border-radius: 8px;
+  text-align: center;
+}
+```
+
+
+## Slots
+
+| 名称    | 说明                         | 最低版本 |
+| ------- | ---------------------------- | -------- |
+| default | 默认插槽，用于渲染传送内容   | -        | 

docs/component/select-picker.md

@@ -361,6 +361,7 @@ function handleConfirm({ value, selectedItems }) {
 | prop                   | 表单域 `model` 字段名，在使用表单校验功能的情况下，该属性是必填的                                        | string                            | -                | -        | -                |
 | rules                  | 表单验证规则，结合`wd-form`组件使用                                                                      | `FormItemRule []`                 | -                | `[]`     | -                |
 | clearable              | 显示清空按钮                                                                                             | boolean                           | -                | false    | 1.3.13 |
+| root-portal            | 是否从页面中脱离出来，用于解决各种 fixed 失效问题                                                       | boolean                           | -                | false    | $LOWEST_VERSION$ |
 
 ### FormItemRule 数据结构
 

docs/en-US/component/curtain.md

@@ -95,6 +95,7 @@ function handleClick() {
 | close-on-click-modal| Close on mask click                                         | boolean | -                                                                         | false   | -        |
 | hide-when-close     | Hide popup layer when closed (display: none)                 | boolean | -                                                                         | true    | -        |
 | z-index             | Set layer level                                              | number  | -                                                                         | 10      | 1.4.0    |
+| root-portal         | Whether to detach from the page, used to solve various fixed positioning issues | boolean | -                                                                         | false   | $LOWEST_VERSION$ |
 
 ## Events
 

docs/en-US/component/datetime-picker.md

@@ -313,6 +313,7 @@ const displayFormatTabLabel = (items) => {
 | rules | Form validation rules, used with `wd-form` component | `FormItemRule []` | - | `[]` | - |
 | immediate-change | Whether to trigger the picker-view's change event immediately when the finger is released. If not enabled, the change event will be triggered after the scrolling animation ends. Available from version 1.2.25, only supported on WeChat Mini Program and Alipay Mini Program. | boolean | - | false | 1.2.25 |
 | use-second | Whether to display the second selection, only effective for time and datetime types | boolean | - | false | 1.10.0 |
+| root-portal | Whether to detach from the page, used to solve various fixed positioning issues | boolean | - | false | $LOWEST_VERSION$ |
 
 ### FormItemRule Data Structure
 

docs/en-US/component/drop-menu.md

@@ -206,6 +206,7 @@ Set the `direction` property value to `up`, and the menu will expand upward
 | value-key | Key for value in options object | string | - | value | - |
 | label-key | Key for display text in options object | string | - | label | - |
 | tip-key | Key for option description in options object | string | - | tip | - |
+| root-portal | Whether to detach from the page, used to solve various fixed positioning issues | boolean | - | false | $LOWEST_VERSION$ |
 | icon-name | Selected icon name (available names in wd-icon component) | string | - | check | - |
 
 ## DropMenu Slot

docs/en-US/component/keyboard.md

@@ -213,6 +213,7 @@ You can bind the keyboard's current input value through `v-model` and limit the
 | show-close-button | Whether to show close button | boolean | true | - |
 | safe-area-inset-bottom | Whether to enable bottom safe area adaptation | boolean | true | - |
 | z-index | Keyboard z-index | number | 100 | - |
+| root-portal | Whether to detach from the page, used to solve various fixed positioning issues | boolean | false | $LOWEST_VERSION$ |
 
 ## Events
 

docs/en-US/component/message-box.md

@@ -214,6 +214,7 @@ You can customize the style of operation buttons through the button properties `
 | close-on-click-modal | Whether to close when clicking modal | boolean | - | true | - |
 | before-confirm | Function executed before confirmation | function({ resolve }) | - | - | - |
 | selector | Component unique identifier | string | - | wd-message-box | - |
+| root-portal | Whether to detach from the page, used to solve various fixed positioning issues | boolean | - | false | $LOWEST_VERSION$ |
 
 ## Events
 

docs/en-US/component/notify.md

@@ -193,6 +193,7 @@ export default {
 | background | Background color | string | - | - | - |
 | safeHeight | Top safe height | number / string | - | - | - |
 | selector | Unique identifier | number | - | - | - |
+| root-portal | Whether to detach from the page, used to solve various fixed positioning issues | boolean | - | false | $LOWEST_VERSION$ |
 
 ## Events
 | Event Name | Description | Parameters | Version |

docs/en-US/component/number-keyboard.md

@@ -217,6 +217,7 @@ Currently, `modal` only controls whether the overlay is transparent, while `hide
 | random-key-order | Whether to shuffle keyboard keys | boolean | - | `false` | - |
 | hide-on-click-outside | Whether to hide keyboard when clicking outside | boolean | - | `true` | - |
 | modal | Whether to show transparent modal | boolean | - | `true` | - |
+| root-portal | Whether to detach from the page, used to solve various fixed positioning issues | boolean | - | `false` | $LOWEST_VERSION$ |
 
 ## Events
 | Event Name | Description | Parameters | Version |

docs/en-US/component/popup.md

@@ -74,6 +74,26 @@ Set the `close-on-click-modal` attribute to `false` to disable closing the popup
 </wd-popup>
 ```
 
+## root-portal
+
+When the `root-portal` attribute is set to `true`, the popup will be teleported to the page root node, which can avoid the influence of parent component's transform, filter and other CSS properties on the fixed positioning of the popup.
+
+Different platforms use different implementation schemes:
+- **H5**: Use Vue 3's teleport feature
+- **APP**: Use renderjs to move elements to the uni-app root node
+- **WeChat Mini Program/Alipay Mini Program**: Use root-portal component
+- **Other platforms**: root-portal feature is not supported
+
+```html
+<wd-popup v-model="show" root-portal position="center" custom-style="height: 200px;" @close="handleClose">
+  <text class="custom-txt">I'm teleported to the root node</text>
+</wd-popup>
+```
+
+:::tip Tip
+This feature is mainly used to solve layering and positioning issues of popups in complex layouts, and it is recommended to enable it only when needed.
+:::
+
 ## Attributes
 
 | Attribute | Description | Type | Default | Version |
@@ -93,6 +113,7 @@ Set the `close-on-click-modal` attribute to `false` to disable closing the popup
 | custom-style | Custom popup style | object | - | - |
 | border-radius | Border radius of the popup | string | 0 | - |
 | safe-area-inset-bottom | Whether to enable bottom safe area adaptation | boolean | false | - |
+| root-portal | Whether to break away from the page to solve various fixed failure issues | boolean | false | $LOWEST_VERSION$ |
 
 ## Events
 

docs/en-US/component/root-portal.md

@@ -0,0 +1,58 @@
+# Root Portal<el-tag text style="vertical-align: middle;margin-left:8px;" effect="plain">$LOWEST_VERSION$</el-tag>
+
+Whether to break out of the page, used to solve various fixed positioning issues, mainly used for making popups and overlays.
+
+:::tip Tip
+The root portal component only supports `WeChat Mini Program`, `Alipay Mini Program`, `APP` and `H5` platforms. The component automatically chooses the appropriate implementation based on the platform:
+
+- **H5**: Uses `teleport` feature
+- **WeChat Mini Program and Alipay Mini Program**: Uses `root-portal` component
+- **App**: Uses renderjs implementation
+- **Other platforms**: Not supported
+
+This feature is mainly used to solve the hierarchy and positioning problems of popups in complex layouts, and is recommended only when needed.
+:::
+
+## Basic Usage
+
+Use `wd-root-portal` to render content to the root node, avoiding style interference from parent components.
+
+```html
+<wd-button type="primary" @click="show = true">Show Modal</wd-button>
+<wd-root-portal v-if="show">
+  <view class="modal">
+    <view class="modal-content">
+      <text>This is a global modal</text>
+      <wd-button @click="show = false">Close</wd-button>
+    </view>
+  </view>
+</wd-root-portal>
+```
+
+```scss
+.modal {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background-color: rgba(0, 0, 0, 0.5);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+}
+
+.modal-content {
+  background-color: #fff;
+  padding: 20px;
+  border-radius: 8px;
+  text-align: center;
+}
+```
+
+## Slots
+
+| Name    | Description                    | Version |
+| ------- | ------------------------------ | ------- |
+| default | Default slot for portal content | -       | 

src/locale/en-US.json

@@ -1609,5 +1609,16 @@
   "zuo-shang": "Top Left",
   "zuo-xia": "lower left",
   "zuo-you-hua-dong": "Slide left and right",
-  "zuo-zhong": "Middle Left"
+  "zuo-zhong": "Middle Left",
+  "xian-shi-tan-chuang": "Show Modal",
+  "yu-zhe-zhao-ceng-jie-he": "Combined with Overlay",
+  "xian-shi-mo-tai-kuang": "Show Modal",
+  "quan-ju-tong-zhi": "Global Notification",
+  "xian-shi-tong-zhi": "Show Notification",
+  "quan-ju-jia-zai": "Global Loading",
+  "xian-shi-jia-zai": "Show Loading",
+  "zhe-shi-yi-ge-quan-ju-tan-chuang": "This is a global modal",
+  "mo-tai-kuang-biao-ti": "Modal Title",
+  "zhe-shi-mo-tai-kuang-de-nei-rong": "This is modal content",
+  "rootportal-title": "Root Portal"
 }

src/locale/zh-CN.json

@@ -1609,5 +1609,37 @@
   "zuo-shang": "左上",
   "zuo-xia": "左下",
   "zuo-you-hua-dong": "左右滑动",
-  "zuo-zhong": "左中"
+  "zuo-zhong": "左中",
+  "xian-shi-tan-chuang": "显示弹窗",
+  "yu-zhe-zhao-ceng-jie-he": "与遮罩层结合",
+  "xian-shi-mo-tai-kuang": "显示模态框",
+  "quan-ju-tong-zhi": "全局通知",
+  "xian-shi-tong-zhi": "显示通知",
+  "quan-ju-jia-zai": "全局加载",
+  "xian-shi-jia-zai": "显示加载",
+  "zhe-shi-yi-ge-quan-ju-tan-chuang": "这是一个全局弹窗",
+  "mo-tai-kuang-biao-ti": "模态框标题",
+  "zhe-shi-mo-tai-kuang-de-nei-rong": "这是模态框的内容",
+  "rootportal-title": "Root Portal 根节点传送门",
+  "ji-chu-yong-fa": "基本用法",
+  "xian-shi-ji-ben-tan-chuang": "显示基本弹窗",
+  "ji-ben-tan-chuang": "基本弹窗",
+  "zhe-shi-yi-ge-shi-yong-root-portal-de-ji-ben-tan-chuang-shi-li": "这是一个使用 root-portal 的基本弹窗示例",
+  "guan-bi": "关闭",
+  "zai-zhe-zhao-ceng-zhong-de-xiao-guo-dui-bi": "在遮罩层中的效果对比",
+  "bu-shi-yong-root-portal": "不使用 root-portal",
+  "ke-neng-shou-dao-fu-zu-jian-yang-shi-ying-xiang": "可能受到父组件样式影响",
+  "xian-shi-pu-tong-tan-chuang": "显示普通弹窗",
+  "shi-yong-root-portal": "使用 root-portal",
+  "bu-shou-fu-zu-jian-yang-shi-ying-xiang": "不受父组件样式影响",
+  "xian-shi-chuan-song-men-tan-chuang": "显示传送门弹窗",
+  "pu-tong-tan-chuang": "普通弹窗",
+  "chuan-song-men-tan-chuang": "传送门弹窗",
+  "que-ding": "确定",
+  "quan-ju-tong-zhi": "全局通知",
+  "xian-shi-tong-zhi": "显示通知",
+  "zhe-shi-yi-tiao-quan-ju-tong-zhi": "这是一条全局通知",
+  "quan-ju-jia-zai-zhuang-tai": "全局加载状态",
+  "xian-shi-jia-zai": "显示加载",
+  "jia-zai-zhong": "加载中..."
 }

src/pages.json

@@ -1311,6 +1311,21 @@
             "navigationBarTitleText": "%wxrewardad-title%"
             // #endif
           }
+        },
+        {
+          "path": "rootPortal/Index",
+          "name": "rootPortal",
+          "style": {
+            "mp-alipay": {
+              "allowsBounceVertical": "NO"
+            },
+            // #ifdef MP
+            "navigationBarTitleText": "Root Portal 根节点传送门",
+            // #endif
+            // #ifndef MP
+            "navigationBarTitleText": "%rootportal-title%"
+            // #endif
+          }
         }
       ]
     }

src/pages/index/Index.vue

@@ -94,6 +94,10 @@ const list = computed(() => [
       {
         id: 'text',
         name: t('text-wen-ben')
+      },
+      {
+        id: 'rootPortal',
+        name: t('rootportal-title')
       }
     ]
   },

src/subPages/popup/Index.vue

@@ -45,6 +45,12 @@
         </wd-cell-group>
       </demo-block>
 
+      <demo-block title="嵌套弹窗" transparent>
+        <wd-cell-group border>
+          <wd-cell title="嵌套弹窗测试" is-link @click="handleClick11" />
+        </wd-cell-group>
+      </demo-block>
+
       <wd-popup v-model="show1" @close="handleClose1" custom-style="border-radius:32rpx;">
         <text class="custom-txt">{{ $t('dan-dan-dan') }}</text>
       </wd-popup>
@@ -72,6 +78,36 @@
         custom-style="height: 200px;"
         @close="handleClose10"
       ></wd-popup>
+
+      <!-- 嵌套弹窗测试：父弹窗 -->
+      <wd-popup v-model="show11" position="center" custom-style="padding: 20px; border-radius: 16px;" @close="handleClose11">
+        <view class="nested-popup-content">
+          <text class="nested-title">父弹窗（普通模式）</text>
+          <text class="nested-desc">这是一个普通的弹窗，点击下面的按钮会打开子弹窗</text>
+          <view class="nested-buttons">
+            <wd-button type="primary" size="small" @click="openChildPopup(false)">打开普通子弹窗</wd-button>
+            <wd-button type="success" size="small" @click="openChildPopup(true)">打开传送子弹窗</wd-button>
+          </view>
+        </view>
+
+        <!-- 嵌套弹窗测试：子弹窗（普通） -->
+        <wd-popup v-model="showChild1" position="center" custom-style="padding: 20px; border-radius: 16px;" @close="handleCloseChild1">
+          <view class="nested-popup-content">
+            <text class="nested-title">子弹窗（普通模式）</text>
+            <text class="nested-desc">这个子弹窗可能会被父弹窗的层级影响</text>
+            <wd-button type="primary" size="small" @click="handleCloseChild1">关闭</wd-button>
+          </view>
+        </wd-popup>
+
+        <!-- 嵌套弹窗测试：子弹窗（传送） -->
+        <wd-popup v-model="showChild2" root-portal position="center" custom-style="padding: 20px; border-radius: 16px;" @close="handleCloseChild2">
+          <view class="nested-popup-content">
+            <text class="nested-title">子弹窗（传送模式）</text>
+            <text class="nested-desc">这个子弹窗使用传送功能，避免了层级问题</text>
+            <wd-button type="success" size="small" @click="handleCloseChild2">关闭</wd-button>
+          </view>
+        </wd-popup>
+      </wd-popup>
     </page-wraper>
   </view>
 </template>
@@ -160,6 +196,37 @@ function handleClick10() {
 function handleClose10() {
   show10.value = false
 }
+
+const show11 = ref<boolean>(false)
+const showChild1 = ref<boolean>(false)
+const showChild2 = ref<boolean>(false)
+
+function handleClick11() {
+  show11.value = true
+}
+
+function handleClose11() {
+  show11.value = false
+  // 关闭父弹窗时也关闭子弹窗
+  showChild1.value = false
+  showChild2.value = false
+}
+
+function openChildPopup(useTeleport: boolean) {
+  if (useTeleport) {
+    showChild2.value = true
+  } else {
+    showChild1.value = true
+  }
+}
+
+function handleCloseChild1() {
+  showChild1.value = false
+}
+
+function handleCloseChild2() {
+  showChild2.value = false
+}
 </script>
 <style lang="scss" scoped>
 .wot-theme-dark {
@@ -178,4 +245,54 @@ function handleClose10() {
   font-size: 40rpx;
   border-radius: 32rpx;
 }
+
+.teleport-demo-txt {
+  color: black;
+  width: 300rpx;
+  height: 150rpx;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  font-size: 32rpx;
+  text-align: center;
+  line-height: 1.4;
+}
+
+.nested-popup-content {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 20rpx;
+}
+
+.nested-title {
+  color: black;
+  font-size: 36rpx;
+  font-weight: bold;
+  text-align: center;
+}
+
+.nested-desc {
+  color: #666;
+  font-size: 28rpx;
+  text-align: center;
+  line-height: 1.5;
+  margin: 10rpx 0;
+}
+
+.nested-buttons {
+  display: flex;
+  gap: 20rpx;
+  margin-top: 20rpx;
+}
+
+.wot-theme-dark {
+  .nested-title {
+    color: $-dark-color;
+  }
+
+  .nested-desc {
+    color: $-dark-color3;
+  }
+}
 </style>

src/subPages/rootPortal/Index.vue

@@ -0,0 +1,63 @@
+<template>
+  <view class="root-portal-demo">
+    <demo-block :title="$t('ji-chu-yong-fa')">
+      <wd-button type="primary" @click="showBasic = true">{{ $t('xian-shi-ji-ben-tan-chuang') }}</wd-button>
+      <wd-root-portal v-if="showBasic">
+        <view class="basic-modal">
+          <view class="basic-modal-content">
+            <text class="basic-modal-title">{{ $t('ji-ben-tan-chuang') }}</text>
+            <text class="basic-modal-text">{{ $t('zhe-shi-yi-ge-shi-yong-root-portal-de-ji-ben-tan-chuang-shi-li') }}</text>
+            <wd-button type="primary" @click="showBasic = false">{{ $t('guan-bi') }}</wd-button>
+          </view>
+        </view>
+      </wd-root-portal>
+    </demo-block>
+  </view>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const showBasic = ref(false)
+</script>
+
+<style lang="scss" scoped>
+.root-portal-demo {
+  padding: 16px;
+}
+
+.basic-modal {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background-color: rgba(0, 0, 0, 0.5);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+}
+
+.basic-modal-content {
+  background-color: #fff;
+  padding: 24px;
+  border-radius: 12px;
+  width: 280px;
+  text-align: center;
+}
+
+.basic-modal-title {
+  font-size: 18px;
+  font-weight: bold;
+  margin-bottom: 12px;
+  display: block;
+}
+
+.basic-modal-text {
+  font-size: 14px;
+  color: #666;
+  margin-bottom: 20px;
+  display: block;
+}
+</style>

src/uni_modules/wot-design-uni/components/wd-action-sheet/types.ts

@@ -1,12 +1,3 @@
-/*
- * @Author: weisheng
- * @Date: 2024-03-18 11:22:03
- * @LastEditTime: 2024-04-04 22:35:25
- * @LastEditors: weisheng
- * @Description:
- * @FilePath: /wot-design-uni/src/uni_modules/wot-design-uni/components/wd-action-sheet/types.ts
- * 记得注释
- */
 import type { ExtractPropTypes } from 'vue'
 import { baseProps, makeArrayProp, makeBooleanProp, makeNumberProp, makeRequiredProp, makeStringProp } from '../common/props'
 
@@ -115,7 +106,13 @@ export const actionSheetProps = {
    * @default true
    * @type {boolean}
    */
-  safeAreaInsetBottom: makeBooleanProp(true)
+  safeAreaInsetBottom: makeBooleanProp(true),
+  /**
+   * 是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
+   * 类型：boolean
+   * 默认值：false
+   */
+  rootPortal: makeBooleanProp(false)
 }
 
 export type ActionSheetProps = ExtractPropTypes<typeof actionSheetProps>

src/uni_modules/wot-design-uni/components/wd-action-sheet/wd-action-sheet.vue

@@ -9,6 +9,7 @@
       :close-on-click-modal="closeOnClickModal"
       :safe-area-inset-bottom="safeAreaInsetBottom"
       :lazy-render="lazyRender"
+      :root-portal="rootPortal"
       @enter="handleOpen"
       @close="close"
       @after-enter="handleOpened"

src/uni_modules/wot-design-uni/components/wd-calendar/types.ts

@@ -181,7 +181,11 @@ export const calendarProps = {
    * 是否使用内置单元格
    * 默认为 true，使用内置单元格
    */
-  withCell: makeBooleanProp(true)
+  withCell: makeBooleanProp(true),
+  /**
+   * 是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
+   */
+  rootPortal: makeBooleanProp(false)
 }
 
 export type CalendarDisplayFormat = (value: number | number[], type: CalendarType) => string

src/uni_modules/wot-design-uni/components/wd-calendar/wd-calendar.vue

@@ -34,6 +34,7 @@
       :close-on-click-modal="closeOnClickModal"
       :safe-area-inset-bottom="safeAreaInsetBottom"
       :z-index="zIndex"
+      :root-portal="rootPortal"
       @close="close"
     >
       <view class="wd-calendar__header">

src/uni_modules/wot-design-uni/components/wd-col-picker/types.ts

@@ -132,7 +132,11 @@ export const colPickerProps = {
    * value 外部自定义样式
    */
   customLabelClass: makeStringProp(''),
-  customValueClass: makeStringProp('')
+  customValueClass: makeStringProp(''),
+  /**
+   * 是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
+   */
+  rootPortal: makeBooleanProp(false)
 }
 
 export type ColPickerProps = ExtractPropTypes<typeof colPickerProps>

src/uni_modules/wot-design-uni/components/wd-col-picker/wd-col-picker.vue

@@ -36,6 +36,7 @@
       :close-on-click-modal="closeOnClickModal"
       :z-index="zIndex"
       :safe-area-inset-bottom="safeAreaInsetBottom"
+      :root-portal="rootPortal"
       @open="handlePickerOpend"
       @close="handlePickerClose"
       @closed="handlePickerClosed"

src/uni_modules/wot-design-uni/components/wd-curtain/types.ts

@@ -64,7 +64,11 @@ export const curtainProps = {
    * 类型：string
    * 默认值：''
    */
-  customCloseStyle: makeStringProp('')
+  customCloseStyle: makeStringProp(''),
+  /**
+   * 是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
+   */
+  rootPortal: makeBooleanProp(false)
 }
 
 export type CurtainProps = ExtractPropTypes<typeof curtainProps>

src/uni_modules/wot-design-uni/components/wd-curtain/wd-curtain.vue

@@ -7,6 +7,7 @@
       :close-on-click-modal="closeOnClickModal"
       :hide-when-close="hideWhenClose"
       :z-index="zIndex"
+      :root-portal="rootPortal"
       @before-enter="beforeenter"
       @enter="enter"
       @after-enter="afterenter"

src/uni_modules/wot-design-uni/components/wd-datetime-picker/types.ts

@@ -184,7 +184,11 @@ export const datetimePickerProps = {
   /**
    * 是否在手指松开时立即触发picker-view的 change 事件。若不开启则会在滚动动画结束后触发 change 事件，1.2.25版本起提供，仅微信小程序和支付宝小程序支持。
    */
-  immediateChange: makeBooleanProp(false)
+  immediateChange: makeBooleanProp(false),
+  /**
+   * 是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
+   */
+  rootPortal: makeBooleanProp(false)
 }
 
 export type DatetimePickerDisplayFormat = (items: Record<string, any>[]) => string

src/uni_modules/wot-design-uni/components/wd-datetime-picker/wd-datetime-picker.vue

@@ -52,6 +52,7 @@
       :close-on-click-modal="closeOnClickModal"
       :safe-area-inset-bottom="safeAreaInsetBottom"
       :z-index="zIndex"
+      :root-portal="rootPortal"
       @close="onCancel"
       custom-class="wd-picker__popup"
     >

src/uni_modules/wot-design-uni/components/wd-drop-menu-item/types.ts

@@ -71,7 +71,11 @@ export const dorpMenuItemProps = {
   /**
    * 自定义下拉菜单popup样式
    */
-  customPopupStyle: makeStringProp('')
+  customPopupStyle: makeStringProp(''),
+  /**
+   * 是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
+   */
+  rootPortal: makeBooleanProp(false)
 }
 
 export type DropMenuItemProps = ExtractPropTypes<typeof dorpMenuItemProps>

src/uni_modules/wot-design-uni/components/wd-drop-menu-item/wd-drop-menu-item.vue

@@ -13,6 +13,7 @@
       :custom-class="customPopupClass"
       :modal="false"
       :close-on-click-modal="false"
+      :root-portal="rootPortal"
       @before-enter="beforeEnter"
       @after-enter="afterEnter"
       @before-leave="beforeLeave"

src/uni_modules/wot-design-uni/components/wd-keyboard/types.ts

@@ -75,5 +75,9 @@ export const keyboardProps = {
   /**
    * 额外按键
    */
-  extraKey: [String, Array] as PropType<string | Array<string>>
+  extraKey: [String, Array] as PropType<string | Array<string>>,
+  /**
+   * 是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
+   */
+  rootPortal: makeBooleanProp(false)
 }

src/uni_modules/wot-design-uni/components/wd-keyboard/wd-keyboard.vue

@@ -7,6 +7,7 @@
     :modal-style="modal ? '' : 'opacity: 0;'"
     :modal="hideOnClickOutside"
     :lockScroll="lockScroll"
+    :root-portal="rootPortal"
     @click-modal="handleClose"
   >
     <view :class="`wd-keyboard ${customClass}`" :style="customStyle">

src/uni_modules/wot-design-uni/components/wd-message-box/types.ts

@@ -7,7 +7,7 @@
  * @FilePath: \wot-design-uni\src\uni_modules\wot-design-uni\components\wd-message-box\types.ts
  * 记得注释
  */
-import { baseProps, makeStringProp } from '../common/props'
+import { baseProps, makeStringProp, makeBooleanProp } from '../common/props'
 import type { ButtonProps } from '../wd-button/types'
 import { type InputSize, type InputType } from '../wd-input/types'
 
@@ -133,5 +133,9 @@ export const messageBoxProps = {
   /**
    * 指定唯一标识
    */
-  selector: makeStringProp('')
+  selector: makeStringProp(''),
+  /**
+   * 是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
+   */
+  rootPortal: makeBooleanProp(false)
 }

src/uni_modules/wot-design-uni/components/wd-message-box/wd-message-box.vue

@@ -9,6 +9,7 @@
       @click-modal="toggleModal('modal')"
       :z-index="messageState.zIndex"
       :duration="200"
+      :root-portal="rootPortal"
     >
       <view :class="rootClass">
         <view :class="bodyClass">

src/uni_modules/wot-design-uni/components/wd-notify/types.ts

@@ -58,5 +58,9 @@ export const notifyProps = {
   /**
    * 背景颜色
    */
-  background: makeStringProp('')
+  background: makeStringProp(''),
+  /**
+   * 是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
+   */
+  rootPortal: makeBooleanProp(false)
 }

src/uni_modules/wot-design-uni/components/wd-notify/wd-notify.vue

@@ -6,6 +6,7 @@
     :z-index="state.zIndex"
     :duration="250"
     :modal="false"
+    :root-portal="state.rootPortal"
     @leave="onClosed"
     @enter="onOpened"
   >

src/uni_modules/wot-design-uni/components/wd-number-keyboard/types.ts

@@ -75,5 +75,9 @@ export const numberKeyboardProps = {
   /**
    * 额外按键
    */
-  extraKey: [String, Array] as PropType<string | Array<string>>
+  extraKey: [String, Array] as PropType<string | Array<string>>,
+  /**
+   * 是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
+   */
+  rootPortal: makeBooleanProp(false)
 }

src/uni_modules/wot-design-uni/components/wd-number-keyboard/wd-number-keyboard.vue

@@ -7,6 +7,7 @@
     :modal-style="modal ? '' : 'opacity: 0;'"
     :modal="hideOnClickOutside"
     :lockScroll="lockScroll"
+    :root-portal="rootPortal"
     @click-modal="handleClose"
   >
     <view :class="`wd-number-keyboard ${customClass}`" :style="customStyle">

src/uni_modules/wot-design-uni/components/wd-picker/types.ts

@@ -151,7 +151,11 @@ export const pickerProps = {
   /**
    * 显示清空按钮
    */
-  clearable: makeBooleanProp(false)
+  clearable: makeBooleanProp(false),
+  /**
+   * 是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
+   */
+  rootPortal: makeBooleanProp(false)
 }
 
 export type PickerProps = ExtractPropTypes<typeof pickerProps>

src/uni_modules/wot-design-uni/components/wd-picker/wd-picker.vue

@@ -37,6 +37,7 @@
       :close-on-click-modal="closeOnClickModal"
       :z-index="zIndex"
       :safe-area-inset-bottom="safeAreaInsetBottom"
+      :root-portal="rootPortal"
       @close="onCancel"
       custom-class="wd-picker__popup"
     >

src/uni_modules/wot-design-uni/components/wd-popup/types.ts

@@ -1,10 +1,10 @@
 /*
  * @Author: weisheng
  * @Date: 2024-03-18 11:22:03
- * @LastEditTime: 2024-11-08 12:55:58
+ * @LastEditTime: 2025-07-06 21:00:04
  * @LastEditors: weisheng
  * @Description:
- * @FilePath: \wot-design-uni\src\uni_modules\wot-design-uni\components\wd-popup\types.ts
+ * @FilePath: /wot-design-uni/src/uni_modules/wot-design-uni/components/wd-popup/types.ts
  * 记得注释
  */
 import type { PropType } from 'vue'
@@ -94,5 +94,11 @@ export const popupProps = {
    * 类型：boolean
    * 默认值：true
    */
-  lockScroll: makeBooleanProp(true)
+  lockScroll: makeBooleanProp(true),
+  /**
+   * 是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
+   * 类型：boolean
+   * 默认值：false
+   */
+  rootPortal: makeBooleanProp(false)
 }

src/uni_modules/wot-design-uni/components/wd-popup/wd-popup.vue

@@ -1,5 +1,39 @@
 <template>
-  <view class="wd-popup-wrapper">
+  <wd-root-portal v-if="rootPortal">
+    <view class="wd-popup-wrapper">
+      <wd-overlay
+        v-if="modal"
+        :show="modelValue"
+        :z-index="zIndex"
+        :lock-scroll="lockScroll"
+        :duration="duration"
+        :custom-style="modalStyle"
+        @click="handleClickModal"
+        @touchmove="noop"
+      />
+      <wd-transition
+        :lazy-render="lazyRender"
+        :custom-class="rootClass"
+        :custom-style="style"
+        :duration="duration"
+        :show="modelValue"
+        :name="transitionName"
+        :destroy="hideWhenClose"
+        @before-enter="emit('before-enter')"
+        @enter="emit('enter')"
+        @after-enter="emit('after-enter')"
+        @before-leave="emit('before-leave')"
+        @leave="emit('leave')"
+        @after-leave="emit('after-leave')"
+      >
+        <slot />
+        <wd-icon v-if="closable" custom-class="wd-popup__close" name="add" @click="close" />
+      </wd-transition>
+    </view>
+  </wd-root-portal>
+
+  <!-- 非传送模式 -->
+  <view v-else class="wd-popup-wrapper">
     <wd-overlay
       v-if="modal"
       :show="modelValue"
@@ -43,10 +77,11 @@ export default {
 </script>
 
 <script lang="ts" setup>
+import { computed, onBeforeMount, ref } from 'vue'
 import wdIcon from '../wd-icon/wd-icon.vue'
 import wdOverlay from '../wd-overlay/wd-overlay.vue'
 import wdTransition from '../wd-transition/wd-transition.vue'
-import { computed, onBeforeMount, ref } from 'vue'
+import wdRootPortal from '../wd-root-portal/wd-root-portal.vue'
 import { popupProps } from './types'
 import type { TransitionName } from '../wd-transition/types'
 
@@ -128,6 +163,7 @@ function close() {
 }
 function noop() {}
 </script>
+
 <style lang="scss" scoped>
 @import './index.scss';
 </style>

src/uni_modules/wot-design-uni/components/wd-root-portal/wd-root-portal.vue

@@ -0,0 +1,49 @@
+<template>
+  <!-- #ifdef H5 -->
+  <!-- H5端使用 teleport -->
+  <teleport to="body">
+    <!-- #endif -->
+    <!-- #ifdef MP-WEIXIN || MP-ALIPAY -->
+    <!-- #ifndef MP-DINGTALK -->
+    <!-- 小程序使用 root-portal -->
+    <root-portal>
+      <!-- #endif -->
+      <!-- #endif -->
+      <slot />
+      <!-- #ifdef MP-WEIXIN || MP-ALIPAY -->
+      <!-- #ifndef MP-DINGTALK -->
+    </root-portal>
+    <!-- #endif -->
+    <!-- #endif -->
+    <!-- #ifdef H5 -->
+  </teleport>
+  <!-- #endif -->
+</template>
+<script>
+export default {
+  name: 'wd-root-portal',
+  options: {
+    virtualHost: true,
+    addGlobalClass: true,
+    styleIsolation: 'shared'
+  }
+}
+</script>
+
+<!-- #ifdef APP-PLUS -->
+<script module="render" lang="renderjs">
+export default {
+  mounted() {
+    if (this.$ownerInstance.$el) {
+      (document.querySelector('uni-app') || document.body).appendChild(this.$ownerInstance.$el)
+    }
+  },
+  beforeDestroy() {
+    // 清理，将元素移回原位置
+    if (this.$ownerInstance.$el) {
+      (document.querySelector('uni-app') || document.body).removeChild(this.$ownerInstance.$el)
+    }
+  }
+}
+</script>
+<!-- #endif -->

src/uni_modules/wot-design-uni/components/wd-select-picker/types.ts

@@ -87,7 +87,11 @@ export const selectPickerProps = {
   /**
    * 显示清空按钮
    */
-  clearable: makeBooleanProp(false)
+  clearable: makeBooleanProp(false),
+  /**
+   * 是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
+   */
+  rootPortal: makeBooleanProp(false)
 }
 export type SelectPickerProps = ExtractPropTypes<typeof selectPickerProps>
 

src/uni_modules/wot-design-uni/components/wd-select-picker/wd-select-picker.vue

@@ -42,6 +42,7 @@
       :close-on-click-modal="closeOnClickModal"
       :z-index="zIndex"
       :safe-area-inset-bottom="safeAreaInsetBottom"
+      :root-portal="rootPortal"
       @close="close"
       @opened="scrollIntoView ? setScrollIntoView() : ''"
       custom-header-class="wd-select-picker__header"

src/uni_modules/wot-design-uni/global.d.ts

@@ -94,6 +94,7 @@ declare module 'vue' {
     WdCountTo: typeof import('./components/wd-count-to/wd-count-to.vue')['default']
     WdFloatingPanel: typeof import('./components/wd-floating-panel/wd-floating-panel.vue')['default']
     WdSignature: typeof import('./components/wd-signature/wd-signature.vue')['default']
+    WdRootPortal: typeof import('./components/wd-root-portal/wd-root-portal.vue')['default']
   }
 }
 

tests/components/wd-root-portal.test.ts

@@ -0,0 +1,70 @@
+import { mount } from '@vue/test-utils'
+import '../mocks/wd-transition.mock'
+import WdRootPortal from '@/uni_modules/wot-design-uni/components/wd-root-portal/wd-root-portal.vue'
+import { describe, test, expect, vi } from 'vitest'
+
+describe('WdRootPortal', () => {
+  // 测试组件名称
+  test('组件名称', () => {
+    const wrapper = mount(WdRootPortal)
+    expect(wrapper.vm.$options.name).toBe('wd-root-portal')
+  })
+
+  // 测试组件渲染
+  test('组件渲染', () => {
+    const wrapper = mount(WdRootPortal)
+    expect(wrapper.exists()).toBe(true)
+  })
+
+  // 测试组件选项
+  test('组件选项配置', () => {
+    const wrapper = mount(WdRootPortal)
+    const options = wrapper.vm.$options
+    // 由于条件编译，在测试环境中可能无法获取到这些选项
+    // 我们只测试组件能够正常挂载
+    expect(wrapper.exists()).toBe(true)
+  })
+
+  // 测试插槽渲染
+  test('插槽渲染', () => {
+    const wrapper = mount(WdRootPortal, {
+      slots: {
+        default: '<div class="test-slot">测试插槽</div>'
+      }
+    })
+    // 由于条件编译，插槽内容可能不会在测试环境中正确渲染
+    // 我们只测试组件能够正常挂载
+    expect(wrapper.exists()).toBe(true)
+  })
+
+  // 测试组件结构
+  test('组件结构', () => {
+    const wrapper = mount(WdRootPortal, {
+      slots: {
+        default: '<div class="portal-content">传送门内容</div>'
+      }
+    })
+
+    // 检查组件是否正确挂载
+    expect(wrapper.exists()).toBe(true)
+  })
+
+  // 测试复杂插槽内容
+  test('复杂插槽内容', () => {
+    const complexSlot = `
+      <view class="modal">
+        <view class="modal-content">
+          <text>这是一个模态框</text>
+        </view>
+      </view>
+    `
+    const wrapper = mount(WdRootPortal, {
+      slots: {
+        default: complexSlot
+      }
+    })
+    // 由于条件编译，插槽内容可能不会在测试环境中正确渲染
+    // 我们只测试组件能够正常挂载
+    expect(wrapper.exists()).toBe(true)
+  })
+})