auto-gen-crud 0.1.0

package/dist/core/form-utils.d.ts

@@ -0,0 +1,51 @@
+import { CrudFormComponent, CrudFormItem, CrudFormRule, CrudOption } from './types';
+/**
+ * 将 options 归一化为数组。
+ *
+ * 支持两种常见写法：
+ * - 数组：`[{ label: "启用", value: 1 }]`
+ * - 对象：`{ 1: "启用", 0: "禁用" }`
+ */
+export declare function normalizeOptions(options: unknown, formData?: Record<string, unknown>, item?: CrudFormItem): CrudOption[];
+/** 判断当前组件是否属于输入类，用于自动生成 placeholder 和校验 trigger。 */
+export declare function isInputComponent(component: string): boolean;
+/** 判断当前组件是否通常使用数组值，用于初始化默认值和必填规则类型。 */
+export declare function isArrayComponent(component: string): boolean;
+/** 判断当前组件是否通常使用数字值。 */
+export declare function isNumberComponent(component: string): boolean;
+/**
+ * 生成字段默认值。
+ *
+ * 目的：业务无需给每个字段都手写初始值；新增弹窗和搜索重置都可以复用这套规则。
+ */
+export declare function getDefaultValue(component: CrudFormComponent | string, value?: unknown): unknown;
+/**
+ * 根据 columns 和外部初始 data 构建完整表单数据。
+ *
+ * 这个函数是新包状态初始化的核心：
+ * - 搜索表单用它生成初始搜索条件。
+ * - 新增弹窗用它重建干净表单，避免残留上一次编辑的数据。
+ */
+export declare function createFormData(columns: CrudFormItem[], data?: Record<string, unknown>): Record<string, unknown>;
+/** 判断表单项是否应该显示。 */
+export declare function shouldShowFormItem(item: CrudFormItem, formData: Record<string, unknown>): boolean;
+/** 判断表单项是否应该禁用。 */
+export declare function shouldDisableFormItem(item: CrudFormItem, formData: Record<string, unknown>, forceDisabled?: boolean): boolean;
+/** 获取表单项 label，兼容函数写法。 */
+export declare function getFormItemLabel(item: CrudFormItem, formData: Record<string, unknown>): string;
+/**
+ * 生成默认 placeholder。
+ *
+ * 输入类组件使用“请输入”，选择类组件使用“请选择”。
+ */
+export declare function getPlaceholder(item: CrudFormItem, formData: Record<string, unknown>): string;
+/**
+ * 生成字段校验规则。
+ *
+ * 规则来源有两类：
+ * - `required/isReq` 自动生成必填规则。
+ * - `rules` 追加业务自定义规则。
+ */
+export declare function createRules(item: CrudFormItem, formData: Record<string, unknown>): CrudFormRule[];
+/** 为整个表单生成 rules 对象。 */
+export declare function createFormRules(columns: CrudFormItem[], formData: Record<string, unknown>): Record<string, CrudFormRule[]>;

package/dist/core/object-utils.d.ts

