Castor3 UI AI API 合同

本文是 AI 和业务项目使用 Castor3 UI 时的公开 API 合同。源码发生 API 变化后，运行 npm run docs:api 重新生成。

AI 使用规则

1. 只使用本文列出的 props、事件、暴露成员和配置字段，不要猜测不存在的 API。
2. Vue 模板使用 kebab-case 属性；TypeScript 配置对象使用 camelCase 字段。
3. elementProps 仅用于透传底层 Element Plus 属性，不能替代 Castor3 UI 自身 props。
4. CommonCommand.command 会成为组件触发的同名事件；使用动态事件时必须同时实现监听器。
5. 表单和表格配置优先显式标注 FormField[]、QueryField[]、TableField[] 或 ReportField[]，让 TypeScript 阻止错误属性。
6. upload 的 model[dataField] 是 Element Plus 文件列表；avatarUploader 保留 Vue 2 的图片 URL 模型，上传成功后由业务回调更新 URL。
7. EditTable 会给行对象写入 operateType: add | edit | view；提交不接受该字段的接口前应由业务剔除。

导入

import Castor3UI, { CaCommonForm, type FormField } from "castor3-ui-element";
import "castor3-ui-element/style.css";

CaCommonForm

配置式表单，支持编辑/查看状态、字段校验、分组和命令。

Props

属性	模板写法	类型	默认值	说明
loading	loading	boolean	false	是否显示加载状态。
operateType	operate-type	OperateType	'add'	操作状态；view 会禁用字段并隐藏底部命令。
rowFieldsCount	row-fields-count	number	2	每行字段数量。
model	model	AnyRecord	{}	响应式数据模型；组件会直接读写该对象。
fields	fields	FormField[]	[]	字段配置数组，结构见本文“配置对象”章节。
commands	commands	CommonCommand[]	[]	命令按钮配置；command 同时是触发的事件名。
customCommands	custom-commands	CommonCommand[]	[]	额外业务命令按钮配置。
customComponents	custom-components	CustomComponentMap	{}	自定义组件映射，key 对应配置中的 componentKey。
elementProps	element-props	AnyRecord	{}	透传给底层 Element Plus 主组件的属性。
extendProps	extend-props	FormExtendProps	{}	表单内容区和底部区域的样式扩展。
emitRegister	emit-register	Record<string, any>	{}	传入可变对象后，组件会向其中注册可调用方法。

Events

事件	参数	说明
[command.command]	payload	点击底部、顶部或分组命令时触发对应同名事件。

Exposed

成员	说明
validate	执行当前表单或编辑行校验。
validateField	校验指定的一个或多个表单字段。
clearValidate	清除指定字段或全部字段的校验结果。
resetFields	重置指定字段或全部表单字段。
scrollToField	滚动到指定表单字段。
formRef	底层 Element Plus 表单实例。

emitRegister

注册成员	说明
validate	执行当前表单或编辑行校验。
validateField	校验指定的一个或多个表单字段。
clearValidate	清除指定字段或全部字段的校验结果。
resetFields	重置指定字段或全部表单字段。
scrollToField	滚动到指定表单字段。

CaCommonQuery

带动态字段选择器的后台查询栏。

Props

属性	模板写法	类型	默认值	说明
formId	form-id	string	-	表单 DOM id；未传时组件生成实例唯一 id。
loading	loading	boolean	false	是否显示加载状态。
maxFieldWidth	max-field-width	number	280	自动计算列数时单个字段的目标最大宽度。
commandsFloat	commands-float	'left' | 'right'	'right'	命令区水平对齐方向。
model	model	AnyRecord	{}	响应式数据模型；组件会直接读写该对象。
fields	fields	QueryField[]	[]	字段配置数组，结构见本文“配置对象”章节。
commands	commands	CommonCommand[]	[]	命令按钮配置；command 同时是触发的事件名。
dynamicFieldsPosition	dynamic-fields-position	'start' | 'end'	'end'	动态字段显示在静态字段之前或之后。
defaultCheckedKeys	default-checked-keys	Array<string | number>	[]	默认展示的动态字段 key。
downloadOpt	download-opt	DownloadConfig	{}	导出按钮及下拉命令配置。
elementProps	element-props	AnyRecord	{}	透传给底层 Element Plus 主组件的属性。
fixedRowCount	fixed-row-count	number	0	每行固定字段数；0 表示根据宽度自动计算。
customComponents	custom-components	CustomComponentMap	{}	自定义组件映射，key 对应配置中的 componentKey。
emitRegister	emit-register	Record<string, any>	{}	传入可变对象后，组件会向其中注册可调用方法。

