@dazhicheng/ui 1.6.27 → 1.6.28

package/dist/hooks/useFormSchemasLink.d.ts

@@ -2,6 +2,10 @@ import { TtFormSchema } from '../components/tt-form';
 import { Recordable } from '../../../utils/src';
 import { MaybeRef, Ref } from 'vue';
 import { BusinessDataType, DataPermissionOptionsMap } from './useDataPermissionOptions';
+/**
+ * 参与表单联动的业务数据类型（平台、店铺、采购地、业务线、锁单人）。
+ * 排除 userId（用户数据独立拉取，不参与通用联动构建）。
+ */
 type DataType = Exclude<BusinessDataType, "userId">;
 /**
  * 表单使用场景。
@@ -11,7 +15,13 @@ type DataType = Exclude<BusinessDataType, "userId">;
  * 且店铺默认值设为 showAllField ?? 'all'。
  */
 export type FormScene = "list" | "action";
+/**
+ * 透传给字段组件的 props 类型，支持静态对象或根据当前表单状态计算的函数。
+ */
 type FieldComponentProps = Recordable | ((values: Recordable, actions: any, options: SelectOption[]) => Recordable);
+/**
+ * 针对单个数据类型字段的 schema 覆盖与扩展配置。
+ */
 type FieldSchemaConfig = Partial<TtFormSchema> & UseFormSchemasLinkFieldConfig;
 /**
  * 字段 onChange 回调上下文。
@@ -40,8 +50,9 @@ export interface FieldOnChangeContext {
  * 组件 props、校验规则、依赖关系和追加 onChange 行为。
  */
 export interface UseFormSchemasLinkFieldConfig {
-    /** 字段组件，默认使用 TtApiComponent 包装 ElSelectV2 */
+    /** 字段组件，默认使用 TtApiComponent 包装 ElSelectV2 或 TtPanelSelect */
     component?: TtFormSchema["component"];
+    /** 是否支持多选，默认为 true */
     multiple?: boolean;
     /** 透传给字段组件的 props；传函数时会在渲染时接收表单值、操作对象和当前选项 */
     componentProps?: FieldComponentProps;
@@ -54,19 +65,22 @@ export interface UseFormSchemasLinkFieldConfig {
     /** “全部”选项的值，默认为 "all"。用于自定义“全部”选项对应的 value，与 TtPanelSelect 的 showAllField 对齐 */
     showAllField?: string | number;
     /**
-     * @description 自定义过滤数据源
-     * @param values 表单对象
-     * @param options 下拉数据源（完整的）
+     * 自定义过滤数据源
+     * @param values - 当前表单值对象
+     * @param options - 完整的下拉数据源
+     * @returns 过滤后的下拉数据源
      */
     customOptions?: (values: Recordable, options: SelectOption[]) => SelectOption[];
 }
 /**
- * useFormSchemasLink 的批量配置
+ * useFormSchemasLink 的批量配置选项。
  * 可以通过 fromOptions(options) 一次性传入，也可以使用 builder 链式方法逐项配置。
  */
 export interface UseFormSchemasLinkOptions {
     /** 表单场景，默认 list */
     scene?: FormScene;
+    /** 字段路径前缀，用于嵌套对象或数组行（如 "condition" 或 "tableData[0]"） */
+    basePath?: string;
     /** 外部数据源。未传时会按 codes 调用 queryDataPermissionDetailDataTypeContext。 */
     dataSource?: MaybeRef<DataPermissionOptionsMap | undefined>;
     /** 字段级配置，key 为 DataType */
@@ -75,7 +89,7 @@ export interface UseFormSchemasLinkOptions {
     schemas?: Partial<Record<DataType, FieldSchemaConfig>>;
 }
 /**
- * ElSelectV2 消费的统一选项结构。
+ * 下拉组件消费的统一选项结构。
  */
 export type SelectOption = Recordable & {
     /** 展示文案 */
@@ -86,11 +100,21 @@ export type SelectOption = Recordable & {
     platformId?: string | number;
 };
 /**
- * 返回值会包含每个 DataType 对应的 TtFormSchema，以及当前已归一化的下拉数据源。
+ * useFormSchemasLink 构建结果，包含各数据维度的 TtFormSchema、归一化数据源及数组行 schema 工厂函数。
  */
 type UseFormSchemasLinkResult = Record<DataType, TtFormSchema> & {
+    /** 响应式数据源对象 */
     dataSource: Ref<Record<BusinessDataType, SelectOption[]>>;
+    /**
+     * 为指定行路径（如 tableData[0]）生成对应行 schema 映射，共享同一个数据源与配置
+     * @param itemPath - 行路径或嵌套前缀
+     * @returns 对应行的字段 schema 映射
+     */
+    createRowSchemas: (itemPath: string) => Record<DataType, TtFormSchema>;
 };
+/**
+ * useFormSchemasLink 的链式配置构建器。
+ */
 type FormSchemasLinkBuilder = {
     /** 设置为查询筛选场景 */
     list(): FormSchemasLinkBuilder;
@@ -98,13 +122,22 @@ type FormSchemasLinkBuilder = {
     action(): FormSchemasLinkBuilder;
     /** 设置表单场景 */
     scene(scene: FormScene): FormSchemasLinkBuilder;
+    /** 设置路径前缀，支持嵌套对象或数组行路径（如 "items[0]" 或 "query"） */
+    basePath(basePath: string): FormSchemasLinkBuilder;
     /** 指定需要请求和构建的字段类型，默认包含全部 DataType */
     codes(codes: BusinessDataType[]): FormSchemasLinkBuilder;
     /** 使用外部数据源，跳过内部接口请求 */
     dataSource(dataSource: MaybeRef<DataPermissionOptionsMap | undefined>): FormSchemasLinkBuilder;
     /** 覆盖单个字段配置 */
     field(dataType: DataType, config: FieldSchemaConfig): FormSchemasLinkBuilder;
+    /** 构建顶层 schemas 与数据源 */
     build(): UseFormSchemasLinkResult;
+    /**
+     * 为数组子行或嵌套路径生成 schemas，复用当前数据源与配置
+     * @param itemPath - 行或嵌套路径，例如 "tableData[0]"
+     * @returns 对应行的字段 schema 映射
+     */
+    createRowSchemas(itemPath: string): Record<DataType, TtFormSchema>;
 };
 /**
  * 构建数据权限相关的表单联动 schema。
@@ -116,10 +149,11 @@ type FormSchemasLinkBuilder = {
  * - 平台变更时清空店铺值，并按平台过滤店铺选项
  * - 多选字段支持“全部”互斥选择逻辑
  * - action 场景下平台为“全部”或多平台时禁用店铺并取消必填
+ * - 支持深层嵌套字段（如 a.b.c）与数组行（arraySchema）
  *
  * @example
  * ```ts
- * const { platformId, shopId, businessType } = useFormSchemasLink()
+ * const { platformId, shopId, businessType, createRowSchemas } = useFormSchemasLink()
  *   .list()
  *   .codes(["platformId", "shopId", "businessType"])
  *   .field("platformId", {
@@ -133,6 +167,8 @@ type FormSchemasLinkBuilder = {
  *
  * const schemas = [platformId, shopId, businessType];
  * ```
+ *
+ * @returns FormSchemasLinkBuilder 链式构建器
  */
 export declare function useFormSchemasLink(): FormSchemasLinkBuilder;
 export {};