urit-qf-ui 0.2.7 → 1.0.0

package/dist/model/cascader.d.ts

@@ -0,0 +1,135 @@
+/**
+ * UCascader —— 多级级联选择的数据结构定义（model 层）
+ *
+ * 本层只定义**数据结构**，不放任何逻辑：
+ *   - 渲染期逻辑（层级骨架 / 选项推导 / 清理更深字段）在 ../utils/cascader.ts；
+ *   - 后端 yaml → 本层结构的转换在 ../parser/cascader.ts。
+ *
+ * 定位：**多个 el-select 组合**出来的级联选择（不是 el-cascader）。
+ *   - 树有几层就渲染几个 select，**默认全部显示**（不是选了第一级才冒出第二级）；
+ *   - 每一级各自带标签，标签来自节点上的 fieldLabel；
+ *   - 上一级改选 → 下面各级的**值清空、选项换成新分支**
+ *     （选了广西就只会出现桂林/柳州，不会混进湖南的城市）。
+ *
+ * 为什么不用 el-cascader：业务上每一级都是一个**独立的查询字段 / 表单字段**
+ * （province / city / county 各自入库、各自拼查询串），一个数组值表达不了。
+ *
+ * 节点上的字段含义（都是描述「下一级」的，不是自己的）：
+ *   node.field      —— **下一级**的字段名
+ *   node.fieldLabel —— **下一级**的标签文字（不写则退回用下一级的 field）
+ * 第 1 级的字段 / 标签来自配置的 field / fieldLabel / label。
+ *
+ * 例：
+ *   {
+ *     field: 'province', fieldLabel: '省份', options: [
+ *       {label: '广西', value: 'gx', field: 'city', fieldLabel: '地级市', children: [
+ *         {label: '桂林', value: 'gl', field: 'county', fieldLabel: '县城', children: [
+ *           {label: '兴安', value: 'xingan'},
+ *         ]},
+ *         {label: '柳州', value: 'lz'},
+ *       ]},
+ *       {label: '湖南', value: 'hn'},
+ *     ],
+ *   }
+ *   → 渲染 3 个 select：省份 / 地级市 / 县城（即使一级都没选也都画出来），
+ *     所以一项级联会往 model 里写**多个 key**：{province, city, county}。
+ */
+/** 级联选项节点（树形；带 children 即构成下一级） */
+export interface CascaderOption {
+    /** 显示文字 */
+    label: string;
+    /** 实际值 */
+    value: any;
+    /**
+     * **下一级**的字段名。
+     * 例：{label: '广西', value: 'gx', field: 'city', children: [...]}
+     *     → 选中广西后，下一级（桂林 / 柳州）的值写进 model.city
+     */
+    field?: string;
+    /** **下一级**的标签文字（例：'地级市'）。不写则退回用下一级的 field 当标签。 */
+    fieldLabel?: string;
+    /** 子级选项；有 children 的节点下方会多一个 el-select（层级总数 = 树的最大深度） */
+    children?: CascaderOption[];
+    /** 是否禁用该项 */
+    disabled?: boolean;
+    /** 其它透传给 el-option 的字段原样保留 */
+    [key: string]: any;
+}
+/**
+ * 「级联数据源」——只要能表达「第 1 级叫什么 + 一棵选项树」就够。
+ * USearch 的 SearchItem 结构上就满足它，所以能直接喂给 utils/cascader.ts 的工具函数。
+ */
+export interface CascaderSource {
+    /** 第 1 级的字段名（支持点路径，如 'info.province'） */
+    field: string;
+    /** 第 1 级的标签文字（fieldLabel 优先） */
+    label?: string;
+    /** 第 1 级的标签文字（与节点上的 fieldLabel 同位写法） */
+    fieldLabel?: string;
+    /** 选项树 */
+    options?: CascaderOption[];
+    /** 其它字段原样保留 */
+    [key: string]: any;
+}
+/** UCascader 配置：数据源 + 外观 */
+export interface CascaderOptions extends CascaderSource {
+    /** 标签位置：left 左边 | top 上面，默认 'left' */
+    labelPosition?: 'left' | 'top';
+    /** 标签宽度（labelPosition 为 left 时生效），数字按 px，默认 80 */
+    labelWidth?: number | string;
+    /** 标签对齐（labelPosition 为 left 时生效），默认 'right'；top 时恒为左对齐 */
+    labelAlign?: 'left' | 'center' | 'right';
+    /** 是否显示标签，默认 true */
+    showLabel?: boolean;
+    /** 各级之间的间距（px），默认 8 */
+    gutter?: number;
+    /** 透传给每一级 el-select 的属性（filterable / clearable / size …） */
+    props?: Record<string, any>;
+    /** 第 1 级的占位提示 */
+    placeholder?: string;
+    /** 第 2 级及以后的占位提示，默认 '请选择' */
+    subPlaceholder?: string;
+    /** 是否禁用整组 */
+    disabled?: boolean;
+}
+/** 级联实际渲染出来的一级 */
+export interface CascaderLevel {
+    /** 该级的字段名 */
+    field: string;
+    /** 该级的标签文字 */
+    label: string;
+    /** 该级的选项（上级没选 / 该分支没有下级时是空数组，但这一级照样渲染） */
+    options: CascaderOption[];
+    /** 该级当前选中的值 */
+    value: any;
+}
+/**
+ * 「某一级」的描述 —— 级联**只声明了层级、选项树在字典里**时用
+ * （yaml 用 children 链写法的：每级只写 field / fieldLabel，整棵树来自一个 dictType）。
+ *
+ * 解析层算出每级叫什么后带在 `SearchItem.cascaderLevels` 上；
+ * 使用方取到字典树后调 `new CascaderParser().stampLevels(树, levels)` 把每级的字段名打上去。
+ */
+export interface CascaderLevelMeta {
+    /** 该级的字段名 */
+    field: string;
+    /** 该级的标签文字 */
+    label: string;
+    /** 该级的选项从哪个字典类型取（children 链写法才有） */
+    dictType?: string;
+    /** 该级自己的 el-select 透传属性 */
+    props?: Record<string, any>;
+}
+/** 级联变化事件的载荷 */
+export interface CascaderChangePayload {
+    /** 第几级（从 0 开始） */
+    level: number;
+    /** 该级的字段名 */
+    field: string;
+    /** 该级新选中的值 */
+    value: any;
+    /** 写回后的完整模型对象 */
+    model: Record<string, any>;
+    /** 当前各级快照 */
+    levels: CascaderLevel[];
+}

