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/general/button.md
+++ b/.agents/skills/arco-design-vue/references/components/general/button.md
@@ -0,0 +1,83 @@
+---
+name: arco-vue-button
+description: "Arco Design Vue 按钮 Button 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-button>`、属性、事件、插槽、示例和实现细节。"
+user-invocable: false
+---
+
+# 按钮 Button
+
+## 简介
+
+按钮分为 `primary` - **主要按钮**、`secondary` - **次要按钮（默认）**、`dashed` - **虚线按钮**、`outline` - **线形按钮**、`text` - **文本按钮**五种类型。
+
+## 基本用法
+
+```vue
+<template>
+  <a-space>
+    <a-button type="primary">Primary</a-button>
+    <a-button>Secondary</a-button>
+    <a-button type="dashed">Dashed</a-button>
+    <a-button type="outline">Outline</a-button>
+    <a-button type="text">Text</a-button>
+  </a-space>
+</template>
+```
+
+## API
+
+### `<button>` 属性
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|type|按钮的类型，分为五种：次要按钮、主要按钮、虚框按钮、线性按钮、文字按钮。|`ButtonTypes`|`'secondary'`|
+|shape|按钮的形状|`BorderShape`|`-`|
+|status|按钮的状态|`'normal' \| 'warning' \| 'success' \| 'danger'`|`'normal'`|
+|size|按钮的尺寸|`'mini' \| 'small' \| 'medium' \| 'large'`|`'medium'`|
+|long|按钮的宽度是否随容器自适应。|`boolean`|`false`|
+|loading|按钮是否为加载中状态|`boolean`|`false`|
+|disabled|按钮是否禁用|`boolean`|`false`|
+|html-type|设置 `button` 的原生 `type` 属性，可选值参考 [HTML标准](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-type "_blank")|`HTMLButtonElement['type']`|`'button'`|
+|autofocus|设置 `button` 的原生 `autofocus` 属性，可选值参考 [HTML标准](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-type "_blank")|`boolean`|`false`|
+|href|设置跳转链接。设置此属性时，按钮渲染为a标签。|`string`|`-`|
+
+### `<button>` 事件
+
+|事件名|描述|参数|
+|---|---|---|
+|click|点击按钮时触发|ev: `MouseEvent`|
+
+### `<button>` 插槽
+
+|插槽名|描述|参数|
+|---|:---:|---|
+|icon|图标|-|
+
+### `<button-group>` 属性
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|type|按钮的类型，分为五种：次要按钮、主要按钮、虚框按钮、线性按钮、文字按钮。|`ButtonTypes`|`-`|
+|status|按钮的状态|`'normal' \| 'warning' \| 'success' \| 'danger'`|`-`|
+|shape|按钮的形状|`BorderShape`|`-`|
+|size|按钮的尺寸|`'mini' \| 'small' \| 'medium' \| 'large'`|`-`|
+|disabled|全部子按钮是否禁用|`boolean`|`false`|
+
+## 常用模式
+
+- **图标按钮**：按钮可以嵌入图标。在只设置图标时，按钮的宽高相等。
+- **按钮形状**：按钮分为 `square` - **长方形（默认）**、`circle` - **圆形**、`round` - **全圆角**三种形状。
+- **按钮尺寸**：按钮分为 `mini`、`small`、`medium`、`large` 四种尺寸。高度分别为：`24px`、`28px`、`32px`、`36px`。推荐（默认）尺寸为 `medium`。可在不同场景及不同业务需求选择适合尺寸。
+- **按钮状态**：按钮的状态分为 `normal` - **正常（默认）**、`success` - **成功**、`warning` - **警告**、`danger` - **危险**四种，可以与按钮类型同时使用。
+- **禁用状态**：按钮的禁用状态。
+- **加载中状态**：通过设置 `loading` 可以让按钮处于加载中状态。处于加载中状态的按钮不会触发点击事件。
+- **长按钮**：通过设置 `long` 属性，使按钮的宽度跟随容器的宽度。
+- **组合按钮**：通过 `<a-button-group>` 组件使按钮以组合方式出现。可用在同级多项操作中。
+
+## 最佳实践
+
+- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
+- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
+- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
+- 基础组件保持语义清晰，主操作、次操作和危险操作要用不同 `type` 或 `status` 区分。
+- 图标、按钮、链接等交互元素要同时考虑禁用、加载和可访问文本。
--- a/.agents/skills/arco-design-vue/references/components/general/config-provider.md
+++ b/.agents/skills/arco-design-vue/references/components/general/config-provider.md
@@ -0,0 +1,124 @@
+---
+name: arco-vue-config-provider
+description: "Arco Design Vue 全局配置 ConfigProvider 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-config-provider>`、属性、事件、插槽、示例和实现细节。"
+user-invocable: false
+---
+
+# 全局配置 ConfigProvider
+
+## 简介
+
+设置国际化语言的基本用法。
+
+## 基本用法
+
+```vue
+<template>
+  <a-config-provider :locale="locale">
+    <a-radio-group
+      type="button"
+      v-model="localeType"
+      :options="localeOptions"
+    ></a-radio-group>
+    <div>
+      <a-pagination
+        :total="50"
+        show-total
+        show-jumper
+        show-page-size
+        style="margin-top: 20px; margin-bottom: 20px;"
+      />
+    </div>
+    <a-space :size="20" style="margin-bottom: 20px;">
+      <a-range-picker style="width: 300px;" />
+      <a-time-picker type="time-range" style="width: 300px;" />
+      <a-popconfirm content="Are you sure you want to delete?">
+        <a-button type="primary">Popconfirm</a-button>
+      </a-popconfirm>
+    </a-space>
+  </a-config-provider>
+</template>
+
+<script>
+import { ref, computed } from 'vue';
+import zhCN from '@arco-design/web-vue/es/locale/lang/zh-cn';
+import enUS from '@arco-design/web-vue/es/locale/lang/en-us';
+import esES from '@arco-design/web-vue/es/locale/lang/es-es';
+import jaJP from '@arco-design/web-vue/es/locale/lang/ja-jp';
+import idID from '@arco-design/web-vue/es/locale/lang/id-id';
+import frFR from '@arco-design/web-vue/es/locale/lang/fr-fr';
+import ptPT from '@arco-design/web-vue/es/locale/lang/pt-pt';
+import deDE from '@arco-design/web-vue/es/locale/lang/de-de';
+import koKR from '@arco-design/web-vue/es/locale/lang/ko-kr';
+import itIT from '@arco-design/web-vue/es/locale/lang/it-it';
+import thTH from '@arco-design/web-vue/es/locale/lang/th-th';
+import viVN from '@arco-design/web-vue/es/locale/lang/vi-vn';
+import nlNL from '@arco-design/web-vue/es/locale/lang/nl-nl';
+
+const locales = {
+  'zh-CN': zhCN,
+  'en-US': enUS,
+  'es-ES': esES,
+  'ja-JP': jaJP,
+  'id-ID': idID,
+  'fr-FR': frFR,
+  'pt-PT': ptPT,
+  'de-DE': deDE,
+  'ko-KR': koKR,
+  'it-IT': itIT,
+  'th-TH': thTH,
+  'vi-VN': viVN,
+  'nl-NL': nlNL,
+};
+
+export default {
+  setup() {
+    const localeType = ref('es-ES');
+    const locale = computed(() => {
+      return locales[localeType.value] || zhCN;
+    });
+
+    return {
+      localeType,
+      locale,
+      localeOptions: Object.keys(locales),
+    };
+  },
+};
+</script>
+```
+
+## API
+
+### `<config-provider>` 属性
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|prefix-cls|组件类名前缀|`string`|`'arco'`||
+|locale|配置语言包|`ArcoLang`|`-`||
+|size|大小|`Size`|`-`|2.14.0|
+|global|是否全局生效|`boolean`|`false`|2.25.0|
+|update-at-scroll|是否在容器滚动时更新弹出框的位置|`boolean`|`false`|2.25.0|
+|scroll-to-close|是否在滚动时关闭弹出框|`boolean`|`false`|2.46.0|
+|exchange-time|是否交换时间|`boolean`|`true`|2.48.0|
+|rtl|视图的表现形式是从右开始向左结束|`boolean`|`false`||
+
+### `<config-provider>` 插槽
+
+|插槽名|描述|参数|版本|
+|---|:---:|---|:---|
+|loading|自定义加载中元素|-|2.28.0|
+|empty|自定义空状态元素|component: `string`|2.28.0|
+
+## 常用模式
+
+- **自定义空状态元素**：通过 `empty` 插槽可以全局自定义空状态元素。
+- **RTL 视图**：设置组件为从右向左阅读的视图。
+
+## 最佳实践
+
+- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
+- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
+- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
+- 基础组件保持语义清晰，主操作、次操作和危险操作要用不同 `type` 或 `status` 区分。
+- 图标、按钮、链接等交互元素要同时考虑禁用、加载和可访问文本。
--- a/.agents/skills/arco-design-vue/references/components/general/icon.md
+++ b/.agents/skills/arco-design-vue/references/components/general/icon.md
@@ -0,0 +1,43 @@
+---
+name: arco-vue-icon
+description: "Arco Design Vue Icon 图标参考。用于 `@arco-design/web-vue/es/icon`、`ArcoVueIcon`、`<icon-xx>`、图标按需导入、图标属性、旋转图标和 iconfont.cn 集成。"
+user-invocable: false
+---
+
+# Icon 图标
+
+## 简介
+
+Icon 图标参考。用于 `@arco-design/web-vue/es/icon`、`ArcoVueIcon`、`<icon-xx>`、图标按需导入、图标属性、旋转图标和 iconfont.cn 集成。
+
+## 基本用法
+
+```ts
+import { createApp } from 'vue';
+import ArcoVue from '@arco-design/web-vue';
+import ArcoVueIcon from '@arco-design/web-vue/es/icon';
+import '@arco-design/web-vue/dist/arco.css';
+import App from './App.vue';
+
+const app = createApp(App);
+app.use(ArcoVue);
+app.use(ArcoVueIcon);
+app.mount('#app');
+```
+
+## API
+
+当前组件没有单独整理的 API 表。使用时优先参考组件属性、事件和插槽约定。
+
+## 常用模式
+
+- **基础使用**：直接使用全局 `a-` 前缀组件，按需绑定属性、事件和插槽。
+- **受控状态**：涉及值或显隐时优先使用 `v-model` 或命名 `v-model:*`。
+
+## 最佳实践
+
+- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
+- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
+- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
+- 基础组件保持语义清晰，主操作、次操作和危险操作要用不同 `type` 或 `status` 区分。
+- 图标、按钮、链接等交互元素要同时考虑禁用、加载和可访问文本。
--- a/.agents/skills/arco-design-vue/references/components/general/link.md
+++ b/.agents/skills/arco-design-vue/references/components/general/link.md
@@ -0,0 +1,56 @@
+---
+name: arco-vue-link
+description: "Arco Design Vue 链接 Link 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-link>`、属性、事件、插槽、示例和实现细节。"
+user-invocable: false
+---
+
+# 链接 Link
+
+## 简介
+
+链接的基本用法。
+
+## 基本用法
+
+```vue
+<template>
+  <a-space>
+    <a-link href="link">Link</a-link>
+    <a-link href="link" disabled>Link</a-link>
+  </a-space>
+</template>
+```
+
+## API
+
+### `<link>` 属性
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|href|链接地址|`string`|`-`||
+|status|链接的状态|`'normal' \| 'warning' \| 'success' \| 'danger'`|`'normal'`||
+|hoverable|鼠标悬浮时存在底色|`boolean`|`true`|2.7.0|
+|icon|图标|`boolean`|`false`|2.7.0|
+|loading|链接是否为加载中状态|`boolean`|`false`|2.37.0|
+|disabled|链接是否禁用|`boolean`|`false`||
+
+### `<link>` 事件
+
+|事件名|描述|参数|
+|---|---|---|
+|click|点击时触发|ev: `MouseEvent`|
+
+## 常用模式
+
+- **链接的状态**：链接的状态分为 `normal` - **正常（默认）**、`success` - **成功**、`warning` - **警告**、`danger` - **危险**四种。
+- **悬浮状态底色**：可以通过 hoverable 属性设置是否在悬浮状态时隐藏底色。
+- **图标**：通过 `icon` 设置带图标的链接，设置为 `true` 时候显示默认图标。
+- **加载中状态**：通过设置 `loading` 可以让链接处于加载中状态。处于加载中状态的链接不会触发点击事件。
+
+## 最佳实践
+
+- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
+- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
+- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
+- 基础组件保持语义清晰，主操作、次操作和危险操作要用不同 `type` 或 `status` 区分。
+- 图标、按钮、链接等交互元素要同时考虑禁用、加载和可访问文本。
--- a/.agents/skills/arco-design-vue/references/components/general/typography.md
+++ b/.agents/skills/arco-design-vue/references/components/general/typography.md
@@ -0,0 +1,137 @@
+---
+name: arco-vue-typography
+description: "Arco Design Vue 排版 Typography 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-typography>`、属性、事件、插槽、示例和实现细节。"
+user-invocable: false
+---
+
+# 排版 Typography
+
+## 简介
+
+排版组件用于展示标题、段落、文本内容，这里展示了排版的组合使用。
+
+## 基本用法
+
+```vue
+<template>
+  <a-typography :style="{ marginTop: '-40px' }">
+    <a-typography-title>
+      Design system
+    </a-typography-title>
+    <a-typography-paragraph>
+      A design is a plan or specification for the construction of an object or system or for the implementation of an activity or process, or the result of that plan or specification in the form of a prototype, product or process. The verb to design expresses the process of developing a design.
+    </a-typography-paragraph>
+    <a-typography-paragraph>
+      In some cases, the direct construction of an object without an explicit prior plan (such as in craftwork, some engineering, coding, and graphic design) may also be considered <a-typography-text bold>to be a design activity.</a-typography-text>
+    </a-typography-paragraph>
+    <a-typography-title :heading="2">ArcoDesign</a-typography-title>
+    <a-typography-paragraph>
+      The ArcoDesign component library defines a set of default particle variables, and a custom theme is to <a-typography-text mark>customize</a-typography-text> and <a-typography-text underline>overwrite</a-typography-text> this variable list.
+    </a-typography-paragraph>
+    <a-typography-paragraph blockquote>
+      A design is a plan or specification for the construction of an object or system or for the implementation of an activity or process, or the result of that plan or specification in the form of a <a-typography-text code>prototype</a-typography-text>, <a-typography-text code>product</a-typography-text> or <a-typography-text code>process</a-typography-text>. The verb to design expresses the process of developing a design.
+    </a-typography-paragraph>
+    <a-typography-paragraph mark underline delete>A design is a plan or specification for the construction of an object or system or for the implementation of an activity or process.</a-typography-paragraph>
+    <a-typography-paragraph>
+      <ul>
+        <li>
+          Architectural blueprints
+          <ul>
+            <li>Architectural blueprints</li>
+          </ul>
+        </li>
+        <li>Engineering drawings</li>
+        <li>Business processes</li>
+      </ul>
+    </a-typography-paragraph>
+    <a-typography-paragraph>
+      <ol>
+        <li>Architectural blueprints</li>
+        <li>Engineering drawings</li>
+        <li>Business processes</li>
+      </ol>
+    </a-typography-paragraph>
+  </a-typography>
+</template>
+```
+
+## API
+
+### `Common` Props
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|type|文本类型|`'primary' \| 'secondary' \| 'success' \| 'danger' \| 'warning'`|`-`||
+|bold|粗体|`boolean`|`false`||
+|mark|添加标记样式|`boolean \| { color: string }`|`false`||
+|underline|下划线样式|`boolean`|`false`||
+|delete|删除线样式|`boolean`|`false`||
+|code|代码块样式|`boolean`|`false`||
+|disabled|禁用状态|`boolean`|`false`||
+|editable|开启可编辑功能|`boolean`|`false`||
+|editing **(v-model)**|是否在编辑状态|`boolean`|`-`||
+|default-editing|默认的编辑状态|`boolean`|`false`||
+|edit-text **(v-model)**|编辑的文字|`string`|`-`||
+|copyable|开启复制功能|`boolean`|`false`||
+
+> 仅列出常用项，低频属性按需查阅官方 API。
+
+### `Common` Events
+
+|事件名|描述|参数|
+|---|---|---|
+|edit-start|开始编辑|-|
+|change|编辑内容变化|text: `string`|
+|edit-end|编辑结束|-|
+|copy|复制|text: `string`|
+|ellipsis|省略变化事件|isEllipsis: `boolean`|
+|expand|展开收起事件|expanded: `boolean`|
+
+### `Common` Slots
+
+|插槽名|描述|参数|
+|---|:---:|---|
+|expand-node|自定义展开和折叠按钮|expanded: `boolean`|
+|copy-icon|自定义复制按钮图标|copied: `boolean`|
+|copy-tooltip|自定义复制按钮的 tooltip 内容|copied: `boolean`|
+
+### `<typography-title>` 属性
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|heading|标题级别，相当于 `h1` `h2` `h3` `h4` `h5` `h6`|`'1' \| '2' \| '3' \| '4' \| '5' \| '6'`|`1`|
+
+### `<typography-paragraph>` 属性
+
+|参数名|描述|类型|默认值|
+|---|---|---|:---:|
+|blockquote|长引用|`boolean`|`false`|
+|spacing|段落的的行高，长文本(大于5行)的时候推荐使用默认行高，短文本(小于等于3行)推荐使用 `close` 紧密的行高。|`'default' \| 'close'`|`'default'`|
+
+### EllipsisConfig
+
+|参数名|描述|类型|默认值|版本|
+|---|---|---|:---:|:---|
+|rows|显示省略的行数|`number`|`1`||
+|expandable|是否支持展开/折叠|`boolean`|`false`||
+|ellipsisStr|省略号|`string`|`'...'`||
+|suffix|后缀|`string`|`-`||
+|showTooltip|配置省略时的弹出框|`boolean    \| { type: 'tooltip' \| 'popover'; props: Record<string, any> }`|`false`||
+|css|是否使用 CSS 省略（此模式暂不支持展开、自定义省略号和后缀）|`boolean`|`false`|2.37.0|
+
+## 常用模式
+
+- **组合使用**：排版组件用于展示标题、段落、文本内容，这里展示了排版的组合使用。
+- **标题**：展示不同级别的标题。
+- **文本**：不同样式的文本以及超链接组件。
+- **段落**：文本段落样式。
+- **可交互**：提供复制、编辑文本等功能。
+- **省略**：在空间不足时省略多行文本内容。
+
+## 最佳实践
+
+- 新代码优先使用 Vue 3、Composition API 和 `<script setup lang="ts">`。
+- 模板属性使用 kebab-case，事件使用 `@event-name`，插槽使用 `#slot-name`。
+- 不要套用 React 专属 API，例如 JSX children、`Component.Sub` 或 `Form.useForm`。
+- 基础组件保持语义清晰，主操作、次操作和危险操作要用不同 `type` 或 `status` 区分。
+- 图标、按钮、链接等交互元素要同时考虑禁用、加载和可访问文本。