@dazhicheng/ui 1.6.6 → 1.6.8

package/dist/components/tt-vtable/src/features/selection/useRowSelection.d.ts

@@ -0,0 +1,65 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
+import { TtVTableRowKey } from '../../public/table-api';
+import { TtVTableSelectionOptions } from '../../public/table-props';
+/** 支持的行选择模式。 */
+export type VTableSelectionMode = NonNullable<TtVTableSelectionOptions<unknown>["mode"]>;
+/** 暴露给表格 runtime 的选择状态。 */
+export interface VTableSelectionState<Row, Key extends TtVTableRowKey> {
+    /** 按选择顺序稳定排列的主键。 */
+    keys: ComputedRef<readonly Key[]>;
+    /** 当前 runtime 数据源中仍存在的已选记录。 */
+    loadedRows: ComputedRef<readonly Row[]>;
+    /** 当前 runtime 数据源中不存在的已选主键。 */
+    missingKeys: ComputedRef<readonly Key[]>;
+    /** 是否正在把公共 model 同步到原生选择状态。 */
+    isSyncingNative: Readonly<Ref<boolean>>;
+}
+/** 挂载到表格命名空间 API 的选择动作。 */
+export interface VTableSelectionActions<Row, Key extends TtVTableRowKey> {
+    /** 替换全部已选主键。 */
+    setKeys: (keys: readonly Key[]) => void;
+    /** 按主键切换一条记录的选择状态。 */
+    toggleKey: (key: Key, selected?: boolean) => void;
+    /** 选择当前页全部可选记录。 */
+    selectCurrentPage: () => void;
+    /** 选择 runtime 当前已加载的全部可选记录。 */
+    selectLoadedRecords: () => void;
+    /** 清空选择。 */
+    clear: () => void;
+    /** 判断记录是否允许选择。 */
+    isSelectable: (record: Row) => boolean;
+}
+/** 完整的选择 feature 契约。 */
+export interface VTableRowSelection<Row, Key extends TtVTableRowKey> extends VTableSelectionState<Row, Key>, VTableSelectionActions<Row, Key> {
+    /** 接收并应用 VTable 的 checkbox 或 radio 变化。 */
+    onNativeSelectionChange: (record: Row, selected: boolean) => void;
+    /** runtime 记录源变化后校正已选主键。 */
+    reconcileRecords: () => void;
+    /** 原生实例 ready 后同步最终选择状态。 */
+    syncNativeState: () => Promise<void>;
+}
+/** 行选择 feature 所需依赖。 */
+export interface UseRowSelectionOptions<Row, Key extends TtVTableRowKey> {
+    /** 选择模式。 */
+    mode: MaybeRefOrGetter<VTableSelectionMode>;
+    /** 公共 selected-row-keys model。 */
+    selectedRowKeys: Ref<Key[]>;
+    /** 读取 runtime 当前加载的全部记录。 */
+    getLoadedRecords: () => readonly Row[];
+    /** 读取当前本地页或远程页记录。 */
+    getCurrentPageRecords: () => readonly Row[];
+    /** 按业务主键读取一条已加载记录。 */
+    getRecordByKey: (key: Key) => Row | undefined;
+    /** 读取记录的稳定业务主键。 */
+    getRowKey: (record: Row) => Key;
+    /** 可选的业务可选性判断函数。 */
+    isRowSelectable?: (record: Row) => boolean;
+    /** 是否跨远程分页保留未加载主键。 */
+    reserveAcrossPages?: MaybeRefOrGetter<boolean>;
+    /** 返回参与树级联的记录，结果包含源记录。 */
+    getCascadeRecords?: (record: Row) => readonly Row[];
+    /** 把公共主键同步到原生 checkbox 或 radio 视觉状态。 */
+    syncNativeSelection?: (keys: readonly Key[]) => Promise<void> | void;
+}
+/** 创建受控的单选或多选行选择 feature。 */
+export declare function useRowSelection<Row, Key extends TtVTableRowKey = TtVTableRowKey>(options: UseRowSelectionOptions<Row, Key>): VTableRowSelection<Row, Key>;

package/dist/components/tt-vtable/src/features/selection/useRowSelection.js