package/dist/model/form.d.ts

@@ -0,0 +1,143 @@
+import { FormItemRule } from 'element-plus';
+/**
+ * 控件类型：直接写 Element Plus 的组件名。
+ * 支持 EP 常用表单控件，也允许写任意自定义组件名（会原样交给 <component :is> 解析）。
+ */
+export type FormControlType = 'el-input' | 'el-input-number' | 'el-select' | 'el-radio-group' | 'el-checkbox-group' | 'el-switch' | 'el-slider' | 'el-rate' | 'el-color-picker' | 'el-date-picker' | 'el-time-picker' | 'el-time-select' | 'el-cascader' | 'el-tree-select' | 'el-autocomplete' | 'el-segmented' | (string & {});
+/** 选项数据（el-select / el-radio-group / el-checkbox-group / el-cascader 用） */
+export interface FormFieldOption {
+    /** 显示文字 */
+    label: string;
+    /** 实际值 */
+    value: any;
+    /** 是否禁用该项 */
+    disabled?: boolean;
+    /** 子选项（级联 / 树形选择用） */
+    children?: FormFieldOption[];
+    /** 其它透传给选项组件的属性 */
+    [key: string]: any;
+}
+/** 单个字段配置 */
+export interface FormFieldConfig {
+    /**
+     * 字段名，对应表单数据里的 key。
+     * 支持点路径（如 'info.remark'），会直接用作 el-form-item 的 prop 参与校验。
+     */
+    field: string;
+    /** 控件类型（EP 组件名），默认 'el-input' */
+    type?: FormControlType;
+    /** 标签文字 */
+    label?: string;
+    /**
+     * 透传给控件的属性（如 placeholder / clearable / multiple / rows / show-password / filterable …）。
+     * EP 有什么属性就写什么，库不做二次封装。
+     */
+    props?: Record<string, any>;
+    /** 选项数据（el-select / el-radio-group / el-checkbox-group / el-cascader 用） */
+    options?: FormFieldOption[];
+    /** 校验规则，直接吃 async-validator 格式（EP 原生） */
+    rules?: FormItemRule[];
+    /**
+     * 是否必填。等价于往 rules 里补一条 {required: true, ...}，
+     * trigger 会根据控件类型自动选 blur / change（见 ../utils/form.ts 的 getValidateTrigger）。
+     */
+    required?: boolean;
+    /** 栅格占宽（24 栅格制）。不传则按表单的 columns 均分 */
+    colSpan?: number;
+    /** 是否禁用该字段（会与表单一级的 disabled 取或） */
+    disabled?: boolean;
+    /** 字段下方的灰色说明文字 */
+    tip?: string;
+    /** 是否隐藏该字段（隐藏后不渲染，但仍参与数据） */
+    hidden?: boolean;
+    /** el-form-item 的其它属性（如 labelWidth / required / showMessage / error …） */
+    itemProps?: Record<string, any>;
+    /** 默认值。仅用于 utils/form.ts 的 getDefaultModel() 生成初始数据，组件本身不注入 */
+    default?: any;
+}
+/** UForm 表单级配置 */
+export interface FormOptions {
+    /** 字段列表 */
+    fields: FormFieldConfig[];
+    /** 每行几列（1~4），底层用 el-row / el-col 的 24 栅格等分，默认 1 */
+    columns?: number;
+    /** 栅格间距（px），默认 0 */
+    gutter?: number;
+    /** 标签宽度（直接给 el-form 的 label-width） */
+    labelWidth?: string | number;
+    /** 标签位置，默认 'right'（EP 默认值） */
+    labelPosition?: 'left' | 'right' | 'top';
+    /** 标签后缀，默认 '：' */
+    labelSuffix?: string;
+    /** 是否隐藏必填星号 */
+    hideRequiredAsterisk?: boolean;
+    /** 表单项尺寸 */
+    size?: 'large' | 'default' | 'small';
+    /** 是否禁用整个表单 */
+    disabled?: boolean;
+}
+/**
+ * 表单接口地址（yaml 的 api 段原样带出）。
+ *
+ * UForm 自己**永远不碰**这几个地址 —— 它们由 <UTablePage> 或使用方消费：
+ *   get  回显单条（拼 `?<key>=<行id>`）
+ *   add  新增（POST 整个表单数据）
+ *   edit 编辑（POST 整个表单数据，主键在数据里）
+ */
+export interface FormApi {
+    /** 回显单条：GET，组件会拼 `?<key>=<value>` */
+    get?: string;
+    /** 新增提交地址（POST） */
+    add?: string;
+    /** 编辑提交地址（POST） */
+    edit?: string;
+    /** 其它自定义接口地址原样保留 */
+    [key: string]: any;
+}
+/**
+ * 表单的页面级布局（yaml 的 layout 段原样带出）。
+ * UForm 不消费它（表单组件只认 FormOptions 里的 columns / labelPosition），
+ * 由打开表单的那一方决定怎么用 —— 比如 UTablePage 用 width 当弹窗宽度。
+ */
+export interface FormLayout {
+    /** 打开方式：dialog 弹窗（默认）| page 整页 | drawer 抽屉 */
+    open?: 'dialog' | 'page' | 'drawer' | (string & {});
+    /** 弹窗 / 抽屉宽度（数字按 px） */
+    width?: number | string;
+    /** 每行几列（与 FormOptions.columns 同义，解析时已并进去，这里保留原始值） */
+    columns?: number;
+    /** 标签位置 */
+    labelPosition?: 'left' | 'right' | 'top';
+    /** 按钮对齐 */
+    buttonAlign?: 'left' | 'center' | 'right';
+    /** 其它自定义键原样保留 */
+    [key: string]: any;
+}
+/**
+ * 表单配置（`GetFormConfig(id)` 的返回值）。
+ *
+ *   FormConfig = {formOptions, api?, layout?, meta?}
+ *     ├─ formOptions → 直接喂 <UForm :options>
+ *     └─ api / layout / meta → 页面级配置，组件不吃，打开表单的那一方消费
+ */
+export interface FormConfig {
+    /** 表单组件配置，直接喂 <UForm :options> */
+    formOptions: FormOptions;
+    /** 接口地址（yaml 的 `api` 段）：get / add / edit */
+    api?: FormApi;
+    /** 页面级布局（yaml 的 `layout` 段）：open / width / buttonAlign … */
+    layout?: FormLayout;
+    /** 后端 yaml 的 meta 段原样带出（formId / title / version） */
+    meta?: Record<string, any>;
+}
+/** 字段插槽的作用域参数 */
+export interface FormFieldSlotProps {
+    /** 当前字段的配置 */
+    field: FormFieldConfig;
+    /** 当前字段的值 */
+    value: any;
+    /** 整个表单数据 */
+    model: Record<string, any>;
+    /** 把值写回表单（等价于控件自己的 v-model 行为） */
+    setValue: (value: any) => void;
+}

