diff --git a/.agents/skills/arco-design-vue/SKILL.md b/.agents/skills/arco-design-vue/SKILL.md new file mode 100644 index 0000000..34bd7f3 --- /dev/null +++ b/.agents/skills/arco-design-vue/SKILL.md @@ -0,0 +1,171 @@ +--- +name: arco-design-vue +description: "Arco Design Vue UI 组件库参考,面向 Vue 3 和 `@arco-design/web-vue`。当用户要求构建 Vue 页面、创建 Vue UI、使用 Arco Vue 编写前端代码、开发 Vue 仪表盘或应用,或提到 Arco Design Vue、`@arco-design/web-vue`、`a-button`、`a-table`、`a-form`、`a-modal`、`a-select`、`Message`、任意 Arco Vue 组件名时使用。覆盖安装、全局注册、按需加载、主题、国际化、Vue 3 Composition API 约定、组件属性/事件/插槽、示例、表单、表格、弹窗、导航、数据录入、数据展示、反馈和响应式布局。" +--- + +# Arco Design Vue Skill + +`@arco-design/web-vue` 是 Arco Design 的 Vue 3 组件库实现。 + +## 关键约定 + +编写 Arco Design Vue 代码时始终遵守这些规则: + +- 使用 Vue 3。新代码优先使用 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|shape|头像的形状,有圆形(circle)和正方形(square)两种|`'circle' \| 'square'`|`'circle'`|| +|image-url|自定义头像图片地址,如果传入该属性,会默认渲染img标签|`string`|`-`|2.40.0| +|size|头像的尺寸大小,单位是 `px`。未填写时使用样式中的大小 `40px`|`number`|`-`|| +|auto-fix-font-size|是否自动根据头像尺寸调整字体大小|`boolean`|`true`|| +|trigger-type|可点击的头像交互类型|`'mask' \| 'button'`|`'button'`|| +|trigger-icon-style|交互图标的样式|`CSSProperties`|`-`|| +|object-fit|图片在容器内的的适应类型|`ObjectFit`|`-`|2.52.0| + +### `` 事件 + +|事件名|描述|参数| +|---|---|---| +|click|点击回调|ev: `MouseEvent`| +|error|图片加载错误|-| +|load|图片加载成功|-| + +### `` 插槽 + +|插槽名|描述|参数| +|---|:---:|---| +|trigger-icon|可点击的头像交互图标|-| + +### `` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|shape|头像的形状,有圆形(circle)和正方形(square)两种|`'circle' \| 'square'`|`'circle'`|| +|size|头像的尺寸大小,单位是 `px`|`number`|`-`|| +|auto-fix-font-size|是否自动根据头像尺寸调整字体大小|`boolean`|`true`|| +|max-count|头像组最多显示的头像数量,多余头像将以 `+x` 的形式展示。|`number`|`0`|| +|z-index-ascend|头像组内的头像 `z-index` 递增,默认是递减。|`boolean`|`false`|| +|max-style|多余头像样式。|`CSSProperties`|`-`|2.7.0| +|max-popover-trigger-props|多余头像气泡的 `TriggerProps`|`TriggerProps`|`-`|2.7.0| + +## 常用模式 + +- **大小和形状**:通过设置 `size` 字段,可以调节头像的大小,默认大小为 `40px`。设置 `shape` 字段,可以设置头像是圆形 (circle) 还是正方形 (square)。 +- **头像组**:使用 `Avatar.Group` 可以使用头像组功能,可通过 `size` 指定头像的大小。 +- **交互按钮**:可以通过 `trigger-icon` `trigger-type` 来定制交互按钮,类型有 `mask (遮罩)` 和 `button (按钮)` 两种。 +- **自动调整字体大小**:如果头像是文字的话,会自动调节字体大小,来适应头像框。 +- **自定义头像路径**:自定义头像图片路径 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|text|自定义提示内容|`string`|`-`| +|dot|显示为小红点|`boolean`|`false`| +|dot-style|徽标的样式|`object`|`-`| +|max-count|徽标最大显示数值,如果count超过这个数值会显示为maxCount|`number`|`99`| +|offset|设置徽标位置的偏移|`number[]`|`[]`| +|color|内置的一些颜色|`ColorType \| string`|`-`| +|status|徽标的状态类型|`'normal' \| 'processing' \| 'success' \| 'warning' \| 'danger'`|`-`| +|count|徽标显示的数字|`number`|`-`| + +## 常用模式 + +- **独立使用**:`default slot` 为空时,将会独立展示徽标。 +- **小红点**:设置 `dot`,即可只显示小红点而不显示数字。`count > 0` 时才显示。 +- **文本内容**:设置 `text`,可设置自定义提示内容。 +- **最大值**:设置 `max-count`,可以限制最大显示的徽标数值,超过将会加 `+` 后缀。`max-count` 默认为 `99`。 +- **状态点**:设置 `status`,可以得到不同的状态点。`normal - 正常` `processing - 进行中` `success - 成功` `warning - 提醒` `danger - 危险`。 +- **颜色**:我们提供多种预设色彩的徽标样式。如果预设值不能满足你的需求,`color` 字段也可以设置自定义色值。 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|model-value **(v-model)**|绑定值|`date`|`-`| +|default-value|默认值(非受控状态)|`date`|`-`| +|mode|模式|`'month' \| 'year'`|`-`| +|default-mode|默认模式|`'month' \| 'year'`|`'month'`| +|modes|显示的模式|`('month' \| 'year')[]`|`['month', 'year']`| + +### `` 事件 + +|事件名|描述|参数| +|---|---|---| +|change|选择的日期改变时触发|date: `Date`| +|panel-change|日期面板改变时触发|date: `Date`| + +### `` 插槽 + +|插槽名|描述|参数|版本| +|---|:---:|---|:---| +|header|自定义头部内容|year: `number`
month: `number`|2.53.0| +|default|自定义单元格内容|year: `number`
month: `number`
date: `number`|2.53.0| + +## 常用模式 + +- **基础使用**:直接使用全局 `a-` 前缀组件,按需绑定属性、事件和插槽。 +- **受控状态**:涉及值或显隐时优先使用 `v-model` 或命名 `v-model:*`。 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|current **(v-model)**|当前展示索引|`number`|`-`| +|default-current|当前展示索引|`number`|`1`| +|auto-play|是否自动循环展示,或者传入 `{ interval: 自动切换的时间间隔(默认: 3000), hoverToPause: 鼠标悬浮时是否暂停自动切换(默认: true) }` 进行高级配置|`boolean \| CarouselAutoPlayConfig`|`false`| +|move-speed|幻灯片移动速率(ms)|`number`|`500`| +|animation-name|切换动画|`'slide' \| 'fade' \| 'card'`|`'slide'`| +|trigger|幻灯片切换触发方式, click/hover 指示器|`'click' \| 'hover'`|`'click'`| +|direction|幻灯片移动方向|`'horizontal' \| 'vertical'`|`'horizontal'`| +|show-arrow|切换箭头显示时机|`'always' \| 'hover' \| 'never'`|`'always'`| +|arrow-class|切换箭头样式|`string`|`''`| +|indicator-type|指示器类型,可为小方块和小圆点或不显示|`'line' \| 'dot' \| 'slider' \| 'never'`|`'dot'`| +|indicator-position|指示器位置|`'bottom' \| 'top' \| 'left' \| 'right' \| 'outer'`|`'bottom'`| +|indicator-class|指示器的样式|`string`|`''`| + +> 仅列出常用项,低频属性按需查阅官方 API。 + +### `` 事件 + +|事件名|描述|参数| +|---|---|---| +|change|幻灯片发生切换时的回调函数|index: `number`
prevIndex: `number`
isManual: `boolean`| + +## 常用模式 + +- **自动切换**:可以通过 `autoPlay` 设置是否自动切换。可设置 `moveSpeed`, `timingFunc` 实现不同切换幻灯片效果。 +- **指示器**:可以指定指示器类型:`dot` | `line` | `slider` 和位置 `left` | `right` | `top` | `bottom` | `outer`。 +- **切换方向**:默认情况下,`direction` 为 `horizontal`。通过设置 `direction` 为 `vertical` 来使用垂直方向切换。 +- **卡片化**:当页面宽度方向空间空余,但高度方向空间多余时,可指定 `animation` 为 `card` 使用卡片化风格。 +- **渐隐切换**:指定 `animation` 为 `fade` 使用渐隐切换效果。 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` + +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|author|作者名|`string`|`-`| +|avatar|头像|`string`|`-`| +|content|评论内容|`string`|`-`| +|datetime|时间描述|`string`|`-`| +|align|靠左/靠右 展示 datetime 和 actions|`'left' \| 'right' \| { datetime?: "left" \| "right"; actions?: "left" \| "right" }`|`'left'`| + +### `` 插槽 + +|插槽名|描述|参数| +|---|:---:|---| +|avatar|头像|-| +|author|作者|-| +|datetime|时间描述|-| +|content|评论内容|-| +|actions|操作列表|-| + +## 常用模式 + +- **对齐**:通过 `align` 属性可以设置 `datetime` 和 `actions` 的对齐方式. +- **嵌套评论**:评论可以嵌套使用 +- **回复框**:评论框配合回复框使用 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|data|描述列表的数据|`DescData[]`|`[]`|| +|column|每行放置的数据个数。2.20.0 版本支持响应式配置,配置可参考 Grid|`number \| ResponsiveValue`|`3`|| +|title|描述列表的标题|`string`|`-`|| +|layout|描述列表的排列方式|`'horizontal' \| 'vertical' \| 'inline-horizontal' \| 'inline-vertical'`|`'horizontal'`|| +|align|文字的对齐位置|`TextAlign \| { label?: TextAlign; value?: TextAlign }`|`'left'`|| +|size|描述列表的大小|`'mini' \| 'small' \| 'medium' \| 'large'`|`-`|| +|bordered|是否显示边框|`boolean`|`false`|| +|label-style|数据标签的样式|`CSSProperties`|`-`|| +|value-style|数据内容的样式|`CSSProperties`|`-`|| +|table-layout|描述中表格样式的 `layout-fixed`,当设置成 `fixed` 时,宽度会均分。|`'auto' \| 'fixed'`|`'auto'`|2.38.0| + +### `` 插槽 + +|插槽名|描述|参数| +|---|:---:|---| +|value|数据内容|value: `string`
index: `number`
data: `DescData`| +|label|数据标签|label: `string`
index: `number`
data: `DescData`| +|title|标题|-| + +### `` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|span|所占列数|`number`|`1`|2.18.0| +|label|标签|`string`|`-`|2.18.0| + +### `` 插槽 + +|插槽名|描述|参数|版本| +|---|:---:|---|:---| +|label|标签|-|2.18.0| + +### DescData + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|label|标签|`string \| RenderFunction`|`-`| +|value|数据|`string \| RenderFunction`|`-`| +|span|所占列数|`number`|`1`| + +## 常用模式 + +- **单列样式**:单列的描述列表样式。 +- **标签文本对齐**:标签文本可以设置左对齐右对齐,也可以设置垂直的排列方式。 +- **带边框样式**:带边框和背景颜色的列表。 +- **布局模式**:有水平排列、垂直排列、行内水平排列、行内垂直排列四种布局模式。 +- **布局示例**:`span` 所占列数大于 `column` 可放置的数据个数时,`span` 会被设置为 `column` 的值,当行剩余列数不够放置下一列时将自动换行,每行末尾列会自动填充剩余量。 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|min|最少展示的元素个数|`number`|`0`| +|margin|项目间隔|`number`|`8`| +|from|折叠方向|`'start' \| 'end'`|`'end'`| + +### `` 事件 + +|事件名|描述|参数| +|---|---|---| +|change|溢出数量改变时触发|value: `number`| + +### `` 插槽 + +|插槽名|描述|参数| +|---|:---:|---| +|overflow|折叠元素|number: `number`| + +## 常用模式 + +- **基本使用**:折叠列表的基本使用方法。 +- **折叠方向**:通过 `from` 属性可以设置折叠的方向。 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|columns|表格的列描述信息|`TableColumnData[]`|`[]`|| +|data|表格的数据|`TableData[]`|`[]`|| +|bordered|是否显示边框|`boolean \| TableBorder`|`true`|| +|hoverable|是否显示选中效果|`boolean`|`true`|| +|stripe|是否开启斑马纹效果|`boolean`|`false`|| +|size|表格的大小|`'mini' \| 'small' \| 'medium' \| 'large'`|`'large'`|| +|table-layout-fixed|表格的 table-layout 属性设置为 fixed,设置为 fixed 后,表格的宽度不会被内容撑开超出 100%。|`boolean`|`false`|| +|loading|是否为加载中状态|`boolean\|object`|`false`|| +|row-selection|表格的行选择器配置|`TableRowSelection`|`-`|| +|expandable|表格的展开行配置|`TableExpandable`|`-`|| +|scroll|表格的滚动属性配置。`2.13.0` 版本增加字符型值的支持。`2.20.0` 版本增加 `minWidth`,`maxHeight` 的支持。|`{ x?: number \| string; y?: number \| string; minWidth?: number \| string; maxHeight?: number \| string;}`|`-`|| +|pagination|分页的属性配置|`boolean \| PaginationProps`|`true`|| + +> 仅列出常用项,低频属性按需查阅官方 API。 + +### `
` 事件 + +|事件名|描述|参数|版本| +|---|---|---|:---| +|expand|点击展开行时触发|rowKey: `string \| number`
record: `TableData`|| +|expanded-change|已展开的数据行发生改变时触发|rowKeys: `(string \| number)[]`|| +|select|点击行选择器时触发|rowKeys: `string \| number[]`
rowKey: `string \| number`
record: `TableData`|| +|select-all|点击全选选择器时触发|checked: `boolean`|| +|selection-change|已选择的数据行发生改变时触发|rowKeys: `(string \| number)[]`|| +|sorter-change|排序规则发生改变时触发|dataIndex: `string`
direction: `string`|| +|filter-change|过滤选项发生改变时触发|dataIndex: `string`
filteredValues: `string[]`|| +|page-change|表格分页发生改变时触发|page: `number`|| +|page-size-change|表格每页数据数量发生改变时触发|pageSize: `number`|| +|change|表格数据发生变化时触发|data: `TableData[]`
extra: `TableChangeExtra`
currentData: `TableData[]`|2.40.0 增加 currentData| +|cell-mouse-enter|单元格 hover 进入时触发|record: `TableData`
column: `TableColumnData`
ev: `Event`|| +|cell-mouse-leave|单元格 hover 退出时触发|record: `TableData`
column: `TableColumnData`
ev: `Event`|| + +> 仅列出常用项,低频属性按需查阅官方 API。 + +### `
` 方法 + +|方法名|描述|参数|返回值|版本| +|---|---|---|---|:---| +|selectAll|设置全选状态|checked: ` boolean `|-|2.22.0| +|select|设置行选择器状态|rowKey: ` string \| number \| (string \| number)[] `
checked: ` boolean `|-|2.31.0| +|expandAll|设置全部展开状态|checked: ` boolean `|-|2.31.0| +|expand|设置展开状态|rowKey: ` string \| number \| (string \| number)[] `
checked: ` boolean `|-|2.31.0| +|resetFilters|重置列的筛选器|dataIndex: ` string \| string[] `|-|2.31.0| +|clearFilters|清空列的筛选器|dataIndex: ` string \| string[] `|-|2.31.0| +|resetSorters|重置列的排序|-|-|2.31.0| +|clearSorters|清空列的排序|-|-|2.31.0| + +### `
` 插槽 + +|插槽名|描述|参数|版本| +|---|:---:|---|:---| +|th|自定义 th 元素|column: `TableColumnData`|2.26.0| +|thead|自定义 thead 元素|-|2.26.0| +|empty|空白展示|-|| +|summary-cell|总结行|column: `TableColumnData`
record: `TableData`
rowIndex: `number`|2.23.0| +|pagination-right|分页器右侧内容|-|2.18.0| +|pagination-left|分页器左侧内容|-|2.18.0| +|td|自定义 td 元素|column: `TableColumnData`
record: `TableData`
rowIndex: `number`|2.16.0| +|tr|自定义 tr 元素|record: `TableData`
rowIndex: `number`|2.16.0| +|tbody|自定义 tbody 元素|-|2.16.0| +|drag-handle-icon|拖拽锚点图标|-|2.16.0| +|footer|表格底部|-|| +|expand-row|展开行内容|record: `TableData`|| + +> 仅列出常用项,低频属性按需查阅官方 API。 + +### `` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|data-index|列信息的标识,对应TableData中的数据|`string`|`-`|| +|title|列标题|`string`|`-`|| +|width|列宽度|`number`|`-`|| +|min-width|最小列宽|`number`|`-`|| +|align|对齐方向|`TableColumnData['align']`|`-`|| +|fixed|固定位置|`TableColumnData['fixed']`|`-`|| +|ellipsis|是否显示为省略|`boolean`|`false`|| +|sortable|排序相关选项|`TableSortable`|`-`|| +|filterable|过滤相关选项|`TableFilterable`|`-`|| +|cell-class|自定义单元格类名|`ClassName`|`-`|2.36.0| +|header-cell-class|自定义表头单元格类名|`ClassName`|`-`|2.36.0| +|body-cell-class|自定义内容单元格类名|`ClassName \| ((record: TableData) => ClassName)`|`-`|2.36.0| + +> 仅列出常用项,低频属性按需查阅官方 API。 + +### `` 插槽 + +|插槽名|描述|参数|版本| +|---|:---:|---|:---| +|filter-icon|筛选按钮图标|-|2.23.0| +|filter-content|自定义筛选弹出框内容|filterValue: `string[]`
setFilterValue: `(filterValue: string[]) => void`
handleFilterConfirm: `(event: Event) => void`
handleFilterReset: `(event: Event) => void`|2.23.0| +|title|标题|-|| +|cell|单元格|record: `TableData`
column: `TableColumnData`
rowIndex: `number`|| + +### 类型定义 + +```ts +type Filters = Record; + +type Sorter = { filed: string; direction: 'ascend' | 'descend' } | Record; +``` + +### TableData + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|key|数据行的key|`string`|`-`|| +|expand|扩展行内容|`string \| RenderFunction`|`-`|| +|children|子数据|`TableData[]`|`-`|| +|disabled|是否禁用行选择器|`boolean`|`false`|| +|isLeaf|是否是叶子节点|`boolean`|`false`|2.13.0| + +### TableSortable + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|sortDirections|支持的排序方向|`('ascend' \| 'descend')[]`|`-`| +|sorter|排序函数。设置为 `true` 可关闭内部排序。2.19.0 版本修改传出数据。|`(( a: TableData, b: TableData, extra: { dataIndex: string; direction: 'ascend' \| 'descend' } ) => number) \| boolean`|`-`| +|sortOrder|排序方向|`'ascend' \| 'descend' \| ''`|`-`| +|defaultSortOrder|默认排序方向(非受控模式)|`'ascend' \| 'descend' \| ''`|`-`| + +### TableFilterData + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|text|筛选数据选项的内容|`string \| RenderFunction`|`-`| +|value|筛选数据选项的值|`string`|`-`| + +### TableFilterable + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|filters|筛选数据|`TableFilterData[]`|`-`|| +|filter|筛选函数|`(filteredValue: string[], record: TableData) => boolean`|`-`|| +|multiple|是否支持多选|`boolean`|`false`|| +|filteredValue|筛选项|`string[]`|`-`|| +|defaultFilteredValue|默认筛选项|`string[]`|`-`|| +|renderContent|筛选框的内容|`(data: { filterValue: string[]; setFilterValue: (filterValue: string[]) => void; handleFilterConfirm: (event: Event) => void; handleFilterReset: (event: Event) => void; }) => VNodeChild`|`-`|| +|icon|筛选按钮的图标|`RenderFunction`|`-`|| +|triggerProps|筛选框的弹出框配置|`TriggerProps`|`-`|| +|alignLeft|筛选图标是否左对齐|`boolean`|`false`|2.13.0| + +### TableColumnData + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|dataIndex|列信息的标识,对应 `TableData` 中的数据|`string`|`-`|| +|title|列标题|`string \| RenderFunction`|`-`|| +|width|列宽度|`number`|`-`|| +|minWidth|最小列宽|`number`|`-`|| +|align|对齐方向|`'left' \| 'center' \| 'right'`|`-`|| +|fixed|固定位置|`'left' \| 'right'`|`-`|| +|ellipsis|是否显示省略号|`boolean`|`false`|| +|tooltip|是否在显示省略号时显示文本提示。可填入 tooltip 组件属性|`boolean \| Record`|`-`|2.26.0| +|sortable|排序相关选项|`TableSortable`|`-`|| +|filterable|过滤相关选项|`TableFilterable`|`-`|| +|children|表头子数据,用于表头分组|`TableColumnData[]`|`-`|| +|cellClass|自定义单元格类名|`ClassName`|`-`|2.36.0| + +> 仅列出常用项,低频属性按需查阅官方 API。 + +### TableBorder + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|wrapper|是否展示外边框|`boolean`|`false`| +|cell|是否展示单元格边框(表头+主体)|`boolean`|`false`| +|headerCell|是否展示表头单元格边框|`boolean`|`false`| +|bodyCell|是否展示主体单元格边框|`boolean`|`false`| + +### TableRowSelection + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|type|行选择器的类型|`'checkbox' \| 'radio'`|`-`|| +|selectedRowKeys|已选择的行(受控模式)|`BaseType[]`|`-`|| +|defaultSelectedRowKeys|默认已选择的行(非受控模式)|`BaseType[]`|`-`|| +|showCheckedAll|是否显示全选选择器|`boolean`|`false`|| +|title|列标题|`string`|`-`|| +|width|列宽度|`number`|`-`|| +|fixed|是否固定|`boolean`|`false`|| +|checkStrictly|是否开启严格选择模式|`boolean`|`true`|2.29.0| +|onlyCurrent|是否仅展示当前页的 keys(切换分页时清空 keys)|`boolean`|`false`|2.32.0| + +### TableExpandable + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|expandedRowKeys|显示的展开行(受控模式)|`BaseType[]`|`-`| +|defaultExpandedRowKeys|默认显示的展开行(非受控模式)|`BaseType[]`|`-`| +|defaultExpandAllRows|是否默认展开所有的行|`boolean`|`false`| +|expandedRowRender|自定义展开行内容|`(record: TableData) => VNodeChild`|`-`| +|icon|展开图标|`(expanded: boolean, record: TableData) => VNodeChild`|`-`| +|title|列标题|`string`|`-`| +|width|列宽度|`number`|`-`| +|fixed|是否固定|`boolean`|`false`| + +### TableDraggable + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|type|拖拽类型|`'row' \| 'handle'`|`-`| +|title|列标题|`string`|`-`| +|width|列宽度|`number`|`-`| +|fixed|是否固定|`boolean`|`false`| + +### TableChangeExtra + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|type|触发类型|`'pagination' \| 'sorter' \| 'filter' \| 'drag'`|`-`| +|page|页码|`number`|`-`| +|pageSize|每页数据数|`number`|`-`| +|sorter|排序信息|`Sorter`|`-`| +|filters|筛选信息|`Filters`|`-`| +|dragTarget|拖拽信息|`TableData`|`-`| + +### VirtualListProps + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|height|可视区域高度|`number \| string`|`-`|| +|threshold|开启虚拟滚动的元素数量阈值,当数据数量小于阈值时不会开启虚拟滚动。|`number`|`-`|| +|isStaticItemHeight|(已废除)元素高度是否是固定的。2.34.1 版本废除,请使用 `fixedSize`|`boolean`|`false`|| +|fixedSize|元素高度是否是固定的。|`boolean`|`false`|2.34.1| +|estimatedSize|元素高度不固定时的预估高度。|`number`|`-`|2.34.1| +|buffer|视口边界外提前挂载的元素数量。|`number`|`10`|2.34.1| + +## 常用模式 + +- **行选择器**:通过设置 `row-selection` 开启行选择器。 +- **行选择器(单选框)**:通过设置 `rowSelection.type='radio'` 开启单选模式。 +- **展开行**:通过设置 `expandable` 开启展开行功能。可以在 `data` 中添加 `expand` 属性,设置展开行显示内容。 +- **文本省略和提示**:开启 `ellipsis` 属性可以显示省略号,如果同时开启 `tooltip` 会在显示省略号时使用文本提示。注意:开启 `tooltip` 后会修改 `table-cell` 中的 DOM 结构。 +- **树形数据展示**:树形数据展示的例子,`data` 里有 `children` 字段时会展示为树形表格。 +- **子树懒加载**:通过 `load-more` 属性可以开启子树懒加载功能。开启子树懒加载功能后,需要在无子树节点标注 `isLeaf: true`,没有标注且没有 `children` 属性的节点会认为需要子树懒加载处理。`load-more` 属性有提供 `done` 函数进行回调,可以在回调中传入懒加载的子树。 +- **表格属性**:这里罗列了一些表格的属性,你可以方便的打开或关闭一些属性,查看它的效果。 +- **排序和筛选**:通过设置 `columns` 中的 `sortable` 和 `filterable` 属性,可以配置排序和筛选功能。通过 `filter-icon-align-left` 属性可以让筛选按钮左对齐。 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|reverse|是否倒序|`boolean`|`false`| +|direction|时间轴方向|`'horizontal' \| 'vertical'`|`'vertical'`| +|mode|时间轴的展示类型:时间轴在左侧,时间轴在右侧, 交替出现。|`'left' \| 'right' \| 'top' \| 'bottom' \| 'alternate'`|`'left'`| +|pending|是否展示幽灵节点,设置为 true 时候只展示幽灵节点。传入字符串时,会作为节点内容展示。|`boolean\|string`|`-`| +|label-position|设置标签文本的位置|`'relative' \| 'same'`|`'same'`| + +### `` 插槽 + +|插槽名|描述|参数| +|---|:---:|---| +|dot|幽灵节点|-| + +### `` 属性 + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|dot-color|节点颜色|`string`|`-`| +|dot-type|节点类型:空心圆/实心圆|`'hollow' \| 'solid'`|`'solid'`| +|line-type|时间轴类型:实线/虚线/点状线|`'solid' \| 'dashed' \| 'dotted'`|`'solid'`| +|line-color|时间轴颜色|`string`|`-`| +|label|标签文本|`string`|`-`| +|position|Item 位置|`PositionType`|`-`| + +### `` 插槽 + +|插槽名|描述|参数|版本| +|---|:---:|---|:---| +|dot|自定义节点|-|| +|label|自定义标签|-|2.50.0| + +## 常用模式 + +- **自定义节点内容**:自定义节点内容 +- **自定义节点**:可以通过属性 `dotColor`, `dotType` 设置节点的颜色以及节点类型。同时可通过 `dot` 直接传入 DOM 自定义节点样式。优先级高于 `dotColor` 和 `dotType` +- **自定义轴线样式**:自定义轴线的示例。 +- **幽灵节点**:当任务状态正在发生,还在记录过程中,可用幽灵节点来表示当前的时间节点,通过`slot#pending-dot`定制其轴点。 +- **时间轴展示类型**:设置 `mode=alternate`时将会交替展示内容。同时可以通过设置 `TimelineItem` 的 `positon`属性控制时间轴节点的位置. +- **纵向时间轴**:竖直方向的时间轴。 +- **横向时间轴**:可以通过 `direction` 设置展示横向时间轴 +- **标签文本位置**:通过 `labelPosition` 可以设置标签文本的位置。 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|size|尺寸|`'mini' \| 'small' \| 'medium' \| 'large'`|`'medium'`|| +|block-node|节点是否占据一行|`boolean`|`false`|| +|default-expand-all|是否默认展开父节点|`boolean`|`true`|| +|multiple|是否支持多选|`boolean`|`false`|| +|checkable|是否在节点前添加复选框,从 `2.27.0` 开始支持函数格式|`boolean\| (( node: TreeNodeData, info: { level: number; isLeaf: boolean; } ) => boolean)`|`false`|| +|selectable|是否支持选择,从 `2.27.0` 开始支持函数格式|`boolean\| (( node: TreeNodeData, info: { level: number; isLeaf: boolean; } ) => boolean)`|`true`|| +|check-strictly|是否取消父子节点关联|`boolean`|`false`|| +|checked-strategy|定制回填方式
all: 返回所有选中的节点
parent: 父子节点都选中时只返回父节点
child: 只返回子节点|`'all' \| 'parent' \| 'child'`|`'all'`|| +|default-selected-keys|默认选中的树节点|`Array`|`-`|| +|selected-keys **(v-model)**|选中的树节点|`Array`|`-`|| +|default-checked-keys|默认选中复选框的树节点|`Array`|`-`|| +|checked-keys **(v-model)**|选中复选框的树节点|`Array`|`-`|| + +> 仅列出常用项,低频属性按需查阅官方 API。 + +### `` 事件 + +|事件名|描述|参数| +|---|---|---| +|select|点击树节点时触发|selectedKeys: `Array`
data: `{ selected?: boolean; selectedNodes: TreeNodeData[]; node?: TreeNodeData; e?: Event; }`| +|check|点击树节点复选框时触发。`halfCheckedKeys` 和 `halfCheckedNodes` 从 `2.19.0` 开始支持。|checkedKeys: `Array`
data: `{ checked?: boolean; checkedNodes: TreeNodeData[]; node?: TreeNodeData; e?: Event; halfCheckedKeys: (string \| number)[]; halfCheckedNodes: TreeNodeData[]; }`| +|expand|展开/关闭|expandKeys: `Array`
data: `{ expanded?: boolean; expandNodes: TreeNodeData[]; node?: TreeNodeData; e?: Event; }`| +|drag-start|节点开始拖拽|ev: `DragEvent`
node: `TreeNodeData`| +|drag-end|节点结束拖拽|ev: `DragEvent`
node: `TreeNodeData`| +|drag-over|节点被拖拽至可释放目标|ev: `DragEvent`
node: `TreeNodeData`| +|drag-leave|节点离开可释放目标|ev: `DragEvent`
node: `TreeNodeData`| +|drop|节点在可释放目标上释放|data: `{ e: DragEvent; dragNode: TreeNodeData; dropNode: TreeNodeData; dropPosition: number; }`| + +### `` 方法 + +|方法名|描述|参数|返回值|版本| +|---|---|---|---|:---| +|scrollIntoView|虚拟列表滚动某个元素|options: `{ index?: number; key?: number \| string; align: 'auto' \| 'top' \| 'bottom'}`|-|| +|getSelectedNodes|获取选中的节点|-|TreeNodeData[]|2.19.0| +|getCheckedNodes|获取选中复选框的节点。支持传入 `checkedStrategy`,没有传则取组件的配置。|options: ` checkedStrategy?: 'all' \| 'parent' \| 'child'; includeHalfChecked?: boolean; `|TreeNodeData[]|2.19.0| +|getHalfCheckedNodes|获取复选框半选的节点|-|TreeNodeData[]|2.19.0| +|getExpandedNodes|获取展开的节点|-|TreeNodeData[]|2.19.0| +|checkAll|设置全部节点的复选框状态|checked: ` boolean `|-|2.20.0| +|checkNode|设置指定节点的复选框状态|key: ` TreeNodeKey \| TreeNodeKey[] `
checked: ` boolean `
onlyCheckLeaf: ` boolean `|-|2.20.0,onlyCheckLeaf from 2.21.0| +|selectAll|设置全部节点的选中状态|selected: ` boolean `|-|2.20.0| +|selectNode|设置指定节点的选中状态|key: ` TreeNodeKey \| TreeNodeKey[] `
selected: ` boolean `|-|2.20.0| +|expandAll|设置全部节点的展开状态|expanded: ` boolean `|-|2.20.0| +|expandNode|设置指定节点的展开状态|key: ` TreeNodeKey \| TreeNodeKey[] `
expanded: ` boolean `|-|2.20.0| + +### `` 插槽 + +|插槽名|描述|参数|版本| +|---|:---:|---|:---| +|title|标题|title: `string`|| +|extra|渲染额外的节点内容|-|| +|drag-icon|定制 drag 图标|node: `TreeNodeData`|| +|loading-icon|定制 loading 图标|-|| +|switcher-icon|定制 switcher 图标|-|| +|icon|定制节点图标|node: `TreeNodeData`|2.18.0| + +### TreeNodeData + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|key|唯一标示|`string \| number`|`-`| +|title|该节点显示的标题|`string`|`-`| +|selectable|是否允许选中|`boolean`|`false`| +|disabled|是否禁用节点|`boolean`|`false`| +|disableCheckbox|是否禁用复选框|`boolean`|`false`| +|checkable|是否显示多选框|`boolean`|`false`| +|draggable|是否可以拖拽|`boolean`|`false`| +|isLeaf|是否是叶子节点。动态加载时有效|`boolean`|`false`| +|icon|节点的图标|`() => VNode`|`-`| +|switcherIcon|定制 switcher 图标,优先级大于 tree|`() => VNode`|`-`| +|loadingIcon|定制 loading 图标,优先级大于 tree|`() => VNode`|`-`| +|dragIcon|定制 drag 图标,优先级大于 tree|`() => VNode`|`-`| + +> 仅列出常用项,低频属性按需查阅官方 API。 + +### TreeFieldNames + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|key|指定 key 在 TreeNodeData 中的字段名|`string`|`key`| +|title|指定 title 在 TreeNodeData 中的字段名|`string`|`title`| +|disabled|指定 disabled 在 TreeNodeData 中的字段名|`string`|`disabled`| +|children|指定 children 在 TreeNodeData 中的字段名|`string`|`children`| +|isLeaf|指定 isLeaf 在 TreeNodeData 中的字段名|`string`|`isLeaf`| +|disableCheckbox|指定 disableCheckbox 在 TreeNodeData 中的字段名|`string`|`disableCheckbox`| +|checkable|指定 checkable 在 TreeNodeData 中的字段名|`string`|`checkable`| +|icon|指定 icon 在 TreeNodeData 中的字段名|`string`|`checkable`| + +### VirtualListProps + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|height|可视区域高度|`number \| string`|`-`|| +|threshold|开启虚拟滚动的元素数量阈值,当数据数量小于阈值时不会开启虚拟滚动。|`number`|`-`|| +|isStaticItemHeight|(已废除)元素高度是否是固定的。2.34.1 版本废除,请使用 `fixedSize`|`boolean`|`false`|| +|fixedSize|元素高度是否是固定的。|`boolean`|`false`|2.34.1| +|estimatedSize|元素高度不固定时的预估高度。|`number`|`-`|2.34.1| +|buffer|视口边界外提前挂载的元素数量。|`number`|`10`|2.34.1| + +## 常用模式 + +- **节点占一行**:节点占据一整行。 +- **多选**:`Tree` 设置 `multiple` 属性为`true`,可以启用多选。 +- **带复选框的树**:为 `Tree` 添加 `checkable` 属性即可使树具有复选框功能,可以用 `defaultCheckedKeys` 指定复选框默认选中的节点。 +- **双向绑定**:`selectedKeys` 、 `checkedKeys` 、 `expandedKeys` 属性均可受控,不仅支持 `v-model` ,还可以在对应的 `select` / `check` / `expand` 事件中自行控制如何更新属性值。 +- **动态加载**:动态加载节点。 +- **拖拽**:可拖拽的树节点。 +- **设置回填方式**:为 `Tree` 添加 `checkedStrategy` 可以设置选中时的回填方式 +- **显示连接线**:为 `Tree` 添加 `showLine` 属性即可使树具有连接线 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|model-value **(v-model)**|绑定值|`string`|`-`|| +|default-value|默认值(非受控模式)|`string`|`''`|| +|disabled|是否禁用|`boolean`|`false`|| +|data|用于自动提示的数据|`(string \| number \| SelectOptionData \| SelectOptionGroup)[]`|`[]`|| +|popup-container|弹出框的挂载容器|`string \| HTMLElement \| null \| undefined`|`-`|| +|strict|是否为严格校验模式|`boolean`|`false`|| +|filter-option|自定义选项过滤方法|`FilterOption`|`true`|| +|trigger-props|trigger 组件属性|`TriggerProps`|`-`|2.14.0| +|allow-clear|是否允许清空输入框|`boolean`|`false`|2.23.0| +|virtual-list-props|传递虚拟列表属性,传入此参数以开启虚拟滚动 [VirtualListProps](#VirtualListProps)|`VirtualListProps`|`-`|2.50.0| + +### `` 事件 + +|事件名|描述|参数|版本| +|---|---|---|:---| +|change|绑定值发生改变时触发|value: `string`|| +|search|用户搜索时触发|value: `string`|| +|select|选择选项时触发|value: `string`|| +|clear|用户点击清除按钮时触发|ev: `Event`|2.23.0| +|dropdown-scroll|下拉菜单发生滚动时触发|ev: `Event`|2.52.0| +|dropdown-reach-bottom|下拉菜单滚动到底部时触发|ev: `Event`|2.52.0| + +### `` 方法 + +|方法名|描述|参数|返回值|版本| +|---|---|---|---|:---| +|focus|使输入框获取焦点|-|-|2.40.0| +|blur|使输入框失去焦点|-|-|2.40.0| + +### `` 插槽 + +|插槽名|描述|参数|版本| +|---|:---:|---|:---| +|option|选项内容|data: `OptionInfo`|2.13.0| +|footer|弹出框的页脚|-|| + +## 常用模式 + +- **区分大小写**:使用 `strict` 属性来指明在匹配时严格区分大小写。 +- **弹出框的页脚**:自定义弹出框的页脚 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|path-mode|绑定值是否为路径|`boolean`|`false`|| +|multiple|是否为多选状态(多选模式默认开启搜索)|`boolean`|`false`|| +|model-value **(v-model)**|绑定值|`string\| number\| Record\| ( \| string \| number \| Record \| (string \| number \| Record)[] )[]\| undefined`|`-`|| +|default-value|默认值(非受控状态)|`string\| number\| Record\| ( \| string \| number \| Record \| (string \| number \| Record)[] )[]\| undefined`|`'' \| undefined \| []`|| +|options|级联选择器的选项|`CascaderOption[]`|`[]`|| +|disabled|是否禁用|`boolean`|`false`|| +|error|是否为错误状态|`boolean`|`false`|| +|size|选择框的大小|`'mini' \| 'small' \| 'medium' \| 'large'`|`'medium'`|| +|allow-search|是否允许搜索|`boolean`|`false (single) \| true (multiple)`|| +|allow-clear|是否允许清除|`boolean`|`false`|| +|input-value **(v-model)**|输入框的值|`string`|`-`|| +|default-input-value|输入框的默认值(非受控状态)|`string`|`''`|| + +> 仅列出常用项,低频属性按需查阅官方 API。 + +### `` 事件 + +|事件名|描述|参数| +|---|---|---| +|change|选中值改变时触发|value: `string \| number \| (string \| number \| (string \| number)[])[] \| undefined`| +|input-value-change|输入值改变时触发|value: `string`| +|clear|点击清除按钮时触发|-| +|search|用户搜索时触发|value: `string`| +|popup-visible-change|下拉框的显示状态改变时触发|visible: `boolean`| +|focus|获得焦点时触发|ev: `FocusEvent`| +|blur|失去焦点时触发|ev: `FocusEvent`| + +### `` 插槽 + +|插槽名|描述|参数|版本| +|---|:---:|---|:---| +|label|选择框的显示内容|data: `CascaderOption`|2.18.0| +|prefix|前缀元素|-|2.23.0| +|arrow-icon|选择框的箭头图标|-|2.16.0| +|loading-icon|选择框的加载中图标|-|2.16.0| +|search-icon|选择框的搜索图标|-|2.16.0| +|empty|选项为空时的显示内容|-|2.23.0| +|option|选项内容|data: `CascaderOption`|2.18.0| + +### `` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|path-mode|绑定值是否为路径|`boolean`|`false`|| +|multiple|是否为多选状态(多选模式默认开启搜索)|`boolean`|`false`|| +|model-value **(v-model)**|绑定值|`string\| number\| Record\| ( \| string \| number \| Record \| (string \| number \| Record)[] )[]\| undefined`|`-`|| +|default-value|默认值(非受控状态)|`string\| number\| Record\| ( \| string \| number \| Record \| (string \| number \| Record)[] )[]\| undefined`|`'' \| undefined \| []`|| +|options|级联选择器的选项|`CascaderOption[]`|`[]`|| +|expand-trigger|展开下一级的触发方式|`string`|`'click'`|| +|check-strictly|是否开启严格选择模式|`boolean`|`false`|| +|load-more|数据懒加载函数,传入时开启懒加载功能|`( option: CascaderOption, done: (children?: CascaderOption[]) => void) => void`|`-`|2.13.0| +|field-names|自定义 `CascaderOption` 中的字段|`CascaderFieldNames`|`-`|2.22.0| +|value-key|用于确定选项键值的属性名|`string`|`'value'`|2.29.0| +|expand-child|是否展开子菜单|`boolean`|`false`|2.29.0| + +### `` 事件 + +|事件名|描述|参数| +|---|---|---| +|change|选中值改变时触发|value: `string \| number \| (string \| number \| (string \| number)[])[] \| undefined`| + +### `` 插槽 + +|插槽名|描述|参数|版本| +|---|:---:|---|:---| +|empty|选项为空时的显示内容|-|2.23.0| + +### CascaderOption + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|value|选项值,2.29.0 版本支持对象|`string \| number \| Record`|`-`|| +|label|选项文本|`string`|`-`|| +|render|自定义渲染|`RenderFunction`|`-`|| +|disabled|是否禁用|`boolean`|`false`|| +|tagProps|展示的标签属性|`TagProps`|`-`|2.8.0| +|children|下一级选项|`CascaderOption[]`|`-`|| +|isLeaf|是否是叶子节点|`boolean`|`false`|| + +## 常用模式 + +- **基本使用**:级联选择器的基本用法。 +- **允许清除**:允许清除。 +- **禁用选项**:指定 `option` 的 `disabled` 为 `true`,可以禁用该选项。 +- **自定义输入框的展示值**:利用 `formatLabel` 对显示的内容进行自定义处理。 +- **多选模式**:通过设置 `multiple` 开启多选模式。 +- **严格选择模式**:设置属性 `check-strictly`,开启严格选择模式,点击任何结点都可以选择。多选时将会解除父子节点的关联。 +- **加载中**:选择框和下拉菜单显示加载中状态。 +- **子选项懒加载**:通过 `load-more` 属性可以开启数据懒加载功能。开启数据懒加载功能后,需要在叶子节点标注 `isLeaf: true`,没有标注且没有 `children` 属性的节点会认为需要懒加载处理。`load-more` 属性有提供 `done` 函数进行回调,可以在回调中传入懒加载的子数据。 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|model-value **(v-model)**|绑定值|`string`|`-`| +|default-value|默认值(非受控状态)|`string`|`-`| +|format|颜色值的格式|`'hex' \| 'rgb'`|`-`| +|size|尺寸|`'mini' \| 'small' \| 'medium' \| 'large'`|`'medium'`| +|show-text|显示颜色值|`boolean`|`false`| +|show-history|显示历史颜色|`boolean`|`false`| +|show-preset|显示预设颜色|`boolean`|`false`| +|disabled|禁用|`boolean`|`false`| +|disabled-alpha|禁用透明通道|`boolean`|`false`| +|hide-trigger|没有触发元素,只显示颜色面板|`boolean`|`false`| +|trigger-props|接受所有 [Trigger](../other/trigger.md) 组件的Props|`Partial`|`-`| +|history-colors|历史颜色的颜色数组|`string[]`|`-`| + +> 仅列出常用项,低频属性按需查阅官方 API。 + +### `` 事件 + +|事件名|描述|参数| +|---|---|---| +|change|颜色值改变时触发|value: `string`| +|popup-visible-change|颜色面板展开和收起时触发|visible: `boolean`
value: `string`| + +## 常用模式 + +- **基本使用**:基本用法 +- **尺寸**:颜色选择器定义了四种尺寸(`mini`,`small`, `medium`, `large`),分别为 24px,28px,32px,36px。 +- **禁用**:设置 `disabled` 禁用选择器。 +- **颜色格式**:通过 `format` 设置颜色值的格式,支持 `hex` 和 `rgb`。 +- **预设颜色和历史颜色**:通过 `showPreset` 和 `showHistory` 开启预设颜色和历史颜色区域。历史颜色需要用户自行控制展示内容。 +- **触发器**:可以通过 `trigger-props` 设置触发器的所有属性。 +- **自定义触发元素**:自定义触发元素。 +- **只使用面板**:只用颜色选择面板。 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `
` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|model **(必填)**|表单数据对象|`object`|`-`|| +|layout|表单的布局方式,包括水平、垂直、多列|`'horizontal' \| 'vertical' \| 'inline'`|`'horizontal'`|| +|size|表单控件的尺寸|`'mini' \| 'small' \| 'medium' \| 'large'`|`'medium'`|| +|label-col-props|标签元素布局选项。参数同 `
` 组件一致|`object`|` span: 5, offset: 0 `|| +|wrapper-col-props|表单控件布局选项。参数同 `` 组件一致|`object`|` span: 19, offset: 0 `|| +|label-align|标签的对齐方向|`'left' \| 'right'`|`'right'`|| +|disabled|是否禁用表单|`boolean`|`-`|| +|rules|表单项校验规则|`Record`|`-`|| +|auto-label-width|是否开启自动标签宽度,仅在 `layout="horizontal"` 下生效。|`boolean`|`false`|2.13.0| +|id|表单 `id` 属性和表单控件 `id` 前缀|`string`|`-`|| +|scroll-to-first-error|验证失败后滚动到第一个错误字段|`boolean`|`false`|2.51.0| + +### `` 事件 + +|事件名|描述|参数| +|---|---|---| +|submit|表单提交时触发|data: `{values: Record; errors: Record \| undefined}`
ev: `Event`| +|submit-success|验证成功时触发|values: `Record`
ev: `Event`| +|submit-failed|验证失败时触发|data: `{values: Record; errors: Record}`
ev: `Event`| + +### `` 方法 + +|方法名|描述|参数|返回值|版本| +|---|---|---|---|:---| +|validate|校验全部表单数据|callback: `(errors: undefined \| Record) => void`|Promise>|| +|validateField|校验部分表单数据|field: `string \| string[]`
callback: `(errors: undefined \| Record) => void`|Promise>|| +|resetFields|重置表单数据|field: `string \| string[]`|-|| +|clearValidate|清除校验状态|field: `string \| string[]`|-|| +|setFields|设置表单项的值和状态|data: `Record`|-|| +|scrollToField|滚动到指定表单项|field: `string`|-|2.51.0| + +### `` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|field|表单元素在数据对象中的path(数据项必填)|`string`|`''`|| +|label|标签的文本|`string`|`-`|| +|tooltip|提示内容|`string`|`-`|2.41.0| +|show-colon|是否显示冒号|`boolean`|`false`|| +|no-style|是否去除样式|`boolean`|`false`|| +|disabled|是否禁用|`boolean`|`-`|| +|help|帮助文案|`string`|`-`|| +|extra|额外显示的文案|`string`|`-`|| +|required|是否必须填写|`boolean`|`false`|| +|asterisk-position|可选择将星号置于 label 前/后|`'start' \| 'end'`|`'start'`|2.41.0| +|rules|表单项校验规则(优先级高于 form 的 rules)|`FieldRule \| FieldRule[]`|`-`|| +|validate-status|校验状态|`'success' \| 'warning' \| 'error' \| 'validating'`|`-`|| + +> 仅列出常用项,低频属性按需查阅官方 API。 + +### `` 插槽 + +|插槽名|描述|参数| +|---|:---:|---| +|label|标签|-| +|help|帮助信息|-| +|extra|额外内容|-| + +### 类型定义 + +### FieldRule + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|type|校验的值的类型,默认为 `'string'`|`'string' \| 'number' \| 'boolean' \| 'array' \| 'object' \| 'email' \| 'url' \| 'ip'`|`-`| +|required|是否必填|`boolean`|`false`| +|message|校验失败时展示的信息|`string`|`-`| +|length|校验长度(string, array)|`number`|`-`| +|maxLength|最大长度(string)|`number`|`-`| +|minLength|最小长度(string)|`number`|`-`| +|match|匹配校验(string)|`RegExp`|`-`| +|uppercase|大写(string)|`boolean`|`false`| +|lowercase|小写(string)|`boolean`|`false`| +|min|最小值(number)|`number`|`-`| +|max|最大值(number)|`number`|`-`| +|equal|校验数值(number)|`number`|`-`| + +> 仅列出常用项,低频属性按需查阅官方 API。 + +### FieldData + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|value|字段的值|`any`|`-`| +|status|字段的状态|`ValidateStatus`|`-`| +|message|字段的错误信息|`string`|`-`| + +### ValidatedError + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|label|标签的文本|`string`|`-`|2.18.0| +|field|字段名|`string`|`-`|| +|value|字段值|`any`|`-`|| +|type|字段类型|`string`|`-`|| +|isRequiredError|是否为 `required` 错误|`boolean`|`false`|| +|message|错误信息|`string`|`-`|| + +### FormItemEventHandler + +|参数名|描述|类型|默认值| +|---|---|---|:---:| +|onChange|onChange|`(ev?: Event) => void`|`-`| +|onInput|onInput|`(ev?: Event) => void`|`-`| +|onFocus|onFocus|`(ev?: Event) => void`|`-`| +|onBlur|onBlur|`(ev?: Event) => void`|`-`| + +### useFormItem + +```ts +const useFormItem = (data: { + size?: Ref; + disabled?: Ref; + error?: Ref; +}) => { + mergedSize:Ref; + mergedDisabled:Ref; + mergedError:Ref; + feedback:Ref; + eventHandlers:Ref; +} +``` + +## 常用模式 + +- **表单布局**:表单支持三种布局方式: `horizontal` - 水平排列 **(默认)**, `vertical` - 垂直排列, `inline` - 行内排列。 +- **额外信息和帮助信息**:可以使用 `extra` 添加额外信息。如果需要在外部自定义校验信息,可以使用 `help` 属性或插槽。设置 `help` 时校验信息会被屏蔽。 +- **嵌套数据**:展示了多种表单项嵌套的方式。表单项组件默认会将表单项状态和事件绑定到第一子组件,如果想要使用表单项进行布局设置,请设置 `:merge-props="false"` 以关闭绑定,或者使用函数指定需要绑定的数据。 +- **栅格布局**:展示了使用栅格布局的方式。可以使用 `label-col-flex` 属性指定标签的具体宽度。 +- **自动标签宽度**:设置 `auto-label-width` 开启自动标签宽度。仅在 `layout="horizontal"` 布局下生效。_* 目前仅在首次加载后生效。_ +- **验证表单**:展示了表单校验的使用方法。 +- **验证表单2**:展示了表单校验`rules`使用在`a-form`上的使用方法,以及可以直接校验`email`、`ip`、`url` +- **自定义表单校验状态**:开启 `feedback` 可以让部分输入组件展示当前状态信息 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|model-value **(v-model)**|绑定值|`number`|`-`|| +|default-value|默认值(非受控模式)|`number`|`-`|| +|mode|模式(`embed`:按钮内嵌模式,`button`:左右按钮模式)|`'embed' \| 'button'`|`'embed'`|| +|precision|数字精度|`number`|`-`|| +|step|数字变化步长|`number`|`1`|| +|disabled|是否禁用|`boolean`|`false`|| +|error|是否为错误状态|`boolean`|`false`|| +|max|最大值|`number`|`Infinity`|| +|min|最小值|`number`|`-Infinity`|| +|formatter|定义输入框展示值|`func`|`-`|| +|parser|从 `formatter` 转换为数字,和 `formatter` 搭配使用|`func`|`-`|| +|placeholder|输入框提示文字|`string`|`-`|| + +> 仅列出常用项,低频属性按需查阅官方 API。 + +### `` 事件 + +|事件名|描述|参数|版本| +|---|---|---|:---| +|change|值发生改变时触发|value: ` number \| undefined `
ev: `Event`|| +|focus|输入框获取焦点时触发|ev: `FocusEvent`|| +|blur|输入框失去焦点时触发|ev: `FocusEvent`|| +|clear|用户点击清除按钮时触发|ev: `Event`|2.23.0| +|input|输入时触发|value: ` number \| undefined `
inputValue: `string`
ev: `Event`|2.27.0| +|keydown|按下键盘时触发|ev: `MouseEvent`|2.56.0| + +### `` 方法 + +|方法名|描述|参数|返回值| +|---|---|---|---| +|focus|使输入框获取焦点|-|-| +|blur|使输入框失去焦点|-|-| + +### `` 插槽 + +|插槽名|描述|参数| +|---|:---:|---| +|minus|数值减少图标|-| +|plus|数值增加图标|-| +|append|后置标签|-| +|prepend|前置标签|-| +|suffix|后缀|-| +|prefix|前缀|-| + +## 常用模式 + +- **按钮模式**:指定 `mode` 为 `button` 来使用带按钮的数字输入框。 +- **四种尺寸**:设置 `size` 可以使用四种尺寸(`mini`, `small`, `medium`, `large`)的数字输入框。高度分别对应`24px`、`28px`、`32px`、`36px`。 +- **精度和步长**:通过 `precision` 来设置数字精度。当 `precision` 小于 `step` 的小数位时,精度取 `step` 的小数个数。 +- **前缀与后缀**:通过指定 `prefix` 和 `suffix` 插槽来在输入框内添加前缀和后缀。 +- **自定义图标**:通过指定 `plus` 和 `minus` 插槽来修改数值增减操作的图标。 +- **格式化展示值**:通过 `formatter` 和 `parser` 配合使用可以定义输入框展示值。 +- **v-model 的触发事件**:数字输入框默认在 blur 或者按下 Enter 时会修改绑定的值,通过设置属性 model-event="input" 让组件在输入时修改绑定的值。注意:在此模式下,输入时的值会超出设置的 min/max,组件会在失焦时修正值的大小。 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 属性 + +|参数名|描述|类型|默认值|版本| +|---|---|---|:---:|:---| +|model-value **(v-model)**|绑定值|`string`|`-`|| +|default-value|默认值(非受控状态)|`string`|`''`|| +|data|用于自动补全的数据|`(string \| number \| SelectOptionData \| SelectOptionGroup)[]`|`[]`|| +|prefix|触发自动补全的关键字|`string \| string[]`|`'@'`|| +|split|选中项的前后分隔符|`string`|`' '`|| +|type|输入框或文本域|`'input' \| 'textarea'`|`'input'`|| +|disabled|是否禁用|`boolean`|`false`|| +|allow-clear|是否允许清空输入框|`boolean`|`false`|2.23.0| + +### `` 事件 + +|事件名|描述|参数|版本| +|---|---|---|:---| +|change|值发生改变时触发|value: `string`|| +|search|动态搜索时触发,2.47.0 版本增加 prefix 参数|value: `string`
prefix: `string`|| +|select|选择下拉选项时触发|value: `string \| number \| Record \| undefined`|| +|clear|用户点击清除按钮时触发|-|2.23.0| +|focus|文本框获取焦点时触发|ev: `FocusEvent`|2.42.0| +|blur|文本框失去焦点时触发|ev: `FocusEvent`|2.42.0| + +### `` 方法 + +|方法名|描述|参数|返回值|版本| +|---|---|---|---|:---| +|focus|使输入框获取焦点|-|-|2.24.0| +|blur|使输入框失去焦点|-|-|2.24.0| + +### `` 插槽 + +|插槽名|描述|参数|版本| +|---|:---:|---|:---| +|option|选项内容|data: `OptionInfo`|2.13.0| + +## 常用模式 + +- **基本使用**:用于在输入中提及某人或某事,常用于发布、聊天或评论功能。 +- **自定义触发字符**:指定 `prefix` 来自定义触发字符。默认为 `@`,可以自定义为任意字符。 + +## 最佳实践 + +- 新代码优先使用 Vue 3、Composition API 和 ` +``` + +## API + +### `` 事件 + +|事件名|描述|参数|版本| +|---|---|---|:---| +|change|值发生改变时触发|value: ` string \| number \| boolean \| Record \| (string \| number \| boolean \| Record)[] `|| +|input-value-change|输入框的值发生改变时触发|inputValue: `string`|| +|popup-visible-change|下拉框的显示状态改变时触发|visible: `boolean`|| +|clear|点击清除按钮时触发|-|| +|remove|点击标签的删除按钮时触发|removed: `string \| number \| boolean \| Record \| undefined`|| +|search|用户搜索时触发|inputValue: `string`|| +|dropdown-scroll|下拉菜单发生滚动时触发|-|| +|dropdown-reach-bottom|下拉菜单滚动到底部时触发|-|| +|exceed-limit|多选超出限制时触发|value: `string \| number \| boolean \| Record \| undefined`
ev: `Event`|2.18.0| + +### `