@dazhicheng/ui 1.6.7 → 1.6.8

package/dist/components/tt-vtable/src/public/table-api.d.ts

@@ -0,0 +1,215 @@
+import { ListTable } from '@visactor/vtable';
+import { ComputedRef, Ref } from 'vue';
+import { TtVTableColumn } from './table-column';
+/** 业务记录允许使用的稳定主键。 */
+export type TtVTableRowKey = number | string;
+/** VTable 可读取的字段路径。 */
+export type TtVTableFieldPath = number | string;
+/** 记录更新时采用的所有权策略。 */
+export type TtVTableMutationMode = "copy-on-write" | "shared";
+/** 精确记录变更的来源。 */
+export type TtVTableRecordChangeSource = "api" | "editing" | "renderer" | "tree";
+/** 远程排序方向。 */
+export type TtVTableSortDirection = "asc" | "desc";
+/** 一条远程排序条件。 */
+export interface TtVTableSortDescriptor {
+    /** 参与排序的字段。 */
+    field: TtVTableFieldPath;
+    /** 当前排序方向。 */
+    order: TtVTableSortDirection;
+}
+/** 一条按主键提交的记录补丁。 */
+export interface TtVTableRecordPatch<Row, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 目标记录主键。 */
+    rowKey: Key;
+    /** 要覆盖的顶层字段。 */
+    changes: Partial<Row>;
+    /** 本次变更来源。 */
+    source?: TtVTableRecordChangeSource;
+}
+/** 单次记录变化的精确描述。 */
+export interface TtVTableRecordChange<Row, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 变化前的记录主键。 */
+    rowKey: Key;
+    /** 变化后的记录主键。 */
+    nextRowKey: Key;
+    /** 变化后的运行时记录。 */
+    record: Readonly<Row>;
+    /** 变化前的运行时记录。 */
+    previousRecord: Readonly<Row>;
+    /** 本次变化涉及的字段。 */
+    changedFields: readonly TtVTableFieldPath[];
+    /** 变更来源。 */
+    source: TtVTableRecordChangeSource;
+}
+/** 当前编辑单元格的稳定身份。 */
+export interface TtVTableEditingCell<Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 业务记录主键。 */
+    rowKey: Key;
+    /** 当前字段路径。 */
+    field: TtVTableFieldPath;
+    /** 开始编辑时的值。 */
+    previousValue: unknown;
+    /** 当前草稿值。 */
+    value: unknown;
+}
+/** records 命名空间的只读状态与动作。 */
+export interface TtVTableRecordsApi<Row, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 当前运行时持有的浅层工作列表。 */
+    records: ComputedRef<readonly Row[]>;
+    /** 当前记录数量。 */
+    count: ComputedRef<number>;
+    /** 返回当前运行时工作列表的只读视图。 */
+    getAll: () => readonly Row[];
+    /** 按业务主键读取当前记录。 */
+    getByKey: (rowKey: Key) => Row | undefined;
+    /** 使用新的根快照替换全部记录。 */
+    replaceAll: (records: readonly Row[]) => void;
+    /** 在尾部追加一条或多条记录。 */
+    append: (records: Row | readonly Row[]) => void;
+    /** 在指定源索引前插入一条或多条记录。 */
+    insertAt: (recordIndex: number, records: Row | readonly Row[]) => void;
+    /** 按业务主键更新一条记录。 */
+    patchByKey: (rowKey: Key, changes: Partial<Row>, source?: TtVTableRecordChangeSource) => void;
+    /** 在一次原生调度内更新多条记录。 */
+    patchMany: (patches: readonly TtVTableRecordPatch<Row, Key>[]) => void;
+    /** 按业务主键和字段路径更新一个单元格。 */
+    setCellValue: (rowKey: Key, field: TtVTableFieldPath, value: unknown, source?: TtVTableRecordChangeSource) => void;
+    /** 按业务主键删除多条记录。 */
+    removeByKeys: (rowKeys: readonly Key[]) => void;
+}
+/** query 命名空间的只读状态与动作。 */
+export interface TtVTableQueryApi {
+    /** 最新请求是否仍在进行。 */
+    isFetching: Readonly<Ref<boolean>>;
+    /** 最新有效请求错误。 */
+    error: Readonly<Ref<Error | undefined>>;
+    /** 使用当前查询状态发起请求。 */
+    fetch: () => Promise<boolean>;
+    /** 重放最近一次已接受请求。 */
+    refresh: () => Promise<boolean>;
+    /** 取消当前请求并使其响应失效。 */
+    cancel: () => void;
+}
+/** pagination 命名空间的只读状态与动作。 */
+export interface TtVTablePaginationApi {
+    /** 当前页码，起始值为 1。 */
+    page: Readonly<Ref<number>>;
+    /** 当前每页记录数。 */
+    pageSize: Readonly<Ref<number>>;
+    /** 当前总记录数。 */
+    total: ComputedRef<number>;
+    /** 修改当前页码。 */
+    setPage: (page: number) => void;
+    /** 修改每页记录数并回到第一页。 */
+    setPageSize: (pageSize: number) => void;
+    /** 恢复初始分页状态。 */
+    reset: () => void;
+}
+/** selection 命名空间的只读状态与动作。 */
+export interface TtVTableSelectionApi<Row, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 按选择顺序保存的主键。 */
+    keys: ComputedRef<readonly Key[]>;
+    /** 当前已加载且能按主键命中的选中记录。 */
+    loadedRows: ComputedRef<readonly Row[]>;
+    /** 已选但当前未加载的主键。 */
+    missingKeys: ComputedRef<readonly Key[]>;
+    /** 替换全部选择主键。 */
+    setKeys: (rowKeys: readonly Key[]) => void;
+    /** 切换一个主键的选择状态。 */
+    toggleKey: (rowKey: Key, selected?: boolean) => void;
+    /** 选择当前页可选记录。 */
+    selectCurrentPage: () => void;
+    /** 选择运行时已经加载的全部可选记录。 */
+    selectLoadedRecords: () => void;
+    /** 清空选择。 */
+    clear: () => void;
+}
+/** columns 命名空间的只读状态与动作。 */
+export interface TtVTableColumnsApi<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 当前生效的语义列树。 */
+    columns: ComputedRef<readonly TtVTableColumn<Row, Key>[]>;
+    /** 替换全部语义列。 */
+    replaceAll: (columns: readonly TtVTableColumn<Row, Key>[]) => void;
+    /** 显示指定列。 */
+    show: (columnKey: string) => void;
+    /** 隐藏指定列。 */
+    hide: (columnKey: string) => void;
+    /** 在同级列中移动指定列。 */
+    move: (columnKey: string, targetIndex: number) => void;
+    /** 恢复默认列偏好。 */
+    resetPreferences: () => Promise<void>;
+}
+/** editing 命名空间的只读状态与动作。 */
+export interface TtVTableEditingApi<Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 当前编辑单元格。 */
+    activeCell: Readonly<Ref<Readonly<TtVTableEditingCell<Key>> | undefined>>;
+    /** 当前是否正在执行异步校验。 */
+    isValidating: Readonly<Ref<boolean>>;
+    /** 当前编辑校验错误。 */
+    validationError: Readonly<Ref<Error | undefined>>;
+    /** 开始编辑一个单元格。 */
+    start: (rowKey: Key, field: TtVTableFieldPath) => Promise<void>;
+    /** 校验并提交当前编辑。 */
+    commit: (value?: unknown) => Promise<boolean>;
+    /** 取消当前编辑。 */
+    cancel: () => void;
+    /** 仅校验当前编辑值。 */
+    validate: (value?: unknown) => Promise<boolean>;
+}
+/** tree 命名空间的只读状态与动作。 */
+export interface TtVTableTreeApi<Row, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 当前展开节点主键。 */
+    expandedKeys: Readonly<Ref<readonly Key[]>>;
+    /** 当前正在加载子节点的主键。 */
+    loadingKeys: Readonly<Ref<readonly Key[]>>;
+    /** 展开一个节点。 */
+    expand: (rowKey: Key) => Promise<void>;
+    /** 收起一个节点。 */
+    collapse: (rowKey: Key) => void;
+    /** 切换一个节点的展开状态。 */
+    toggle: (rowKey: Key) => Promise<void>;
+    /** 获取或加载一个节点的子记录。 */
+    fetchChildren: (rowKey: Key) => Promise<readonly Row[]>;
+}
+/** layout 命名空间的只读状态与动作。 */
+export interface TtVTableLayoutApi<Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 原生实例是否已经可用。 */
+    isReady: Readonly<Ref<boolean>>;
+    /** 当前可用容器宽度。 */
+    width: Readonly<Ref<number>>;
+    /** 当前可用容器高度。 */
+    height: Readonly<Ref<number>>;
+    /** 重新计算表格布局。 */
+    recalculate: () => void;
+    /** 滚动到指定记录。 */
+    scrollToRecord: (rowKey: Key) => void;
+    /** 滚动到指定记录和字段。 */
+    scrollToCell: (rowKey: Key, field: TtVTableFieldPath) => void;
+}
+/** native 命名空间的高级逃生口。 */
+export interface TtVTableNativeApi {
+    /** 返回当前原生 ListTable，未就绪或释放后返回 undefined。 */
+    getInstance: () => ListTable | undefined;
+}
+/** TtVTable 稳定且按能力分组的公共 API。 */
+export interface TtVTableApi<Row extends Record<string, unknown> = Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 记录状态与增量动作。 */
+    records: TtVTableRecordsApi<Row, Key>;
+    /** 远程查询状态与动作。 */
+    query: TtVTableQueryApi;
+    /** 分页状态与动作。 */
+    pagination: TtVTablePaginationApi;
+    /** 单选、多选状态与动作。 */
+    selection: TtVTableSelectionApi<Row, Key>;
+    /** 列状态与偏好动作。 */
+    columns: TtVTableColumnsApi<Row, Key>;
+    /** 编辑状态与动作。 */
+    editing: TtVTableEditingApi<Key>;
+    /** 树节点状态与动作。 */
+    tree: TtVTableTreeApi<Row, Key>;
+    /** 视口布局状态与动作。 */
+    layout: TtVTableLayoutApi<Key>;
+    /** 原生实例逃生口。 */
+    native: TtVTableNativeApi;
+}