package/dist/model/grid.d.ts

@@ -0,0 +1,53 @@
+export type GridDirection = 'row' | 'column';
+export interface GridOptions {
+    /**
+     * 容器宽度。数字按 px 处理，字符串原样使用（如 '80%' / '600px' / 'calc(100% - 24px)'）。
+     * 不传则撑满父容器（100%）。
+     */
+    width?: number | string;
+    /**
+     * 容器高度。数字按 px 处理，字符串原样使用。
+     * 不传则撑满父容器（100%）。
+     */
+    height?: number | string;
+    /**
+     * 列数（1~12）。卡片宽度 = 12 / columns 份，即用 quasar 的 .col-<12/columns> 等分整行。
+     * 只在 direction === 'row' 时作为「列」，direction === 'column' 时作为「行」。
+     * 不传或超出 1~12（且不能整除 12）时，退化为 .col（每张卡片等分、自动换行）。
+     */
+    columns?: number;
+    direction?: GridDirection;
+    /**
+     * 卡片间距（quasar 的 q-gutter-<size>，即卡片之间的间隔）。
+     * 取值：none / xs(4px) / sm(8px) / md(16px) / lg(24px) / xl(48px)，默认 md。
+     * 传 none 表示无间距。
+     */
+    gutter?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    /**
+     * 容器内边距（quasar 的 q-pa-<size>）。取值同 gutter，默认 md。
+     * 传 none 表示无内边距。
+     */
+    padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    count?: number;
+    items?: any[];
+}
+export interface CardOptions {
+    /**
+     * 卡片宽度。不传则由容器的 columns 算出（.col-<12/columns>）。
+     * 传了就固定该宽度：数字按 px，字符串原样使用（如 '200px' / '30%'）。
+     */
+    width?: number | string;
+    /**
+     * 卡片高度。数字按 px，字符串原样使用。
+     * 不传则由内容撑开（并受容器 align 限制）。
+     */
+    height?: number | string;
+    direction?: GridDirection;
+    padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    bordered?: boolean;
+}
+export interface GridCardSlotProps {
+    index: number;
+    item: any;
+    options: CardOptions;
+}

