x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/trend-chart.md

@@ -0,0 +1,335 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# TrendChart AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`TrendChart`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./trend-chart-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/base.css`（包含 base.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/trend-chart.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./trend-chart-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于展示小型趋势、指标变化和概览图表。组件默认渲染为 100% 宽 × 60px 高的迷你图，适合放在仪表盘卡片、表格单元格和指标标签中。
+
+
+### 与其它图表的分工
+
+TrendChart 是**迷你图**：无坐标轴、无图例、单条曲线，用于卡片角落的形态提示。需要坐标轴读数或多系列对比时用 [LineChart 折线图](./line-chart.md)；完整的选择指引见[图表总览](./charts.md)。
+
+
+### 基础用法
+
+不设置 `height` 时组件使用 60px 默认高度，无需外部容器样式。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TrendChart } from 'x-next';
+const dataset = [12, 18, 14, 24, 32, 28, 36, 42];
+</script>
+<template>
+<TrendChart :dataset="dataset" status="success" />
+</template>
+```
+
+### 尺寸与权重
+
+迷你图的推荐高度是 **40 ~ 60px**。高度超过 80px 后曲线会显得空旷，观感更接近「一条没有坐标轴的大图」而不是角标趋势；这种场景应该改用 [LineChart 折线图](./line-chart.md)。
+
+`height` 与 `width` 接受数字（按 px 处理）或 CSS 值。数字宽度下组件不再撑满父容器，适合固定尺寸的卡片角标。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TrendChart } from 'x-next';
+const dataset = [12, 18, 14, 24, 32, 28, 36, 42];
+</script>
+<template>
+<TrendChart :dataset="dataset" :height="40" />
+  <TrendChart :dataset="dataset" :height="60" />
+  <TrendChart :dataset="dataset" :height="80" />
+</template>
+```
+
+### 卡片场景
+
+迷你图的实际用法是在指标卡里当角标：卡片给数值，图表给形态。下面的例子把宽度收到 120px 左右，与数值并排。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TrendChart } from 'x-next';
+const dataset = [12, 18, 14, 24, 32, 28, 36, 42];
+</script>
+<template>
+<div class="metric-card">
+    <div>
+      <div class="metric-card-label">今日请求量</div>
+      <div class="metric-card-value">12,480</div>
+    </div>
+    <TrendChart :dataset="dataset" status="success" :height="40" :width="120" />
+  </div>
+</template>
+<style scoped>
+.metric-card {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  width: 280px;
+  max-width: 100%;
+  padding: 12px 16px;
+  border: 1px solid var(--x-color-border-subtle);
+  border-radius: 8px;
+}
+.metric-card-value {
+  font-size: 20px;
+  font-weight: 500;
+}
+.metric-card-label {
+  color: var(--x-color-text-3);
+  font-size: 12px;
+}
+</style>
+```
+
+### 状态主题
+
+不传 `status` 时使用主色；`info` 为中性次要指标语义，适合同一卡片里弱化的对比项。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TrendChart } from 'x-next';
+const dataset = [12, 18, 14, 24, 32, 28, 36, 42];
+</script>
+<template>
+<TrendChart :dataset="dataset" status="primary" :height="56" />
+  <TrendChart :dataset="dataset" status="warning" :height="56" />
+  <TrendChart :dataset="dataset" status="danger" :height="56" />
+</template>
+```
+
+### 曲线与填充
+
+填充默认使用由描边色到透明的渐变；需要纯色块时通过 `theme.fill.type="solid"` 切换。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TrendChart } from 'x-next';
+const dataset = [12, 18, 14, 24, 32, 28, 36, 42];
+</script>
+<template>
+<TrendChart :dataset="dataset" :smooth="false" :height="56" />
+  <TrendChart :dataset="dataset" :fill="false" :height="56" />
+  <TrendChart :dataset="dataset" :stroke="false" :height="56" />
+</template>
+```
+
+### 数据点显示
+
+`show-points` 为 `auto`（默认）时，相邻点横向间距小于 18px 就自动隐藏普通点，避免小尺寸下点挤成一团；`true` 强制常显（点数多且空间窄时会显得拥挤，如上方第二例），`false` 完全隐藏。hover 时激活点始终可见。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TrendChart } from 'x-next';
+const dataset = [12, 18, 14, 24, 32, 28, 36, 42];
+const denseDataset = [
+  12, 18, 14, 24, 32, 28, 36, 42, 30, 22, 26, 34,
+  18, 26, 22, 30, 38, 34, 40, 46, 36, 28, 32, 44,
+];
+/* 延迟趋势：整体平稳、尾部抬头，用于卡片示例 */
+const latencyDataset = [196, 205, 188, 214, 202, 221, 208, 236];
+</script>
+<template>
+<!-- 默认 auto：点距不足时自动隐藏普通点；show-points 强制常显 -->
+  <div class="chart-320">
+    <TrendChart :dataset="denseDataset" :height="80" />
+  </div>
+  <div class="chart-320">
+    <TrendChart :dataset="denseDataset" show-points :height="80" />
+  </div>
+  <div class="chart-320">
+    <TrendChart :dataset="dataset" :show-points="false" :height="80" />
+  </div>
+</template>
+<style scoped>
+.chart-320 {
+  width: 320px;
+  max-width: 100%;
+}
+</style>
+```
+
+### 纯形态，不带坐标轴
+
+TrendChart 的 `grid` 与 `labels` 已**废弃**（1.8.0 起不渲染任何内容，props 声明保留到 2.0.0 移除）。这是有意的：**带网格和坐标文字的图属于 [LineChart 折线图](./line-chart.md)**，那里有类目轴、数值轴、多系列、图例和悬浮读数。
+
+迷你图的职责只有一个——让用户一眼看出「在涨还是在跌、有没有异常尖峰」。加上坐标轴后，40~60px 的高度里曲线会被压扁，而标签又读不清，反而不如直接用折线图。
+
+需要读数时：用 LineChart；想在这个尺寸下看具体数值，开 `tooltip` 悬浮即可（提示气泡会贴边收敛，不会被裁）。
+
+
+### 交互事件
+
+`tooltip` 开启后 hover 会在激活点旁显示 `tooltipFormatter` 的返回值，无需业务自己画提示层；激活竖线只从当前数据点连到绘图区底部，不会穿过整张图表；`mouse-move` 在数据变化导致激活点越界时会补发 `null`，业务侧不用额外兜底。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TrendChart } from 'x-next';
+import { ref } from 'vue';
+
+const dataset = [12, 18, 14, 24, 32, 28, 36, 42];
+const hoverInfo = ref('等待鼠标移动');
+// tooltip 文本格式化函数放在 script 中，避免模板内联类型注解
+const formatVolume = (value: number) => `${value} 单`;
+const handleMouseMove = (event: { index: number; data: number } | null) => {
+  hoverInfo.value = event ? `index: ${event.index}, value: ${event.data}` : '已离开';
+};
+</script>
+<template>
+<TrendChart
+    :dataset="dataset"
+    interactive
+    tooltip
+    :height="120"
+    :tooltip-formatter="formatVolume"
+    @mouse-move="handleMouseMove"
+  />
+  <p>{{ hoverInfo }}</p>
+</template>
+```
+
+### 数值区间
+
+`min` / `max` 传入后即锁定可见区间，超出范围的数据会被裁剪在绘图区之外。适合「只看某个区间」或让同一组卡片统一 Y 轴口径。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TrendChart } from 'x-next';
+const dataset = [12, 18, 14, 24, 32, 28, 36, 42];
+</script>
+<template>
+<TrendChart :dataset="dataset" :min="20" :max="40" interactive tooltip />
+</template>
+```
+
+### 自定义主题
+
+主题会与状态主题按层级合并：只写 `color` 即可统一换色，单独设置 `stroke.color` 等字段可覆盖单层。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TrendChart } from 'x-next';
+const dataset = [12, 18, 14, 24, 32, 28, 36, 42];
+
+const customTheme = {
+  // 统一基础色：未单独指定颜色的层级都会继承
+  color: '#7c3aed' as const,
+  // 默认权重：描边 1.5px、点半径 2px、激活竖线 1px
+  stroke: { width: 2 },
+  fill: { type: 'gradient' as const, opacity: 0.16 },
+  // point.width 实际为半径
+  point: { width: 3 },
+  axisLine: { width: 1, opacity: 0.7 },
+};
+</script>
+<template>
+<TrendChart :dataset="dataset" :theme="customTheme" />
+</template>
+```
+
+### 边界数据
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TrendChart } from 'x-next';
+const dataset = [12, 18, 14, 24, 32, 28, 36, 42];
+</script>
+<template>
+<TrendChart :dataset="[10, 10, 10, 10, 10]" :height="56" />
+  <TrendChart :dataset="[16]" :height="56" />
+  <TrendChart :dataset="[]" :height="56" />
+</template>
+```
+
+### 响应式尺寸
+
+容器尺寸变化（侧边栏折叠、ResizeBox 拖动、Tab 切换）会由 `ResizeObserver` 自动触发重算，图表的点位和标签不会错位。拖动下面的右边缘或底边缘查看效果。
+
+`height` 传 `'100%'` 时图表跟随父容器高度；容器尺寸变化无需监听 `window.resize`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ResizeBox, TrendChart } from 'x-next';
+import { ref } from 'vue';
+
+const dataset = [12, 18, 14, 24, 32, 28, 36, 42];
+const resizeWidth = ref(320);
+const resizeHeight = ref(56);
+</script>
+<template>
+<ResizeBox
+    v-model:width="resizeWidth"
+    v-model:height="resizeHeight"
+    :min-width="120"
+    :max-width="480"
+    :directions="['right', 'bottom']"
+    class="chart-box"
+  >
+    <TrendChart :dataset="dataset" :height="'100%'" status="primary" />
+  </ResizeBox>
+</template>
+<style scoped>
+.chart-box {
+  border: 1px solid var(--x-color-border-subtle);
+  border-radius: 6px;
+}
+</style>
+```
+
+### 无障碍
+
+设置 `aria-label` 后根节点会输出 `role="img"` 与可访问名称，屏幕阅读器可以播报图表用途。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { TrendChart } from 'x-next';
+const dataset = [12, 18, 14, 24, 32, 28, 36, 42];
+</script>
+<template>
+<TrendChart
+    :dataset="dataset"
+    :height="56"
+    ariaLabel="近七日订单量趋势"
+    interactive
+    tooltip
+  />
+</template>
+```
+
+### 使用说明
+
+- 默认高度 60px，无需外部容器样式；需要更高时通过 `height` 指定。
+- 不带网格与坐标轴（`grid` / `labels` 自 1.8.0 起废弃、不再渲染）：需要读数请改用 [LineChart](./line-chart.md)，或在当前尺寸下开 `tooltip`。
+- 空数组会渲染空态文案，不会抛错。
+- 单点数据会渲染为一个点，且不渲染填充。
+- 所有值相同时，趋势线绘制在图表中线。
+- `min` / `max` 锁定数据域后，超出部分被裁剪而非扩展区间，适合区间放大与多图对齐口径。
+- 容器尺寸变化会自动重算；初始隐藏在 `display: none` 中的图表，在变为可见后同样会重新计算尺寸。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./trend-chart-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/trigger-api.md