package/dist/components/tt-vtable/src/public/table-column.d.ts

@@ -0,0 +1,123 @@
+import { ColumnDefine, ListTable } from '@visactor/vtable';
+import { VNodeChild } from 'vue';
+import { TtVTableApi, TtVTableFieldPath, TtVTableRowKey } from './table-api';
+/** 需要由封装层控制的原生列字段。 */
+type TtVTableReservedNativeColumnKey = "columns" | "field" | "key" | "title";
+/** 对联合类型的每个成员分别移除字段。 */
+type OmitUnion<Union, Key extends PropertyKey> = Union extends unknown ? Omit<Union, Extract<keyof Union, Key>> : never;
+/** 允许业务透传的原生 VTable 列配置。 */
+export type TtVTableNativeColumnOptions = OmitUnion<ColumnDefine, TtVTableReservedNativeColumnKey>;
+/** 不依赖 VisActor 内部声明的单元格矩形。 */
+export interface TtVTableCellRect {
+    /** 左边界。 */
+    left: number;
+    /** 右边界。 */
+    right: number;
+    /** 上边界。 */
+    top: number;
+    /** 下边界。 */
+    bottom: number;
+    /** 矩形宽度。 */
+    width: number;
+    /** 矩形高度。 */
+    height: number;
+}
+/** Vue 单元格额外暴露的原生坐标上下文。 */
+export interface TtVTableNativeCellContext {
+    /** 原生列坐标。 */
+    col: number;
+    /** 原生行坐标。 */
+    row: number;
+    /** 当前原生表格实例。 */
+    table: ListTable;
+    /** 原生单元格矩形。 */
+    rect?: TtVTableCellRect;
+}
+/** Vue 正文 renderer 的标准上下文。 */
+export interface TtVTableCellRenderContext<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 当前运行时记录。 */
+    record: Readonly<Row>;
+    /** 当前记录稳定主键。 */
+    rowKey: Key;
+    /** 当前显示顺序，只能用于展示。 */
+    rowIndex: number;
+    /** 当前语义列。 */
+    column: Readonly<TtVTableColumn<Row, Key>>;
+    /** 当前字段路径。 */
+    field?: TtVTableFieldPath;
+    /** 当前原始值。 */
+    value: unknown;
+    /** 当前表格稳定公共 API。 */
+    tableApi: TtVTableApi<Row, Key>;
+    /** 通过 records feature 精确修改当前单元格。 */
+    setCellValue: (value: unknown) => void;
+    /** 需要原生坐标时使用的高级上下文。 */
+    nativeContext: TtVTableNativeCellContext;
+}
+/** Vue 表头 renderer 的标准上下文。 */
+export interface TtVTableHeaderRenderContext<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 当前语义列。 */
+    column: Readonly<TtVTableColumn<Row, Key>>;
+    /** 当前表格稳定公共 API。 */
+    tableApi: TtVTableApi<Row, Key>;
+    /** 需要原生坐标时使用的高级上下文。 */
+    nativeContext: TtVTableNativeCellContext;
+}
+/** 正文 Vue DOM renderer，可使用内联 JSX 回调或命名插槽。 */
+export interface TtVTableVueRenderer<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 固定为 Vue DOM 渲染通道。 */
+    kind: "vue";
+    /** 内联 Vue render/JSX 回调。 */
+    render?: (context: TtVTableCellRenderContext<Row, Key>) => VNodeChild;
+    /** 命名插槽。 */
+    slot?: string;
+    /** 是否允许 DOM 接收鼠标和键盘交互。 */
+    interactive?: boolean;
+    /** 当前列建议保留的最大 DOM 缓存数。 */
+    maxCacheCount?: number;
+}
+/** 表头 Vue DOM renderer，可使用内联 JSX 回调或命名插槽。 */
+export interface TtVTableVueHeaderRenderer<Row extends Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 固定为 Vue DOM 渲染通道。 */
+    kind: "vue";
+    /** 内联 Vue render/JSX 回调。 */
+    render?: (context: TtVTableHeaderRenderContext<Row, Key>) => VNodeChild;
+    /** 命名插槽。 */
+    slot?: string;
+    /** 是否允许 DOM 接收鼠标和键盘交互。 */
+    interactive?: boolean;
+    /** 当前表头建议保留的最大 DOM 缓存数。 */
+    maxCacheCount?: number;
+}
+/** TtVTable 的语义列定义。 */
+export interface TtVTableColumn<Row extends Record<string, unknown> = Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 整棵列树中唯一且稳定的语义键。 */
+    key: string;
+    /** 业务字段或嵌套字段路径。 */
+    field?: TtVTableFieldPath;
+    /** 默认 Canvas 表头文字。 */
+    title?: string;
+    /** 固定列宽。 */
+    width?: number | string;
+    /** 最小列宽。 */
+    minWidth?: number | string;
+    /** 最大列宽。 */
+    maxWidth?: number | string;
+    /** 正文对齐方式。 */
+    align?: "center" | "left" | "right";
+    /** 是否隐藏该列。 */
+    visible?: boolean;
+    /** 冻结列位置。 */
+    frozen?: boolean | "left" | "right";
+    /** 是否作为树结构展示列。 */
+    tree?: boolean;
+    /** 嵌套表头子列。 */
+    columns?: readonly TtVTableColumn<Row, Key>[];
+    /** 复杂正文启用的 Vue DOM renderer。 */
+    renderer?: TtVTableVueRenderer<Row, Key>;
+    /** 复杂表头启用的 Vue DOM renderer。 */
+    headerRenderer?: TtVTableVueHeaderRenderer<Row, Key>;
+    /** Canvas、VRender 和其他原生列能力的受控透传配置。 */
+    native?: TtVTableNativeColumnOptions;
+}
+export {};

