@kayak-sj/design 1.0.49 → 1.0.51

package/dist/components/k-table/composables/useTableRowSort.d.ts

@@ -9,6 +9,15 @@ export interface UseTableRowSortOptions {
     rebindKey: MaybeRefOrGetter<unknown>;
     onSortEnd: (event: Sortable.SortableEvent) => void;
 }
+/**
+ * 行拖拽排序（SortableJS 绑定 ElTable tbody）。
+ *
+ * - 拖拽把手：`.sort-handle`
+ * - 禁止拖拽行：单元格加 `.ignore-elements`，或通过 `sortFilter` 索引
+ * - `rebindKey` 变化时自动重新绑定（列显隐后 DOM 结构变化）
+ *
+ * @param options - 见 {@link UseTableRowSortOptions}
+ */
 export declare function useTableRowSort(options: UseTableRowSortOptions): {
     initSortable: () => Promise<void>;
     destroySortable: () => void;

package/dist/components/k-table/composables/useTableTreeLoad.d.ts

@@ -2,6 +2,18 @@ import { TableInstance } from 'element-plus';
 import { MaybeRefOrGetter, Ref } from 'vue';
 /** ElTable 树懒加载回调签名 */
 export type TreeLoadHandler<T> = (row: T, treeNode: unknown, resolve: (data: T[]) => void) => void;
+/**
+ * 树表懒加载辅助。
+ *
+ * 包装 ElTable `load` 回调并缓存节点上下文，供 `refreshTree` 按父节点刷新子级。
+ * 对应旧版 `refreshTableTree(parentId)`。
+ *
+ * @typeParam T - 表格行数据类型
+ * @param options.tableRef - ElTable 实例 ref
+ * @param options.rowKey - 行主键字段名
+ * @param options.load - 业务侧懒加载回调（可选）
+ * @returns `wrapLoad` 包装 load；`refreshTree` 按父节点 rowKey 重拉子级
+ */
 export declare function useTableTreeLoad<T>(options: {
     tableRef: Ref<TableInstance | undefined>;
     rowKey: MaybeRefOrGetter<string>;

package/dist/components/k-table/dictOptions.d.ts

@@ -4,5 +4,10 @@ export interface DictGroupRow {
     item_key: unknown;
     item_value: unknown;
 }
-/** 将 getGroupDict 结果转为表单下拉选项 */
+/**
+ * 将 `getGroupDict` 结果转为表单 / 查询区下拉选项。
+ *
+ * @param rows - 字典分组行列表（`item_key` / `item_value`）
+ * @returns `{ value, label }` 选项数组，可直接赋给 Select `options`
+ */
 export declare function mapGroupDictToOptions(rows: DictGroupRow[]): DictSelectOption[];

package/dist/components/k-table/report/exportKTableReport.d.ts

@@ -3,22 +3,47 @@ import { KTableInstance } from '../composables/useKTable';
 import { KTableColumn } from '../types';
 import { KTableExportApi } from './types';
 import { PickExportColumnsOptions } from './pickExportColumns';
+/**
+ * {@link exportKTableReport} 入参。
+ *
+ * @typeParam T - 表格行数据类型
+ */
 export interface ExportKTableReportOptions<T> extends PickExportColumnsOptions {
+    /** KTable 实例 ref（需能调用 `getQueryRef()?.getParams()`） */
     tableRef: Ref<KTableInstance<T> | undefined>;
+    /** 参与导出的列配置，会再经 `pickExportColumns` 过滤 */
     columns: KTableColumn<T>[];
+    /** 导出接口；入参为 `{ globColumnlist, jsondata }` */
     exportApi: KTableExportApi;
-    /** 与列表 :convert-params 保持一致 */
+    /** 与列表 `:convert-params` 保持一致 */
     convertParams?: (params: Record<string, unknown>) => Record<string, unknown>;
 }
-/** 导出当前 KTable 查询条件 */
+/**
+ * 导出当前 KTable 查询条件下的报表。
+ *
+ * 从 `tableRef` 读取查询参数，经 `convertParams` 后与列配置一并交给 `exportApi`。
+ * 需要防重 / 响应式列时请用 {@link useExportKTableReport}。
+ *
+ * @typeParam T - 表格行数据类型
+ * @param options - 见 {@link ExportKTableReportOptions}
+ * @returns `exportApi` 的 Promise 结果
+ */
 export declare function exportKTableReport<T>(options: ExportKTableReportOptions<T>): Promise<unknown>;
-/** 弹窗等场景：直接传入已转换的 jsondata */
+/**
+ * 弹窗等场景：直接传入已转换的 `jsondata` 导出报表（不读表格查询区）。
+ *
+ * @typeParam T - 表格行数据类型
+ * @param options.columns - 参与导出的列配置
+ * @param options.jsondata - 已转换的导出查询参数
+ * @param options.exportApi - 导出接口
+ * @returns `exportApi` 的 Promise 结果
+ */
 export declare function exportKTableReportData<T>(options: {
     columns: KTableColumn<T>[];
     jsondata: Record<string, unknown>;
     exportApi: KTableExportApi;
 } & PickExportColumnsOptions): Promise<unknown>;
-/** @deprecated 使用 exportKTableReport */
+/** @deprecated 使用 {@link exportKTableReport} */
 export declare const exportReportTable: typeof exportKTableReport;
-/** @deprecated 使用 exportKTableReportData */
+/** @deprecated 使用 {@link exportKTableReportData} */
 export declare const exportReportData: typeof exportKTableReportData;

package/dist/components/k-table/types.d.ts

@@ -140,6 +140,10 @@ export interface DictService {
     /** 分组字典 → `{ label, value }[]`，供 Select / Checkbox 直接使用 */
     getGroupOptions?: (dictType: string) => DictSelectOption[];
 }
+/**
+ * 字典服务注入键。
+ * 业务 app 通过 `provide(DICT_KEY, dictService)` 注入；KTable / 单元格字典列经 `inject` 消费。
+ */
 export declare const DICT_KEY: InjectionKey<DictService>;
 /**
  * 列表页声明式配置（可选）。

package/dist/components/k-upload/utils/uploadFileValue.d.ts

@@ -2,23 +2,23 @@ import { KUploadFileItem } from '../../../config/uploadConfig';
 /**
  * Upload 工具函数约定：
  *
- * 1. 回填：toUploadFiles(资源id, { fileName, listType }) → KUploadFileItem[]
- *    需 imp_id 时用 createUploadFileItem(id, name, { impId, listType })
- * 2. 提交：统一 toUploadSubmitFields(字段值) → { resource_id, file_name, imp_id, imp_count? }
- *    普通文件取 resource_id / file_name；导入类取 imp_id / imp_count，内部自动识别，无需区分函数。
+ * 1. 回填：`toUploadFiles(资源id, { fileName, listType })` → `KUploadFileItem[]`
+ *    需 `imp_id` 时用 `createUploadFileItem(id, name, { impId, listType })`
+ * 2. 提交：统一 `toUploadSubmitFields(字段值)` → `{ resource_id, file_name, imp_id, imp_count? }`
+ *    普通文件取 `resource_id` / `file_name`；导入类取 `imp_id` / `imp_count`，内部自动识别。
  */
 export interface CreateUploadFileItemOptions {
-    /** 对齐 KUpload listType，决定预览/下载 URL 前缀 */
+    /** 对齐 KUpload `listType`，决定预览/下载 URL 前缀 */
     listType?: string;
     impId?: string;
 }
 export interface ToUploadFilesOptions {
-    /** 展示文件名；未提供时回退为 resource_id */
+    /** 展示文件名；未提供时回退为 `resource_id` */
     fileName?: string;
     listType?: string;
 }
 export interface ToUploadSubmitFieldsOptions {
-    /** value 已是资源 id 字符串时，用于补齐 file_name */
+    /** value 已是资源 id 字符串时，用于补齐 `file_name` */
     fileName?: string;
 }
 /** 提交用统一结构：普通文件与导入类共用，按实际有值的字段取用即可 */
@@ -29,21 +29,49 @@ export type UploadSubmitFields = {
     imp_count?: unknown;
 };
 /**
- * 按 resource_id 构造 KUpload 反显项。
+ * 按 `resource_id` 构造 KUpload 反显项。
  *
- * listType 为 picture 系时使用 SHOW_IMG_URL，其余使用 DOWNLOAD_FILE_URL。
+ * `listType` 为 picture 系时使用 `SHOW_IMG_URL`，其余使用 `DOWNLOAD_FILE_URL`。
+ *
+ * @param resourceId - 资源 id
+ * @param fileName - 展示文件名
+ * @param options - `listType` / `impId`，见 {@link CreateUploadFileItemOptions}
+ * @returns 长度为 1 的 `KUploadFileItem[]`，可直接赋给 KUpload `v-model`
  */
 export declare function createUploadFileItem(resourceId: string, fileName: string, options?: CreateUploadFileItemOptions): KUploadFileItem[];
 /**
- * 将 Upload 字段值规范为组件所需的 KUploadFileItem[]。
+ * 将 Upload 字段值规范为组件所需的 `KUploadFileItem[]`。
+ *
+ * - 已是数组：原样返回
+ * - 资源 id 字符串：经 {@link createUploadFileItem} 构造
+ * - 其他空值：返回 `[]`
+ *
+ * @param value - 接口回填值（资源 id 字符串或已有 fileList）
+ * @param options - `fileName` / `listType`，见 {@link ToUploadFilesOptions}
+ * @returns 可供 KUpload 绑定的文件列表
  */
 export declare function toUploadFiles(value: unknown, options?: ToUploadFilesOptions): KUploadFileItem[];
 /**
  * 将 Upload 字段值规范为接口提交字段。
  *
- * 自动兼容普通文件（resource_id / file_name）与导入类（imp_id / imp_count），
+ * 自动兼容普通文件（`resource_id` / `file_name`）与导入类（`imp_id` / `imp_count`），
  * 业务侧统一调用此函数，按需解构所需字段。
+ *
+ * @param value - KUpload `v-model` 或资源 id 字符串
+ * @param options - 字符串回填时补齐 `file_name`，见 {@link ToUploadSubmitFieldsOptions}
+ * @returns 统一提交结构；无内容时各字段为空串
+ *
+ * @example
+ * ```ts
+ * const { resource_id, file_name } = toUploadSubmitFields(form.attach)
+ * const { imp_id, imp_count } = toUploadSubmitFields(form.importFile)
+ * ```
  */
 export declare function toUploadSubmitFields(value: unknown, options?: ToUploadSubmitFieldsOptions): UploadSubmitFields;
-/** 是否存在可提交的上传内容 */
+/**
+ * 是否存在可提交的上传内容（普通文件或导入类任一有值即可）。
+ *
+ * @param fields - {@link toUploadSubmitFields} 的返回值
+ * @returns 是否具备 `resource_id` 或 `imp_id`
+ */
 export declare function hasUploadSubmitFields(fields: UploadSubmitFields): boolean;

package/dist/config/uploadConfig.d.ts

@@ -41,5 +41,16 @@ export interface UploadConfig {
     /** 由 cms-base 注入，携带 Kayak 会话公共参数 */
     uploadRequest?: (ctx: KayakUploadRequestContext) => Promise<Record<string, unknown>>;
 }
+/**
+ * 合并更新全局 Upload 配置（URL、业务码字段、`uploadRequest` 等）。
+ * 通常由 cms-base 在应用启动时注入会话参数与上传实现。
+ *
+ * @param patch - 部分覆盖的 {@link UploadConfig} 字段
+ */
 export declare function updateUploadConfig(patch: Partial<UploadConfig>): void;
+/**
+ * 读取当前全局 Upload 配置。
+ *
+ * @returns 当前 {@link UploadConfig} 快照（模块单例引用）
+ */
 export declare function getUploadConfig(): UploadConfig;

package/dist/index.d.ts

@@ -6,5 +6,9 @@ export { createUploadFileItem, hasUploadSubmitFields, toUploadFiles, toUploadSub
 export { useFormSchema, mapFieldVisibility, resolveSchemaField } from './components/k-form';
 export { useHandlePageInit, type UseHandlePageInitOptions } from './components/k-handle-page';
 export * from './utils/validators';
-/** 全局注册 @kayak-sj/design 组件（可选，业务侧也可按需 import） */
+/**
+ * 全局注册 `@kayak-sj/design` 组件（可选，业务侧也可按需 import）。
+ *
+ * @param app - Vue 应用实例
+ */
 export declare function setupDesign(app: App): void;