@@ -0,0 +1,129 @@
+import "axios";
+import "element-plus";
+import { isNumber as L, isString as V } from "../../../../../packages/utils/src/is.js";
+import { shallowRef as F, computed as o, toValue as K, watch as S } from "vue";
+import "dayjs";
+import "numeral";
+import "xe-utils";
+import "dayjs/plugin/utc";
+import "dayjs/plugin/timezone";
+import "../../../../../node_modules/.pnpm/decimal.js@10.6.0/node_modules/decimal.js/decimal.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/aes.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/enc-utf8.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/mode-ecb.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/pad-pkcs7.js";
+import "lodash-es";
+function M(e) {
+  return V(e) ? !!e : L(e) && Number.isFinite(e);
+}
+function w(e, n) {
+  return e.length === n.length && e.every((u, c) => u === n[c]);
+}
+function O(e) {
+  const n = /* @__PURE__ */ new Set(), u = [];
+  return e.forEach((c) => {
+    !M(c) || n.has(c) || (n.add(c), u.push(c));
+  }), u;
+}
+function p(e) {
+  const n = F(!1);
+  let u = 0;
+  const c = o(() => K(e.mode)), s = o(() => d(e.selectedRowKeys.value)), h = o(() => {
+    const t = [];
+    return s.value.forEach((r) => {
+      const l = e.getRecordByKey(r);
+      l && t.push(l);
+    }), t;
+  }), N = o(() => s.value.filter((t) => !e.getRecordByKey(t)));
+  function d(t) {
+    const r = O(t);
+    return c.value === "none" ? [] : c.value === "single" ? r.slice(0, 1) : r;
+  }
+  function i(t) {
+    return e.isRowSelectable ? e.isRowSelectable(t) : !0;
+  }
+  function a(t) {
+    const r = d(t);
+    w(e.selectedRowKeys.value, r) || (e.selectedRowKeys.value = r);
+  }
+  function b(t) {
+    var l;
+    return (((l = e.getCascadeRecords) == null ? void 0 : l.call(e, t)) ?? [t]).filter(i).map(e.getRowKey);
+  }
+  function m(t, r) {
+    const l = e.getRecordByKey(t);
+    if (!l || !i(l) || c.value === "none") return;
+    const x = s.value.includes(t), R = r ?? !x, A = c.value === "single" ? [t] : b(l);
+    if (c.value === "single") {
+      a(R ? [t] : []);
+      return;
+    }
+    const f = new Set(s.value);
+    A.forEach((g) => {
+      R ? f.add(g) : f.delete(g);
+    }), a([...f]);
+  }
+  function v(t) {
+    if (c.value === "none") return;
+    const r = t.filter(i).map(e.getRowKey);
+    if (c.value === "single") {
+      a(r.slice(0, 1));
+      return;
+    }
+    a([...s.value, ...r]);
+  }
+  function z() {
+    v(e.getCurrentPageRecords());
+  }
+  function B() {
+    v(e.getLoadedRecords());
+  }
+  function C() {
+    a([]);
+  }
+  function q(t, r) {
+    n.value || m(e.getRowKey(t), r);
+  }
+  function E() {
+    K(e.reserveAcrossPages ?? !1) || a(s.value.filter((t) => !!e.getRecordByKey(t)));
+  }
+  async function y(t) {
+    if (!e.syncNativeSelection) return;
+    u += 1;
+    const r = u;
+    n.value = !0;
+    try {
+      await e.syncNativeSelection(t);
+    } finally {
+      r === u && (n.value = !1);
+    }
+  }
+  function P() {
+    return y(s.value);
+  }
+  return S(
+    e.selectedRowKeys,
+    (t) => {
+      const r = d(t);
+      w(t, r) || (e.selectedRowKeys.value = r), y(r);
+    },
+    { immediate: !0 }
+  ), S(c, () => a(e.selectedRowKeys.value)), {
+    keys: s,
+    loadedRows: h,
+    missingKeys: N,
+    isSyncingNative: n,
+    setKeys: a,
+    toggleKey: m,
+    selectCurrentPage: z,
+    selectLoadedRecords: B,
+    clear: C,
+    isSelectable: i,
+    onNativeSelectionChange: q,
+    reconcileRecords: E,
+    syncNativeState: P
+  };
+}
+export {
+  p as useRowSelection
+};

package/dist/components/tt-vtable/src/features/tree/useTreeRecords.d.ts