Events

事件	参数	说明
[command.command]	model	点击命令、导出项或按 Enter 时触发对应同名事件。

Exposed

成员	说明
resetFields	重置指定字段或全部表单字段。
checkedKeys	当前启用的动态查询字段 key。
formRef	底层 Element Plus 表单实例。

emitRegister

注册成员	说明
resetFields	重置指定字段或全部表单字段。

CaCommonQueryPlus

带展开/收起和已生效条件标签的查询栏。

Props

属性	模板写法	类型	默认值	说明
formId	form-id	string	-	表单 DOM id；未传时组件生成实例唯一 id。
loading	loading	boolean	false	是否显示加载状态。
maxFieldWidth	max-field-width	number	280	自动计算列数时单个字段的目标最大宽度。
model	model	AnyRecord	{}	响应式数据模型；组件会直接读写该对象。
fields	fields	QueryField[]	[]	字段配置数组，结构见本文“配置对象”章节。
commands	commands	CommonCommand[]	[]	命令按钮配置；command 同时是触发的事件名。
downloadOpt	download-opt	DownloadConfig	{}	导出按钮及下拉命令配置。
elementProps	element-props	AnyRecord	{}	透传给底层 Element Plus 主组件的属性。
fixedRowCount	fixed-row-count	number	0	每行固定字段数；0 表示根据宽度自动计算。
queryTag	query-tag	string	''	折叠状态的 localStorage key；空字符串表示不持久化。
defaultCollapsed	default-collapsed	boolean	true	首次加载时是否收起动态字段。
showActiveTags	show-active-tags	boolean	true	是否展示已提交筛选条件标签。
searchText	search-text	string	'查询'	内置查询按钮文案。
resetText	reset-text	string	'重置'	内置重置按钮文案。
customComponents	custom-components	CustomComponentMap	{}	自定义组件映射，key 对应配置中的 componentKey。
emitRegister	emit-register	Record<string, any>	{}	传入可变对象后，组件会向其中注册可调用方法。

Events

事件	参数	说明
search	model	提交查询或删除单个条件标签后触发。
reset	-	清空全部查询条件后触发。
collapse-change	collapsed: boolean	展开/收起状态变化时触发。
[command.command]	model	点击额外命令或导出项时触发对应同名事件。

Exposed

成员	说明
search	提交查询并刷新已生效条件快照。
reset	按字段类型清空查询条件。
toggleCollapse	切换展开/收起状态。
collapsed	当前是否处于收起状态。
activeTags	当前已提交的筛选条件标签。

emitRegister

注册成员	说明
submitQuery	通过 emitRegister 提交查询。
resetFields	重置指定字段或全部表单字段。
toggleCollapse	切换展开/收起状态。

CaCommonTable

配置式数据表格，支持列设置、批量选择、分页和排序。

Props

属性	模板写法	类型	默认值	说明
loading	loading	boolean	false	是否显示加载状态。
title	title	string	''	组件标题。
tips	tips	TableTips	{}	表格上方提示信息配置。
rowKey	row-key	string	'id'	行唯一键字段名。
dataSource	data-source	AnyRecord[]	[]	表格数据源；编辑类组件会直接修改数组和行对象，并给编辑行写入 operateType。
columns	columns	TableField[]	[]	表格列配置数组，结构见本文“配置对象”章节。
pagination	pagination	PaginationConfig | false	{}	可变的响应式分页、排序配置；组件会直接修改，传 false 关闭分页。
addCommand	add-command	CommonCommand	-	新增按钮命令配置。
customCommands	custom-commands	CommonCommand[]	[]	额外业务命令按钮配置。
settingCommands	setting-commands	CommonCommand[]	[]	表格设置类命令按钮。
getList	get-list	() => any | Promise<any>	-	刷新、分页或排序后调用的数据加载函数。
customComponents	custom-components	CustomComponentMap	{}	自定义组件映射，key 对应配置中的 componentKey。
tableTag	table-tag	string	''	列设置缓存标识；非空时用于生成 localStorage key。
elementProps	element-props	AnyRecord	{}	透传给底层 Element Plus 主组件的属性。
extendProps	extend-props	TableExtendProps	() => ({ cacheConfigColumns: true, showRefresh: true, showColumnConfig: true })	刷新按钮、列设置和列设置缓存开关。
emitRegister	emit-register	Record<string, any>	{}	传入可变对象后，组件会向其中注册可调用方法。

