create-yss-spec 2.1.10 → 2.1.11

package/template/.cursor/skills/yss-ui/assets/docs/components/card.md

@@ -0,0 +1,162 @@
+---
+toc: content
+---
+
+# Card 卡片
+
+基于 `ant-design-vue` 的 `Card` 组件封装，专注于单个卡片功能，不包含布局逻辑。完全保留 Ant Design Card 的所有功能，同时提供更灵活的样式控制能力。
+
+## 何时使用
+
+- 需要将信息分组、分块展示，承载列表、表单、统计、图表等内容
+- 需要灵活的样式定制，不受组件内部强制样式限制
+- 希望业务层完全控制布局和样式，使用现代 CSS 布局方案（Grid/Flexbox）
+- 保持与 Ant Design 生态完全兼容的同时，获得更好的定制性
+
+## 代码演示
+
+### 基础样式与定制
+
+<code id="demo-card-basic" src="./demos/card/basic/index.vue" title="基础样式和灵活定制"></code>
+
+### 标题与额外内容
+
+<code id="demo-card-header-extra" src="./demos/card/header-extra/index.vue" title="标题插槽和额外操作"></code>
+
+### 封面卡片
+
+<code id="demo-card-cover" src="./demos/card/cover/index.vue" title="封面和操作区域"></code>
+
+### Meta 信息展示
+
+<code id="demo-card-meta" src="./demos/card/meta/index.vue"></code>
+
+### 加载中状态
+
+<code id="demo-card-loading" src="./demos/card/loading/index.vue" title="加载状态"></code>
+
+### 自适应布局示例
+
+<code id="demo-card-flexible-layout" src="./demos/card/flexible-layout/index.vue" title="自适应网格布局"></code>
+
+### 监控仪表盘示例
+
+<code id="demo-card-layout-metrics" src="./demos/card/layout-metrics/index.vue" title="仪表盘布局示例"></code>
+
+## API
+
+### YCard Props
+
+完全兼容 `ant-design-vue` Card 的所有 Props，并额外提供以下扩展属性：
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| padding | `number \| string` | - | 内容区内边距，支持数字（px）或字符串（如 '16px', '8px 16px'）。会合并到 `bodyStyle.padding`，显式传入的 `bodyStyle.padding` 优先级更高。 |
+| className | `string \| string[]` | - | 自定义卡片类名，可以是字符串或字符串数组，用于业务层样式定制。 |
+| customStyle | `CSSProperties` | - | 自定义卡片样式对象，用于业务层直接设置样式，避免类名污染。 |
+| metaTitle | `string` | - | Meta 标题，若提供任一 Meta 相关内容，将在内容区顶部渲染 Meta 信息。 |
+| metaDescription | `string` | - | Meta 描述。 |
+
+> **重要说明**: 组件不包含任何布局逻辑，所有布局由业务层通过 CSS Grid、Flexbox 等现代布局方案控制。
+
+
+### Slots
+
+| 插槽名 | 说明 |
+| --- | --- |
+| default | 卡片内容 |
+| title | 标题插槽（对应 antd `#title`） |
+| extra | 右上角额外内容（对应 antd `#extra`） |
+| cover | 封面区域（对应 antd `#cover`） |
+| actions | 底部操作区（对应 antd `#actions`） |
+| tabBarExtraContent | Tabs 额外内容（当使用带 Tabs 的卡片时） |
+| meta | Meta 整块内容插槽（若提供，将优先渲染此插槽） |
+| meta-avatar | Meta 头像插槽（未提供 `meta` 时生效） |
+| meta-title | Meta 标题插槽（未提供 `meta` 时生效） |
+| meta-description | Meta 描述插槽（未提供 `meta` 时生效） |
+
+### 设计理念
+
+**灵活性优先**: y-card 专注于卡片功能本身，不强制任何布局样式，让业务层拥有完全的控制权。
+
+**现代化布局**: 推荐使用 CSS Grid 和 Flexbox 等现代布局方案，而不是传统的栅格系统。
+
+**样式可控**: 通过 `className` 和 `customStyle` 提供灵活的样式定制方式。
+
+**完全兼容**: 保持与 Ant Design Card 的完全兼容，所有原有功能都可正常使用。
+
+## 布局最佳实践
+
+### 响应式布局指南
+
+#### 1. 自适应网格布局（推荐）
+```css
+.cards-container {
+  display: grid;
+  /* 自动适应：最小宽度 280px，自动调整列数 */
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: 24px;
+}
+
+/* 响应式优化 */
+@media (max-width: 768px) {
+  .cards-container {
+    grid-template-columns: 1fr;
+    gap: 16px;
+  }
+}
+```
+
+#### 2. 固定列数布局
+```css
+/* 4 列布局，适合大屏展示 */
+.cards-grid-4 {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 24px;
+}
+
+/* 响应式断点 */
+@media (max-width: 1400px) {
+  .cards-grid-4 { grid-template-columns: repeat(3, 1fr); }
+}
+@media (max-width: 1024px) {
+  .cards-grid-4 { grid-template-columns: repeat(2, 1fr); }
+}
+@media (max-width: 768px) {
+  .cards-grid-4 { grid-template-columns: 1fr; }
+}
+```
+
+#### 3. Flexbox 布局
+```css
+.cards-flex {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 16px;
+}
+
+.cards-flex .y-card {
+  flex: 1 1 280px; /* 弹性增长，最小宽度 280px */
+  max-width: 400px; /* 防止在大屏幕上过宽 */
+}
+```
+
+### 布局选择建议
+
+| 场景 | 推荐方案 | 说明 |
+|------|----------|------|
+| **仪表盘/数据展示** | 自适应网格 | 内容重要性相等，需要充分利用空间 |
+| **产品列表** | 固定列数网格 | 统一展示效果，控制每行显示数量 |
+| **信息卡片** | Flexbox | 内容长度不一，需要灵活排列 |
+| **移动端优先** | 单列 + 响应式 | 优先保证移动端体验 |
+
+### 关键设计原则
+
+1. **最小宽度保护**: 确保卡片最小宽度 280px，保证内容可读性
+2. **合理间距**: 使用主题变量设置间距，保持视觉一致性
+3. **响应式优先**: 从移动端开始设计，逐步增强桌面端体验
+4. **内容适配**: 卡片内部内容要能够适应宽度变化
+5. **性能考虑**: 避免过度复杂的布局计算，优先使用原生 CSS 特性
+
+

