aps-design-pro 组件库编码指南

本 skill 帮助在 Vue 3 + TypeScript 项目中正确使用 aps-design-pro（v0.3.1，管理后台组件库，179 个公开组件）。按本指南生成的代码可直接通过 vue-tsc 类型检查并运行。

何时使用

需要编写后台管理界面：表格、表单、筛选、导航、图表、浮层、反馈状态等。
用户提到组件名（AppButton、AppDataTable…）或要求使用该组件库。
需要查询组件 API、Props/Events/Slots、类型、图标名或组合用法。

核心规则（必须遵守）

组件名：一律 App 前缀 PascalCase（AppButton、AppDataTable、AppFormField），从 aps-design-pro 包根按需导入。
样式：使用组件前必须 import "aps-design-pro/style.css";。
图标：icon 属性只接受 IconName 的 50 个合法字面量（见 references/icon-names.md），写错会 TS 报错。
类型：DataTableColumn、ChartSeries、TreeOption、SelectOption、UploadFileItem、ControlSize 等从包根导出，可 import { type X }；NavigationItem/ContextMenuItem/DropdownItem 等未导出，传数组时用内联对象 + icon: "x" as const。
组件不发起请求：加载/禁用/数据获取由页面控制；组件只做展示与交互。
受控优先：有状态组件多用 v-model / v-model:xxx（如 selected-keys、expanded-keys、page）。
生成代码后：如果项目可运行 vue-tsc，先跑类型检查确认无错误再交付。

使用流程

读 references/getting-started.md 确认引入方式与约定（如首次使用）。
从 references/components-index.md 定位需求对应的组件（179 个组件按 9 分类索引，含一句话用途）。
组件具体 Props/Events/Slots：优先读 npm 包内 node_modules/aps-design-pro/dist/types/components/<category>/<Component>.vue.d.ts（最权威）。
组合场景参考 references/patterns.md（表格页、弹窗表单、删除确认、图表卡片等 8 个已验证模板）。
类型与图标：references/common-types.md、references/icon-names.md。

关键 API 备忘

| 需求 | 组件 | | --- | --- | | 表格 + 选择 + 排序 + 操作列 | AppDataTable（selectable/sortable/action-label + #actions 插槽） | | 表格批量操作 | AppTableToolbar #bulk 插槽 / AppTableBatchEditor | | 列筛选 / 列设置 / 密度 | AppTableColumnFilters / AppColumnSettings / AppTableHeader v-model:table-size | | 分页 | AppPagination（v-model:page + v-model:page-size + total 必填） | | 表单 | AppForm（columns/gap 栅格 + AppFormField 的 span/required/error/description） | | 搜索 / 筛选 | AppSearchBar / AppFilterBar（#actions 放查询按钮，@submit 触发） | | 弹窗 / 抽屉 | AppDialog / AppDrawer（modelValue 必填 + #footer 插槽） | | 确认删除 | AppPopconfirm（#trigger="{ toggle }" + @confirm） | | 命令面板 / 右键菜单 | AppCommandPalette / AppContextMenu / AppMenuRight（modelValue 必填） | | 反馈 | AppAlert / AppToast / AppResult / AppSkeleton / AppEmptyState / AppStatePanel | | 图表 | AppChartCard / AppLineChart / AppBarChart / AppDonutChart / AppRingChart（series: ChartSeries[] + categories） | | 导航 | AppTabs / AppSteps / AppBreadcrumb / AppMenu / AppSidebarMenu / AppAnchor |

常见坑（来自真实示例校验）

AppDialog/AppDrawer/AppPopconfirm/AppDropdown/AppContextMenu/AppCommandPalette 等浮层组件的 modelValue 多为必填，必须挂 v-model。
AppFastEnter/AppGlobalSearch 同样要求 modelValue，且需外部触发器按钮。
AppTableBatchEditor 的 fields 需用 DataTableBatchEditField<Row>[] 注解（先定义 interface Row 含字段），否则泛型 key 推断为 never。
AppDataTable 的 columns 建议用 DataTableColumn<Row>[] 注解；row-key 为行唯一字段名（字符串）。
图表组件（AppBarChart 等）与 AppChart 共享 ChartDisplayProps：series 必填、categories 可选。
回调签名：UploadBeforeUpload 返回 boolean | Promise<boolean>（不要返回字符串）；DataTableEditValidator 为 (context, value) => void | string | Promise<...>。
v-model 不能绑定插槽作用域变量（如可编辑表格的自定义编辑插槽参数 draft 只读）——需要自定义编辑器时改用 column.editor 配置内置编辑器。