Events

事件	参数	说明
selection-change	selection	选中行变化。
sort-change	{ prop, order }	排序条件变化。
page-index-change	pageIndex	当前页变化。
page-size-change	pageSize	每页数量变化。
row-click	Element Plus 原始参数	行单击。
row-dblclick	Element Plus 原始参数	行双击。
cell-click	Element Plus 原始参数	单元格单击。
cell-dblclick	Element Plus 原始参数	单元格双击。
[command.command]	命令相关参数	新增、批量、设置或行命令的同名事件。

Exposed

成员	说明
tableRef	底层 Element Plus 表格实例。
refresh	重新执行 getList。
clearSelection	清空表格选中行。
multipleSelection	当前选中行数组。

emitRegister

注册成员	说明
refresh	重新执行 getList。
clearSelection	清空表格选中行。
getSelectionRows	返回当前选中行数组的副本。

CaEditTable

行内编辑表格，支持自动/手动编辑、校验、新增、取消恢复和未保存草稿保护。

Props

属性	模板写法	类型	默认值	说明
editTriggerMode	edit-trigger-mode	'manual' | 'auto'	'manual'	编辑触发方式：手动命令或点击行自动进入编辑。
loading	loading	boolean	false	是否显示加载状态。
title	title	string	''	组件标题。
rowKey	row-key	string	'id'	行唯一键字段名。
childrenKey	children-key	string	'children'	树形数据的子节点字段名。
treeMode	tree-mode	boolean	false	是否启用树形表格模式。
dataSource	data-source	AnyRecord[]	[]	表格数据源；编辑类组件会直接修改数组和行对象，并给编辑行写入 operateType。
columns	columns	TableField[]	[]	表格列配置数组，结构见本文“配置对象”章节。
pagination	pagination	PaginationConfig	{}	可变的响应式分页、排序配置；组件会直接修改，不支持 false。干净编辑会先结束再继续；未保存编辑会保留草稿并阻止修改。
addCommand	add-command	CommonCommand	-	新增按钮命令配置。
editCommand	edit-command	CommonCommand	-	自动模式进入编辑时使用的命令。
saveCommand	save-command	CommonCommand	-	自动模式离开行或表格时使用的保存命令。
dirtyCheck	dirty-check	(row: AnyRecord, originalRow: AnyRecord) => boolean	-	自定义已有行是否发生业务变更；默认深比较所有 editable: true 字段。
addInside	add-inside	boolean	false	是否由组件直接向数据源插入新增行。
addInsidePosition	add-inside-position	'beforeFirst' | 'afterLast'	'beforeFirst'	新增行或子节点插入到数组头部还是尾部。
customCommands	custom-commands	CommonCommand[]	[]	额外业务命令按钮配置。
appendContent	append-content	string	''	表格底部附加文本。
getList	get-list	() => any | Promise<any>	-	分页或排序获准后调用的数据加载函数；存在未保存编辑而被阻止时不会调用。
customComponents	custom-components	CustomComponentMap	{}	自定义组件映射，key 对应配置中的 componentKey。
elementProps	element-props	AnyRecord	{}	透传给底层 Element Plus 主组件的属性。
emitRegister	emit-register	Record<string, any>	{}	传入可变对象后，组件会向其中注册可调用方法。

Events

事件	参数	说明
update:validateStatus	valid: boolean	编辑行校验状态变化。
add-sub	parent, row	新增子节点后触发。
row-click	Element Plus 原始参数	手动模式下的行单击。
page-index-change	pageIndex	当前页实际变化后发出；脏编辑阻断时不发出。
page-size-change	pageSize	每页数量实际变化后发出；脏编辑阻断时不发出。
sort-change	{ prop, order }	排序条件实际变化后发出；脏编辑阻断时不发出。
[command.command]	index, row, done, reason?	编辑、保存、取消或自定义命令的同名事件。