package/dist/model/menu.d.ts

@@ -0,0 +1,140 @@
+/**
+ * UMenu —— 菜单的数据结构定义（model 层）
+ *
+ * 本层只定义**数据结构**，不放任何逻辑：
+ *   - 逻辑（菜单项兜底规范化）在 ../utils/menu.ts；
+ *   - 后端 yaml → 本层结构的转换在 ../parser/menu.ts。
+ *
+ * 设计原则：
+ *   1. UMenu 是**纯展示组件**：不发任何请求，菜单数据全部由外部传入
+ *      （`options` prop 或 `setOptions()`）。
+ *   2. 只负责「画出来 + 把点击意图抛出去」——点击由外部按 payload.type 分发，
+ *      组件自己不 router.push、不 window.open。
+ *   3. 默认**全部展开**，带子菜单的一级菜单标题加粗当分组标题用（`expandAll` 默认 true）。
+ *
+ * 数据来源（谁把菜单塞进来，组件不管）：
+ *   - 静态 yaml：GET /api/form?type=menus&id=<id> → Qf.GetMenuConfig(id) 转成 MenuOptions
+ *   - 字典菜单：使用方自己取字典树（yaml 里的 dictType 会原样带出来）后填进 `menus`
+ */
+/**
+ * 菜单跳转类型
+ *   route —— 前端路由（vue-router），取 path
+ *   url   —— 外部链接，取 path
+ *   form  —— 表单配置（config/forms/<id>.yaml），由使用方打开表单
+ *   table —— 表格配置（config/tables/<id>.yaml），由使用方打开表格
+ *   menu  —— 菜单配置（config/menus/<id>.yaml），由使用方切换菜单
+ */
+export type MenuJumpType = 'route' | 'url' | 'form' | 'table' | 'menu';
+/** url 类型的打开方式：new 新窗口（默认）| self 当前窗口 */
+export type MenuOpenType = 'new' | 'self';
+/** 菜单项（最多支持 2 级） */
+export interface MenuItem {
+    /** 菜单名称 */
+    label: string;
+    /** 跳转类型，默认 route */
+    type?: MenuJumpType;
+    /** 跳转目标：route -> 路由地址；url -> 完整地址 */
+    path?: string;
+    /**
+     * 配置文件 id（type 为 form/table/menu 时使用，
+     * 对应 config/<forms|tables|menus>/<id>.yaml）。不写则回退用 path。
+     */
+    id?: string;
+    /** 打开方式（仅 url 类型生效）：new 新窗口 | self 当前窗口 */
+    open?: MenuOpenType;
+    /** 图标名（@element-plus/icons-vue 的组件名，如 User / Setting） */
+    icon?: string;
+    /** 二级菜单（再往下不再展开） */
+    children?: MenuItem[];
+    /** 其它自定义字段原样保留（使用方可按自己的业务取用） */
+    [key: string]: any;
+}
+/**
+ * UMenu 配置
+ * 组件只认下面这些键；其余键原样忽略（yaml 里的额外信息请走解析层消化）。
+ */
+export interface MenuOptions {
+    /** 项目名称：sidebar 模式显示在顶部，horizontal 模式显示在最左侧；为空不显示 */
+    projectName?: string;
+    /** 项目 logo 图片地址 */
+    logo?: string;
+    /** 菜单模式：sidebar 左侧栏 | horizontal 水平，默认 'sidebar' */
+    mode?: 'sidebar' | 'horizontal';
+    /** 菜单宽度（仅 sidebar 模式生效），默认 220 */
+    width?: number;
+    /**
+     * 是否默认展开全部子菜单，**默认 true**。
+     * 展开时带子菜单的一级菜单标题加粗，当分组标题用。
+     */
+    expandAll?: boolean;
+    /** 是否只允许同时展开一个子菜单，默认 false（expandAll 为 true 时该项无效） */
+    uniqueOpened?: boolean;
+    /** 菜单列表 */
+    menus?: MenuItem[];
+    /** 是否显示退出登录区域，默认 true */
+    showLogout?: boolean;
+    /** 退出登录按钮文本，默认 '退出登录' */
+    logoutText?: string;
+    /**
+     * 字典菜单类型 —— yaml 里写了就原样带出来给使用方。
+     * 非空表示菜单数据要去字典接口按该 dictType 取一棵树（取数属于使用方的活），
+     * 取到后填进 `menus`。
+     */
+    dictType?: string;
+    /** 其它自定义字段原样保留 */
+    [key: string]: any;
+}
+/**
+ * 菜单配置（`GetMenuConfig(id)` 的返回值）。
+ *
+ * 和 TablePageConfig / FormConfig 一个思路：yaml 里除了组件直接吃的部分，
+ * 还有些**不属于组件**的页面级信息，所以包一层带出来。
+ *
+ *   MenuConfig = {menuOptions, menuId?, meta?}
+ *     ├─ menuOptions → 直接喂 <UMenu :options>
+ *     └─ menuId / meta → yaml 的 meta 段原样带出（使用方记录「当前是哪份菜单」时用）
+ *
+ * 字典菜单的 `dictType` 不在这一层 —— 它就在 MenuOptions 上（使用方取到字典树后填 menus）。
+ */
+export interface MenuConfig {
+    /** 菜单组件配置，直接喂 <UMenu :options> */
+    menuOptions: MenuOptions;
+    /** 菜单配置 ID（yaml 的 meta.menuId） */
+    menuId?: string;
+    /** 后端 yaml 的 meta 段原样带出（menuId / title / version） */
+    meta?: Record<string, any>;
+}
+/** 菜单点击事件载荷（外部按 type 判断跳转类型） */
+export interface MenuClickPayload {
+    /** 跳转类型：route / url / form / table / menu */
+    type: MenuJumpType;
+    /** 原始跳转目标（route/url 为目标地址，form/table/menu 一般为配置文件名） */
+    path: string;
+    /** type === 'route' 时的路由地址 */
+    route?: string;
+    /** type === 'url' 时的完整地址 */
+    url?: string;
+    /** type === 'url' 时的打开方式 */
+    open?: MenuOpenType;
+    /** type 为 form / table / menu 时的配置文件 id（取自菜单项 id，缺失时回退 path） */
+    id?: string;
+    /** 被点击的菜单项原始配置 */
+    item: MenuItem;
+    /** 菜单层级（1 或 2） */
+    level: number;
+    /** el-menu 的 index 链路 */
+    indexPath: string[];
+    /** el-menu 的 index */
+    index: string;
+}
+/** #menu-title / #menu-item 插槽的作用域参数 */
+export interface MenuItemSlotProps {
+    /** 当前菜单项 */
+    item: MenuItem;
+    /** 层级：1 一级 | 2 二级 */
+    level: number;
+    /** 同级中的下标 */
+    index: number;
+    /** 二级菜单的父项（一级项为 null） */
+    parent: MenuItem | null;
+}