package/template/.cursor/skills/yss-ui/assets/docs/components/conditionBuilder.md

@@ -0,0 +1,114 @@
+---
+toc: content
+---
+
+### Y-ConditionBuilder 条件构造器
+
+基于 Vue3 与 TypeScript 的表达式构造组件，支持嵌套 AND/OR、联动选项、BETWEEN、多种输入形态与远程数据源。
+
+## 代码演示
+
+### 1. 基础用法（固定选项，无联动）
+<code id="demo-cb-basic" src="./demos/condition-builder/basic/index.vue"></code>
+
+### 2. 固定选项 + 联动（字段 → 操作符/值）
+<code id="demo-cb-linked" src="./demos/condition-builder/linked/index.vue"></code>
+
+### 3. 服务端返回（自定义联动逻辑）
+<code id="demo-cb-remote" src="./demos/condition-builder/remote/index.vue"></code>
+
+### 4. 嵌套 + BETWEEN 特性
+<code id="demo-cb-nesting-between" src="./demos/condition-builder/nesting-between/index.vue"></code>
+
+### 5. 表单校验（严格模式）
+<code id="demo-cb-validation" src="./demos/condition-builder/validation/index.vue"></code>
+
+### 6. 非严格模式（允许空值）
+<code id="demo-cb-validation-custom" src="./demos/condition-builder/validation-custom/index.vue"></code>
+
+## 使用说明
+
+- 默认提供 `field/operator/value` 三段；操作符内置 `none/single/between/multiple` 四类输入语义。
+- 通过 `operator-options` 传入静态操作符；或通过 `get-operators(field)` 动态拉取。
+- 通过 `load-fields(q)` 与 `load-values({ q, field, operator })` 实现本地/远程搜索。
+- 事件：`update:modelValue`、`change`、`blur`；实例方法见类型定义。
+
+## API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| v-model | 绑定的条件组数据 | `ConditionGroup` | - |
+| max-depth | 最大嵌套深度 | `number` | `3` |
+| load-fields | 加载字段选项的方法，支持搜索 | `(q: string) => Promise<OptionItem[]>` | - |
+| load-values | 加载值选项的方法，支持搜索 | `(params: { q: string, field: string, operator: string }) => Promise<OptionItem[]>` | - |
+| operator-options | 静态操作符选项列表 | `OperatorOption[]` | `DEFAULT_OPERATOR_OPTIONS` |
+| get-operators | 动态获取操作符选项的方法 | `(field: string) => Promise<OperatorOption[]>` | - |
+| and-text | "且" 逻辑关系的显示文本 | `string` | `'且'` |
+| or-text | "或" 逻辑关系的显示文本 | `string` | `'或'` |
+| disabled | 是否禁用（只读模式） | `boolean` | `false` |
+| strict-mode | 是否开启严格校验模式（false允许空值） | `boolean` | `true` |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| update:modelValue | 数据更新时触发 | `(value: ConditionGroup) => void` |
+| change | 数据变化时触发 | `(value: ConditionGroup) => void` |
+| validate | 每次数据变化时自动触发，返回当前验证状态 | `(valid: boolean) => void` |
+| blur | 条件失去焦点时触发 | `(value: ConditionGroup) => void` |
+
+### Methods
+
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| validate | 校验所有条件是否完整填写（字段、操作符、值） | - | `boolean` |
+
+### Types
+
+#### ConditionGroup
+
+```typescript
+interface ConditionGroup {
+  id: string;
+  type: 'GROUP';
+  logicalOp: 'AND' | 'OR';
+  children: (ConditionGroup | ConditionLeaf)[];
+  linkedFromLeafId?: string; // 关联的父级叶子节点ID
+}
+```
+
+#### ConditionLeaf
+
+```typescript
+interface ConditionLeaf {
+  id: string;
+  type: 'LEAF';
+  field: string;
+  operator: string;
+  value: any;
+  betweenValue1?: any;
+  betweenValue2?: any;
+}
+```
+
+#### OptionItem
+
+```typescript
+interface OptionItem {
+  label: string;
+  value: string | number;
+  [key: string]: any;
+}
+```
+
+#### OperatorOption
+
+```typescript
+interface OperatorOption {
+  label: string;
+  value: string;
+  kind?: 'single' | 'multiple' | 'between' | 'none'; // 输入框类型
+}
+```