Exposed

成员	说明
tableRef	底层 Element Plus 表格实例。
editingRow	当前正在编辑的行。
editing	当前是否有行处于编辑状态。
dirty	当前编辑行是否有业务字段变更。
addRow	创建并插入一条新行。
addSubRow	向指定父行插入子节点。
startEdit	让指定行进入编辑状态。
finishEdit	结束编辑并保留当前值。
cancelEdit	取消编辑；已有行恢复快照，新增行被移除。
isDirty	判断当前编辑行是否有业务字段变更。
validate	执行当前表单或编辑行校验。
requestSave	校验并请求保存当前编辑行。

emitRegister

注册成员	说明
addRow	创建并插入一条新行。
addSubRow	向指定父行插入子节点。
startEdit	让指定行进入编辑状态。
finishEdit	结束编辑并保留当前值。
cancelEdit	取消编辑；已有行恢复快照，新增行被移除。
isDirty	判断当前编辑行是否有业务字段变更。
validate	执行当前表单或编辑行校验。
requestSave	校验并请求保存当前编辑行。

CaTreeEditTable

启用树形能力的 EditTable 包装组件。

继承说明：除下表属性外，还支持 CaEditTable 的全部属性和事件。

Props

属性	模板写法	类型	默认值	说明
addInside	add-inside	boolean	true	是否由组件直接向数据源插入新增行。
addInsidePosition	add-inside-position	'beforeFirst' | 'afterLast'	'beforeFirst'	新增行或子节点插入到数组头部还是尾部。
childrenKey	children-key	string	'children'	树形数据的子节点字段名。

Events

事件	参数	说明
inherited	-	事件与 CaEditTable 一致，组件会透传监听器。

Exposed

成员	说明
addRow	创建并插入一条新行。
addSubRow	向指定父行插入子节点。
startEdit	让指定行进入编辑状态。
finishEdit	结束编辑并保留当前值。
cancelEdit	取消编辑；已有行恢复快照，新增行被移除。
dirty	当前编辑行是否有业务字段变更。
isDirty	判断当前编辑行是否有业务字段变更。
validate	执行当前表单或编辑行校验。
requestSave	校验并请求保存当前编辑行。
editTableRef	TreeEditTable 内部的 EditTable 实例。

CaReportTable

支持多级表头、动态列和单元格合并的报表表格。

Props

属性	模板写法	类型	默认值	说明
loading	loading	boolean	false	是否显示加载状态。
dataSource	data-source	AnyRecord[]	[]	表格数据源；编辑类组件会直接修改数组和行对象，并给编辑行写入 operateType。
columns	columns	ReportField[]	[]	表格列配置数组，结构见本文“配置对象”章节。
pagination	pagination	PaginationConfig	() => ({ pageIndex: 1, pageSize: 10, total: 0 })	可变的响应式分页、排序配置；组件会直接修改，不支持 false。
addCommand	add-command	CommonCommand	-	新增按钮命令配置。
customCommands	custom-commands	CommonCommand[]	[]	额外业务命令按钮配置。
getList	get-list	() => any | Promise<any>	-	刷新、分页或排序后调用的数据加载函数。
customComponents	custom-components	CustomComponentMap	{}	自定义组件映射，key 对应配置中的 componentKey。
dynamicFields	dynamic-fields	string[]	[]	当前显示的动态报表字段，可匹配 dataField 或 label。
elementProps	element-props	AnyRecord	{}	透传给底层 Element Plus 主组件的属性。
emitRegister	emit-register	Record<string, any>	{}	传入可变对象后，组件会向其中注册可调用方法。

Events

事件	参数	说明
selection-change	selection	选中行变化。
row-click	Element Plus 原始参数	行单击。
page-index-change	pageIndex	当前页变化。
page-size-change	pageSize	每页数量变化。
sort-change	{ prop, order }	排序条件变化。
[command.command]	命令相关参数	新增、批量或列命令的同名事件。

Exposed

成员	说明
tableRef	底层 Element Plus 表格实例。
multipleSelection	当前选中行数组。
filteredColumns	应用动态列过滤后的报表列。

emitRegister