package/dist/components/tt-vtable/src/public/table-errors.d.ts

@@ -0,0 +1,26 @@
+/** TtVTable 可识别的语义错误码。 */
+export type TtVTableErrorCode = "TT_VTABLE_SOURCE_CONFLICT" | "TT_VTABLE_ROW_KEY_REQUIRED" | "TT_VTABLE_ROW_KEY_INVALID" | "TT_VTABLE_DUPLICATE_ROW_KEY" | "TT_VTABLE_DUPLICATE_COLUMN_KEY" | "TT_VTABLE_CONTAINER_SIZE_INVALID" | "TT_VTABLE_RENDERER_INVALID" | "TT_VTABLE_SLOT_MISSING" | "TT_VTABLE_NATIVE_OPTION_RESERVED" | "TT_VTABLE_NATIVE_EVENT_RESERVED" | "TT_VTABLE_RECORD_NOT_FOUND" | "TT_VTABLE_NOT_READY" | "TT_VTABLE_CONTROLLER_BOUND" | "TT_VTABLE_RELEASED" | "TT_VTABLE_INIT_FAILED" | "TT_VTABLE_FETCH_FAILED" | "TT_VTABLE_TREE_FETCH_FAILED" | "TT_VTABLE_EDIT_VALIDATION_FAILED";
+/** 错误附带的结构化上下文。 */
+export type TtVTableErrorContext = Readonly<Record<string, unknown>>;
+/** TtVTable 对外抛出的语义错误。 */
+export declare class TtVTableError extends Error {
+    /** 稳定错误码。 */
+    readonly code: TtVTableErrorCode;
+    /** 帮助定位配置或运行状态的上下文。 */
+    readonly context: TtVTableErrorContext;
+    /**
+     * 创建一个带稳定错误码的表格错误。
+     * @param code 稳定错误码
+     * @param message 可读错误说明
+     * @param context 结构化上下文
+     */
+    constructor(code: TtVTableErrorCode, message: string, context?: TtVTableErrorContext);
+}
+/**
+ * 创建一个 TtVTable 语义错误。
+ * @param code 稳定错误码
+ * @param message 可读错误说明
+ * @param context 结构化上下文
+ * @returns 新建的语义错误
+ */
+export declare function createTtVTableError(code: TtVTableErrorCode, message: string, context?: TtVTableErrorContext): TtVTableError;

