docs(agents): add design references

2026-08-10 23:34:28 +08:00
parent a2383fc8a1
commit 72a83f5fcd
86 changed files with 8889 additions and 0 deletions
--- a/.agents/skills/arco-design-vue/references/components/navigation/breadcrumb.md
+++ b/.agents/skills/arco-design-vue/references/components/navigation/breadcrumb.md
@@ -0,0 +1,86 @@
+---
+name: arco-vue-breadcrumb
+description: "Arco Design Vue 面包屑 Breadcrumb 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-breadcrumb>`、属性、事件、插槽、示例和实现细节。"
+user-invocable: false
+---
+
+# 面包屑 Breadcrumb
+
+## 简介
+
+面包屑的基本用法。
+
+## 基本用法
+
+```vue
+<template>
+  <a-breadcrumb>
+    <a-breadcrumb-item>Home</a-breadcrumb-item>
+    <a-breadcrumb-item>Channel</a-breadcrumb-item>
+    <a-breadcrumb-item>News</a-breadcrumb-item>
+  </a-breadcrumb>
+</template>
+```
+
+## API
+
+### `<breadcrumb>` 属性
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|max-count|最多展示的面包屑数量（0表示不限制）|`number`|`0`||
+|routes|设置路径|`BreadcrumbRoute[]`|`-`|2.36.0|
+|separator|分隔符文字|`string\|number`|`-`|2.36.0|
+|custom-url|自定义链接地址|`(paths: string[]) => string`|`-`|2.36.0|
+
+### `<breadcrumb>` 插槽
+
+|插槽名|描述|参数|版本|
+|---|:---:|---|:---|
+|more-icon|自定义更多图标|-|2.36.0|
+|item-render|routes 设置时生效，自定义渲染面包屑|route: `BreadcrumbRoute`<br>routes: `BreadcrumbRoute[]`<br>paths: `string[]`|2.36.0|
+|separator|自定义分隔符|-||
+
+### `<breadcrumb-item>` 属性
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|separator|分隔符文字|`string\|number`|`-`|2.36.0|
+|droplist|下拉菜单内容|`BreadcrumbRoute['children']`|`-`|2.36.0|
+|dropdown-props|下拉菜单属性|`DropDownProps`|`-`|2.36.0|
+
+### `<breadcrumb-item>` 插槽
+
+|插槽名|描述|参数|版本|
+|---|:---:|---|:---|
+|droplist|自定义下拉菜单|-|2.36.0|
+|separator|自定义分隔符|-|2.36.0|
+
+### BreadcrumbRoute
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|label|面包屑名称|`string`|`-`|
+|path|跳转路径 (`a`标签的`href`)|`string`|`-`|
+|children|下拉菜单展示项|`{    label: string;    path: string;  }[]`|`-`|
+
+### 使用提示
+
+同名的自定义插槽优先级是高于属性的
+
+## 常用模式
+
+- **自定义分隔符**：通过 `separator` 属性或插槽自定义分隔符。面包屑子项也可通过 `separator` 属性或插槽自定义分隔符，且优先级高于父项。
+- **自定义尺寸**：通过指定样式来自定义面包屑的尺寸。
+- **自定义图标**：可以在内容中使用自定义图标。
+- **参数化配置**：通过 `routes` 来传递面包屑数据。若是要自定义面包屑的话，建议使用 `<a-breadcrumb-item />` 组件。默认使用 `a` 标签的 `href` 属性绑定路径，可通过 `item` 插槽自定义渲染。
+- **带有下拉菜单**：通过 `droplist` 或者 `routes` 来指定下拉菜单。
+- **显示省略**：通过 `max-count` 来指定面包屑的最多渲染数量，超出的部分将显示为省略号。
+
+## 最佳实践
+
+- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
+- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
+- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
+- 导航状态应与路由或业务状态保持单一来源，避免组件内部状态和路由不同步。
+- 菜单、分页、步骤等受控状态优先使用 `v-model` 或命名 `v-model:*`。
--- a/.agents/skills/arco-design-vue/references/components/navigation/dropdown.md
+++ b/.agents/skills/arco-design-vue/references/components/navigation/dropdown.md
@@ -0,0 +1,203 @@
+---
+name: arco-vue-dropdown
+description: "Arco Design Vue 下拉菜单 Dropdown 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-dropdown>`、属性、事件、插槽、示例和实现细节。"
+user-invocable: false
+---
+
+# 下拉菜单 Dropdown
+
+## 简介
+
+下拉菜单的基本用法。下拉菜单开启后会为触发元素添加 `arco-dropdown-open` 类名。
+
+## 基本用法
+
+```vue
+<template>
+  <a-space size="large">
+    <a-dropdown @select="handleSelect">
+      <a-button>Click Me</a-button>
+      <template #content>
+        <a-doption>Option 1</a-doption>
+        <a-doption disabled>Option 2</a-doption>
+        <a-doption :value="{ value: 'Option3' }">Option 3</a-doption>
+      </template>
+    </a-dropdown>
+    <a-dropdown @select="handleSelect" disabled>
+      <a-button disabled>Click Me</a-button>
+      <template #content>
+        <a-doption>Option 1</a-doption>
+        <a-doption disabled>Option 2</a-doption>
+        <a-doption>Option 3</a-doption>
+      </template>
+    </a-dropdown>
+    <a-dropdown @select="handleSelect" :popup-max-height="false">
+      <a-button>No Max Height <icon-down/></a-button>
+      <template #content>
+        <a-doption>Option 1</a-doption>
+        <a-doption disabled>Option 2</a-doption>
+        <a-doption>Option 3</a-doption>
+        <a-doption>Option 4</a-doption>
+        <a-doption>Option 5</a-doption>
+        <a-doption>Option 6</a-doption>
+        <a-doption>Option 7</a-doption>
+        <a-doption>Option 8</a-doption>
+        <a-doption>Option 9</a-doption>
+      </template>
+    </a-dropdown>
+  </a-space>
+</template>
+
+<script>
+export default {
+  setup() {
+    const handleSelect = (v) => {
+      console.log(v)
+    };
+
+    return {
+      handleSelect
+    }
+  },
+}
+</script>
+
+<style>
+.arco-dropdown-open .arco-icon-down {
+  transform: rotate(180deg);
+}
+</style>
+```
+
+## API
+
+### `<dropdown>` 属性
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|popup-visible **(v-model)**|弹出框是否可见|`boolean`|`-`||
+|default-popup-visible|弹出框默认是否可见（非受控模式）|`boolean`|`false`||
+|trigger|触发方式|`'hover' \| 'click' \| 'focus' \| 'contextMenu'`|`'click'`||
+|position|弹出位置|`'top' \| 'tl' \| 'tr' \| 'bottom' \| 'bl' \| 'br'`|`'bottom'`||
+|popup-container|弹出框的挂载容器|`string \| HTMLElement`|`-`||
+|popup-max-height|弹出框最大高度|`boolean\|number`|`true`|2.29.0|
+|hide-on-select|是否在用户选择后隐藏弹出框|`boolean`|`true`|2.43.0|
+
+### `<dropdown>` 事件
+
+|事件名|描述|参数|
+|---|---|---|
+|popup-visible-change|下拉框显示状态发生改变时触发|visible: `boolean`|
+|select|用户选择时触发|value: `string \| number \| Record<string, any> \| undefined `<br>ev: `Event`|
+
+### `<dropdown>` 插槽
+
+|插槽名|描述|参数|版本|
+|---|:---:|---|:---|
+|content|内容|-||
+|footer|页脚|-|2.10.0|
+
+### `<doption>` 属性
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|value|选项值|`string\|number\|object`|`-`|
+|disabled|是否禁用|`boolean`|`false`|
+
+### `<doption>` 事件
+
+|事件名|描述|参数|
+|---|---|---|
+|click|点击按钮时触发|ev: `MouseEvent`|
+
+### `<doption>` 插槽
+
+|插槽名|描述|参数|
+|---|:---:|---|
+|icon|图标|-|
+
+### `<dgroup>` 属性
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|title|分组标题|`string`|`-`|
+
+### `<dgroup>` 插槽
+
+|插槽名|描述|参数|版本|
+|---|:---:|---|:---|
+|title|分组标题|-|2.10.0|
+
+### `<dsubmenu>` 属性
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|value|选项值（2.16.0 版本后暂无用处）|`string\|number`|`-`||
+|disabled|是否禁用|`boolean`|`false`|2.10.0|
+|trigger|触发方式|`'hover' \| 'click'`|`'click'`|2.10.0|
+|position|弹出位置|`'rt' \| 'lt'`|`'rt'`|2.10.0|
+|popup-visible **(v-model)**|弹出框是否可见|`boolean`|`-`||
+|default-popup-visible|弹出框默认是否可见（非受控模式）|`boolean`|`false`||
+|option-props|自定义选项属性|`object`|`-`|2.29.0|
+
+### `<dsubmenu>` 事件
+
+|事件名|描述|参数|
+|---|---|---|
+|popup-visible-change|下拉框显示状态发生改变时触发|visible: `boolean`|
+
+### `<dsubmenu>` 插槽
+
+|插槽名|描述|参数|版本|
+|---|:---:|---|:---|
+|icon|图标|-|2.29.0|
+|content|子菜单内容|-||
+|footer|页脚|-|2.10.0|
+
+### `<dropdown-button>` 属性
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|popup-visible **(v-model)**|弹出框是否可见|`boolean`|`-`|
+|default-popup-visible|弹出框默认是否可见（非受控模式）|`boolean`|`false`|
+|trigger|触发方式|`'hover' \| 'click' \| 'focus' \| 'contextMenu'`|`'click'`|
+|position|弹出位置|`'top' \| 'tl' \| 'tr' \| 'bottom' \| 'bl' \| 'br'`|`'br'`|
+|popup-container|弹出框的挂载容器|`string \| HTMLElement`|`-`|
+|disabled|是否禁用|`boolean`|`false`|
+|type|按钮类型|`string`|`-`|
+|size|按钮大小|`string`|`-`|
+|button-props|按钮属性|`ButtonProps`|`-`|
+|hide-on-select|是否在用户选择后隐藏弹出框|`boolean`|`true`|
+
+### `<dropdown-button>` 事件
+
+|事件名|描述|参数|
+|---|---|---|
+|popup-visible-change|下拉框显示状态发生改变时触发|visible: `boolean`|
+|click|点击按钮时触发|ev: `MouseEvent`|
+|select|用户选择时触发|value: `string \| number \| Record<string, any> \| undefined`<br>ev: `Event`|
+
+### `<dropdown-button>` 插槽
+
+|插槽名|描述|参数|
+|---|:---:|---|
+|icon|按钮图标|popupVisible: `boolean`|
+|content|内容|-|
+
+## 常用模式
+
+- **弹出方向**：通过 `position` 支持指定 6 种弹出方位，分别是：top: 向上, tl: 左上, tr: 右上, bottom: 下方(默认), bl: 左下, br: 右下。
+- **触发方式**：通过 `trigger` 指定触发方式。
+- **按钮下拉框**：可以使用 `<dropdown-button>` 组件用来展示右边是额外相关功能菜单的按钮。`2.16.0` 版本添加支持。
+- **分组选项**：通过 `<dgroup>` 组件使用分组选项。
+- **多级菜单**：带有多级菜单的下拉框。
+- **右键菜单**：移入区域后，可点击鼠标右键触发。
+- **带图标的选项**：通过 `icon` 插槽在选项前添加图标。
+
+## 最佳实践
+
+- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
+- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
+- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
+- 导航状态应与路由或业务状态保持单一来源，避免组件内部状态和路由不同步。
+- 菜单、分页、步骤等受控状态优先使用 `v-model` 或命名 `v-model:*`。
--- a/.agents/skills/arco-design-vue/references/components/navigation/menu.md
+++ b/.agents/skills/arco-design-vue/references/components/navigation/menu.md
@@ -0,0 +1,143 @@
+---
+name: arco-vue-menu
+description: "Arco Design Vue 菜单 Menu 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-menu>`、属性、事件、插槽、示例和实现细节。"
+user-invocable: false
+---
+
+# 菜单 Menu
+
+## 简介
+
+设置 `mode` 为 `horizontal` 时，使用水平菜单。
+
+## 基本用法
+
+```vue
+<template>
+  <div class="menu-demo">
+    <a-menu mode="horizontal" :default-selected-keys="['1']">
+      <a-menu-item key="0" :style="{ padding: 0, marginRight: '38px' }" disabled>
+        <div
+          :style="{
+            width: '80px',
+            height: '30px',
+            borderRadius: '2px',
+            background: 'var(--color-fill-3)',
+            cursor: 'text',
+          }"
+        />
+      </a-menu-item>
+      <a-menu-item key="1">Home</a-menu-item>
+      <a-menu-item key="2">Solution</a-menu-item>
+      <a-menu-item key="3">Cloud Service</a-menu-item>
+      <a-menu-item key="4">Cooperation</a-menu-item>
+    </a-menu>
+  </div>
+</template>
+<style scoped>
+.menu-demo {
+  box-sizing: border-box;
+  width: 100%;
+  padding: 40px;
+  background-color: var(--color-neutral-2);
+}
+</style>
+```
+
+## API
+
+### `<menu>` 属性
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|theme|菜单的主题|`'light' \| 'dark'`|`'light'`||
+|mode|菜单的模式|`'vertical' \| 'horizontal' \| 'pop' \| 'popButton'`|`'vertical'`||
+|level-indent|层级之间的缩进量|`number`|`-`||
+|auto-open|默认展开所有多级菜单|`boolean`|`false`||
+|collapsed **(v-model)**|是否折叠菜单|`boolean`|`-`||
+|default-collapsed|默认是否折叠菜单|`boolean`|`false`||
+|collapsed-width|折叠菜单宽度|`number`|`-`||
+|accordion|开启手风琴效果|`boolean`|`false`||
+|auto-scroll-into-view|是否自动滚动选中项目到可见区域|`boolean`|`false`||
+|show-collapse-button|是否内置折叠按钮|`boolean`|`false`||
+|selected-keys **(v-model)**|选中的菜单项 key 数组|`string[]`|`-`||
+|default-selected-keys|默认选中的菜单项 key 数组|`string[]`|`[]`||
+
+> 仅列出常用项，低频属性按需查阅官方 API。
+
+### `<menu>` 事件
+
+|事件名|描述|参数|
+|---|---|---|
+|collapse|折叠状态改变时触发|collapsed: `boolean`<br>type: `'clickTrigger'\|'responsive'`|
+|menu-item-click|点击菜单项时触发|key: `string`|
+|sub-menu-click|点击子菜单时触发|key: `string`<br>openKeys: `string[]`|
+
+### `<menu>` 插槽
+
+|插槽名|描述|参数|
+|---|:---:|---|
+|collapse-icon|折叠图标|collapsed: `boolean`|
+|expand-icon-right|向右展开的图标|-|
+|expand-icon-down|向下展开的图标|-|
+
+### `<sub-menu>` 属性
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|title|子菜单的标题|`string`|`-`||
+|selectable|弹出模式下，是否将多级菜单头也作为一个菜单项，支持点击选中等状态|`boolean`|`false`||
+|popup|是否强制使用弹出模式，`level` 表示当前子菜单的层级|`boolean \| ((level: number) => boolean)`|`false`||
+|popup-max-height|弹出框的最大高度|`boolean \| number`|`true`|2.23.0|
+
+### `<sub-menu>` 插槽
+
+|插槽名|描述|参数|版本|
+|---|:---:|---|:---|
+|title|标题|-||
+|expand-icon-right|向右展开的图标|-||
+|expand-icon-down|向下展开的图标|-||
+|icon|菜单的图标|-|2.11.0|
+
+### `<menu-item-group>` 属性
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|title|菜单组的标题|`string`|`-`|
+
+### `<menu-item-group>` 插槽
+
+|插槽名|描述|参数|
+|---|:---:|---|
+|title|标题|-|
+
+### `<menu-item>` 属性
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|disabled|是否禁用|`boolean`|`false`|
+
+### `<menu-item>` 插槽
+
+|插槽名|描述|参数|版本|
+|---|:---:|---|:---|
+|icon|菜单的图标|-|2.11.0|
+
+## 常用模式
+
+- **顶部导航菜单**：设置 `mode` 为 `horizontal` 时，使用水平菜单。
+- **深色模式导航**：通过 `theme` 指定主题，分为 `light` 和 `dark` 两种。
+- **缩起内嵌菜单**：通过 `collapsed` 来指定菜单收起。
+- **响应式收缩**：设置 `breakpoint` 可触发响应式收缩。
+- **内嵌菜单**：菜单内可以嵌入多个子项，通过 `openKeys` 可以设置默认打开的子项。
+- **不同大小菜单**：通过 `style` 自由指定菜单的宽度和菜单项的高度。
+- **悬浮菜单**：指定 `mode` 为 `pop` 可以使用悬浮菜单。
+- **悬浮按钮菜单**：指定 `mode` 为 `popButton` 使用按钮组样式的悬浮菜单。
+
+## 最佳实践
+
+- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
+- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
+- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
+- 导航状态应与路由或业务状态保持单一来源，避免组件内部状态和路由不同步。
+- 菜单、分页、步骤等受控状态优先使用 `v-model` 或命名 `v-model:*`。
--- a/.agents/skills/arco-design-vue/references/components/navigation/page-header.md
+++ b/.agents/skills/arco-design-vue/references/components/navigation/page-header.md
@@ -0,0 +1,73 @@
+---
+name: arco-vue-page-header
+description: "Arco Design Vue 页头 PageHeader 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-page-header>`、属性、事件、插槽、示例和实现细节。"
+user-invocable: false
+---
+
+# 页头 PageHeader
+
+## 简介
+
+基础页头，适合使用在需要简单描述的场景。默认是没有底色的。
+
+## 基本用法
+
+```vue
+<template>
+  <div :style="{ background: 'var(--color-fill-2)', padding: '28px' }" >
+    <a-page-header
+      :style="{ background: 'var(--color-bg-2)' }"
+      title="ArcoDesign"
+      subtitle="ArcoDesign Vue 2.0"
+    >
+      <template #extra>
+        <a-radio-group type="button" default-value="large">
+          <a-radio value="mini">Mini</a-radio>
+          <a-radio value="small">Small</a-radio>
+          <a-radio value="large">Large</a-radio>
+        </a-radio-group>
+      </template>
+    </a-page-header>
+  </div>
+</template>
+```
+
+## API
+
+### `<page-header>` 属性
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|title|页头的主标题|`string`|`-`|
+|subtitle|页头的次标题|`string`|`-`|
+|show-back|是否显示返回按钮|`boolean`|`true`|
+
+### `<page-header>` 事件
+
+|事件名|描述|参数|
+|---|---|---|
+|back|点击返回按钮时触发|event: `Event`|
+
+### `<page-header>` 插槽
+
+|插槽名|描述|参数|版本|
+|---|:---:|---|:---|
+|breadcrumb|面包屑|-||
+|back-icon|返回按钮|-|2.36.0|
+|title|主标题|-||
+|subtitle|次标题|-||
+|extra|额外的展示内容|-||
+
+## 常用模式
+
+- **带有面包屑**：在页头中展示面包屑。
+- **透明底色**：默认是没有底色的，如果有需要可以通过`style`或类名设置不同底色。
+- **组合示例**：页头的完整示例。
+
+## 最佳实践
+
+- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
+- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
+- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
+- 导航状态应与路由或业务状态保持单一来源，避免组件内部状态和路由不同步。
+- 菜单、分页、步骤等受控状态优先使用 `v-model` 或命名 `v-model:*`。
--- a/.agents/skills/arco-design-vue/references/components/navigation/pagination.md
+++ b/.agents/skills/arco-design-vue/references/components/navigation/pagination.md
@@ -0,0 +1,75 @@
+---
+name: arco-vue-pagination
+description: "Arco Design Vue 分页 Pagination 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-pagination>`、属性、事件、插槽、示例和实现细节。"
+user-invocable: false
+---
+
+# 分页 Pagination
+
+## 简介
+
+分页的基本用法，`total` 属性为必填项。
+
+## 基本用法
+
+```vue
+<template>
+  <a-pagination :total="50"/>
+</template>
+```
+
+## API
+
+### `<pagination>` 属性
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|total **(必填)**|数据总数|`number`|`-`||
+|current **(v-model)**|当前的页数|`number`|`-`||
+|default-current|默认的页数（非受控状态）|`number`|`1`||
+|page-size **(v-model)**|每页展示的数据条数|`number`|`-`||
+|default-page-size|默认每页展示的数据条数（非受控状态）|`number`|`10`||
+|disabled|是否禁用|`boolean`|`false`||
+|hide-on-single-page|单页时是否隐藏分页|`boolean`|`false`||
+|simple|是否为简单模式|`boolean`|`false`||
+|show-total|是否显示数据总数|`boolean`|`false`||
+|show-more|是否显示更多按钮|`boolean`|`false`||
+|show-jumper|是否显示跳转|`boolean`|`false`||
+|show-page-size|是否显示数据条数选择器|`boolean`|`false`||
+
+> 仅列出常用项，低频属性按需查阅官方 API。
+
+### `<pagination>` 事件
+
+|事件名|描述|参数|
+|---|---|---|
+|change|页码改变时触发|current: `number`|
+|page-size-change|数据条数改变时触发|pageSize: `number`|
+
+### `<pagination>` 插槽
+
+|插槽名|描述|参数|版本|
+|---|:---:|---|:---|
+|total|总数|total: `number`|2.9.0|
+|page-item-ellipsis|分页按钮（省略）|-|2.9.0|
+|page-item-step|分页按钮（步）|type: `'previous'\|'next'`The type of page item step|2.9.0|
+|page-item|分页按钮|page: `number`The page number of the paging button|2.9.0|
+
+## 常用模式
+
+- **更多页码**：当页码较大时，会使用更多页码的分页样式。
+- **每页条数**：通过设置 `show-page-size`， 展示每页条数选择器。
+- **页码跳转**：通过设置 `show-jumper`，显示页码跳转输入框。
+- **分页尺寸**：分页分为 `mini`、`small`、`medium`、`large` 四种尺寸。
+- **简洁模式**：通过设置 `simple` 属性开启简洁模式。
+- **展示总数**：通过设置 `show-total` 属性显示数据总数。
+- **全部展示**：展示全部配置项。
+- **自定义分页按钮**：可以通过插槽自定义分页按钮内容
+
+## 最佳实践
+
+- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
+- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
+- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
+- 导航状态应与路由或业务状态保持单一来源，避免组件内部状态和路由不同步。
+- 菜单、分页、步骤等受控状态优先使用 `v-model` 或命名 `v-model:*`。
--- a/.agents/skills/arco-design-vue/references/components/navigation/steps.md
+++ b/.agents/skills/arco-design-vue/references/components/navigation/steps.md
@@ -0,0 +1,87 @@
+---
+name: arco-vue-steps
+description: "Arco Design Vue 步骤条 Steps 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-steps>`、属性、事件、插槽、示例和实现细节。"
+user-invocable: false
+---
+
+# 步骤条 Steps
+
+## 简介
+
+步骤条的基本用法。
+
+## 基本用法
+
+```vue
+<template>
+  <div>
+    <a-steps :current="2">
+      <a-step>Succeeded</a-step>
+      <a-step>Processing</a-step>
+      <a-step>Pending</a-step>
+    </a-steps>
+    <a-divider/>
+    <div style="line-height: 140px; text-align: center; color: #C9CDD4; ">
+      Step 2 Content
+    </div>
+  </div>
+</template>
+```
+
+## API
+
+### `<steps>` 属性
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|type|步骤条的类型|`'default' \| 'arrow' \| 'dot' \| 'navigation'`|`'default'`|
+|direction|步骤条的显示方向|`'horizontal' \| 'vertical'`|`'horizontal'`|
+|label-placement|标签描述文字放置的位置|`'horizontal' \| 'vertical'`|`'horizontal'`|
+|current **(v-model)**|当前步骤数|`number`|`-`|
+|default-current|默认的步骤数（非受控状态）|`number`|`1`|
+|status|当前步骤的状态|`'wait' \| 'process' \| 'finish' \| 'error'`|`'process'`|
+|line-less|是否使用无连接线样式|`boolean`|`false`|
+|small|是否使用小型步骤条|`boolean`|`false`|
+|changeable|是否可以点击切换|`boolean`|`false`|
+
+### `<steps>` 事件
+
+|事件名|描述|参数|
+|---|---|---|
+|change|步骤数发生改变时触发|step: `number`<br>ev: `Event`|
+
+### `<step>` 属性
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|title|步骤的标题|`string`|`-`|
+|description|步骤的描述信息|`string`|`-`|
+|status|步骤的状态|`'wait' \| 'process' \| 'finish' \| 'error'`|`-`|
+|disabled|是否禁用|`boolean`|`false`|
+
+### `<step>` 插槽
+
+|插槽名|描述|参数|
+|---|:---:|---|
+|node|节点|step: `number`<br>status: `string`|
+|icon|图标|step: `number`<br>status: `string`|
+|description|描述内容|-|
+
+## 常用模式
+
+- **描述信息**：通过设置 `description` 可以添加描述信息。
+- **标签放置位置**：通过设置 `label-placement` 可以改变标签描述文字放置的位置。放置位置分为 `horizontal` - **放置在图标右侧（默认）**、`vertical` - **放置在图标下方**两种。
+- **步骤错误**：通过设置 `status="error"` 来展示错误状态。
+- **自定义图标**：通过 `#icon` 插槽可以自定义节点图标。
+- **隐藏连接线**：通过设置 `line-less` 可以使用无连接线模式。
+- **竖直步骤条**：竖直方向的步骤条。
+- **箭头步骤条**：通过设置 `type="arrow"`，可以使用箭头类型的步骤条。**注意**：仅支持水平步骤条。
+- **点状步骤条**：通过设置 `type="dot"` ， 可以使用点状的步骤条。此模式没有 small 尺寸。
+
+## 最佳实践
+
+- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
+- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
+- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
+- 导航状态应与路由或业务状态保持单一来源，避免组件内部状态和路由不同步。
+- 菜单、分页、步骤等受控状态优先使用 `v-model` 或命名 `v-model:*`。