@@ -0,0 +1,124 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Trigger 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Trigger API
+
+公开声明：`dist/components/trigger/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| popupVisible | 弹出框是否可见，支持 v-model:popup-visible | undefined &#124; false &#124; true | 否 | undefined |
+| defaultPopupVisible | 默认是否可见，非受控模式 | undefined &#124; false &#124; true | 否 | false |
+| trigger | 触发方式 | undefined &#124; "click" &#124; "hover" &#124; "focus" &#124; "contextMenu" &#124; ("click" &#124; "hover" &#124; "focus" &#124; "contextMenu")[] | 否 | "hover" |
+| position | 弹出位置 | undefined &#124; "top" &#124; "bottom" &#124; "right" &#124; "left" &#124; "tl" &#124; "tr" &#124; "bl" &#124; "br" &#124; "lt" &#124; "rt" &#124; "lb" &#124; "rb" | 否 | "bottom" |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| popupOffset | 弹出框偏移 | undefined &#124; number | 否 | 0 |
+| popupTranslate | 弹出框移动距离 | undefined &#124; [number, number] &#124; { top?: [number, number] &#124; undefined; bottom?: [number, number] &#124; undefined; right?: [number, number] &#124; undefined; left?: [number, number] &#124; undefined; tl?: [number, number] &#124; undefined; tr?: [number, number] &#124; undefined; bl?: [number, number] &#124; undefined; br?: [number, number] &#124; undefined; lt?: [number, number] &#124; undefined; rt?: [number, number] &#124; undefined; lb?: [number, number] &#124; undefined; rb?: [number, number] &#124; undefined; } | 否 | 未声明 |
+| showArrow | 是否显示箭头 | undefined &#124; false &#124; true | 否 | false |
+| alignPoint | 是否跟随鼠标位置，常用于右键菜单 | undefined &#124; false &#124; true | 否 | false |
+| popupHoverStay | hover 触发时移入浮层是否保持显示 | undefined &#124; false &#124; true | 否 | true |
+| blurToClose | focus 触发时失焦是否关闭 | undefined &#124; false &#124; true | 否 | true |
+| clickToClose | 点击触发器时是否允许关闭 | undefined &#124; false &#124; true | 否 | true |
+| clickOutsideToClose | 点击外部是否关闭 | undefined &#124; false &#124; true | 否 | true |
+| unmountOnClose | 关闭时是否卸载弹出框 | undefined &#124; false &#124; true | 否 | true |
+| contentClass | 弹出内容类名 | undefined &#124; string &#124; { [x: string]: any; } &#124; unknown[] | 否 | 未声明 |
+| contentStyle | 弹出内容样式 | undefined &#124; CSSProperties | 否 | 未声明 |
+| arrowClass | 箭头类名 | undefined &#124; string &#124; { [x: string]: any; } &#124; unknown[] | 否 | 未声明 |
+| arrowStyle | 箭头样式 | undefined &#124; CSSProperties | 否 | 未声明 |
+| popupStyle | 弹出框定位节点样式 | undefined &#124; CSSProperties | 否 | 未声明 |
+| animationName | 弹出动画名称 | undefined &#124; string | 否 | "x-fade-in" |
+| duration | 动画持续时间 | undefined &#124; number &#124; { enter: number; leave: number; } | 否 | 未声明 |
+| mouseEnterDelay | mouseenter 延迟，单位毫秒 | undefined &#124; number | 否 | 100 |
+| mouseLeaveDelay | mouseleave 延迟，单位毫秒 | undefined &#124; number | 否 | 100 |
+| focusDelay | focus 延迟，单位毫秒 | undefined &#124; number | 否 | 0 |
+| autoFitPopupWidth | 是否将弹出框宽度设为触发器宽度 | undefined &#124; false &#124; true | 否 | false |
+| autoFitPopupMinWidth | 是否将弹出框最小宽度设为触发器宽度 | undefined &#124; false &#124; true | 否 | false |
+| autoFixPosition | 触发器尺寸变化时是否重新定位 | undefined &#124; false &#124; true | 否 | true |
+| popupContainer | 弹出框挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | 未声明 |
+| updateAtScroll | 容器滚动时是否更新浮层位置 | undefined &#124; false &#124; true | 否 | false |
+| autoFitTransformOrigin | 是否自动调整 transform-origin | undefined &#124; false &#124; true | 否 | false |
+| hideEmpty | 内容为空时是否隐藏 | undefined &#124; false &#124; true | 否 | false |
+| openedClass | 打开时给触发元素添加的类名 | undefined &#124; string &#124; { [x: string]: any; } &#124; unknown[] | 否 | 未声明 |
+| autoFitPosition | 是否自动调整位置适配视口 | undefined &#124; false &#124; true | 否 | true |
+| renderToBody | 是否挂载到 body | undefined &#124; false &#124; true | 否 | true |
+| preventFocus | 点击弹出层元素时是否阻止获取焦点 | undefined &#124; false &#124; true | 否 | false |
+| scrollToClose | 滚动时是否关闭 | undefined &#124; false &#124; true | 否 | false |
+| scrollToCloseDistance | 滚动关闭阈值 | undefined &#124; number | 否 | 0 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:popupVisible | 弹出框显隐变化时触发 | undefined &#124; (visible: boolean) => any |
+| popupVisibleChange | 弹出框显隐变化时触发 | undefined &#124; (visible: boolean) => any |
+| show | 显示动画结束后触发 | undefined &#124; () => any |
+| hide | 隐藏动画结束后触发 | undefined &#124; () => any |
+| resize | 内部尺寸变化时触发 | undefined &#124; () => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 触发元素 | any |
+| content | 弹出内容 | any |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type TriggerPopupTranslate = [number, number] | {
+    [key in TriggerPosition]?: [number, number];
+};
+
+interface TriggerProps {
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    trigger?: TriggerEvent;
+    position?: TriggerPosition;
+    disabled?: boolean;
+    popupOffset?: number;
+    popupTranslate?: TriggerPopupTranslate;
+    showArrow?: boolean;
+    alignPoint?: boolean;
+    popupHoverStay?: boolean;
+    blurToClose?: boolean;
+    clickToClose?: boolean;
+    clickOutsideToClose?: boolean;
+    scrollToClose?: boolean;
+    scrollToCloseDistance?: number;
+    unmountOnClose?: boolean;
+    contentClass?: any;
+    contentStyle?: CSSProperties;
+    arrowClass?: any;
+    arrowStyle?: CSSProperties;
+    popupStyle?: CSSProperties;
+    animationName?: string;
+    duration?: number | {
+        enter: number;
+        leave: number;
+    };
+    mouseEnterDelay?: number;
+    mouseLeaveDelay?: number;
+    focusDelay?: number;
+    autoFitPopupWidth?: boolean;
+    autoFitPopupMinWidth?: boolean;
+    autoFixPosition?: boolean;
+    popupContainer?: string | HTMLElement;
+    updateAtScroll?: boolean;
+    autoFitPosition?: boolean;
+}
+```
+
+
+返回 [Trigger 用法](./trigger.md)。

