n-popover 气泡
单个触发内容旁的文字提示、操作菜单或自定义内容。定位、测量、箭头、遮罩、尺寸变化与关闭动画由组件处理。多列筛选栏使用 n-dropdown，单触发器操作菜单直接使用本组件的 items。
平台兼容性
| App | H5 | 微信小程序 |
|---|---|---|
| √ | √ | √ |
API
Popover 属性
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| visible | 显隐状态，推荐 v-model:visible；交互经 update:visible 回传，外部可以延迟或拒绝更新 | boolean | false |
| content | 气泡文字；content 插槽优先，其次 items 菜单，最后显示文字 | string | "" |
| items | 操作菜单数据；传入 content 插槽时由插槽接管渲染 | NPopoverItem[] | [] |
| position | 弹出方位；top/bottom 配 -left/-right，left/right 配 -top/-bottom，auto 自动选向 | NPopoverPosition | "top" |
| show-arrow | 是否显示与气泡同色的指向箭头 | boolean | true |
| arrow-size | 箭头方块边长 px，支持 6–20；箭头尖端与触发器保持间距 | number | 10 |
| bg-color | 气泡背景，空串使用主题令牌 --n-popover-bg；箭头同色 | string | "" |
| color | 文字与菜单项颜色，空串使用 --n-popover-color；自定义插槽自行设置文字颜色 | string | "" |
| font-size | 内置文字与菜单字号 px，须大于 0 | number | 14 |
| font-weight | 内置文字与菜单字重，如 normal、bold、600 | string | "normal" |
| padding-x | 内容水平内边距 px，须非负 | number | 12 |
| padding-y | 内容垂直内边距 px，须非负 | number | 8 |
| round | 气泡圆角 px，须非负 | number | 8 |
| width | 固定宽度 px，0 按内容自适应；始终受视口与 maxWidth 限制 | number | 0 |
| max-width | 内容最大宽度 px，0 仅受视口限制；超宽自动换行，超高内部滚动 | number | 260 |
| z-index | 气泡层级，-1 使用主题令牌；显式设置时遮罩为此值减一 | number | -1 |
| duration | 出入场时长 ms，0 在测量完成后即时显隐 | number | 200 |
| disabled | 禁用触发器和菜单项点击，并降低触发器透明度；外部仍可控制 visible | boolean | false |
| show-mask | 是否渲染遮罩；关闭后外部区域可以交互 | boolean | true |
| close-on-click-mask | 是否允许点遮罩关闭，关闭时仍拦截页面交互 | boolean | true |
| close-on-click-item | 菜单选择后是否自动请求关闭 | boolean | true |
| mask-color | 遮罩颜色，空串使用 --n-popover-mask-color，默认透明 | string | "" |
| show-line | 菜单项之间是否显示分隔线 | boolean | true |
| line-color | 菜单分隔线颜色，空串使用 --n-popover-line-color | string | "" |
| content-style | 内容区域行内样式，如 border-width；背景统一使用 bgColor，尺寸统一使用 width/maxWidth | string | "" |
| item-style | 内置菜单项行内样式；间距与触控高度由组件提供 | string | "" |
| custom-class | 根节点额外类名，类须定义在组件自己的样式表内 | string | "" |
| custom-style | 根节点行内样式 | string | "" |
Popover 事件
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| update:visible | 请求更新显隐，v-model:visible 接收 | boolean |
| change | 与 update:visible 同参同发 | boolean |
| click | 有效菜单项点击，默认随后请求关闭 | NPopoverClick： |
| open | 测量成功后开始显示 | - |
| opened | 入场完成；测量未完成、取消或过期请求不会触发 | - |
| close | 开始收起 | trigger / mask / item / page / api / error |
| closed | 退场完成，保留插槽状态 | - |
| error | 配置、菜单或测量失败；停止显示并请求 visible=false | NPopoverError： |
Popover 插槽
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 触发内容 | |
| content | 自定义气泡内容，接管内置菜单或文字 | |
| itemIcon | 菜单项图标或图片，自定义大小和颜色 | {item, index, size}，size 与内置文字行高一致 |
Popover 方法
| 方法名 | 说明 |
|---|---|
| open() | 请求 visible=true，禁用或无内容时不触发；需绑定更新通道 |
| close() | 请求 visible=false，关闭来源 api；需绑定更新通道 |
| toggle() | 请求相反显隐状态；需绑定更新通道 |
普通调用推荐 v-model:visible。自定义内容使用插槽 close，均无需实例类型声明。
实现说明
| 参考机制 | 本组件做法 | 融合理由 |
|---|---|---|
| 文字气泡的内容、配色、字号、内边距、圆角、方位、宽度、层级、时长、禁用、遮罩 | 对应 content、bgColor、color、fontSize、paddingX/Y、round、position、width/maxWidth、zIndex、duration、disabled、showMask | 保留提示形态与主题定制通道，数值尺寸统一为 px |
| 触发方式为点击触发器开合（再点、遮罩、菜单项或外部控制关闭）；不提供 hover 悬停与长按触发 | 同左，未设触发方式 prop | 移动端悬停不可靠且各参考实现同为点击触发；hover 引导与长按手势由调用方在触发内容上自行组合 |
| 菜单气泡的 items、点击载荷、图标、图片、分隔线、字重 | items、click({index,item})、itemIcon 插槽、showLine、lineColor、fontWeight | 菜单由组件绘制；图标与图片使用统一插槽，无需调用方绘制整份列表 |
| 遮罩渲染、颜色与可关闭性独立配置 | showMask、maskColor、closeOnClickMask | 支持透明或自定义遮罩，也支持阻断页面但禁止点外关闭 |
| 触发内容旁的坐标、方向与三角位置维护 | 组件测量触发器和自然内容尺寸，方位拆成主方向与起止对齐，按最终钳制位置计算箭头 | 无需调用者维护 left/right/top/bottom 或箭头补偿；页面任意坐标的自由浮层属于弹层组件，不属于触发器气泡 |
| 相对定位与手动 fixed 定位 | fixed 原点排版与整数位移，测量与定位使用统一坐标；先完成测量再进入显示阶段 | 内容自然宽度不随气泡最终横坐标改变；Web 内部加入导航栏坐标差，调用方无需适配 |
| 屏幕边缘与长内容 | 限制实际宽度和滚动视口高度，并给箭头预留空间 | 钳制坐标与约束尺寸同时执行，超高内容内部滚动 |
| 展开后内容变化 | 属性变化后 nextTick 重新测量；展开期间每 100ms 检查异步插槽尺寸与触发器位置，仅几何变化时提交更新 | 无需调用者 refresh；触发器移动、消失、页面滚动或隐藏时收起并释放资源 |
| 异步测量与过渡 | 开合代次与测量序号共同取消过期回调；duration=0 仍先测量 | 快速开合不会复用旧坐标，测量失败明确报告 error，不伪造默认几何 |
| 气泡底色、文字、遮罩、分隔线和层级 | CSS 令牌 > SCSS 默认值；显式 prop 配置覆盖对应变量，customClass/customStyle 作用于根 | 空值跟随主题；contentStyle/itemStyle 定制内部节点 |
主题令牌：--n-popover-bg、--n-popover-color、--n-popover-shadow-color、--n-popover-z-index、--n-popover-mask-z-index、--n-popover-mask-color、--n-popover-line-color、--n-popover-disabled-opacity。SCSS 覆盖 bubble z-index 时默认同时推导遮罩层级；运行时 CSS 变量分别控制两层。过渡时长在每次展开或收起开始时取值，修改 duration 不改变已经开始的过渡。zIndex prop 默认为 -1（使用主题，默认气泡 999、遮罩 998），显式设置时统一调整两层。