x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/popover.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Popover AI 使用
 
-适用版本：x-next@1.12.0；来源指纹：`9f9adf42b42dc1e551f500aabdcb7fb07b69a93ea44ff3dc1d16dab1a4c85843`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`Popover`；模型：v-model:popup-visible；已核对事件：popupVisibleChange。
+先读 [通用接入](../core.md)。公开导出：`Popover`；主要模型：v-model:popup-visible。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./popover-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/popover`（包含 base.css、popover.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/popover)。使用 `v-model:popup-visible`；默认 `trigger='click'`、`position='bottom'`、`showArrow=false`、`defaultPopupVisible=false`、`unmountOnClose=true`。默认插槽是触发器，`title` / `content` 插槽放浮层内容。
 
 `popup-visible-change(visible)` 返回布尔值，`show` / `hide` 无参数。点击触发器或外部默认可以关闭；`popupContainer` 和 `renderToBody` 决定宿主，用于定位、滚动及裁剪。通过 ConfigProvider 配置的主题会由 Trigger 同步到浮层根，默认挂到 body 也生效；任意业务 CSS 变量或仅在局部 DOM 调用 applyThemeColor 不等于该注入协议，仍要核对实际继承。
@@ -32,4 +34,207 @@ function changed(value: boolean) { feedback.value = value ? '说明已打开' :
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/popover.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./popover-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+围绕触发元素展示一块非模态浮动卡片，适合承载简短详情、辅助信息或轻量操作。
+
+
+### 何时使用
+
+- 需要点击、悬浮、聚焦或右键触发一块贴近目标元素的内容。
+- 需要展示比 Tooltip 更丰富的标题、说明或操作。
+- 需要控制浮层位置、箭头、挂载容器或受控显隐状态。
+
+
+### 组件选择
+
+| 需求 | 推荐组件 |
+| --- | --- |
+| 富内容浮动卡片 | `Popover` |
+| 纯文字说明 | `Tooltip` |
+| 操作菜单 | `Dropdown` |
+| 二次确认 | `Popconfirm` |
+| 封装新的浮层组件 | `Trigger` |
+
+`Trigger` 是底层触发定位 primitive，不建议普通业务直接使用。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popover, Button } from 'x-next';
+
+</script>
+<template>
+<Popover title="项目进度" content="当前任务已完成 62%，还有 3 个待处理节点。">
+    <Button type="primary">查看进度</Button>
+  </Popover>
+</template>
+```
+
+### 自定义内容
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popover, Button } from 'x-next';
+
+</script>
+<template>
+<Popover show-arrow>
+    <Button>查看详情</Button>
+    <template #title>节点详情</template>
+    <template #content>
+      <div>
+        <span>负责人：产品运营组</span>
+        <span>预计完成：今天 18:00</span>
+        <Button size="small" type="primary">进入任务</Button>
+      </div>
+    </template>
+  </Popover>
+</template>
+```
+
+### 触发方式
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popover, Button } from 'x-next';
+
+</script>
+<template>
+<Popover trigger="hover" content="鼠标移入触发元素时显示。">
+    <Button>悬浮</Button>
+  </Popover>
+
+  <Popover trigger="focus" content="获得焦点时显示，失焦后关闭。">
+    <Button>聚焦</Button>
+  </Popover>
+
+  <Popover trigger="contextMenu" align-point content="右键位置触发。">
+    <Button>右键</Button>
+  </Popover>
+</template>
+```
+
+### 弹出位置
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popover, Button } from 'x-next';
+
+</script>
+<template>
+<Popover position="top" content="上方弹出">
+    <Button>Top</Button>
+  </Popover>
+  <Popover position="right" content="右侧弹出">
+    <Button>Right</Button>
+  </Popover>
+</template>
+```
+
+### 箭头和偏移
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popover, Button } from 'x-next';
+
+</script>
+<template>
+<Popover
+    show-arrow
+    :popup-offset="12"
+    title="带箭头的浮层"
+    content="通过 popupOffset 控制与触发元素的距离。"
+  >
+    <Button>带箭头</Button>
+  </Popover>
+</template>
+```
+
+### 受控显隐
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Popover } from 'x-next';
+import { ref } from 'vue';
+
+const visible = ref(false);
+</script>
+<template>
+<Button @click="visible = !visible">
+    {{ visible ? '关闭' : '打开' }}
+  </Button>
+  <Popover
+    v-model:popup-visible="visible"
+    trigger="click"
+    title="受控 Popover"
+    content="外部按钮和触发器都可以同步显隐状态。"
+  >
+    <Button type="primary">受控触发器</Button>
+  </Popover>
+</template>
+```
+
+### 局部容器
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popover, Button } from 'x-next';
+
+</script>
+<template>
+<div id="popover-local-container" style="position: relative; min-height: 180px;">
+    <Popover
+      popup-container="#popover-local-container"
+      show-arrow
+      title="局部挂载"
+      content="局部挂载内容"
+    >
+      <Button>挂载到容器</Button>
+    </Popover>
+  </div>
+</template>
+```
+
+### 保持挂载
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popover, Button } from 'x-next';
+import { ref } from 'vue';
+
+const visible = ref(false);
+</script>
+<template>
+<Popover
+    v-model:popup-visible="visible"
+    :unmount-on-close="false"
+    title="保留 DOM"
+    content="关闭后保留浮层节点"
+  >
+    <Button>切换保留浮层</Button>
+  </Popover>
+</template>
+```
+
+### 与 Popup 的关系
+
+`Popover` 是后续推荐使用的通用浮动卡片组件。`Popup` 是早期命名，已放入即将废弃分组，当前仅作为迁移期兼容入口保留。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./popover-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/popup-api.md

@@ -0,0 +1,75 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Popup 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Popup API
+
+公开声明：`dist/components/popup/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| popupVisible | 见场景用法与类型 | 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")[] | 否 | "click" |
+| 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" |
+| title | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | 未声明 |
+| content | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | 未声明 |
+| disabled | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+| popupOffset | 见场景用法与类型 | undefined &#124; number | 否 | 8 |
+| 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 | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | true |
+| blurToClose | 见场景用法与类型 | 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]: boolean; } &#124; (string &#124; Record<string, boolean>)[] | 否 | 未声明 |
+| contentStyle | 见场景用法与类型 | undefined &#124; CSSProperties | 否 | 未声明 |
+| arrowClass | 见场景用法与类型 | undefined &#124; string &#124; { [x: string]: boolean; } &#124; (string &#124; Record<string, boolean>)[] | 否 | 未声明 |
+| arrowStyle | 见场景用法与类型 | undefined &#124; CSSProperties | 否 | 未声明 |
+| popupStyle | 见场景用法与类型 | undefined &#124; CSSProperties | 否 | 未声明 |
+| animationName | 见场景用法与类型 | undefined &#124; string | 否 | "x-zoom-in-fade-out" |
+| duration | 见场景用法与类型 | undefined &#124; number &#124; { enter: number; leave: number; } | 否 | 未声明 |
+| mouseEnterDelay | 见场景用法与类型 | undefined &#124; number | 否 | 100 |
+| mouseLeaveDelay | 见场景用法与类型 | undefined &#124; number | 否 | 100 |
+| focusDelay | 见场景用法与类型 | 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 |
+| autoFitPosition | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | true |
+| renderToBody | 见场景用法与类型 | 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 |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 见场景用法与类型 | any |
+| title | 见场景用法与类型 | any |
+| content | 见场景用法与类型 | any |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [Popup 用法](./popup.md)。

