xtf-popover

组件说明

xtf-popover 是气泡浮层组件，适用于字段说明、轻量提示和就近操作内容；与弹窗不同，它锚定触发元素展示。 核心能力以当前 xtf-popover.vue 源码为准。

---

基础用法

1. 基础用法

最小配置下即可完成常见业务交互：

<template>
  <xtf-popover title="字段说明" content="GMV 默认不含退款订单。">
    <xtf-button label="查看说明"
  /></xtf-popover>
</template>

<script>
export default {
  data() {
    return { value: false }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

2. 核心交互

监听组件事件并维护页面状态：

<template>
  <xtf-popover
    :show="value"
    trigger="manual"
    title="手动控制"
    content="由外部状态控制"
    @update:show="value = $event"
    ><xtf-button label="切换" @click="value = !value"
  /></xtf-popover>
</template>

<script>
export default {
  data() {
    return { value: false }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

3. 进阶配置

组合布局、样式或插槽能力：

<template>
  <xtf-popover placement="bottom">
    <xtf-button label="插槽内容" /><template #content
      ><xtf-cell title="待发货" desc="仓库正在处理"
    /></template>
  </xtf-popover>
</template>

<script>
export default {
  data() {
    return { value: false }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
show	Boolean	false	控制组件的 show 行为。	按业务需要设置。
trigger	String	'click'	控制组件的 trigger 行为。	按业务需要设置。
placement	String	'bottom'	弹出位置：top/top-start/top-end、bottom/bottom-start/bottom-end、left/left-start/left-end、right/right-start/right-end。	需要控制面板相对触发器的方向和对齐方式。
title	String	''	控制组件的 title 行为。	按业务需要设置。
content	String	''	控制组件的 content 行为。	按业务需要设置。
arrow	Boolean	true	控制组件的 arrow 行为。	按业务需要设置。
disabled	Boolean	false	控制组件的 disabled 行为。	按业务需要设置。
closeOnClickOutside	Boolean	true	可见时是否渲染全屏透明遮罩；点击触发器周围空白区域会触发 update:show(false) 和 close。设为 false 时不渲染遮罩，空白点击不会关闭。	说明提示保持默认；面板内有连续操作或必须明确关闭时设为 false。
overlay	Boolean	false	是否为全屏背景遮罩着色；与 closeOnClickOutside 独立。true + false 可实现有遮罩但点击空白不关闭。	需要突出当前浮层或弱化页面背景时。
overlayColor	String	'rgba(15, 23, 42, 0.42)'	遮罩背景色；仅 overlay 为 true 时使用。	调整遮罩明暗与品牌色调。
autoAdjust	Boolean	true	控制组件的 autoAdjust 行为。	按业务需要设置。
variant	String	'popover'	控制组件的 variant 行为。	按业务需要设置。
animation	String	'scale'	面板进入和退出动画：none / fade / scale / zoom / slide-up / slide-down / slide-left / slide-right。	需要匹配浮层方向、降低动效或突出反馈时。
offset	String | Number	12	触发器与面板在主方向上的基础间距；数字和纯数字字符串按 rpx 处理，也可传入如 '16px' 的单位值。	常规间距控制；保留以兼容已有用法。
offsetX	String | Number	0	面板相对默认定位的水平偏移；正值向右，负值向左。数字按 rpx 处理。	需要微调左右对齐、避开邻近内容时。
offsetY	String | Number	0	面板相对默认定位的垂直偏移；正值向下，负值向上。数字按 rpx 处理。	需要微调上下对齐、避开邻近内容时。
width	[String, Number]	''	控制组件的 width 行为。	按业务需要设置。
maxWidth	[String, Number]	320	控制组件的 maxWidth 行为。	按业务需要设置。
zIndex	[String, Number]	40	控制组件的 zIndex 行为。	按业务需要设置。
customClass	String	''	控制组件的 customClass 行为。	按业务需要设置。
customStyle	[String, Object]	''	控制组件的 customStyle 行为。	按业务需要设置。
panelClass	String	''	控制组件的 panelClass 行为。	按业务需要设置。
panelStyle	[String, Object]	''	自定义浮层面板背景、边框、阴影、圆角等内联样式。	单个实例需要独立视觉时。
titleClass	String	''	控制组件的 titleClass 行为。	按业务需要设置。
titleStyle	[String, Object]	''	自定义标题容器内联样式。	使用 title 插槽时常用于重置内边距。
contentClass	String	''	控制组件的 contentClass 行为。	按业务需要设置。
contentStyle	[String, Object]	''	自定义正文容器内联样式。	使用 content 插槽组合业务组件时。
arrowClass	String	''	控制组件的 arrowClass 行为。	按业务需要设置。
arrowStyle	[String, Object]	''	自定义箭头背景与边框样式。	面板使用非默认背景色时。

---

事件

事件名称	触发时机	回调参数	参数说明
update:show	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('update:show', ...) 为准。
open	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('open', ...) 为准。
close	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('close', ...) 为准。

事件使用示例

<template>
  <xtf-popover @update:show="onEvent" />
</template>
<script>
export default {
  methods: {
    onEvent(payload) {
      console.log('收到事件', payload)
    }
  }
}
</script>

---

插槽

插槽名	说明	作用域参数
default	触发气泡浮层的内容。	无
title	替换标题内容。	无
content	替换浮层正文内容。	无

---

方法

setVisible(value)：切换可见状态；refreshPlacement()：重新计算自动避让位置。

使用示例：

this.$refs.popover.setVisible(true)
this.$refs.popover.refreshPlacement()

---

主题说明

• var(--xtf-popover-z-index) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-popover-offset) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-popover-shift-x) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-popover-shift-y) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-color-surface) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-color-border) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-shadow-popover) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-color-text) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-color-text-secondary) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-popover-arrow-shift-x) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-popover-arrow-shift-y) 参与组件的颜色、背景、边框或动效呈现。
• 视觉变体的可选值以 variant、theme、layout 等属性在源码中的分支为准。

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。