@@ -0,0 +1,43 @@
+import { CrudFormItem } from './types';
+/**
+ * 深度克隆任意数据。
+ *
+ * 使用场景：
+ * - 搜索表单保存初始快照，重置时避免引用同一个对象。
+ * - 弹窗编辑行数据时避免直接修改表格行对象。
+ *
+ * 说明：这里故意不依赖 lodash，方便学习递归克隆的核心思路。
+ */
+export declare function deepClone<T>(value: T): T;
+/**
+ * 按点路径读取对象值。
+ *
+ * @example
+ * ```ts
+ * getByPath({ user: { name: "张三" } }, "user.name") // "张三"
+ * ```
+ */
+export declare function getByPath(source: unknown, path: string): unknown;
+/**
+ * 按点路径写入对象值。
+ *
+ * 这让表单字段可以声明 `user.name`，而不是只能声明一层字段。
+ */
+export declare function setByPath(target: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * 执行“值或函数”配置。
+ *
+ * 很多配置项都支持静态值和函数，例如：
+ * - `show: true`
+ * - `show: formData => formData.type === 1`
+ *
+ * 这个工具统一处理两种写法。
+ */
+export declare function resolveValue<T, Args extends unknown[]>(value: T | ((...args: Args) => T), ...args: Args): T;
+/**
+ * 获取字段实际组件类型。
+ *
+ * 新包推荐使用 `component`，但为了保留旧 auto-gen-crud 的学习迁移价值，
+ * 这里兼容旧字段 `valueKey`。
+ */
+export declare function getFormComponent(item: CrudFormItem): string;

package/dist/core/table-utils.d.ts

@@ -0,0 +1,19 @@
+import { CrudImageOptions, CrudTableAction, CrudTableColumn } from './types';
+/** 获取列字段路径，兼容新字段 `field` 和旧字段 `key`。 */
+export declare function getColumnField<T extends Record<string, unknown>>(column: CrudTableColumn<T>): string;
+/** 获取行数据中的单元格值，支持点路径。 */
+export declare function getCellValue<T extends Record<string, unknown>>(row: T, column: CrudTableColumn<T>): unknown;
+/** 判断列是否显示。 */
+export declare function shouldShowColumn<T extends Record<string, unknown>>(column: CrudTableColumn<T>, data: T[], index: number): boolean;
+/** 获取实际操作按钮列表，兼容旧字段 buttons。 */
+export declare function getColumnActions<T extends Record<string, unknown>>(column: CrudTableColumn<T>): CrudTableAction<T>[];
+/** 判断操作按钮是否显示。 */
+export declare function shouldShowAction<T>(row: T, action: CrudTableAction<T>): boolean;
+/** 获取操作按钮文案，兼容函数写法。 */
+export declare function getActionLabel<T>(row: T, action: CrudTableAction<T>): string;
+/** 获取确认文案，未配置时给出通用中文提示。 */
+export declare function getActionConfirmText<T>(row: T, action: CrudTableAction<T>): string;
+/** 格式化日期列。 */
+export declare function formatDateTime(value: unknown, format?: boolean | string): string;
+/** 归一化图片列配置。 */
+export declare function normalizeImageOptions(image: boolean | CrudImageOptions | undefined): Required<CrudImageOptions>;

package/dist/core/types.d.ts

@@ -0,0 +1,443 @@
+import { App, Plugin, VNodeChild } from 'vue';
+/**
+ * 新包支持的内置 UI 名称。
+ *
+ * 设计目的：
+ * - 使用者只需要在初始化 `createAutoCrud({ ui })` 时选择一次 UI。
+ * - 页面里的表单、表格、弹窗配置保持中立，不需要区分 Naive UI / Element Plus / Ant Design Vue。
+ * - 不传时默认使用 `element-plus`，符合本包的默认定位。
+ */
+export type CrudUIName = "element-plus" | "naive" | "ant-design-vue";
+/**
+ * 表单字段支持的中立组件类型。
+ *
+ * 这些名称不是具体 UI 库组件名，而是业务语义：
+ * - `input` 最终可能渲染为 `ElInput`、`NInput` 或 `AInput`。
+ * - `datePicker` 最终可能渲染为 `ElDatePicker`、`NDatePicker` 或 `ADatePicker`。
+ * - 具体映射由当前初始化时选择的 UI Adapter 决定。
+ */
+export type CrudFormComponent = "input" | "textarea" | "select" | "multipleSelect" | "radio" | "checkbox" | "inputNumber" | "datePicker" | "timePicker" | "switch" | "cascader" | "slider";
+/**
+ * 表单、表格、tabs 等场景通用的选项结构。
+ *
+ * @example
+ * ```ts
+ * const statusOptions: CrudOption[] = [
+ *   { label: "启用", value: 1 },
+ *   { label: "禁用", value: 0 },
+ * ];
+ * ```
+ */
+export interface CrudOption {
+    /** 选项展示文案。 */
+    label: string;
+    /** 选项真实值，提交给业务接口时使用。 */
+    value: unknown;
+    /** 是否禁用该选项。 */
+    disabled?: boolean;
+    /** 级联组件的子选项。 */
+    children?: CrudOption[];
+    /** 允许业务保留额外字段，渲染时会原样透传给当前 UI。 */
+    [key: string]: unknown;
+}
+/**
+ * 表单、表格、tabs映射结构。
+*/
+export interface CrudMap {
+    [key: string]: unknown;
+}
+/**
+ * 表单校验规则的中立描述。
+ *
+ * 说明：三套 UI 的规则对象大体相似但并不完全一致，本包只约定常见字段，
+ * 其它字段允许通过索引签名透传给当前 UI 的 Form 校验能力。
+ */
+export interface CrudFormRule {
+    /** 是否必填。 */
+    required?: boolean;
+    /** 校验失败提示文案。 */
+    message?: string;
+    /** 触发时机，如 `blur`、`change`。 */
+    trigger?: string | string[];
+    /** 值类型，常用于数组、多选、数字等字段。 */
+    type?: string;
+    /** 自定义校验函数，签名兼容常见 UI 库规则。 */
+    validator?: (...args: unknown[]) => boolean | Error | Promise<void> | void;
+    /** 允许透传当前 UI 支持但中立类型没有显式声明的规则字段。 */
+    [key: string]: unknown;
+}
+/**
+ * 表单字段事件上下文。
+ *
+ * 设计目的：
+ * - 业务在字段事件里通常不只需要当前值，还需要知道“哪个字段触发了事件”。
+ * - 字段联动时可以通过 setFieldValue 修改其它字段，避免业务直接操作嵌套对象路径。
+ * - 三套 UI 的原生事件参数不一致，但上下文结构保持稳定。
+ */
+export interface CrudFormFieldEventContext {
+    /** 当前触发事件的字段路径。 */
+    prop: string;
+    /** 当前字段完整配置，方便业务读取 options、component、扩展字段等信息。 */
+    item: CrudFormItem;
+    /** 当前字段使用的中立组件类型。 */
+    component: CrudFormComponent;
+    /** 当前表单数据；onChange 触发时这里已经是更新后的数据。 */
+    formData: Record<string, unknown>;
+    /** 事件触发前的字段旧值，常用于比较本次是否真的发生业务变化。 */
+    oldValue: unknown;
+    /** 按字段路径写入表单值，用于开始时间清空结束时间这类字段联动。 */
+    setFieldValue: (prop: string, value: unknown) => void;
+}
+/**
+ * 表单字段配置。
+ *
+ * 它是搜索表单和弹窗表单的核心 schema。业务只描述字段是什么，
+ * 不描述要用 `ElInput` 还是 `NInput`，具体组件由初始化时选择的 Adapter 决定。
+ */
+export interface CrudFormItem {
+    /** 字段标签，用于 FormItem 的 label。 */
+    label: string | ((formData: Record<string, unknown>, item: CrudFormItem) => string);
+    /** 字段路径，支持 `user.name` 这种点路径。 */
+    prop: string;
+    /**
+     * 动态配置依赖的字段路径。
+     *
+     * 说明：当 show/disabled/required/rules/options/label/placeholder 使用函数时，
+     * 可声明它们依赖哪些字段。组件会基于这些字段值缓存计算结果，避免无关字段变化时重复执行动态函数。
+     */
+    deps?: string[];
+    /** 推荐的新字段：声明当前字段使用的中立组件类型。 */
+    component?: CrudFormComponent;
+    /** 兼容旧 auto-gen-crud 的字段名；如果同时存在，优先使用 `component`。 */
+    valueKey?: CrudFormComponent;
+    /** 初始值；如果未传，会根据组件类型生成空数组、false 或 null。 */
+    value?: unknown;
+    /** 下拉、单选、多选、级联等组件的选项，支持函数形式动态返回。 */
+    options?: CrudOption[] | Record<string, unknown> | ((formData: Record<string, unknown>, item: CrudFormItem) => CrudOption[] | Record<string, unknown>);
+    /** 是否必填；支持函数形式，用于根据其它字段动态决定。 */
+    required?: boolean | ((formData: Record<string, unknown>, item: CrudFormItem) => boolean);
+    /** 兼容旧字段 `isReq`。新代码推荐使用 `required`。 */
+    isReq?: boolean | ((formData: Record<string, unknown>, item: CrudFormItem) => boolean);
+    /** 自定义校验规则；支持函数形式动态生成。 */
+    rules?: CrudFormRule[] | ((formData: Record<string, unknown>, item: CrudFormItem) => CrudFormRule[]);
+    /** 占位文案；不传时本包会根据输入类/选择类自动生成。 */
+    placeholder?: string | ((formData: Record<string, unknown>, item: CrudFormItem) => string);
+    /** 是否显示该字段；用于复杂表单中的联动显隐。 */
+    show?: boolean | ((formData: Record<string, unknown>, item: CrudFormItem) => boolean);
+    /** 是否禁用该字段；查看模式会在组件层统一追加禁用。 */
+    disabled?: boolean | ((formData: Record<string, unknown>, item: CrudFormItem) => boolean);
+    /** 当前字段在表单栅格中占几份；默认 1，最大不超过 layout.columns。 */
+    colSpan?: number;
+    /** 表单项容器属性，如 labelWidth、required 等，会传给当前 UI 的 FormItem。 */
+    formItemProps?: Record<string, unknown>;
+    /** 当前控件的通用透传属性；不会区分三套 UI，因为 UI 在初始化时已经确定。 */
+    props?: Record<string, unknown>;
+    /** 兼容旧字段 `componentProps`。新代码推荐使用 `props`。 */
+    componentProps?: Record<string, unknown>;
+    /**
+     * 字段值变化事件。
+     *
+     * 这是本包推荐的业务事件写法：组件内部会先完成表单值更新，再触发该回调。
+     * 如果需要使用某个 UI 库独有的原生事件，仍可以写在 props 里透传。
+     */
+    onChange?: (value: unknown, context: CrudFormFieldEventContext) => void | Promise<void>;
+    /** 字段失焦事件，适合做格式化、轻量校验或提示收起。 */
+    onBlur?: (event: unknown, context: CrudFormFieldEventContext) => void | Promise<void>;
+    /** 字段聚焦事件，适合做提示展示、远程选项预加载等交互。 */
+    onFocus?: (event: unknown, context: CrudFormFieldEventContext) => void | Promise<void>;
+    /** 是否在提交前加密该字段。加密函数由内置 SM4 工具或用户注入能力提供。 */
+    encrypt?: boolean;
+    /** 字段说明，组件可以渲染为 tooltip 或普通提示。 */
+    tips?: string;
+    /** 自定义渲染；优先级高于 `component`，用于特殊业务字段。 */
+    render?: (formData: Record<string, unknown>, item: CrudFormItem) => VNodeChild;
+    /** 允许业务扩展字段，工具函数会尽量保持原样。 */
+    [key: string]: unknown;
+}
+/**
+ * 表单布局配置。
+ *
+ * 默认搜索表单会使用响应式列数，弹窗表单默认一列。
+ * 如果业务明确传入 columns，则按业务传入值渲染。
+ */
+export interface CrudFormLayout {
+    /** 每行列数。 */
+    columns?: number;
+    /** 横向间距，单位 px。 */
+    gapX?: number;
+    /** 纵向间距，单位 px。 */
+    gapY?: number;
+}
+/** 搜索表单 hook 入参。 */
+export interface UseSearchFormOptions<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** 搜索字段配置。 */
+    columns: CrudFormItem[];
+    /** 初始搜索数据；未包含的字段会按 columns 默认值补齐。 */
+    data?: Partial<T>;
+    /** 搜索提交回调，只负责返回搜索条件，不直接约束列表请求。 */
+    onSubmit?: (data: T) => void | Promise<void>;
+    /** 重置回调，重置后会返回恢复后的搜索条件。 */
+    onReset?: (data: T) => void | Promise<void>;
+    /** 是否显示默认新增按钮。 */
+    addButton?: boolean;
+    /** 默认新增按钮文案。 */
+    addButtonText?: string;
+    /** 点击默认新增按钮后的额外回调。 */
+    onAddClick?: () => void;
+    /** 搜索按钮区域栅格跨度。 */
+    searchButtonSpan?: number;
+    /** 搜索表单布局。 */
+    layout?: CrudFormLayout;
+}
+/** 搜索表单 hook 返回值，也是 AutoCrud 的 searchFormConfig。 */
+export interface CrudSearchFormConfig<T extends Record<string, unknown> = Record<string, unknown>> {
+    columns: CrudFormItem[];
+    /** 搜索表单响应式数据，泛型 T 用于让业务页安全读取查询字段。 */
+    data: T;
+    addButton: boolean;
+    addButtonText: string;
+    searchButtonSpan?: number;
+    layout?: CrudFormLayout;
+    submit: (data?: T) => Promise<void>;
+    reset: () => Promise<T>;
+    onAddClick?: () => void;
+}
+/** 弹窗表单模式。 */
+export type CrudModalMode = "add" | "edit" | "view";
+/** 弹窗展示形态。 */
+export type CrudModalType = "drawer" | "modal";
+/** 弹窗表单 hook 入参。 */
+export interface UseModalFormOptions<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** 弹窗表单字段配置。 */
+    columns: CrudFormItem[];
+    /** 初始表单数据，新增时会以它和 columns 默认值共同生成数据。 */
+    data?: Partial<T>;
+    /** 默认弹窗显示状态。 */
+    visible?: boolean;
+    /** 默认模式。 */
+    mode?: CrudModalMode;
+    /** 弹窗形态，默认 drawer。 */
+    modalType?: CrudModalType;
+    /** 提交回调。 */
+    onSubmit?: (data: T, mode: CrudModalMode) => void | Promise<void>;
+    /** 关闭回调，内部 close 后会继续调用它。 */
+    onClose?: () => void;
+    /** 弹窗标题映射。 */
+    titleMap?: Partial<Record<CrudModalMode, string>>;
+    /** 弹窗按钮文案映射。 */
+    buttonTextMap?: Partial<Record<CrudModalMode, {
+        submit?: string;
+        cancel?: string;
+    }>>;
+    /** 表单布局。 */
+    layout?: CrudFormLayout;
+}
+/** 弹窗表单 hook 返回值，也是 AutoCrud 的 modalFormConfig。 */
+export interface CrudModalFormConfig<T extends Record<string, unknown> = Record<string, unknown>> {
+    columns: CrudFormItem[];
+    data: T;
+    visible: boolean;
+    mode: CrudModalMode;
+    modalType: CrudModalType;
+    titleMap?: Partial<Record<CrudModalMode, string>>;
+    buttonTextMap?: Partial<Record<CrudModalMode, {
+        submit?: string;
+        cancel?: string;
+    }>>;
+    layout?: CrudFormLayout;
+    submit: (data?: T) => Promise<void>;
+    close: () => void;
+    openAdd: (data?: Partial<T>) => void;
+    openEdit: (row: T) => void;
+    openView: (row: T) => void;
+    setFormData: (prop: string, value: unknown) => void;
+}
+/** 表格分页中立结构。 */
+export interface CrudPagination {
+    /** 当前页，从 1 开始。 */
+    page: number;
+    /** 每页条数。 */
+    pageSize: number;
+    /** 总条数。 */
+    total: number;
+    /** 可选分页条数。 */
+    pageSizes?: number[];
+    /** 是否显示 pageSize 选择器。 */
+    showSizePicker?: boolean;
+    /** 是否显示快速跳页。 */
+    showQuickJumper?: boolean;
+}
+/** 表格操作按钮类型。 */
+export type CrudButtonType = "default" | "primary" | "success" | "warning" | "danger" | "info" | "text" | "link";
+/** 表格操作按钮尺寸。 */
+export type CrudButtonSize = "small" | "medium" | "large";
+/** 表格操作列按钮配置。 */
+export interface CrudTableAction<T> {
+    /** 操作唯一标识。 */
+    key: string;
+    /** 操作文案，支持根据行数据动态生成。 */
+    label: string | ((row: T, action: CrudTableAction<T>) => string);
+    /** 操作按钮类型，adapter 会映射成当前 UI 的按钮语义。 */
+    type?: CrudButtonType;
+    /** 操作按钮尺寸。 */
+    size?: CrudButtonSize;
+    /** 是否需要二次确认。 */
+    confirm?: boolean;
+    /** 兼容旧字段 `isConfirm`。 */
+    isConfirm?: boolean;
+    /** 确认文案。 */
+    confirmText?: string | ((row: T, action: CrudTableAction<T>) => string);
+    /** 取消文案。 */
+    cancelText?: string;
+    /** 是否显示该操作。 */
+    show?: boolean | ((row: T, action: CrudTableAction<T>) => boolean);
+    /** 点击回调。 */
+    onClick: (row: T, event?: MouseEvent) => void | Promise<void>;
+}
+/** 图片列配置。 */
+export interface CrudImageOptions {
+    width?: number;
+    height?: number;
+    objectFit?: "cover" | "contain" | "fill" | "none" | "scale-down";
+    preview?: boolean;
+}
+/** 表格列配置。 */
+export interface CrudTableColumn<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** 表头文案。 */
+    title: string;
+    /** 字段路径，支持 `user.name`。 */
+    field?: keyof T | string;
+    /** 兼容旧 auto-gen-crud 的 `key` 字段；新代码推荐使用 `field`。 */
+    key?: keyof T | string | ((row: T) => string);
+    /** 列宽。 */
+    width?: number | string;
+    /** 固定列。 */
+    fixed?: "left" | "right";
+    /** 对齐方式。 */
+    align?: "left" | "center" | "right";
+    /** 是否显示该列。 */
+    show?: boolean | ((column: CrudTableColumn<T>, data: T[], index: number) => boolean);
+    /** 自定义单元格渲染。 */
+    render?: (row: T, column: CrudTableColumn<T>, index: number) => VNodeChild;
+    /** 操作列配置；语义上替代旧包 buttons。 */
+    actions?: CrudTableAction<T>[];
+    /** 兼容旧包 buttons 字段。 */
+    buttons?: CrudTableAction<T>[];
+    /** 是否渲染复制能力。 */
+    copy?: boolean;
+    /** 是否渲染敏感信息解密能力。 */
+    decode?: boolean;
+    /** 是否按图片列渲染。 */
+    image?: boolean | CrudImageOptions;
+    /** 是否格式化为日期时间；字符串时表示 dayjs 格式。 */
+    dateTime?: boolean | string;
+    /** 当前列透传给 UI 表格列的属性。 */
+    props?: Record<string, unknown>;
+}
+/** Tabs 配置项。 */
+export interface CrudTabOption {
+    label: string;
+    value: string | number;
+    disabled?: boolean;
+}
+/** 表格 tabs 配置。 */
+export interface CrudTabsConfig {
+    options: CrudTabOption[];
+    value: string | number;
+    onChange?: (value: string | number) => void | Promise<void>;
+}
+/** 表格滚动配置。 */
+export interface CrudTableScroll {
+    /**
+     * 表格纵向滚动高度。
+     *
+     * - true：默认值，组件根据当前视口、表格位置、分页高度自动计算。
+     * - false：关闭动态高度，表格恢复自然高度。
+     * - number/string：使用业务显式传入的高度。
+     */
+    height?: boolean | number | string;
+    /** 横向滚动宽度，主要用于 Ant Design Vue scroll.x 和 Naive UI scrollX。 */
+    x?: number | string;
+}
+/** 表格 hook 入参。 */
+export interface UseTableOptions<T extends Record<string, unknown> = Record<string, unknown>> {
+    columns: CrudTableColumn<T>[];
+    data?: T[];
+    /** 是否显示分页；只控制分页组件显隐，不改变 pagination 对象类型。 */
+    showPagination?: boolean;
+    /**
+     * 分页配置。
+     *
+     * 推荐只传分页对象；为了兼容旧版本，传 false 时等价于 showPagination: false。
+     */
+    pagination?: Partial<CrudPagination> | false;
+    tabs?: CrudTabsConfig;
+    rowKey?: string | ((row: T) => string | number);
+    immediate?: boolean;
+    /** 表格滚动配置；默认开启自动高度。 */
+    scroll?: CrudTableScroll | boolean;
+    /** 列表请求函数；请求完成后由业务自行写入 table.data 和 table.pagination.total。 */
+    getDataList?: () => void | Promise<void>;
+}
+/** 表格 hook 返回值，也是 AutoCrud 的 tableConfig。 */
+export interface CrudTableConfig<T extends Record<string, unknown> = Record<string, unknown>> {
+    columns: CrudTableColumn<T>[];
+    data: T[];
+    /** 是否显示分页组件；业务开关与分页数据分离，避免 pagination 出现 false 联合类型。 */
+    showPagination: boolean;
+    /** 分页状态对象，始终可直接读写 page/pageSize/total。 */
+    pagination: CrudPagination;
+    tabs?: CrudTabsConfig;
+    loading: boolean;
+    rowKey?: string | ((row: T) => string | number);
+    /** 是否由 AutoCrud 挂载后自动加载首屏数据。 */
+    immediate?: boolean;
+    /** 表格滚动配置，默认 `{ height: true }`。 */
+    scroll: CrudTableScroll;
+    load: () => Promise<void>;
+    reset: () => Promise<void>;
+    setPage: (page: number) => Promise<void>;
+    setPageSize: (pageSize: number) => Promise<void>;
+    setTabsValue: (value: string | number) => Promise<void>;
+}
+/** AutoCrud 容器组件 Props。 */
+export interface AutoCrudProps<T extends Record<string, unknown> = Record<string, unknown>, TSearch extends Record<string, unknown> = Record<string, unknown>> {
+    title?: string;
+    rowKey?: string | ((row: T) => string | number);
+    searchFormConfig?: CrudSearchFormConfig<TSearch>;
+    tableConfig?: CrudTableConfig<T>;
+    modalFormConfig?: CrudModalFormConfig<T>;
+}
+/** 请求函数配置。 */
+export interface CrudRequestOptions {
+    url: string;
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    data?: unknown;
+    params?: Record<string, unknown>;
+    headers?: Record<string, string>;
+}
+/** 用户可注入的请求函数类型。 */
+export type CrudRequestHandler = <T = unknown>(options: CrudRequestOptions) => Promise<T>;
+/** 敏感信息解密函数类型。 */
+export type CrudDecodeHandler = (value: unknown, row?: Record<string, unknown>) => Promise<string> | string;
+/** 敏感信息查看日志函数类型。 */
+export type CrudDecodeLogHandler = (value: unknown, row?: Record<string, unknown>) => Promise<void> | void;
+/** 全局初始化配置。 */
+export interface AutoCrudInstallOptions {
+    /** 初始化时选择的 UI，"element-plus" | "naive" | "ant-design-vue"，默认 `element-plus`。 */
+    ui?: CrudUIName;
+    /** 高级自定义 adapter；传入后优先级高于 ui。 */
+    adapter?: unknown;
+    /** 自定义请求函数，供 decode、日志等内置工具使用。 */
+    request?: CrudRequestHandler;
+    /** 自定义敏感信息解密函数。 */
+    decode?: CrudDecodeHandler;
+    /** 自定义敏感信息查看日志函数。 */
+    decodeLog?: CrudDecodeLogHandler;
+    /** SM4 默认密钥；未传时只使用工具函数调用时的显式 key。 */
+    sm4Key?: string;
+}
+/** createAutoCrud 返回的 Vue 插件类型。 */
+export type AutoCrudPlugin = Plugin & {
+    install: (app: App, options?: AutoCrudInstallOptions) => void;
+};