package/AI_USAGE/components/popup.md

@@ -0,0 +1,52 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Popup AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`Popup`；主要模型：v-model:popup-visible。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./popup-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/popup`（包含 base.css、popover.css、popup.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/popup.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./popup-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+Popup 即将废弃，当前仅作为迁移期兼容入口保留。新项目请使用 [Popover 气泡卡片](./popover.md)。
+
+Popup 用于围绕触发元素展示一块自定义浮层内容。它现在基于 Popover 兼容实现，已有代码可以继续使用；后续新能力只会优先放在 Popover。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popup, Button } from 'x-next';
+
+</script>
+<template>
+<Popup title="兼容 Popup" content="Popup 仍可使用，但推荐迁移到 Popover。">
+    <Button type="primary">点击打开</Button>
+  </Popup>
+</template>
+```
+
+### 迁移到 Popover
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Popover, Button } from 'x-next';
+
+</script>
+<template>
+<Popover title="推荐 Popover" content="Popover 是后续推荐使用的通用浮动卡片组件。">
+    <Button type="primary">使用 Popover</Button>
+  </Popover>
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./popup-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/progress-api.md

@@ -0,0 +1,44 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Progress 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Progress API
+
+公开声明：`dist/components/progress/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| type | 进度条类型 | undefined &#124; "circle" &#124; "line" | 否 | "line" |
+| size | 尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| percent | 当前进度，内部按 0~1 归一化渲染 | undefined &#124; number | 否 | 0 |
+| steps | 步骤条数量，大于 0 时启用步骤模式 | undefined &#124; number | 否 | 0 |
+| animation | 是否开启线性进度动画 | undefined &#124; false &#124; true | 否 | false |
+| strokeWidth | 进度条线宽 | undefined &#124; number | 否 | 未声明 |
+| width | 线性进度条宽度；圆形进度条仅支持数字直径 | undefined &#124; string &#124; number | 否 | 未声明 |
+| color | 进度条颜色，支持渐变对象 | undefined &#124; string &#124; { [x: string]: any; } | 否 | 未声明 |
+| trackColor | 轨道颜色 | undefined &#124; string | 否 | 未声明 |
+| bufferColor | 线性进度条缓冲轨道颜色 | undefined &#124; string &#124; { [x: string]: any; } | 否 | 未声明 |
+| showText | 是否显示文本 | undefined &#124; false &#124; true | 否 | true |
+| status | 状态 | undefined &#124; "normal" &#124; "success" &#124; "warning" &#124; "strong" &#124; "danger" | 否 | 未声明 |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| text | 自定义进度文本 | undefined &#124; (scope: { percent: number; }) => any |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [Progress 用法](./progress.md)。

package/AI_USAGE/components/progress.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Progress AI 使用
 
-适用版本：x-next@1.12.0；来源指纹：`9f9adf42b42dc1e551f500aabdcb7fb07b69a93ea44ff3dc1d16dab1a4c85843`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`Progress`；模型：无；已核对事件：未在精选映射登记事件；其他 API 见下方用法。
+先读 [通用接入](../core.md)。公开导出：`Progress`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./progress-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/progress`（包含 base.css、progress.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/progress)。`percent` 为 **0 到 1** 的比例，默认 `0`，不是 0 到 100；超出范围会裁剪，非有限值显示为 0。默认 `type='line'`、`showText=true`、`animation=false`，`steps>0` 使用分段模式。
 
 无模型和业务 change 事件，由业务更新 `percent`。`status` 为 `'normal' | 'success' | 'warning' | 'strong' | 'danger'`，未设置时达到 1 自动为 success；显式 status 优先，`strong` 不表示完成。`text` 插槽提供 `{ percent }`。