package/template/.cursor/skills/yss-ui/assets/docs/components/cron.md

@@ -0,0 +1,77 @@
+---
+title: Cron 表达式
+description: Cron 表达式可视化编辑器，支持秒/分/时/天/月/年六个维度的配置。
+toc: content
+---
+
+# Cron 表达式
+
+Cron 表达式可视化编辑器，支持秒/分/时/天/月/年六个维度的配置。
+
+## 何时使用
+
+- 需要配置定时任务的执行时间
+- 需要可视化编辑 Cron 表达式
+- 需要在抽屉、弹窗等容器中使用
+
+## 代码演示
+
+### 基础用法
+
+最基础的用法，支持 `v-model` 双向绑定。
+
+<code id="cron-basic" src="./demos/cron/basic/index.vue"></code>
+
+### 在下拉面板中使用
+将组件放入 Popover 下拉面板，模拟类似日期选择器的交互方式，适合表单场景。
+
+<code id="cron-select" src="./demos/cron/select/index.vue"></code>
+
+## API
+
+### Props
+
+| 属性名 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| modelValue / v-model | Cron 表达式 | `string` | `''` |
+| disabled | 是否禁用 | `boolean` | `false` |
+| showSecond | 是否显示秒配置 | `boolean` | `true` |
+| showYear | 是否显示年配置 | `boolean` | `true` |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| update:modelValue | 表达式变化时触发 | `(value: string) => void` |
+| change | 表达式变化时触发 | `(value: string) => void` |
+
+## Cron 表达式说明
+
+组件生成的 Cron 表达式格式为：
+
+```
+秒 分 时 天 月 周 年
+```
+
+各字段说明：
+
+| 字段 | 允许值 | 允许的特殊字符 |
+| --- | --- | --- |
+| 秒 | 0-59 | `, - * /` |
+| 分 | 0-59 | `, - * /` |
+| 时 | 0-23 | `, - * /` |
+| 天 | 1-31 | `, - * / ? L W` |
+| 月 | 1-12 | `, - * /` |
+| 周 | 1-7 (SUN-SAT) | `, - * / ? L #` |
+| 年 | 1970-2099 | `, - * /` |
+
+### 特殊字符说明
+
+- `*`：表示所有值
+- `?`：表示不指定值（仅用于天和周）
+- `-`：表示范围，如 `1-5`
+- `,`：表示列举，如 `1,3,5`
+- `/`：表示间隔，如 `0/5` 表示从 0 开始每隔 5
+- `L`：表示最后，如 `L` 在天字段表示本月最后一天
+- `W`：表示最近的工作日
+- `#`：表示第几个，如 `2#3` 表示第三个星期一