注册成员	说明
clearSelection	清空表格选中行。
getSelectionRows	返回当前选中行数组的副本。

配置对象

以下类型从 packages/types.ts 自动提取。

CommonCommand

字段	类型	必填	说明
text	string	是	按钮或选项显示文本。
command	string	是	命令名；组件会触发同名事件。
commandType	'edit' | 'save' | 'cancel' | 'addSub' | 'link' | string	否	编辑命令语义，例如 edit、save、cancel、addSub、link；自定义命令应显式配置，避免名称推断。
loading	boolean	否	命令加载声明；CommonQuery 和 CommonQueryPlus 仅在组件 loading 同时为 true 时显示加载态。
canKeyDown	boolean	否	是否可通过 Enter 触发。
keyCode	number	否	兼容旧项目的键码；13 表示 Enter。
visibleValidator	(subject: any) => boolean	否	返回 false 时隐藏；兼容直接接收 model、row 或 selection。对象 subject 的 model、row、index、operateType 是保留字段。
disableValidator	(subject: any) => boolean	否	返回 true 时禁用；兼容直接接收 model、row 或 selection。对象 subject 的 model、row、index、operateType 是保留字段。
elementProps	AnyRecord	否	透传给对应 Element Plus 组件。
extendProps	AnyRecord	否	业务扩展配置。

SelectOption

字段	类型	必填	说明
label	string	是	显示标签。
value	string | number | boolean	否	选项值；省略时使用 label 作为值。
disabled	boolean	否	是否禁用。
color	string	否	状态或选项颜色。
children	SelectOption[]	否	子选项或子报表列。
options	SelectOption[]	否	选项数组。

FormFieldExtendProps

字段	类型	必填	说明
options	SelectOption[]	否	选项数组。
formItemProps	AnyRecord	否	透传给 ElFormItem 的属性。
formItemStyle	CSSProperties	否	ElFormItem 的内联样式。
componentKey	string	否	custom 类型使用的自定义组件 key。
groupTitle	string	否	分组标题。
subTitle	string	否	分组副标题。
groupCommands	CommonCommand[]	否	分组右侧命令。
statusOptions	SelectOption[]	否	状态显示选项。
showInFooter	boolean	否	是否把字段放到表单底部区域。
beforeText	string	否	输入框前置文本。
appendText	string	否	输入框或文本字段后置文本。
helpText	string	否	字段帮助提示。
activeText	string	否	开关为 true 时的查询标签文案。
fromField	string	否	区间起始值对应的 model 字段。
toField	string	否	区间结束值对应的 model 字段。
tagKeys	string[]	否	删除自定义查询标签时需要清空的字段。
tagFormatter	(model: T) => string | false	否	自定义查询标签文案函数。
onChange	(model: T, value?: any) => void	否	字段值变化回调。
onSelect	(model: T, item: any) => void	否	选择选项后的回调。
onEnter	(model: T) => void	否	按 Enter 回调。

FormField

字段	类型	必填	说明
type	FormFieldType	否	字段或列类型。
label	string	否	显示标签。
dataField	string	是	绑定的 model 或 row 字段名。
columnSpan	number	否	占用网格列数。
rules	FormItemRule[]	否	Element Plus 表单校验规则。
visibleValidator	(subject: any) => boolean	否	返回 false 时隐藏；兼容直接接收 model、row 或 selection。对象 subject 的 model、row、index、operateType 是保留字段。
disableValidator	(subject: any) => boolean	否	返回 true 时禁用；兼容直接接收 model、row 或 selection。对象 subject 的 model、row、index、operateType 是保留字段。
elementProps	AnyRecord	否	透传给对应 Element Plus 组件。
extendProps	FormFieldExtendProps<T>	否	业务扩展配置。

QueryField extends FormField<T>

字段	类型	必填	说明
showType	'static' | 'dynamic'	否	静态、动态或展开区显示方式。
showTag	boolean	否	是否生成查询条件标签。

FormExtendProps

字段	类型	必填	说明
contentStyle	CSSProperties	否	内容区样式。
footerStyle	CSSProperties	否	底部区域样式。

PaginationConfig