@@ -0,0 +1,60 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
+import { TtVTableRowKey } from '../../public/table-api';
+import { TtVTableTreeLoadError, TtVTableTreeLoadSuccess } from '../../public/table-events';
+import { TtVTableTreeChildrenRequest } from '../../public/table-props';
+/** 暴露给 runtime 的树状态与动作。 */
+export interface VTableTreeRecords<Row, Key extends TtVTableRowKey> {
+    /** 已展开业务主键。 */
+    expandedKeys: Readonly<Ref<readonly Key[]>>;
+    /** 正在加载子节点的业务主键。 */
+    loadingKeys: Readonly<Ref<readonly Key[]>>;
+    /** 最近一次未中止的树请求错误。 */
+    error: Readonly<Ref<Error | undefined>>;
+    /** 是否至少有一个树请求进行中。 */
+    isLoading: ComputedRef<boolean>;
+    /** 展开节点并在需要时懒加载子节点。 */
+    expand: (key: Key) => Promise<void>;
+    /** 折叠节点且不丢弃已缓存子节点。 */
+    collapse: (key: Key) => void;
+    /** 切换节点展开状态。 */
+    toggle: (key: Key) => Promise<void>;
+    /** 加载节点子记录并复用重复请求。 */
+    fetchChildren: (key: Key) => Promise<readonly Row[]>;
+    /** 应用原生层级状态事件。 */
+    onNativeHierarchyChange: (record: Row, expanded: boolean) => Promise<void>;
+    /** records 根引用变化后使进行中的请求失效。 */
+    onRecordsReplaced: () => void;
+    /** 返回树选择级联使用的已加载后代记录。 */
+    getCascadeRecords: (record: Row) => readonly Row[];
+    /** 原生实例 ready 后同步最终展开快照。 */
+    syncExpandedState: () => Promise<void>;
+    /** 释放进行中的请求和状态。 */
+    release: () => void;
+}
+/** 树记录 feature 所需依赖。 */
+export interface UseTreeRecordsOptions<Row, Key extends TtVTableRowKey> {
+    /** 初始展开主键。 */
+    defaultExpandedKeys?: readonly Key[];
+    /** 按主键读取一条 runtime 记录。 */
+    getRecordByKey: (key: Key) => Row | undefined;
+    /** 读取记录的稳定业务主键。 */
+    getRowKey: (record: Row) => Key;
+    /** 从 runtime 记录读取已加载子记录。 */
+    getChildren: (record: Row) => readonly Row[] | undefined;
+    /** 通过 records feature 写入复制后的子记录。 */
+    setChildren: (parentKey: Key, children: readonly Row[]) => Promise<void> | void;
+    /** 可选的子节点懒加载请求回调。 */
+    fetchTreeChildren?: (request: TtVTableTreeChildrenRequest<Row, Key>) => Promise<readonly Row[]>;
+    /** 后续展开时是否复用已加载子记录。 */
+    cacheChildren?: MaybeRefOrGetter<boolean>;
+    /** 同步一个原生层级状态。 */
+    setNativeExpanded?: (key: Key, expanded: boolean) => Promise<void> | void;
+    /** 同步一个原生层级加载状态。 */
+    setNativeLoading?: (key: Key, loading: boolean) => Promise<void> | void;
+    /** 当前子记录被接纳后调用一次。 */
+    onLoadSuccess?: (change: TtVTableTreeLoadSuccess<Row, Key>) => void;
+    /** 当前未中止请求失败后调用一次。 */
+    onLoadError?: (failure: TtVTableTreeLoadError<Key>) => void;
+}
+/** 创建树展开和可防竞态的懒加载 feature。 */
+export declare function useTreeRecords<Row, Key extends TtVTableRowKey = TtVTableRowKey>(options: UseTreeRecordsOptions<Row, Key>): VTableTreeRecords<Row, Key>;

package/dist/components/tt-vtable/src/features/tree/useTreeRecords.js