package/template/.cursor/skills/yss-ui/assets/docs/components/echarts.md

@@ -0,0 +1,110 @@
+---
+title: YssEcharts 图表组件
+description: 基于 ECharts 6.0 封装的 Vue3 图表组件，支持响应式、主题切换、深色模式等特性。
+toc: content
+---
+# Echarts 图表
+
+基于 ECharts 6.0 封装的 Vue3 图表组件，支持响应式、主题、暗黑模式。
+
+## 何时使用
+
+- 需要在中后台快速接入标准化图表，保证响应式与主题一致性。
+- 需要在不同页面中复用 `echarts` 初始化、销毁与自适应逻辑。
+
+## 代码演示
+
+### 基础柱状图
+
+<code src="./demos/echarts/basic.vue"></code>
+
+### 折线图
+
+<code src="./demos/echarts/line.vue"></code>
+
+### 饼图
+
+<code src="./demos/echarts/pie.vue"></code>
+
+### 环形分段占比图
+<code src="./demos/echarts/ring-segment.vue"></code>
+
+### 散点图
+
+<code src="./demos/echarts/scatter.vue"></code>
+
+### 雷达图
+
+<code src="./demos/echarts/radar.vue"></code>
+
+### 暗黑模式 + 主题切换
+
+<code src="./demos/echarts/dark.vue"></code>
+
+### 堆叠柱状图
+
+<code src="./demos/echarts/stacked-bar.vue"></code>
+
+### 堆叠面积图
+
+<code src="./demos/echarts/stacked-area.vue"></code>
+
+### 折柱混合
+
+<code src="./demos/echarts/mix.vue"></code>
+
+### 仪表盘
+
+<code src="./demos/echarts/gauge.vue"></code>
+
+### 漏斗图
+
+<code src="./demos/echarts/funnel.vue"></code>
+
+### 矩形树图
+
+<code src="./demos/echarts/treemap.vue"></code>
+
+### K 线图
+
+<code src="./demos/echarts/candlestick.vue"></code>
+
+### 日历热力图
+
+<code src="./demos/echarts/calendar-heatmap.vue"></code>
+
+### 实例方法示例（getInstance/resize/setOption/dispose）
+
+<code src="./demos/echarts/expose-methods.vue"></code>
+
+## API
+
+### YEcharts Props
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| options | ECharts 配置项 | `EChartsCoreOption` | `{}` |
+| width | 容器宽度，数字或 CSS 值 | `number \| string` | `'100%'` |
+| height | 容器高度，数字或 CSS 值 | `number \| string` | `360` |
+| theme | 图表主题 | `'light' \| 'dark' \| string` | `'light'` |
+| renderer | 渲染器 | `'canvas' \| 'svg'` | `'canvas'` |
+| autoresize | 自适应容器尺寸 | `boolean` | `true` |
+| darkMode | 启用暗黑模式（合入 option.darkMode） | `boolean` | `false` |
+| initOptions | 透传 `echarts.init` 的第三个参数 | `InitOpts` | `{}` |
+| setOptionOpts | 透传 `setOption` 的参数 | `SetOptionOpts` | `{}` |
+
+### YEcharts Expose
+
+| 方法 | 说明 | 类型 |
+| --- | --- | --- |
+| getInstance | 获取原始 ECharts 实例 | `() => ECharts \| null` |
+| resize | 手动触发重绘 | `() => void` |
+| setOption | 更新配置项 | `(opt: EChartsCoreOption, notMerge?: boolean, setOptionOpts?: SetOptionOpts) => void` |
+| dispose | 销毁实例 | `() => void` |
+
+## 使用说明
+
+- 组件默认通过 `ResizeObserver` 监听容器尺寸，父容器变化时将自动 `resize`。
+- 切换 `theme`/`renderer` 会重建实例；切换 `darkMode` 仅通过 `setOption({ darkMode })` 更新，避免闪屏。
+- `theme` 为主题包（`light`/`dark`/自定义）；`darkMode` 是 `option.darkMode` 布尔开关，两者可独立使用。
+- 推荐按需引入各图表系列与组件以减小体积（ECharts 6 支持 tree-shaking）。

