更新记录

0.3.1（2026-09-10） 下载此版本

• 修复 host 关闭退场期间位置残留：closeNaxPopup() / 关闭按钮 / 遮罩关闭统一走 closeHostSession，退场期间冻结最后面板位置（hostClosing + lastHostPosition），picker 完全卸载后再恢复 props 位置，避免 position 提前翻转导致 picker 抽屉分支切换、根层无法卸载；onUnmounted 兜底覆盖退场期间无 picker 实例的场景
• 小程序降级保护：openNaxPopup() 传入自定义 url 时，不支持 dialogPage 的端不再静默降级打开空白面板，改为 console.warn 提示并直接返回，建议业务改用 nax-picker 声明式插槽或普通页面跳转
• 微信小程序左右抽屉顶部安全距离判定修正：胶囊避让不再只看 position == 'right'，改为按面板实际横向范围（width 空值按默认 78% 屏宽、纯数字按 px、百分比按屏宽折算）判断是否覆盖胶囊区域——左抽屉宽度过半、右抽屉覆盖时均预留到胶囊下沿

0.3.0（2026-09-08） 下载此版本

• 新增头部区域：标题（16px 加粗左对齐 + 单行省略）固定在 45px 高头部，右上角「✕」关闭按钮（17px 图标、26px 触区）
• 新增 showHeader / showClose prop（默认 true）：showHeader 控制整体头部（含标题与关闭按钮）显示；showClose 控制右上角关闭
• 命令式 openNaxPopup() options 同步支持 showHeader / showClose（内置 dialogPage host 与页面宿主均生效）
• showClose=false 时右上角隐藏关闭按钮，底部保留「关闭」按钮作为兜底关闭渠道
• 简易面板的 title 文案从正文区移入头部展示；面板加 flex: 1 支持定高面板内插槽 scroll-view 占满剩余空间滚动（演示页新增「面板内滚动」示例）

0.2.5（2026-08-18） 下载此版本

• 蒸汽模式兼容：lines CSS 声明迁移为 <text> 的 :max-lines 属性（官方蒸汽模式方案），消除 Vapor 运行时与 CSS 编译器警告

平台兼容性

uni-app x(4.31)

其他

nax-popup

压窗屏 / 页面级弹层。

压窗屏：遮罩与内容能盖住 pages.json 配置的原生导航栏和底部 tabBar。
官方能力来源：uni-app x dialogPage（HBuilderX 4.31+）。

平台能力矩阵

为什么小程序做不到真压窗？

1. uni-app x 微信小程序端不提供 openDialogPage / closeDialogPage。
2. 页面内 position: fixed 组件（含 nax-picker / page-container）只能盖住页面内容区，盖不住原生导航栏与原生 tabBar。
3. 业务若必须全屏遮罩，请改用：
   • navigationStyle: custom 自定义导航栏；和/或
   • 自定义 tabBar（非原生 tabBar）；或
   • 系统级 uni.showModal（样式不可完全自定义）。

检测：

import { naxPopupSupportsWindowCover } from '@/uni_modules/nax-popup/index.uts'

if (naxPopupSupportsWindowCover()) {
  // App / Web：可压窗
} else {
  // 小程序：仅页面级
}

与 nax-picker / nax-dialog 的关系

复杂自定义 UI：

• 不需要盖原生栏 → 继续用 nax-picker 声明式插槽。
• 需要盖原生栏（App/Web） → openNaxPopup({ url: '/pages/你的透明弹层页' })，自己写 dialog 页。
• 简易文案面板 → openNaxPopup({ title, content }) 走内置 host。

安装与注册

1. 放入 uni_modules/nax-popup（依赖 nax-picker、nax-ui-theme）。
2. 注册内置 host 页（使用简易 title/content 或默认 window 模式时必须）：

{
  "path": "uni_modules/nax-popup/pages/host/index",
  "style": {
    "navigationStyle": "custom",
    "navigationBarTitleText": "",
    "app-plus": {
      "backgroundColor": "transparent",
      "background": "transparent"
    },
    "app-harmony": {
      "backgroundColor": "transparent"
    },
    "h5": {
      "backgroundColor": "transparent"
    }
  }
}

3. 小程序降级 / 声明式宿主：页面挂一次 <nax-popup />（可空标签）。

命令式：压窗屏

import {
  openNaxPopup,
  closeNaxPopup,
  naxPopupSupportsWindowCover
} from '@/uni_modules/nax-popup/index.uts'

// 1) 内置简易面板（App/Web 真压窗；小程序需挂宿主后降级）
openNaxPopup({
  title: '提示',
  content: '遮罩会盖住导航栏与 tabBar（App/Web）',
  position: 'center', // center | bottom | left | right
  maskClosable: true
})

// 2) 打开业务自定义 dialog 页（推荐复杂 UI）
openNaxPopup({
  url: '/pages/components/popup/demo-dialog',
  animationType: 'fade-in'
})

// 3) 强制页面级（全端一致，不压窗）
openNaxPopup({
  mode: 'page',
  title: '页面级',
  content: '不盖原生栏'
})

closeNaxPopup()

options

dialogPage 是独立页面，无法继承触发页的主题 class。内置 host 需要同步暗色主题时，传入当前主题 class：

openNaxPopup({
  title: '提示',
  content: '深色主题会同步到内置 host',
  themeClass: 'nax-theme-dark'
})

mode：

• auto：能压窗用 window，否则 page
• window：强制 dialogPage；不支持则 warn 并降级 page
• page：强制页面宿主（全端不盖原生栏）

声明式：页面级插槽

<nax-button label="打开" @click="show = true"></nax-button>
<nax-popup v-model:show="show" position="bottom">
  <view class="panel">
    <text>自定义内容（页面级，不盖原生栏）</text>
  </view>
</nax-popup>

与 nax-picker 类似，适合自定义导航页或可接受不盖原生栏的场景。

自定义 dialog 页模板（App/Web 压窗）

<!-- pages/xxx/my-dialog.uvue -->
<template>
  <view class="wrap" @click="close">
    <view class="mask"></view>
    <view class="panel" @click.stop>
      <!-- 业务内容 -->
    </view>
  </view>
</template>
<script setup lang="uts">
function close() {
  // #ifdef APP-ANDROID || APP-IOS || APP-HARMONY || WEB
  uni.closeDialogPage({})
  // #endif
}
</script>
<style>
.wrap { position: absolute; left:0; top:0; right:0; bottom:0; }
.mask { position: absolute; left:0; top:0; right:0; bottom:0; background-color: rgba(0,0,0,0.4); }
</style>

pages.json 注册该页，navigationStyle: custom，背景透明；再：

openNaxPopup({ url: '/pages/xxx/my-dialog' })

主题

通过 CSS 变量覆盖：

依赖

• nax-picker（声明式 / 小程序降级）
• nax-ui-theme（token，可选）

自定义 dialog 页动画建议

• 推荐 animationType: 'none'，由页面内部做遮罩淡入 + 面板缩放/滑入。
• 若用页级 fade-in，请勿再在页内对同一遮罩做首帧 opacity 动画，以免鸿蒙叠闪。

已知限制

1. dialogPage 不能把 Vue 插槽跨页传递；复杂 UI 请用独立 dialog 页 + url。
2. 小程序无法真压窗，库内已降级并 warn，请业务按上表改造导航/tabBar。
3. 内置 host 仅为简易 title/content，不承担复杂表单。
4. tabBar 页上 dialogPage 在 App 切换 tab 时可能保持（官方行为）；Web 会随 tab 隐藏/恢复。