Ez-UI 使用规则（给 AI）

本页只定义一件事：AI 在生成业务页面时，如何正确使用 Ez-UI 组件。

场景使用矩阵

场景	要求级别	组件组合	说明
CRUD 列表页（查询 + 表格 + 分页）	必须	EzFastTable（内聚查询面板与分页，按需用 #form 插槽放查询表单）	中后台主路径，不要再自行拼装三件套
通用数据展示表格（非 CRUD 聚焦）	优先	EzTable	结构清晰、配置直接，适合基础展示
弹窗录入/编辑	优先	EzDialog + EzDynamicForm	保持交互一致，减少表单样板代码
选择类字段	优先	EzSelect / EzRadio / EzCheckbox	不优先回退原生 el-* 选择组件
日期范围字段（起止拆分）	优先	EzDatePicker	v-model:start-date / v-model:end-date 双向拆分
图片上传字段	必须	EzImageUpload	上传行为与展示风格统一
图标展示/状态表达	优先	EzIcon + @ez-ui/icons	统一图标来源，避免多图标库混用

必须使用规则

1. 生成 CRUD 列表页时，必须使用 EzFastTable 驱动数据请求与分页，查询表单放 #form 插槽
2. 涉及图片上传时，必须使用 EzImageUpload
3. 文档示例代码必须代表推荐用法，不能用一次性演示写法替代

优先使用规则

1. 表单录入优先使用 EzDynamicForm（配置驱动）或 EzFormItem（自定义布局积木）
2. 弹窗交互优先使用 EzDialog
3. 选择类字段优先使用 EzSelect、EzRadio、EzCheckbox
4. 图标优先使用 EzIcon 与 @ez-ui/icons

不建议使用规则

1. 不建议在标准 CRUD 页直接回退到 el-table + el-pagination + 自定义查询区
2. 不建议为了单个示例引入与 Ez-UI 并行的另一套业务封装
3. 不建议把临时场景包装成默认公共 API
4. 不建议自行拼接 EzQueryPanel + EzTable + EzPagination 复刻 FastTable——聚合组件已处理分页联动、排序路由与竞态守卫

组合模板

模板 A：标准 CRUD 页面（默认模板）

<template>
  <ez-fast-table ref="tableRef" v-model:params="query" :api="listApi" :columns="columns">
    <template #form="{ search, reset }">
      <ez-query-panel>
        <el-form :inline="true" :model="query">
          <!-- 查询字段 -->
        </el-form>
        <template #operate>
          <el-button type="primary" @click="search">查询</el-button>
          <el-button @click="reset">重置</el-button>
        </template>
      </ez-query-panel>
    </template>
  </ez-fast-table>
</template>

要点：api 返回 { code, data: { records, total } } 结构（不一致时用 responseAdapter 适配）；查询参数模型用 QueryParams<T>；新增/编辑成功后调用暴露方法 search()（回第 1 页），删除后调用 query()（保持当前页）。

模板 B：弹窗编辑

<template>
  <ez-dialog v-model="visible" title="编辑" @confirm="onSubmit">
    <ez-dynamic-form v-model="formModel" :items="formItems" />
  </ez-dialog>
</template>

要点：EzDynamicForm 用 v-model 绑定表单数据、:items（或 :groups）传字段配置；提交用暴露方法 getSubmitData()，回填用 setSubmitData()；cancel-text / confirm-text 传空字符串可隐藏按钮。

模板 C：图片字段

<template>
  <ez-image-upload v-model="formModel.image" :api="uploadApi" />
</template>

表格专项补充（FastTable / Table）

1. 存在 fixed 列时，其余数据列必须显式声明 width 或 min-width
2. 分页变更事件监听 changePage，载荷 { size?, current? }
3. 远程排序在列上声明 sortMode: 'remote'（可配 sortField），本地排序用 sortable: true
4. 列插槽需要强类型 row 推导时，用 createTypedFastTable<T, P>() 创建泛型别名
5. doLayout 仅在确认布局时机问题时使用，不作为默认补救
6. 表格错位排查顺序：列配置 -> 父容器布局 -> fixed 列 -> 内容宽度

表单专项补充（DynamicForm / FormItem）

1. serialize 返回含 value / fields / omit 键的对象即按转换输出处理，否则按业务值原样写回
2. 范围类型字段（日期/时间范围）的占位符用 startPlaceholder / endPlaceholder，单值字段用 placeholder
3. 字段联动用 show / disabledWhen 函数配置，不在模板里写 v-if 逻辑

文档与示例一致性

1. 组件行为变化时，中英文文档必须同步
2. 示例与说明冲突时，以可运行示例为准回写文档
3. 删除页面时必须同步更新 sidebar，避免死链
4. 能力变更随版本写入变更日志，破坏性变更必须附迁移动作

AI 输出要求（库使用类任务）

AI 输出至少包含：

• 选用了哪些 Ez-UI 组件
• 为什么该场景下这样选
• 是否满足“必须使用/优先使用”规则
• 影响文件
• 验证结果
• 未验证项