字段	类型	必填	说明
pageIndex	number	否	当前页，从 1 开始。
currentPage	number	否	pageIndex 的兼容别名。
pageSize	number	否	每页数量。
total	number	否	总记录数。
type	'default' | 'bigData'	否	字段或列类型。
direction	'previous' | 'next'	否	大数据分页方向。
sortField	string	否	排序字段。
order	'ascending' | 'descending' | null	否	Element Plus 排序方向。
showPagination	boolean	否	是否强制展示分页器。
pageSizes	number[]	否	可选每页数量。
elementProps	AnyRecord	否	透传给对应 Element Plus 组件。

DownloadConfig

字段	类型	必填	说明
text	string	否	按钮或选项显示文本。
loading	boolean	否	命令加载声明；CommonQuery 和 CommonQueryPlus 仅在组件 loading 同时为 true 时显示加载态。
elementProps	AnyRecord	否	透传给对应 Element Plus 组件。
options	CommonCommand[]	否	选项数组。

TableTips

字段	类型	必填	说明
title	string	否	提示标题。
elementProps	AnyRecord	否	透传给对应 Element Plus 组件。

TableExtendProps

字段	类型	必填	说明
cacheConfigColumns	boolean	否	是否缓存列显示和固定状态。
showRefresh	boolean	否	是否展示刷新按钮。
showColumnConfig	boolean	否	是否展示列设置。

TableColumnExtendProps

字段	类型	必填	说明
options	SelectOption[]	否	选项数组。
commands	CommonCommand[]	否	普通状态行命令。
editableCommands	CommonCommand[]	否	编辑状态行命令。
linkCommand	string	否	链接列点击后触发的命令名。
imageCommand	string	否	图片点击后触发的命令名。
imageSize	string	否	图片宽高。
componentKey	string	否	custom 类型使用的自定义组件 key。
defaultValue	any	否	新增行的默认值。
autoFocus	boolean	否	进入编辑时是否自动聚焦。
isExpandColumn	boolean	否	兼容树形编辑的展开列标识。
format	string	否	日期格式。
onChange	(row: T, value?: any) => void	否	字段值变化回调。
onEnter	(index: number, row: T, done: () => void) => void	否	按 Enter 回调。

TableField

字段	类型	必填	说明
type	TableColumnType	否	字段或列类型。
label	string	否	显示标签。
dataField	string	是	绑定的 model 或 row 字段名。
dataTemplate	(row: T, index: number) => any	否	单元格显示值函数。
rules	FormItemRule[]	否	Element Plus 表单校验规则。
addable	boolean	否	新增行时是否可编辑。
editable	boolean	否	已有行编辑时是否可编辑。
elementProps	AnyRecord	否	透传给对应 Element Plus 组件。
extendProps	TableColumnExtendProps<T>	否	业务扩展配置。

ReportField extends TableField<T>

字段	类型	必填	说明
reportType	'title' | 'data'	否	报表标题列或数据列。
showType	'static' | 'dynamic'	否	静态、动态或展开区显示方式。
children	ReportField<T>[]	否	子选项或子报表列。

公共联合类型

OperateType

'add' \| 'edit' \| 'view'

FormFieldType

\| 'default' \| 'input' \| 'text' \| 'status' \| 'autocomplete' \| 'autoComplete' \| 'inputNumber' \| 'textArea' \| 'select' \| 'multiSelect' \| 'groupedSelect' \| 'cascader' \| 'treeSelect' \| 'switch' \| 'radioGroup' \| 'radioButtonGroup' \| 'checkboxGroup' \| 'time' \| 'timeSelect' \| 'timeRange' \| 'date' \| 'dateRange' \| 'datetime' \| 'dateTimeRange' \| 'month' \| 'monthRange' \| 'year' \| 'yearRange' \| 'splitDateRange' \| 'inputNumberRange' \| 'groupTitle' \| 'hr' \| 'space' \| 'custom' \| 'upload' \| 'avatarUploader' \| 'complexInput'

TableColumnType

\| 'default' \| 'selection' \| 'index' \| 'link' \| 'custom' \| 'commands' \| 'status' \| 'dot-status' \| 'keyToValue' \| 'multiKeyToValue' \| 'expand' \| 'date' \| 'image' \| 'input' \| 'inputNumber' \| 'select' \| 'switch' \| 'dateTimeRange' \| 'dateRange' \| 'monthRange' \| 'month' \| 'year' \| 'yearRange' \| 'datetime'