package/dist/components/tt-vtable/src/public/table-errors.js

@@ -0,0 +1,26 @@
+var s = Object.defineProperty;
+var a = (e, r, t) => r in e ? s(e, r, { enumerable: !0, configurable: !0, writable: !0, value: t }) : e[r] = t;
+var o = (e, r, t) => a(e, typeof r != "symbol" ? r + "" : r, t);
+class T extends Error {
+  /**
+   * 创建一个带稳定错误码的表格错误。
+   * @param code 稳定错误码
+   * @param message 可读错误说明
+   * @param context 结构化上下文
+   */
+  constructor(t, n, c = {}) {
+    super(`[${t}] ${n}`);
+    /** 稳定错误码。 */
+    o(this, "code");
+    /** 帮助定位配置或运行状态的上下文。 */
+    o(this, "context");
+    this.name = "TtVTableError", this.code = t, this.context = c;
+  }
+}
+function l(e, r, t = {}) {
+  return new T(e, r, t);
+}
+export {
+  T as TtVTableError,
+  l as createTtVTableError
+};

package/dist/components/tt-vtable/src/public/table-events.d.ts

@@ -0,0 +1,69 @@
+import { TtVTableApi, TtVTableFieldPath, TtVTableRecordChange, TtVTableRowKey, TtVTableSortDescriptor } from './table-api';
+import { TtVTableFetchRequest, TtVTableFetchResponse } from './table-props';
+/** 分页变化来源。 */
+export type TtVTablePageChangeReason = "page" | "page-size" | "reset";
+/** 分页变化事件载荷。 */
+export interface TtVTablePageChange {
+    /** 当前页码。 */
+    page: number;
+    /** 当前每页记录数。 */
+    pageSize: number;
+    /** 本次变化来源。 */
+    reason: TtVTablePageChangeReason;
+}
+/** 编辑提交事件载荷。 */
+export interface TtVTableEditCommit<Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 业务记录主键。 */
+    rowKey: Key;
+    /** 修改字段路径。 */
+    field: TtVTableFieldPath;
+    /** 修改前的值。 */
+    previousValue: unknown;
+    /** 已提交值。 */
+    value: unknown;
+    /** 本次修改涉及的字段。 */
+    changedFields: readonly TtVTableFieldPath[];
+    /** 固定编辑来源。 */
+    source: "editing";
+}
+/** 树子节点加载成功事件载荷。 */
+export interface TtVTableTreeLoadSuccess<Row, Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 父节点主键。 */
+    parentKey: Key;
+    /** 已写入运行时的子记录。 */
+    children: readonly Row[];
+}
+/** 树子节点加载失败事件载荷。 */
+export interface TtVTableTreeLoadError<Key extends TtVTableRowKey = TtVTableRowKey> {
+    /** 父节点主键。 */
+    parentKey: Key;
+    /** 规范化后的请求错误。 */
+    error: Error;
+}
+/** TtVTable 允许公开的语义事件。 */
+export interface TtVTableEmits<Row extends Record<string, unknown> = Record<string, unknown>, Key extends TtVTableRowKey = TtVTableRowKey, QueryParams extends Record<string, unknown> = Record<string, unknown>> {
+    /** 原生实例与全部 feature 已经就绪。 */
+    ready: [tableApi: TtVTableApi<Row, Key>];
+    /** records API 或 Vue renderer 提交了精确记录变化。 */
+    "record-change": [change: TtVTableRecordChange<Row, Key>];
+    /** 最新远程请求成功。 */
+    "fetch-success": [response: TtVTableFetchResponse<Row>, request: TtVTableFetchRequest<QueryParams>];
+    /** 最新远程请求失败。 */
+    "fetch-error": [error: Error, request: TtVTableFetchRequest<QueryParams>];
+    /** 分页状态发生语义变化。 */
+    "page-change": [change: TtVTablePageChange];
+    /** 排序状态发生语义变化。 */
+    "sort-change": [sort: readonly TtVTableSortDescriptor[]];
+    /** 筛选状态发生语义变化。 */
+    "filter-change": [filters: Readonly<Record<string, unknown>>];
+    /** 编辑器成功提交。 */
+    "edit-commit": [change: TtVTableEditCommit<Key>];
+    /** 编辑校验或提交失败。 */
+    "edit-error": [error: Error];
+    /** 树子节点成功写入。 */
+    "tree-load-success": [change: TtVTableTreeLoadSuccess<Row, Key>];
+    /** 树子节点加载失败。 */
+    "tree-load-error": [failure: TtVTableTreeLoadError<Key>];
+    /** 列偏好发生语义变化。 */
+    "column-preferences-change": [preferences: unknown];
+}