package/dist/model/results.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 单元格文字对齐方式。
+ * 检验结果表里「结果」「单位」「提示」这类短列习惯居中，「项目」「参考区间」左对齐。
+ */
+export type ResultsAlign = 'left' | 'center' | 'right';
+/**
+ * 一列的定义（`options.columns` 的成员）—— 「自定义列」配的就是它。
+ *
+ * 列宽规则（决定这一列分到多宽）：
+ *   ① 配了 `width`      —— 固定值（数字按 px，字符串原样如 `'20%'` / `'1fr'`）
+ *   ② 只配了 `minWidth` —— `minmax(minWidth, 1fr)`：至少这么宽，剩余空间一起分
+ *   ③ 都没配            —— `minmax(0, 1fr)`：把剩余空间等分
+ * 所以「只给两列配宽度、其余自动铺满」直接写就行，不用算百分比。
+ */
+export interface ResultsColumn {
+    /** 表头文字 */
+    label?: string;
+    /**
+     * 取值字段。支持点路径（`'item.name'` → `row.item.name`）。
+     * 同时兼作插槽名（当 `slot: true` 时）。
+     */
+    prop?: string;
+    /** 列宽（数字按 px，字符串原样）。不配则该列等分剩余宽度 */
+    width?: number | string;
+    /** 最小列宽（数字按 px，字符串原样）。配了它、没配 width 时：至少这么宽，剩余空间一起分 */
+    minWidth?: number | string;
+    /** 单元格对齐，默认 `left` */
+    align?: ResultsAlign;
+    /** 表头对齐，默认跟随 `align` */
+    headerAlign?: ResultsAlign;
+    /**
+     * 该列单元格用插槽渲染（结果值要标红/加箭头时用）：
+     *   字符串 —— 插槽名，如 `slot: 'flag'` → 使用方写 `<template #flag="{value, row}">`
+     *   true   —— 用 `prop` 当插槽名
+     * 使用方没提供该插槽时自动退回纯文本（不会渲染成空白）。
+     */
+    slot?: string | boolean;
+}
+/**
+ * 检验结果表配置（UResults 的 `options`）。
+ * 直接喂给组件即可显示 —— 解析层（后端 yaml）负责把它拼出来。
+ */
+export interface ResultsOptions {
+    /** 列定义，数组顺序即列顺序（核心配置） */
+    columns?: ResultsColumn[];
+    /** 数据行（组件 `data` prop 的兜底）。两者都给时以 `data` prop 为准 */
+    data?: any[];
+    /** 斑马纹（隔行底色），默认 false */
+    striped?: boolean;
+    /** 行 / 列分割线与外框，默认 true */
+    border?: boolean;
+    /** 表头背景色，默认 `'#f5f7fa'` */
+    headerBg?: string;
+    /** 表头文字颜色，默认 `'#303133'` */
+    headerColor?: string;
+    /** 数据行背景色，默认 `'#fff'` */
+    itemBg?: string;
+    /** 斑马纹那几行的底色，默认 `'#fafafa'`（要对比明显就往更深的颜色给） */
+    stripeBg?: string;
+    /** 组件宽度（数字按 px，字符串原样），默认 `'100%'` */
+    width?: number | string;
+    /**
+     * 组件高度（数字按 px，字符串原样），默认不限制（随内容自适应）。
+     * 配了它，内容超出时在内容区滚动、**表头吸顶不动**。
+     */
+    height?: number | string;
+    /** 行高（数字按 px）—— 单元格最小高度；内容多把行撑高时以内容为准 */
+    rowHeight?: number | string;
+    /** 表头行高（数字按 px），同 `rowHeight` */
+    headerHeight?: number | string;
+    /** 值为空时的占位，默认 `'-'`。传空串表示什么都不显示 */
+    emptyText?: string;
+    /** 一行数据都没有时的文案，默认 `'暂无数据'`（想自定义布局用 `#empty` 插槽） */
+    emptyDataText?: string;
+}
+/** 列级插槽（`column.slot` 指定的那个）的作用域 */
+export interface ResultsCellSlotProps {
+    /** 当前整行数据 */
+    row: any;
+    /** 当前列定义 */
+    column: ResultsColumn;
+    /** 第几行，从 0 开始 */
+    rowIndex: number;
+    /** 第几列，从 0 开始 */
+    columnIndex: number;
+    /** 该单元格原始值（未经空值占位处理） */
+    value: any;
+    /** 该单元格的展示文本（空值已按 `emptyText` 处理） */
+    text: string;
+}

