115 lines
4.0 KiB
Markdown
115 lines
4.0 KiB
Markdown
|
---
|
|||
|
|
name: arco-vue-trigger
|
|||
|
|
description: "Arco Design Vue 触发器 Trigger 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-trigger>`、属性、事件、插槽、示例和实现细节。"
|
|||
|
|
user-invocable: false
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 触发器 Trigger
|
|||
|
|
|
|||
|
|
## 简介
|
|||
|
|
|
|||
|
|
这个例子展示了触发器的最基础的使用。触发器默认是没有弹出框的样式的。以下示例均为官网添加的样式。
|
|||
|
|
|
|||
|
|
## 基本用法
|
|||
|
|
|
|||
|
|
```vue
|
|||
|
|
<template>
|
|||
|
|
<a-space>
|
|||
|
|
<a-trigger position="top" auto-fit-position :unmount-on-close="false">
|
|||
|
|
<span>Hover Me</span>
|
|||
|
|
<template #content>
|
|||
|
|
<div class="demo-basic">
|
|||
|
|
<a-empty />
|
|||
|
|
</div>
|
|||
|
|
</template>
|
|||
|
|
</a-trigger>
|
|||
|
|
<a-trigger trigger="click" :unmount-on-close="false">
|
|||
|
|
<a-button>Click Me</a-button>
|
|||
|
|
<template #content>
|
|||
|
|
<div class="demo-basic">
|
|||
|
|
<a-empty />
|
|||
|
|
</div>
|
|||
|
|
</template>
|
|||
|
|
</a-trigger>
|
|||
|
|
<a-trigger trigger="focus">
|
|||
|
|
<a-input placeholder="Focus on me" />
|
|||
|
|
<template #content>
|
|||
|
|
<div class="demo-basic">
|
|||
|
|
<a-empty />
|
|||
|
|
</div>
|
|||
|
|
</template>
|
|||
|
|
</a-trigger>
|
|||
|
|
</a-space>
|
|||
|
|
</template>
|
|||
|
|
|
|||
|
|
<style scoped>
|
|||
|
|
.demo-basic {
|
|||
|
|
padding: 10px;
|
|||
|
|
width: 200px;
|
|||
|
|
background-color: var(--color-bg-popup);
|
|||
|
|
border-radius: 4px;
|
|||
|
|
box-shadow: 0 2px 8px 0 rgba(0, 0, 0, 0.15);
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## API
|
|||
|
|
|
|||
|
|
### `<trigger>` 属性
|
|||
|
|
|
|||
|
|
|参数名|描述|类型|默认值|版本|
|
|||
|
|
|---|---|---|:---:|:---|
|
|||
|
|
|popup-visible **(v-model)**|弹出框是否可见|`boolean`|`-`||
|
|||
|
|
|default-popup-visible|弹出框默认是否可见（非受控模式）|`boolean`|`false`||
|
|||
|
|
|trigger|触发方式|`'hover' \| 'click' \| 'focus' \| 'contextMenu'`|`'hover'`||
|
|||
|
|
|position|弹出位置|`'top' \| 'tl' \| 'tr' \| 'bottom' \| 'bl' \| 'br' \| 'left' \| 'lt' \| 'lb' \| 'right' \| 'rt' \| 'rb'`|`'bottom'`||
|
|||
|
|
|disabled|触发器是否禁用|`boolean`|`false`||
|
|||
|
|
|popup-offset|弹出框的偏移量（弹出框距离触发器的偏移距离）|`number`|`0`||
|
|||
|
|
|popup-translate|弹出框的移动距离|`TriggerPopupTranslate`|`-`||
|
|||
|
|
|show-arrow|弹出框是否显示箭头|`boolean`|`false`||
|
|||
|
|
|align-point|弹出框是否跟随鼠标|`boolean`|`false`||
|
|||
|
|
|popup-hover-stay|是否在移出触发器，并移入弹出框时保持弹出框显示|`boolean`|`true`||
|
|||
|
|
|blur-to-close|是否在触发器失去焦点时关闭弹出框|`boolean`|`true`||
|
|||
|
|
|click-to-close|是否在点击触发器时关闭弹出框|`boolean`|`true`||
|
|||
|
|
|
|||
|
|
> 仅列出常用项，低频属性按需查阅官方 API。
|
|||
|
|
|
|||
|
|
### `<trigger>` 事件
|
|||
|
|
|
|||
|
|
|事件名|描述|参数|版本|
|
|||
|
|
|---|---|---|:---|
|
|||
|
|
|popup-visible-change|弹出框显示状态改变时触发|visible: `boolean`||
|
|||
|
|
|show|弹出框显示后（动画结束）触发|-|2.18.0|
|
|||
|
|
|hide|弹出框隐藏后（动画结束）触发|-|2.18.0|
|
|||
|
|
|
|||
|
|
### `<trigger>` 插槽
|
|||
|
|
|
|||
|
|
|插槽名|描述|参数|
|
|||
|
|
|---|:---:|---|
|
|||
|
|
|content|弹出框内容|-|
|
|||
|
|
|
|||
|
|
### 类型定义
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
type TriggerPopupTranslate =
|
|||
|
|
| [number, number]
|
|||
|
|
| { [key in TriggerPosition]?: [number, number] };
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 常用模式
|
|||
|
|
|
|||
|
|
- **多层嵌套**：弹出层可以嵌套在另一个弹出层内。
|
|||
|
|
- **多个触发方式**：通过`trigger`传入数组，可以设置多个触发方式。
|
|||
|
|
- **跟随鼠标显示弹出框**：设置`align-point`属性，可以使弹出层出现在鼠标位置。
|
|||
|
|
- **滚动容器**：通过设置 `update-at-scroll` 监听容器的滚动。
|
|||
|
|
- **显示箭头元素**：通过`show-arrow`属性，可以展示默认的箭头元素。也可以通过`arrow-class`或`arrow-style`进行定制。
|
|||
|
|
- **弹窗偏移量**：通过`popup-translate`属性，可以设置弹窗在原本位置的基础上进行额外的位置调整。
|
|||
|
|
|
|||
|
|
## 最佳实践
|
|||
|
|
|
|||
|
|
- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
|
|||
|
|
- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
|
|||
|
|
- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
|
|||
|
|
- 底层能力组件优先服务明确场景，避免为了样式效果直接暴露复杂配置。
|
|||
|
|
- 涉及滚动、弹层和 DOM 容器时，先确认挂载容器和边界行为。
|