package/AI_USAGE/components/trigger.md

@@ -0,0 +1,185 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Trigger AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`Trigger`；主要模型：v-model:popup-visible。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./trigger-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/trigger`（包含 base.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/trigger.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./trigger-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+Trigger 是底层浮层 primitive，主要给 x-next 内部组件和高级封装使用。普通业务展示浮动卡片时，请优先使用 [Popover 气泡卡片](./popover.md)。
+
+Trigger 负责处理触发事件、显隐状态、浮层定位、Teleport、箭头、滚动更新和外部点击关闭。它不提供业务语义，也不提供卡片视觉规范。
+
+
+### 何时使用
+
+- 你正在封装新的浮层组件，例如 Tooltip、Dropdown、Popover、Popconfirm、SelectDropdown。
+- 你需要完全接管浮层内容结构和样式，不希望使用 Popover 的卡片语义。
+- 你需要直接控制底层定位行为，例如 `alignPoint`、`popupContainer`、`updateAtScroll`、`scrollToClose`。
+
+
+### 不推荐使用
+
+- 展示普通说明卡片：使用 `Popover`。
+- 展示纯文字提示：使用 `Tooltip`。
+- 展示操作菜单：使用 `Dropdown`。
+- 展示二次确认：使用 `Popconfirm`。
+
+
+### 与 Popover 的区别
+
+| 维度 | Popover | Trigger |
+| --- | --- | --- |
+| 用户心智 | 气泡卡片组件 | 底层触发定位 primitive |
+| 是否主推给业务用户 | 是 | 否 |
+| 是否有默认卡片样式 | 有 | 无 |
+| 是否提供 `title` / `content` 语义 | 有 | 无 |
+| 主要用途 | 展示富内容浮层 | 封装 Tooltip、Dropdown、Popover 等组件 |
+
+
+### 基础封装示例
+
+下面示例展示 Trigger 作为底层能力的使用方式。业务代码通常不需要直接这样写。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Trigger, Button } from 'x-next';
+
+</script>
+<template>
+<Trigger trigger="click" show-arrow>
+    <Button>底层触发器</Button>
+    <template #content>
+      <div class="custom-popup">完全自定义的浮层内容</div>
+    </template>
+  </Trigger>
+</template>
+```
+
+### 受控显隐与事件
+
+`disabled` 阻止触发事件；受控 prop 仍以父级值为准。外部直接赋值不派发触发事件。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Checkbox, Trigger } from 'x-next';
+import { ref } from 'vue';
+const visible = ref(false);
+const disabled = ref(false);
+const log = ref('等待开关');
+</script>
+<template>
+<Button @click="visible = !visible">外部切换</Button>
+  <Checkbox v-model="disabled">禁用触发</Checkbox>
+  <Trigger v-model:popup-visible="visible" trigger="click" :disabled="disabled"
+    @popup-visible-change="(value) => log = `visible: ${value}`">
+    <Button>点击触发</Button>
+    <template #content><div class="popup">受控浮层</div></template>
+  </Trigger>
+  <p role="status">{{ log }}；当前 {{ visible ? '打开' : '关闭' }}</p>
+</template>
+<style scoped>
+.popup { padding: 12px; background: var(--x-color-bg-elevated); border: 1px solid var(--x-color-border-default); }
+</style>
+```
+
+### 打开中切换挂载容器
+
+先打开浮层，再切换 A / B，浮层会迁移到当前容器并重新定位。
+
+容器不存在时回退 body；容器延迟出现后，可以更新 `popupContainer` 或再次打开，让组件重新解析目标。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Trigger } from 'x-next';
+import { ref } from 'vue';
+const container = ref('#popup-host-a');
+</script>
+<template>
+<Button @click="container = '#popup-host-a'">容器 A</Button>
+  <Button @click="container = '#popup-host-b'">容器 B</Button>
+  <Trigger trigger="click" :popup-container="container" :click-outside-to-close="false">
+    <Button>打开 / 关闭</Button>
+    <template #content><div class="popup">挂载到 {{ container }}</div></template>
+  </Trigger>
+  <div id="popup-host-a" class="host">容器 A</div>
+  <div id="popup-host-b" class="host">容器 B</div>
+</template>
+<style scoped>
+.host { position: relative; min-height: 60px; margin-top: 12px; border: 1px dashed var(--x-color-border-default); }
+.popup { padding: 12px; background: var(--x-color-bg-elevated); border: 1px solid var(--x-color-border-default); }
+</style>
+```
+
+### 聚焦触发
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Trigger } from 'x-next';
+
+</script>
+<template>
+<Trigger trigger="focus">
+    <input aria-label="聚焦触发示例" placeholder="Tab 或点击聚焦" />
+    <template #content><div>移开焦点后关闭</div></template>
+  </Trigger>
+</template>
+```
+
+### 右键与指针位置
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Trigger } from 'x-next';
+
+</script>
+<template>
+<Trigger trigger="contextMenu" align-point>
+    <button type="button">在这里点右键</button>
+    <template #content><div>跟随右键位置，点击外部关闭</div></template>
+  </Trigger>
+</template>
+```
+
+### 滚动与位置更新
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Trigger, Button } from 'x-next';
+
+</script>
+<template>
+<div class="scroll">
+    <div class="content">
+      <Trigger trigger="click" update-at-scroll>
+        <Button>滚动时保持定位</Button>
+        <template #content><div>浮层跟随触发点</div></template>
+      </Trigger>
+      <Trigger trigger="click" scroll-to-close :scroll-to-close-distance="20">
+        <Button>滚动 20px 关闭</Button>
+        <template #content><div>超过阈值后关闭</div></template>
+      </Trigger>
+    </div>
+  </div>
+</template>
+<style scoped>
+.scroll { height: 120px; overflow: auto; }
+.content { min-height: 360px; padding: 24px; }
+</style>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./trigger-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。