package/dist/model/search.d.ts

@@ -0,0 +1,93 @@
+import { CascaderLevel, CascaderLevelMeta, CascaderOption } from './cascader';
+/**
+ * 搜索项类型：直接写 Element Plus 的组件名也可以（'el-xxx' 原样交给 <component :is>）。
+ *   input     —— el-input 文本输入
+ *   number    —— el-input-number 数字输入
+ *   select    —— el-select 下拉（选项带 children 时自动交给 UCascader 渲染成多级联动）
+ *   date      —— el-date-picker 单日期
+ *   daterange —— el-date-picker 日期范围
+ *   datetime  —— el-date-picker 日期时间
+ */
+export type SearchItemType = 'input' | 'number' | 'select' | 'date' | 'daterange' | 'datetime' | (string & {});
+/** select 的选项节点（就是级联选项，见 ./cascader.ts 的 CascaderOption） */
+export type SearchOption = CascaderOption;
+/** 级联 select 实际渲染出来的一级（见 ./cascader.ts 的 CascaderLevel） */
+export type SearchSelectLevel = CascaderLevel;
+/** 单个搜索项 */
+export interface SearchItem {
+    /**
+     * 字段名（级联 select 时 = **第一级**的字段名）。
+     * 支持点路径（如 'info.remark'）。
+     */
+    field: string;
+    /** 类型，默认 'input' */
+    type?: SearchItemType;
+    /** 标签文字，默认用 fieldLabel / field */
+    label?: string;
+    /**
+     * 级联 select **第一级**的标签（与节点上的 fieldLabel 同位写法）。
+     * 不写则用 item.label。
+     */
+    fieldLabel?: string;
+    /** select 的选项（树形，可有 children 形成级联） */
+    options?: SearchOption[];
+    /**
+     * 透传给控件的属性：
+     * clearable / filterable / multiple / placeholder / value-format / start-placeholder …
+     */
+    props?: Record<string, any>;
+    /** 该项占宽（css 值，如 '240px' / '100%'），不传用 SearchOptions.itemWidth */
+    width?: number | string;
+    /** 是否隐藏该项（不渲染，但也不从 model 里删值） */
+    hidden?: boolean;
+    /**
+     * 字典类型。解析层从 yaml 的 dictType 带过来，
+     * 组件不认这个字段 —— 选项由使用方按 dictType 取好后塞进 options。
+     */
+    dictType?: string;
+    /**
+     * 级联项**只声明了层级、选项树在字典里**（yaml 用 children 链写法）时，
+     * 解析层把层级链带在这里。使用方取到字典树后：
+     * `item.options = new CascaderParser().stampLevels(树, item.cascaderLevels)`。
+     * 内联了选项树（或非级联项）时不会有这个字段。
+     */
+    cascaderLevels?: CascaderLevelMeta[];
+    /** 其它自定义字段原样保留（配置里未被本层消费的键都在这里） */
+    [key: string]: any;
+}
+/** USearch 整体配置 */
+export interface SearchOptions {
+    /** 搜索项列表 */
+    items: SearchItem[];
+    /** 标签位置：left 左边 | top 上面，默认 'left' */
+    labelPosition?: 'left' | 'top';
+    /** 标签宽度（labelPosition 为 left 时生效），数字按 px，默认 80 */
+    labelWidth?: number | string;
+    /** 标签对齐（labelPosition 为 left 时生效），默认 'right'；top 时恒为左对齐 */
+    labelAlign?: 'left' | 'center' | 'right';
+    /** 项与项之间的间距（px），默认 12 */
+    gutter?: number;
+    /** 搜索项默认占宽（css 值），默认 '240px' */
+    itemWidth?: number | string;
+    /** 是否显示「查询」按钮，默认 true */
+    showSearch?: boolean;
+    /** 是否显示「重置」按钮，默认 true */
+    showReset?: boolean;
+    /** 查询按钮文字，默认 '查询' */
+    searchText?: string;
+    /** 重置按钮文字，默认 '重置' */
+    resetText?: string;
+    /** 是否禁用整栏 */
+    disabled?: boolean;
+}
+/** 搜索项插槽的作用域参数 */
+export interface SearchItemSlotProps {
+    /** 当前项的配置 */
+    item: SearchItem;
+    /** 当前项的值（级联项为第一级的值） */
+    value: any;
+    /** 整个搜索条件对象 */
+    model: Record<string, any>;
+    /** 写回整个条件对象 */
+    setModel: (model: Record<string, any>) => void;
+}