@@ -0,0 +1,125 @@
+import "axios";
+import "element-plus";
+import { isArray as G, isError as j } from "../../../../../packages/utils/src/is.js";
+import { shallowRef as E, computed as D, onScopeDispose as H, toValue as M } from "vue";
+import "dayjs";
+import "numeral";
+import "xe-utils";
+import "dayjs/plugin/utc";
+import "dayjs/plugin/timezone";
+import "../../../../../node_modules/.pnpm/decimal.js@10.6.0/node_modules/decimal.js/decimal.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/aes.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/enc-utf8.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/mode-ecb.js";
+import "../../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/pad-pkcs7.js";
+import "lodash-es";
+function V(r) {
+  return new Error(j(r) ? String(r).replace(/^Error:\s*/, "") : String(r));
+}
+function x(r, n) {
+  return r.includes(n) ? [...r] : [...r, n];
+}
+function T(r, n) {
+  return r.filter((i) => i !== n);
+}
+function re(r) {
+  const n = E([...new Set(r.defaultExpandedKeys ?? [])]), i = E([]), v = E(), u = /* @__PURE__ */ new Map();
+  let s = 0, h = !1;
+  const L = D(() => i.value.length > 0);
+  async function w(e, t, a = !0) {
+    var c;
+    n.value = t ? x(n.value, e) : T(n.value, e), a && await ((c = r.setNativeExpanded) == null ? void 0 : c.call(r, e, t));
+  }
+  async function K(e, t) {
+    var a;
+    i.value = t ? x(i.value, e) : T(i.value, e), await ((a = r.setNativeLoading) == null ? void 0 : a.call(r, e, t));
+  }
+  function m(e) {
+    const t = u.get(e);
+    if (t) return t.promise;
+    const a = r.getRecordByKey(e);
+    if (!a) return Promise.reject(new Error(`Cannot load children for missing record "${String(e)}".`));
+    const c = r.getChildren(a);
+    if (M(r.cacheChildren ?? !0) && (c != null && c.length) || !r.fetchTreeChildren)
+      return Promise.resolve(c ?? []);
+    const l = new AbortController(), d = s, g = {}, S = (async () => {
+      var q, b;
+      try {
+        await K(e, !0), v.value = void 0;
+        const o = await r.fetchTreeChildren({ parent: a, parentKey: e, signal: l.signal });
+        if (l.signal.aborted || d !== s || h) return [];
+        if (!G(o)) throw new Error("Tree child request must return an array.");
+        const f = [...o];
+        return await r.setChildren(e, f), l.signal.aborted || d !== s || h ? [] : ((q = r.onLoadSuccess) == null || q.call(r, { parentKey: e, children: f }), f);
+      } catch (o) {
+        const f = V(o);
+        if (l.signal.aborted || d !== s || h) return [];
+        throw v.value = f, (b = r.onLoadError) == null || b.call(r, { parentKey: e, error: f }), f;
+      } finally {
+        const o = u.get(e);
+        (o == null ? void 0 : o.token) === g && u.delete(e), d === s && !h && await K(e, !1);
+      }
+    })();
+    return u.set(e, { controller: l, promise: S, token: g }), S;
+  }
+  async function R(e) {
+    await w(e, !0);
+    try {
+      await m(e);
+    } catch (t) {
+      throw await w(e, !1), t;
+    }
+  }
+  function C(e) {
+    w(e, !1);
+  }
+  function N(e) {
+    return n.value.includes(e) ? (C(e), Promise.resolve()) : R(e);
+  }
+  async function p(e, t) {
+    const a = r.getRowKey(e);
+    if (await w(a, t, !1), !!t)
+      try {
+        await m(a);
+      } catch (c) {
+        throw await w(a, !1), c;
+      }
+  }
+  function P() {
+    s += 1, u.forEach((e) => e.controller.abort()), u.clear(), i.value = [], v.value = void 0, n.value = n.value.filter((e) => !!r.getRecordByKey(e));
+  }
+  function A(e) {
+    const t = /* @__PURE__ */ new Set(), a = [];
+    function c(l) {
+      var g;
+      const d = r.getRowKey(l);
+      t.has(d) || (t.add(d), a.push(l), (g = r.getChildren(l)) == null || g.forEach(c));
+    }
+    return c(e), a;
+  }
+  async function B() {
+    var e;
+    for (const t of n.value) await ((e = r.setNativeExpanded) == null ? void 0 : e.call(r, t, !0));
+  }
+  function y() {
+    h || (h = !0, s += 1, u.forEach((e) => e.controller.abort()), u.clear(), i.value = []);
+  }
+  return H(y), {
+    expandedKeys: n,
+    loadingKeys: i,
+    error: v,
+    isLoading: L,
+    expand: R,
+    collapse: C,
+    toggle: N,
+    fetchChildren: m,
+    onNativeHierarchyChange: p,
+    onRecordsReplaced: P,
+    getCascadeRecords: A,
+    syncExpandedState: B,
+    release: y
+  };
+}
+export {
+  re as useTreeRecords
+};

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

@@ -0,0 +1,7 @@
+/** TtVTable 公共 API、列、事件、props、slots 与错误类型。 */
+export * from './table-api';
+export * from './table-column';
+export * from './table-errors';
+export * from './table-events';
+export * from './table-props';
+export * from './table-slots';

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;
+}