@@ -30,4 +32,247 @@ function advance() { percent.value = Math.min(1, percent.value + 0.25); }
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/progress.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./progress-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于表达任务进度、上传状态或流程完成度。
+
+
+### 何时使用
+
+- 需要展示一个耗时任务的当前完成比例。
+- 需要表达上传、导入、部署、审批等流程的状态。
+- 需要用步骤段落展示离散进度。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Progress } from 'x-next';
+
+</script>
+<template>
+<Progress :percent="0.6" />
+  <Progress :percent="0.6" :show-text="false" />
+</template>
+```
+
+### 动态进度
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Progress, Button } from 'x-next';
+import { onBeforeUnmount, ref } from 'vue';
+
+const percent = ref(0.28);
+let timer: number | undefined;
+
+const clearTimer = () => {
+  if (timer) {
+    window.clearInterval(timer);
+    timer = undefined;
+  }
+};
+
+const start = () => {
+  clearTimer();
+  percent.value = 0;
+  timer = window.setInterval(() => {
+    percent.value = Math.min(1, Number((percent.value + 0.08).toFixed(2)));
+    if (percent.value >= 1) {
+      clearTimer();
+    }
+  }, 280);
+};
+
+const reset = () => {
+  clearTimer();
+  percent.value = 0.28;
+};
+
+onBeforeUnmount(clearTimer);
+</script>
+<template>
+<Progress :percent="percent" animation />
+  <div class="actions">
+    <Button type="primary" size="small" @click="start">开始</Button>
+    <Button size="small" @click="reset">重置</Button>
+  </div>
+</template>
+```
+
+### 状态
+
+五种状态与品牌状态族一一对应，line / circle / steps 三种形态都支持。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Progress } from 'x-next';
+
+</script>
+<template>
+<Progress :percent="0.3" status="normal" />
+  <Progress :percent="0.45" status="warning" />
+  <Progress :percent="0.55" status="strong" />
+  <Progress :percent="0.6" status="danger" />
+  <Progress :percent="1" status="success" />
+</template>
+```
+
+### 尺寸
+
+线性进度的 `mini`、`small`、`medium`、`large` 只改变线条和文本尺寸，不会改变进度条形态；圆形迷你进度请使用 `type="circle" size="mini"`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Progress } from 'x-next';
+
+</script>
+<template>
+<Progress size="mini" :percent="0.4" />
+  <Progress size="small" :percent="0.5" />
+  <Progress :percent="0.6" />
+  <Progress size="large" :percent="0.7" />
+</template>
+```
+
+### 宽度与线宽
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Progress } from 'x-next';
+
+</script>
+<template>
+<Progress :percent="0.54" width="320px" :stroke-width="6" />
+  <Progress :percent="0.7" :stroke-width="10" status="warning" />
+  <Progress type="circle" :percent="0.62" :width="72" :stroke-width="5" />
+  <Progress type="circle" :percent="0.86" :width="88" :stroke-width="6" status="success" />
+</template>
+```
+
+### 圆形进度
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Progress } from 'x-next';
+
+</script>
+<template>
+<Progress type="circle" :percent="0.45" />
+  <Progress type="circle" :percent="0.75" status="warning" />
+  <Progress type="circle" :percent="1" status="success" />
+</template>
+```
+
+### 迷你圆形进度
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Progress } from 'x-next';
+
+</script>
+<template>
+<Progress type="circle" size="mini" :percent="0.4" />
+  <Progress type="circle" size="mini" :percent="0.65" status="warning" />
+  <Progress type="circle" size="mini" :percent="0.8" status="danger" />
+  <Progress type="circle" size="mini" :percent="1" status="success" />
+</template>
+```
+
+### 步骤进度
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Progress } from 'x-next';
+
+</script>
+<template>
+<Progress :steps="5" :percent="0.4" />
+  <Progress :steps="8" :percent="0.5" status="warning" />
+  <Progress :steps="6" :percent="0.67" status="danger" :stroke-width="8" />
+</template>
+```
+
+### 自定义颜色
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Progress } from 'x-next';
+const gradientColor = {
+  '0%': 'var(--x-color-success-6)',
+  '55%': 'var(--x-color-primary-6)',
+  '100%': 'var(--x-color-warning-6)',
+};
+</script>
+<template>
+<Progress
+    :percent="0.68"
+    color="var(--x-color-success-6)"
+    track-color="var(--x-color-success-1)"
+  />
+  <Progress :percent="0.72" :color="gradientColor" />
+  <Progress
+    :percent="0.55"
+    animation
+    color="var(--x-color-primary-6)"
+    buffer-color="var(--x-color-primary-1)"
+  />
+</template>
+```
+
+### 自定义文本
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Progress } from 'x-next';
+
+</script>
+<template>
+<Progress :percent="0.75">
+    <template #text="{ percent }">
+      {{ Math.round(percent * 100) }} / 100
+    </template>
+  </Progress>
+  <Progress type="circle" :percent="0.32">
+    <template #text="{ percent }">
+      已完成 {{ Math.round(percent * 100) }}%
+    </template>
+  </Progress>
+</template>
+```
+
+### 边界值
+
+`percent` 使用 `0~1` 的小数，组件内部会把非法值归一化到 `0~1` 再渲染。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Progress } from 'x-next';
+
+</script>
+<template>
+<Progress :percent="-0.2" />
+  <Progress :percent="1.2" />
+  <Progress type="circle" :percent="-0.2" />
+  <Progress type="circle" :percent="1.2" />
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./progress-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。