package/template/.cursor/skills/yss-ui/assets/docs/components/editTable.md

@@ -0,0 +1,212 @@
+---
+title: EditTable 编辑表格
+route: /components/edit-table
+toc: content
+---
+
+# EditTable 可编辑表格
+
+基于 vxe-table 4.16 封装的可编辑表格组件，支持行内编辑、校验、自定义列、字典转换、下拉过滤、行拖拽排序、操作列与分页等能力。
+
+## 基础使用
+
+<code id="demo-edit-table-basic" src="./demos/edit-table/basic/index.vue"></code>
+
+## 表单类型
+
+<code id="demo-edit-table-all-types" src="./demos/edit-table/all-types/index.vue"></code>
+
+## 行级编辑保存（编辑/保存/取消）
+
+点击"编辑"按钮进入编辑态，通过"保存"按钮提交修改（包含校验），通过"取消"按钮放弃修改并还原数据。
+
+<code id="demo-edit-table-row-edit" src="./demos/edit-table/row-edit/index.vue"></code>
+
+## 必填项校验（editRules）
+
+<code id="demo-edit-table-required" src="./demos/edit-table/required/index.vue"></code>
+
+## 自定义校验（去重/长度）
+
+<code id="demo-edit-table-custom-rule" src="./demos/edit-table/custom-rule/index.vue"></code>
+
+## 下拉过滤（按行过滤）
+
+<code id="demo-edit-table-filter" src="./demos/edit-table/filter/index.vue"></code>
+
+## 行拖拽排序
+
+<code id="demo-edit-table-drag" src="./demos/edit-table/drag/index.vue"></code>
+
+## 分页
+
+<code id="demo-edit-table-pagination-action" src="./demos/edit-table/pagination-action/index.vue"></code>
+
+## 行级字典（rowOptionsFieldName）
+
+当“每一行”的下拉候选不同，或不希望全局字典变化后历史值退化为 code 时，可使用行级字典覆盖。组件读取每行对象上 `rowOptionsFieldName` 指定的字段（默认 `'options'`）作为该行的候选项，优先级：行级 > 列级 `options` > 全局 `optionsMap[field]`。
+
+适用场景：
+- 某列候选项依赖该行的其它字段（如产品→版本），不同的行候选不同；
+- 版本等选项来源于后端联动接口，只想影响当前行而非整体；
+- 全局 `optionsMap` 切换时，已选择的历史值仍需被正确翻译展示。
+
+示例：
+
+<code id="demo-edit-table-row-options" src="./demos/edit-table/row-options/index.vue"></code>
+
+## 直接可编辑（默认进入编辑态）
+
+<code id="demo-edit-table-direct-editable" src="./demos/edit-table/direct-editable/index.vue"></code>
+
+## 字段联动（Select 反显到 Input，并联动其他列）
+
+<code id="demo-edit-table-linkage" src="./demos/edit-table/linkage/index.vue"></code>
+
+## 异步接口联动（同列按行选择触发服务端切换）
+<code id="demo-edit-table-async-remote" src="./demos/edit-table/async-remote/index.vue"></code>
+
+
+## 自定义插槽渲染（控件层联动）
+
+<code id="demo-edit-table-slot-linkage" src="./demos/edit-table/slot-linkage/index.vue"></code>
+
+## 大数据无分页（滚动渲染）
+
+<code id="demo-edit-table-big-data" src="./demos/edit-table/big-data/index.vue"></code>
+
+## 提交后展示保存的数据
+
+<code id="demo-edit-table-submit-view" src="./demos/edit-table/submit-view/index.vue"></code>
+
+## API
+
+### YEditTable Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `data` | `any[]` | `[]` | 表格数据（支持 `v-model:data`） |
+| `columns` | `Array<YEditColumn>` | `[]` | 列配置（见下） |
+| `tableConfig` | `Record<string, any>` | `{}` | vxe-table 配置聚合（兼容 v4：`rowConfig/cellConfig/columnConfig/editConfig/...`） |
+| `optionsMap` | `Record<string, any[]>` | `{}` | 字典数据映射，按列 `field` 取值 |
+| `rowOptionsFieldName` | `string` | `'options'` | 行级字典字段名（用于每行覆盖候选项，优先级最高） |
+| `disabled` | `boolean` | `false` | 禁用编辑 |
+| `loading` | `boolean` | `false` | 加载中 |
+| `maxHeight` | `number \| string` | `-` | 最大高度 |
+| `actionConfig` | `YTableActionConfig` | `{ buttons: [] }` | 列级 `type:'action'` 使用的按钮配置（不默认追加） |
+| `rowDragable` | `boolean` | `false` | 是否开启行拖拽（v4 `rowDragConfig`） |
+| `showDragHandle` | `boolean` | `true` | 是否显示拖拽把手列 |
+| `dragHandleWidth` | `number \| string` | `46` | 把手列宽 |
+| `dragHandlePlacement` | `'left' \| 'right'` | `'left'` | 拖拽把手列位置（左侧或右侧） |
+| `dragHandleFixed` | `boolean \| 'left' \| 'right'` | `false` | 拖拽把手列是否固定。`false` 不固定，`true` 自动根据 `dragHandlePlacement` 决定，`'left'/'right'` 明确指定固定方向 |
+| `rowDragConfig` | `VxeTablePropTypes.RowDragConfig` | `-` | 行拖拽配置（合并到内置配置） |
+| `toolbarConfig` | `{ custom?: boolean }` | `{ custom:false }` | 工具栏配置（最小：开启列设置） |
+| `expandConfig` | `VxeTablePropTypes.ExpandConfig` | `{}` | 展开行配置 |
+| `pageable` | `boolean` | `false` | 是否分页（Ant Design Vue Pagination） |
+| `pagination` | `{ current, pageSize, total?, remote?, showSizeChanger?, showQuickJumper?, pageSizeOptions? }` | `{ current:1,pageSize:20,... }` | 分页配置 |
+| `addable` | `boolean` | `false` | 是否显示“添 加”按钮 |
+| `addBtnText` | `string` | `'添 加'` | “添 加”按钮文案 |
+
+### 事件
+
+| 事件名 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:data` | `data: any[]` | v-model:data 回写 |
+| `updateRow` | `{ row, key, value }` | 单元格变更回调 |
+| `add` | `-` | 点击“添 加” |
+| `delete` | `scope, btn, helpers` | 删除操作回调。`scope` 包含 `{ row, rowIndex, column }`，`btn` 为按钮配置，`helpers` 包含 `{ close, hideLoading }` 方法 |
+| `page-change` | `{ current, pageSize }` | 分页变更 |
+| `size-change` | `pageSize: number` | 页大小变更 |
+
+### 插槽说明
+
+插槽支持如下几类（在 HTML/JSP 等 DOM 模板中请一律使用 kebab-case）：
+
+- **单元格内容（推荐）**：按列字段命名 `#<field>`（如 `#name`），仅作用于该列的非编辑态显示。作用域参数包含 `row`（当前行数据）、`column`（列配置）、`rowIndex`（行索引）。
+- **表头（推荐）**：`#<field>-header`（如 `#name-header`）优先于全局 `#header`。兼容旧写法 `#<field>Header`。
+- **展开行内容**：`#expand-row` / `#expandRow`，用于自定义展开行的内容。需配合列配置 `type: 'expand'` 使用。作用域参数包含 `row`、`rowIndex` 等。
+- **分组表头**：`#group-header` / `#groupHeader`，用于自定义分组表头的内容。仅在列配置包含 `children` 时生效。作用域参数包含 `column` 等。
+- **操作列"更多"图标**：`#action-more-icon` / `#actionMoreIcon` 更换收纳触发图标（适用于所有操作列）。
+
+**提示**：DOM 模板（如 JSP、原生 HTML 模板）会将属性名统一转为小写，`#nameHeader` 会变为 `#nameheader` 导致匹配失败。因此我们统一推荐使用中划线（kebab-case）插槽名；为兼容历史代码，组件内部同时支持 camelCase，但后续将逐步以 kebab-case 为规范。
+
+
+### 方法（通过 ref 获取）
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `getTableInstance` | `() => VxeTable` | 获取 vxe 实例 |
+| `validate` | `() => Promise<{ valid: boolean; errorMsg: Map<string,string> }>` | 触发表格校验（含必填与自定义） |
+
+### 列配置（YEditColumn）
+
+在 `vxe-column` 基础上扩展以下字段：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `field` | `string` | 字段名 |
+| `title` | `string` | 列标题 |
+| `component` | `'form-item-input' \| 'form-item-input-number' \| 'form-item-select' \| 'form-item-date' \| 'form-item-date-range' \| 'form-item-time' \| 'form-item-tree-select' \| 'form-item-cascader' \| 'form-item-switch' \| 'form-item-checkbox'` | 编辑器类型（基于 Ant Design Vue） |
+| `props` | `Record<string,any>` | 透传编辑器 props；<br />`Select` 支持 `fieldNames`、`multiple`、`allowCreate(tags)`；<br />`TreeSelect/Cascader` 支持 `fieldNames:{ label,value,children }`；`Switch/Checkbox` 支持 `trueText/falseText`（查看态显示文案）；`TreeSelect` 支持 `treeNodeFilterProp`（默认按 `label` 过滤）；<br />`DatePicker` 支持 `format/valueFormat`，并默认 `getPopupContainer: () => document.body` |
+| `cellProps` | `(ctx) => Record<string,any>` | 单元格级动态 props 函数。按行/按值返回透传给编辑器的 props，与 `props` 合并后生效，优先级高于 `props`。<br />**参数**：`{ row, field, column }`<br />**使用场景**：为特定行的单元格定制交互，如仅当前行的 Select 显示 loading，或根据行数据动态禁用某些选项。详见下方示例 |
+| `isTransform` | `boolean` | 查看态字典翻译（基于 `optionsMap`） |
+| `formatter` | `(ctx) => string \| number` | 自定义查看态文本渲染函数。若提供，优先于内置翻译。<br />**参数**：`{ cellValue, row, column, transformed }`<br />- `cellValue`：当前单元格的原始值<br />- `row`：当前行数据<br />- `column`：列配置<br />- `transformed`：组件根据字典翻译/路径计算好的文本，可直接复用或自定义拼接 |
+| `filterOptions` | `(ctx) => any[]` | 行级下拉过滤器。参数：`{ field, optionsMap, row }` |
+| `customRule` | `(value, row, field, tableData) => { errMsg?: string }` | 自定义校验函数 |
+| `options` | `any[]` | 行内写死下拉数据（优先于 `optionsMap[field]`） |
+
+**`cellProps` 使用示例**：
+
+```typescript
+{
+  field: 'status',
+  component: 'form-item-select',
+  props: {
+    placeholder: '请选择状态'
+  },
+  // 仅当前行正在加载时显示 loading
+  cellProps: ({ row }) => ({
+    loading: row.isLoadingStatus === true,
+    disabled: row.locked === true
+  })
+}
+```
+
+**`formatter` 使用示例**：
+
+```typescript
+{
+  field: 'status',
+  component: 'form-item-select',
+  isTransform: true,
+  // 在字典翻译的基础上添加图标
+  formatter: ({ cellValue, transformed }) => {
+    const icons = { 1: '✅', 2: '⏸', 3: '❌' }
+    return `${icons[cellValue] || ''} ${transformed}`
+  }
+}
+```
+
+> 其余 `vxe-column` 原生属性（如 `width/sortable/fixed/filters/filterMethod/...`）保持透传。
+
+### 操作列（YTableActionConfig）
+
+不再默认追加操作列。如需操作列，请在 `columns` 中显式声明 `{ type: 'action', actionConfig }` 或自行插槽渲染。沿用 `y-table` 的按钮配置，按权限/禁用/隐藏、二次确认与异步 loading 全部可用：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `title` | `string` | 列标题（默认“操作”） |
+| `width` | `number` | 列宽（默认 120） |
+| `align` | `'left' | 'center' | 'right'` | 对齐方式（默认 'center'） |
+| `fixed` | `'left' | 'right'` | 是否固定（默认 'right'） |
+| `displayLimit` | `number` | 直显按钮个数（默认 3） |
+| `moreRenderType` | `'ellipsis' | 'moreButton'` | 更多的展示形式（默认 'moreButton'） |
+| `buttons` | `ActionButtonConfig[]` | 按钮列表（`key/text/type/permissionCode/fallback/disabledFn/hideFn/isConfirm/confirmProps/clickFn`） |
+
+
+> 属性优先级（从高到低）：`columns[i]` 上显式配置 > `columns[i].actionConfig` > 组件 `props.actionConfig` > 内置默认值（`title:'操作'`、`align:'center'`、`fixed:'right'`、`width:120`）。
+>
+> 因此：当列未显式写 `align/width/fixed/title` 时，可以只在 `actionConfig` 中统一配置这些列级属性。
+
+
+