package/dist/generator/fields.d.ts

@@ -0,0 +1,27 @@
+import { GeneratedEnum, GeneratedField, NormalizedOperation, OpenApiDocument } from './types';
+/**
+ * 生成搜索表单字段。
+ *
+ * 搜索字段来自列表接口的 query 参数；分页字段和公共业务字段会被过滤掉，
+ * 因为分页由 table.pagination 管，traceLogId/operator 这类公共参数应由请求封装统一补齐。
+ */
+export declare function buildSearchFields(document: OpenApiDocument, operation: NormalizedOperation, enums: Map<string, GeneratedEnum>): GeneratedField[];
+/**
+ * 生成弹窗表单字段。
+ *
+ * 新增和编辑接口都可能提供字段，这里合并两边字段，并保留 required 信息；
+ * id 默认不进入表单，因为新增时通常没有 id，编辑时 id 会随 row 数据一起提交。
+ */
+export declare function buildModalFields(document: OpenApiDocument, operations: Array<NormalizedOperation | undefined>, enums: Map<string, GeneratedEnum>): GeneratedField[];
+/** 表格列字段来自列表接口响应里的 records/items schema。 */
+export declare function buildTableFields(document: OpenApiDocument, operation: NormalizedOperation, enums: Map<string, GeneratedEnum>): GeneratedField[];
+/**
+ * 收集所有接口里出现过的枚举。
+ *
+ * Apifox 会把枚举中文名放在 x-apifox-enum 中，生成器优先使用它；
+ * 如果没有 x-apifox-enum，则退回 OpenAPI 标准 enum 值。
+ */
+export declare function collectEnumsFromOperations(document: OpenApiDocument, operations: NormalizedOperation[]): Map<string, GeneratedEnum>;
+export declare function isPaginationField(name: string): boolean;
+export declare function getPageParamName(operation: NormalizedOperation): string;
+export declare function getPageSizeParamName(operation: NormalizedOperation): string;

package/dist/generator/index.d.ts

@@ -0,0 +1,14 @@
+import { GenerateCrudPageOptions, GenerateCrudPageResult } from './types';
+export type { CrudOperationKind, GenerateCrudPageOptions, GenerateCrudPageResult, GeneratedFile, OpenApiDocument, RequestAdapterOptions, RequestRenderContext, } from './types';
+/**
+ * 根据 OpenAPI 3.1 文档生成一个可二次开发的 CRUD 页面目录。
+ *
+ * 使用方式：
+ * - 最简单：`generateCrudPage(openapiUrl)`，生成器自动识别 tag、标题、实体名和输出目录。
+ * - 进阶：`generateCrudPage({ openapi, outDir, operationMap })`，当接口文档不够规范时手动覆盖关键推断。
+ *
+ * 这里是生成器总编排层，只负责串起“读取文档 -> 推断模型 -> 渲染文件 -> 写入磁盘”四步，
+ * 具体推断规则分散在 operations/fields/schema/templates 中，避免入口函数变成难维护的大杂烩。
+ */
+export declare function generateCrudPage(openapi: string): Promise<GenerateCrudPageResult>;
+export declare function generateCrudPage(options: GenerateCrudPageOptions): Promise<GenerateCrudPageResult>;