Ez-UI Usage Rules (for AI)

This page defines one thing: how AI should choose and use Ez-UI components when generating business pages.

Scenario Matrix

Scenario	Requirement Level	Component Combination	Notes
CRUD list page (query + table + pagination)	Must	EzFastTable (built-in query panel and pagination; put the query form in the #form slot)	Main path for admin pages; do not assemble the trio yourself
General data table (not CRUD-focused)	Prefer	EzTable	Clear structure, config-driven, good for plain display
Dialog entry/editing	Prefer	EzDialog + EzDynamicForm	Consistent interaction, less form boilerplate
Selection fields	Prefer	EzSelect / EzRadio / EzCheckbox	Do not fall back to native el-* selection components
Date range fields (start/end split)	Prefer	EzDatePicker	Two-way split via v-model:start-date / v-model:end-date
Image upload fields	Must	EzImageUpload	Unified upload behavior and display style
Icon display / status expression	Prefer	EzIcon + @ez-ui/icons	Single icon source; avoid mixing icon libraries

Must-Use Rules

1. For CRUD list pages, drive data fetching and pagination with EzFastTable; put the query form in the #form slot
2. Use EzImageUpload whenever image upload is involved
3. Doc examples must represent recommended usage, not one-off demo hacks

Prefer-To-Use Rules

1. Prefer EzDynamicForm (config-driven) or EzFormItem (custom layout building block) for form entry
2. Prefer EzDialog for dialog interactions
3. Prefer EzSelect, EzRadio, EzCheckbox for selection fields
4. Prefer EzIcon with @ez-ui/icons for icons

Not-Recommended Rules

1. Do not fall back to el-table + el-pagination + custom query area on standard CRUD pages
2. Do not introduce a parallel business wrapper alongside Ez-UI just for one example
3. Do not promote temporary scenarios into default public APIs
4. Do not hand-assemble EzQueryPanel + EzTable + EzPagination to imitate FastTable — the aggregate component already handles pagination wiring, sort routing and request race guarding

Combination Templates

Template A: Standard CRUD page (default)

<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">
          <!-- query fields -->
        </el-form>
        <template #operate>
          <el-button type="primary" @click="search">Search</el-button>
          <el-button @click="reset">Reset</el-button>
        </template>
      </ez-query-panel>
    </template>
  </ez-fast-table>
</template>

Key points: api should return { code, data: { records, total } } (adapt with responseAdapter otherwise); model query params with QueryParams<T>; call the exposed search() (back to page 1) after create/edit succeeds and query() (keep current page) after delete.

Template B: Dialog editing

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

Key points: EzDynamicForm binds form data with v-model and field config with :items (or :groups); submit via the exposed getSubmitData() and backfill via setSubmitData(); pass an empty string to cancel-text / confirm-text to hide the buttons.

Template C: Image field

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

Table Supplements (FastTable / Table)

1. When fixed columns exist, all remaining data columns must declare explicit width or min-width
2. Listen to changePage for pagination changes; payload is { size?, current? }
3. Remote sorting: declare sortMode: 'remote' on the column (optionally sortField); local sorting: sortable: true
4. Use the createTypedFastTable<T, P>() factory when column slots need strongly typed row inference
5. doLayout is a last resort for confirmed layout timing issues, not a default remedy
6. Table misalignment checklist: column config -> parent layout -> fixed columns -> content width

Form Supplements (DynamicForm / FormItem)

1. When serialize returns an object with value / fields / omit keys it is treated as a transform output, otherwise it is written back as a plain value
2. Range-type fields (date/time ranges) use startPlaceholder / endPlaceholder; single-value fields use placeholder
3. Field linkage uses the show / disabledWhen function configs, not v-if logic in templates

Docs & Example Consistency

1. When component behavior changes, zh-CN and en-US docs must be updated together
2. When examples and descriptions conflict, fix the docs against the runnable example
3. When removing a page, update the sidebar to avoid dead links
4. Record capability changes in the Changelog per release; breaking changes must include migration actions

AI Output Requirements (library-usage tasks)

AI output should include at least:

• Which Ez-UI components were chosen
• Why they fit the scenario
• Whether the must-use / prefer-use rules are satisfied
• Affected files
• Verification results
• Unverified items