niuma-ui 1.1.12 → 1.2.0

package/dist/composables/useRsTableColumnResize.d.ts

@@ -0,0 +1,35 @@
+/**
+ * RsTable 列宽拖拽：mousemove 走 DOM 直写，避免整表 Vue 重渲。
+ *
+ * 性能关键：
+ * - 会话开始时缓存 col/th 元素与基准总宽，RAF 内不再 querySelector 全表
+ * - 拖拽中只更新变化列宽度 + table 总宽（O(1)），不重写其它列
+ * - activeDragWidths 为非响应式 plain object，禁止写入 reactive
+ */
+import { type ComputedRef, type Ref } from 'vue';
+import { type RsTableColumn, type RsTableRowData } from '../components/table-utils';
+export interface UseRsTableColumnResizeOptions<T extends RsTableRowData> {
+    resizable: ComputedRef<boolean> | (() => boolean);
+    minColumnWidth: ComputedRef<number | undefined> | (() => number | undefined);
+    maxColumnWidth: ComputedRef<number | undefined> | (() => number | undefined);
+    displayColumns: ComputedRef<RsTableColumn<T>[]> | (() => RsTableColumn<T>[]);
+    resolvedColumnWidths: {
+        get: () => Record<string, number>;
+        set: (value: Record<string, number>) => void;
+    };
+    /** 前缀列总宽（px），用于 DOM 直写时的 table 总宽 */
+    measurePrefixColumnWidth: () => number;
+    tableMinWidth: ComputedRef<string | undefined> | (() => string | undefined);
+    onColumnResize: (key: string, width: number) => void;
+}
+/**
+ * 列宽拖拽会话。
+ */
+export declare function useRsTableColumnResize<T extends RsTableRowData>(options: UseRsTableColumnResizeOptions<T>): {
+    tableRef: Ref<HTMLTableElement | null, HTMLTableElement | null>;
+    isColumnResizing: Ref<boolean, boolean>;
+    resizePaintWidths: Ref<Record<string, number> | null, Record<string, number> | null>;
+    onResizeStart: (key: string, event: MouseEvent) => void;
+    stopResize: () => void;
+};
+export type RsTableColumnResizeApi = ReturnType<typeof useRsTableColumnResize>;

package/dist/composables/useRsTableColumnResize.js

@@ -0,0 +1,182 @@
+import { clampColumnWidth, parseColumnWidth } from "../components/table-utils.js";
+import { nextTick, onUnmounted, ref } from "vue";
+//#region src/composables/useRsTableColumnResize.ts
+/**
+* RsTable 列宽拖拽：mousemove 走 DOM 直写，避免整表 Vue 重渲。
+*
+* 性能关键：
+* - 会话开始时缓存 col/th 元素与基准总宽，RAF 内不再 querySelector 全表
+* - 拖拽中只更新变化列宽度 + table 总宽（O(1)），不重写其它列
+* - activeDragWidths 为非响应式 plain object，禁止写入 reactive
+*/
+function read(source) {
+	if (typeof source === "function") return source();
+	return source.value;
+}
+/**
+* 列宽拖拽会话。
+*/
+function useRsTableColumnResize(options) {
+	const tableRef = ref(null);
+	const isColumnResizing = ref(false);
+	/** 拖拽会话中的列宽快照（仅首帧写入一次，供 colgroup 初始渲染） */
+	const resizePaintWidths = ref(null);
+	let session = null;
+	/** 非响应式：mousemove 高频更新不得触发 Vue */
+	let activeDragWidths = null;
+	let resizeRafId = 0;
+	let latestResizeClientX = 0;
+	let resizeMoved = false;
+	function cacheColumnElements(table) {
+		const colEls = /* @__PURE__ */ new Map();
+		const thEls = /* @__PURE__ */ new Map();
+		for (const col of table.querySelectorAll("colgroup col[data-col-key]")) {
+			const key = col.dataset.colKey;
+			if (key) colEls.set(key, col);
+		}
+		for (const th of table.querySelectorAll("thead th[data-col-key]")) {
+			const key = th.dataset.colKey;
+			if (key) thEls.set(key, th);
+		}
+		return {
+			colEls,
+			thEls
+		};
+	}
+	/** 会话开始：一次性写满所有列宽到 DOM */
+	function paintAllColumnWidths(table, widths, cache) {
+		let sum = options.measurePrefixColumnWidth();
+		for (const column of read(options.displayColumns)) {
+			const width = widths[column.key] ?? parseColumnWidth(column.width ?? column.minWidth);
+			const col = cache.colEls.get(column.key);
+			if (col) col.style.width = `${width}px`;
+			const th = cache.thEls.get(column.key);
+			if (th) th.style.width = `${width}px`;
+			sum += width;
+		}
+		table.style.width = `${sum}px`;
+		const minWidth = read(options.tableMinWidth);
+		if (minWidth) table.style.minWidth = minWidth;
+		return sum;
+	}
+	/** 确保 colgroup 元素已缓存；fixed 布局首帧可能尚未挂上，失败则返回 false */
+	function ensureSessionDomCache() {
+		if (!session || !tableRef.value || !activeDragWidths) return false;
+		if (session.colEls.size > 0) return true;
+		const cache = cacheColumnElements(tableRef.value);
+		if (cache.colEls.size === 0) return false;
+		session.colEls = cache.colEls;
+		session.thEls = cache.thEls;
+		session.baseTableWidth = paintAllColumnWidths(tableRef.value, activeDragWidths, cache);
+		return true;
+	}
+	/** RAF 热路径：只改变化列 + 总宽；缓存未就绪时先全量写一次 */
+	function paintChangedColumnWidth(width) {
+		if (!session || !tableRef.value) return;
+		if (!ensureSessionDomCache()) return;
+		const { key, colEls, thEls, baseTableWidth, startWidth } = session;
+		const col = colEls.get(key);
+		if (col) col.style.width = `${width}px`;
+		const th = thEls.get(key);
+		if (th) th.style.width = `${width}px`;
+		tableRef.value.style.width = `${baseTableWidth - startWidth + width}px`;
+	}
+	function beginResizeSession() {
+		if (!session || isColumnResizing.value || !tableRef.value) return;
+		isColumnResizing.value = true;
+		activeDragWidths = { ...session.domSnapshot };
+		resizePaintWidths.value = { ...activeDragWidths };
+		if (!ensureSessionDomCache()) nextTick(() => {
+			ensureSessionDomCache();
+		});
+	}
+	function onResizeMove(event) {
+		if (!session) return;
+		latestResizeClientX = event.clientX;
+		if (!resizeMoved && Math.abs(latestResizeClientX - session.startX) < 1) return;
+		if (!resizeMoved) {
+			resizeMoved = true;
+			beginResizeSession();
+		}
+		if (resizeRafId !== 0) return;
+		resizeRafId = requestAnimationFrame(() => {
+			resizeRafId = 0;
+			if (!session || !activeDragWidths) return;
+			const nextWidth = clampColumnWidth(session.startWidth + latestResizeClientX - session.startX, read(options.minColumnWidth), read(options.maxColumnWidth));
+			if (nextWidth === session.currentWidth) return;
+			session.currentWidth = nextWidth;
+			activeDragWidths[session.key] = nextWidth;
+			paintChangedColumnWidth(nextWidth);
+		});
+	}
+	function stopResize() {
+		if (session && resizeMoved) {
+			const finalWidth = clampColumnWidth(session.startWidth + latestResizeClientX - session.startX, read(options.minColumnWidth), read(options.maxColumnWidth));
+			if (finalWidth !== session.startWidth) {
+				const merged = {
+					...session.domSnapshot,
+					[session.key]: finalWidth
+				};
+				options.resolvedColumnWidths.set(merged);
+				options.onColumnResize(session.key, finalWidth);
+			}
+		}
+		if (tableRef.value) {
+			tableRef.value.style.width = "";
+			tableRef.value.style.minWidth = "";
+			for (const th of tableRef.value.querySelectorAll("thead th[data-col-key]")) th.style.width = "";
+		}
+		isColumnResizing.value = false;
+		resizePaintWidths.value = null;
+		activeDragWidths = null;
+		session = null;
+		resizeMoved = false;
+		if (resizeRafId !== 0) {
+			cancelAnimationFrame(resizeRafId);
+			resizeRafId = 0;
+		}
+		document.body.style.cursor = "";
+		document.body.style.userSelect = "";
+		document.removeEventListener("mousemove", onResizeMove);
+		document.removeEventListener("mouseup", stopResize, { capture: true });
+	}
+	function onResizeStart(key, event) {
+		if (!read(options.resizable)) return;
+		const thEl = event.currentTarget.closest("th");
+		if (!thEl) return;
+		const tableEl = thEl.closest("table");
+		if (!tableEl) return;
+		const dataThs = Array.from(tableEl.querySelectorAll("thead th[data-col-key]"));
+		const domSnapshot = {};
+		for (const th of dataThs) domSnapshot[th.dataset.colKey] = th.offsetWidth;
+		const startWidth = domSnapshot[key] ?? thEl.offsetWidth;
+		latestResizeClientX = event.clientX;
+		resizeMoved = false;
+		session = {
+			key,
+			startX: event.clientX,
+			startWidth,
+			currentWidth: startWidth,
+			domSnapshot,
+			baseTableWidth: 0,
+			colEls: /* @__PURE__ */ new Map(),
+			thEls: /* @__PURE__ */ new Map()
+		};
+		document.body.style.cursor = "col-resize";
+		document.body.style.userSelect = "none";
+		document.addEventListener("mousemove", onResizeMove);
+		document.addEventListener("mouseup", stopResize, { capture: true });
+	}
+	onUnmounted(() => {
+		stopResize();
+	});
+	return {
+		tableRef,
+		isColumnResizing,
+		resizePaintWidths,
+		onResizeStart,
+		stopResize
+	};
+}
+//#endregion
+export { useRsTableColumnResize };

package/dist/composables/useRsTableColumnVirtual.d.ts

@@ -0,0 +1,76 @@
+/**
+ * RsTable 横向列虚拟：冻结列始终渲染，中间 fluid 列按 scrollLeft 切片。
+ *
+ * 列宽拖拽 DOM 直写仍在 RsTable；本 composable 只消费已算好的列宽 getter。
+ */
+import { type ComputedRef, type Ref } from 'vue';
+import { type RsTableColumn, type RsTableRowData } from '../components/table-utils';
+/** ComputedRef / Ref / getter 均可（抽离后 RsTable 常直接传入 ref） */
+type Source<T> = ComputedRef<T> | Ref<T> | (() => T);
+/** 前缀列固定宽度（与 CSS / resizable 合计一致） */
+export declare const RS_TABLE_PREFIX_COL_WIDTH: {
+    readonly drag: 40;
+    readonly expand: 40;
+    readonly select: 40;
+    readonly status: 52;
+};
+/**
+ * 计算前缀列总宽（拖拽/展开/选择/序号或 gutter）。
+ * 供列布局合计与列宽拖拽 DOM 直写共用，避免两处公式漂移。
+ */
+export declare function measureRsTablePrefixWidth(flags: {
+    showRowDragHandle?: boolean;
+    detailExpandable?: boolean;
+    showSelectColumn?: boolean;
+    showEditGutterColumn?: boolean;
+    showIndexColumn?: boolean;
+    gutterWidth?: number;
+    indexWidth?: number;
+}): number;
+export interface UseRsTableColumnVirtualOptions<T extends RsTableRowData> {
+    displayColumns: Source<RsTableColumn<T>[]>;
+    /** virtualColumns prop：true / false / 'auto' */
+    virtualColumns: Source<boolean | 'auto' | undefined>;
+    virtualColumnsAutoThreshold: Source<number | undefined>;
+    virtualColumnOverscan: Source<number | undefined>;
+    /** 列宽拖拽中强制关闭列虚拟，避免切片与 DOM 直写打架 */
+    isColumnResizing: Source<boolean>;
+    scrollLeft: Source<number>;
+    measuredViewportWidth: Source<number>;
+    columnWidths: Source<Record<string, number>>;
+    showRowDragHandle: Source<boolean>;
+    detailExpandable: Source<boolean>;
+    showSelectColumn: Source<boolean>;
+    showEditGutterColumn: Source<boolean>;
+    showIndexColumn: Source<boolean>;
+    showRowStatusColumn: Source<boolean>;
+    resolvedGutterWidth: Source<number>;
+    resolvedIndexWidth: Source<number>;
+}
+/**
+ * 横向列虚拟切片状态。
+ *
+ * @returns left/right/fluid 列分组、virtualColumnsEnabled、visibleDataColumns、左右 pad
+ */
+export declare function useRsTableColumnVirtual<T extends RsTableRowData>(options: UseRsTableColumnVirtualOptions<T>): {
+    leftFixedDataColumns: ComputedRef<RsTableColumn<T>[]>;
+    rightFixedDataColumns: ComputedRef<RsTableColumn<T>[]>;
+    fluidDataColumns: ComputedRef<RsTableColumn<T>[]>;
+    dataColumnWidth: (column: RsTableColumn<T>) => number;
+    virtualColumnsEnabled: ComputedRef<boolean>;
+    fluidLeadingOffset: ComputedRef<number>;
+    columnVirtualSlice: ComputedRef<{
+        columns: RsTableColumn<T>[];
+        paddingLeft: number;
+        paddingRight: number;
+        startIndex: number;
+        endIndex: number;
+        fluidCount: number;
+    }>;
+    visibleDataColumns: ComputedRef<RsTableColumn<T>[]>;
+    columnPadLeft: ComputedRef<number>;
+    columnPadRight: ComputedRef<number>;
+};
+/** useRsTableColumnVirtual 返回值类型 */
+export type RsTableColumnVirtualApi<T extends RsTableRowData> = ReturnType<typeof useRsTableColumnVirtual<T>>;
+export {};

package/dist/composables/useRsTableColumnVirtual.js

@@ -0,0 +1,116 @@
+import { resolveColumnPixelWidth, sliceVirtualColumns } from "../components/table-utils.js";
+import { computed } from "vue";
+//#region src/composables/useRsTableColumnVirtual.ts
+/**
+* RsTable 横向列虚拟：冻结列始终渲染，中间 fluid 列按 scrollLeft 切片。
+*
+* 列宽拖拽 DOM 直写仍在 RsTable；本 composable 只消费已算好的列宽 getter。
+*/
+/** 统一读取 ComputedRef / Ref / getter */
+function read(source) {
+	if (typeof source === "function") return source();
+	return source.value;
+}
+/** 前缀列固定宽度（与 CSS / resizable 合计一致） */
+var RS_TABLE_PREFIX_COL_WIDTH = {
+	drag: 40,
+	expand: 40,
+	select: 40,
+	status: 52
+};
+/**
+* 计算前缀列总宽（拖拽/展开/选择/序号或 gutter）。
+* 供列布局合计与列宽拖拽 DOM 直写共用，避免两处公式漂移。
+*/
+function measureRsTablePrefixWidth(flags) {
+	let sum = 0;
+	if (flags.showRowDragHandle) sum += RS_TABLE_PREFIX_COL_WIDTH.drag;
+	if (flags.detailExpandable) sum += RS_TABLE_PREFIX_COL_WIDTH.expand;
+	if (flags.showSelectColumn) sum += RS_TABLE_PREFIX_COL_WIDTH.select;
+	if (flags.showEditGutterColumn) sum += flags.gutterWidth ?? 0;
+	else if (flags.showIndexColumn) sum += flags.indexWidth ?? 0;
+	return sum;
+}
+/**
+* 横向列虚拟切片状态。
+*
+* @returns left/right/fluid 列分组、virtualColumnsEnabled、visibleDataColumns、左右 pad
+*/
+function useRsTableColumnVirtual(options) {
+	const leftFixedDataColumns = computed(() => read(options.displayColumns).filter((c) => c.fixed === "left"));
+	const rightFixedDataColumns = computed(() => read(options.displayColumns).filter((c) => c.fixed === "right"));
+	const fluidDataColumns = computed(() => read(options.displayColumns).filter((c) => !c.fixed));
+	const dataColumnWidth = (column) => resolveColumnPixelWidth(column, read(options.columnWidths));
+	/**
+	* 启用规则：
+	* - false → 关
+	* - 列宽拖拽中 → 关
+	* - true → fluid 列非空即开
+	* - auto → fluid 列数 >= threshold
+	*/
+	const virtualColumnsEnabled = computed(() => {
+		if (read(options.virtualColumns) === false) return false;
+		if (read(options.isColumnResizing)) return false;
+		if (read(options.virtualColumns) === true) return fluidDataColumns.value.length > 0;
+		const threshold = read(options.virtualColumnsAutoThreshold) ?? 0;
+		return threshold > 0 && fluidDataColumns.value.length >= threshold;
+	});
+	/** 左侧前缀 + 左冻结列总宽，用于把 scrollLeft 映射到 fluid 区 */
+	const fluidLeadingOffset = computed(() => {
+		let sum = 0;
+		if (read(options.showRowDragHandle)) sum += RS_TABLE_PREFIX_COL_WIDTH.drag;
+		if (read(options.detailExpandable)) sum += RS_TABLE_PREFIX_COL_WIDTH.expand;
+		if (read(options.showSelectColumn)) sum += RS_TABLE_PREFIX_COL_WIDTH.select;
+		if (read(options.showEditGutterColumn)) sum += read(options.resolvedGutterWidth);
+		else if (read(options.showIndexColumn)) sum += read(options.resolvedIndexWidth);
+		if (read(options.showRowStatusColumn)) sum += RS_TABLE_PREFIX_COL_WIDTH.status;
+		for (const col of leftFixedDataColumns.value) sum += dataColumnWidth(col);
+		return sum;
+	});
+	const columnVirtualSlice = computed(() => {
+		const fluidCount = fluidDataColumns.value.length;
+		if (!virtualColumnsEnabled.value) return {
+			columns: read(options.displayColumns),
+			paddingLeft: 0,
+			paddingRight: 0,
+			startIndex: 0,
+			endIndex: fluidCount,
+			fluidCount
+		};
+		const viewport = Math.max(read(options.measuredViewportWidth) || 320, 120);
+		const midScroll = Math.max(0, read(options.scrollLeft) - fluidLeadingOffset.value);
+		const midViewport = Math.max(120, viewport - Math.min(viewport - 40, fluidLeadingOffset.value));
+		const sliced = sliceVirtualColumns(fluidDataColumns.value, {
+			scrollLeft: midScroll,
+			viewportWidth: midViewport,
+			getWidth: dataColumnWidth,
+			overscan: read(options.virtualColumnOverscan) ?? 2
+		});
+		return {
+			columns: [
+				...leftFixedDataColumns.value,
+				...sliced.columns,
+				...rightFixedDataColumns.value
+			],
+			paddingLeft: sliced.paddingLeft,
+			paddingRight: sliced.paddingRight,
+			startIndex: sliced.startIndex,
+			endIndex: sliced.endIndex,
+			fluidCount
+		};
+	});
+	return {
+		leftFixedDataColumns,
+		rightFixedDataColumns,
+		fluidDataColumns,
+		dataColumnWidth,
+		virtualColumnsEnabled,
+		fluidLeadingOffset,
+		columnVirtualSlice,
+		visibleDataColumns: computed(() => columnVirtualSlice.value.columns),
+		columnPadLeft: computed(() => columnVirtualSlice.value.paddingLeft),
+		columnPadRight: computed(() => columnVirtualSlice.value.paddingRight)
+	};
+}
+//#endregion
+export { RS_TABLE_PREFIX_COL_WIDTH, measureRsTablePrefixWidth, useRsTableColumnVirtual };

package/dist/composables/useRsTableColumns.d.ts

@@ -0,0 +1,70 @@
+/**
+ * RsTable 列模型编排：顺序、列筛选、宽度与 displayColumns。
+ *
+ * 从 RsTable.vue 抽离，保持受控 / 非受控 API 与原先行为一致。
+ * 不负责虚拟列切片、列拖拽排序的 DOM 交互（仍由 RsTable 编排）。
+ */
+import { type ComputedRef, type Ref } from 'vue';
+import { type RsTableColumn, type RsTableRowData } from '../components/table-utils';
+/** 列相关事件（与 RsTable emit 子集对齐） */
+export interface UseRsTableColumnsEmit {
+    (e: 'update:columnOrder', value: string[]): void;
+    (e: 'columnOrderChange', value: string[]): void;
+    (e: 'update:columnFilters', value: Record<string, string>): void;
+    (e: 'columnFiltersChange', value: Record<string, string>): void;
+}
+/**
+ * useRsTableColumns 入参。
+ * 多数字段支持 ComputedRef 或 getter，便于在 RsTable 内直接绑定 props。
+ */
+export interface UseRsTableColumnsOptions<T extends RsTableRowData> {
+    /** 原始列定义（未排序） */
+    columns: ComputedRef<RsTableColumn<T>[]> | (() => RsTableColumn<T>[]);
+    /** 受控列顺序；undefined 表示非受控 */
+    columnOrder: ComputedRef<string[] | undefined> | (() => string[] | undefined);
+    /** 非受控初始列顺序 */
+    defaultColumnOrder: string[];
+    /** 受控列筛选；undefined 表示非受控 */
+    columnFilters: ComputedRef<Record<string, string> | undefined> | (() => Record<string, string> | undefined);
+    /** 非受控初始列筛选 */
+    defaultColumnFilters: Record<string, string>;
+    /** 初始列宽（像素） */
+    initialColumnWidths: ComputedRef<Record<string, number> | undefined> | (() => Record<string, number> | undefined);
+    /** 是否允许拖拽改列宽 */
+    resizable: ComputedRef<boolean> | (() => boolean);
+    /** 列布局：auto 自适应；fixed 固定表布局 */
+    columnLayout: ComputedRef<'auto' | 'fixed'> | (() => 'auto' | 'fixed');
+    /** 是否树表（影响展开列固定） */
+    treeMode: ComputedRef<boolean> | (() => boolean);
+    /** 树表是否固定展开列到左侧 */
+    treeFixExpandColumn: ComputedRef<boolean> | (() => boolean);
+    /** 树表展开列 key */
+    treeExpandColumnKey: ComputedRef<string | null> | (() => string | null);
+    emit: UseRsTableColumnsEmit;
+}
+/**
+ * 列顺序 / 列筛选 / 列宽 / displayColumns。
+ *
+ * @returns
+ * - `columnOrderState` / `columnFiltersState`：受控或非受控读写
+ * - `displayColumns`：按顺序排列；树表可将展开列钉为 fixed-left
+ * - `resolvedColumnWidths` / `useStableColumnWidths`：拖拽列宽与稳定布局判定
+ * - `updateColumnFilter` / `columnFilterValue`：表头筛选写入与读取
+ */
+export declare function useRsTableColumns<T extends RsTableRowData>(options: UseRsTableColumnsOptions<T>): {
+    internalColumnOrder: Ref<string[], string[]>;
+    internalColumnFilters: Ref<Record<string, string>, Record<string, string>>;
+    internalColumnWidths: Ref<Record<string, number>, Record<string, number>>;
+    isColumnOrderControlled: ComputedRef<boolean>;
+    columnOrderState: import("vue").WritableComputedRef<string[], string[]>;
+    isColumnFiltersControlled: ComputedRef<boolean>;
+    columnFiltersState: ComputedRef<Record<string, string>>;
+    displayColumns: ComputedRef<RsTableColumn<T>[]>;
+    resolvedColumnWidths: import("vue").WritableComputedRef<Record<string, number>, Record<string, number>>;
+    useStableColumnWidths: ComputedRef<boolean>;
+    syncInternalColumnWidths: (columns: RsTableColumn<T>[]) => void;
+    updateColumnFilter: (key: string, value: string) => void;
+    columnFilterValue: (key: string) => string;
+};
+/** useRsTableColumns 返回值类型 */
+export type RsTableColumnsApi<T extends RsTableRowData> = ReturnType<typeof useRsTableColumns<T>>;

package/dist/composables/useRsTableColumns.js

@@ -0,0 +1,132 @@
+import { createInitialColumnWidths, resolveColumnOrder, resolveOrderedColumns } from "../components/table-utils.js";
+import { computed, ref, watch } from "vue";
+//#region src/composables/useRsTableColumns.ts
+/**
+* RsTable 列模型编排：顺序、列筛选、宽度与 displayColumns。
+*
+* 从 RsTable.vue 抽离，保持受控 / 非受控 API 与原先行为一致。
+* 不负责虚拟列切片、列拖拽排序的 DOM 交互（仍由 RsTable 编排）。
+*/
+/** 统一读取 ComputedRef / getter */
+function read(source) {
+	return typeof source === "function" ? source() : source.value;
+}
+/**
+* 列顺序 / 列筛选 / 列宽 / displayColumns。
+*
+* @returns
+* - `columnOrderState` / `columnFiltersState`：受控或非受控读写
+* - `displayColumns`：按顺序排列；树表可将展开列钉为 fixed-left
+* - `resolvedColumnWidths` / `useStableColumnWidths`：拖拽列宽与稳定布局判定
+* - `updateColumnFilter` / `columnFilterValue`：表头筛选写入与读取
+*/
+function useRsTableColumns(options) {
+	const internalColumnOrder = ref([...options.defaultColumnOrder]);
+	const internalColumnFilters = ref({ ...options.defaultColumnFilters });
+	const internalColumnWidths = ref({});
+	const isColumnOrderControlled = computed(() => read(options.columnOrder) !== void 0);
+	/** 当前列 key 顺序；受控时写回 update:columnOrder */
+	const columnOrderState = computed({
+		get: () => {
+			if (isColumnOrderControlled.value) return read(options.columnOrder) ?? [];
+			if (internalColumnOrder.value.length) return internalColumnOrder.value;
+			return resolveColumnOrder(read(options.columns));
+		},
+		set: (value) => {
+			if (isColumnOrderControlled.value) options.emit("update:columnOrder", value);
+			else internalColumnOrder.value = value;
+			options.emit("columnOrderChange", value);
+		}
+	});
+	const isColumnFiltersControlled = computed(() => read(options.columnFilters) !== void 0);
+	/** 当前列筛选 map（列 key → 查询串） */
+	const columnFiltersState = computed(() => read(options.columnFilters) ?? internalColumnFilters.value);
+	/**
+	* 更新单列筛选值。
+	* 空串会删除该 key；同时发出 update:columnFilters / columnFiltersChange。
+	*/
+	function updateColumnFilter(key, value) {
+		const next = { ...columnFiltersState.value };
+		if (value.trim()) next[key] = value;
+		else delete next[key];
+		if (isColumnFiltersControlled.value) options.emit("update:columnFilters", next);
+		else internalColumnFilters.value = next;
+		options.emit("columnFiltersChange", next);
+	}
+	/** 读取单列当前筛选文案（无则空串） */
+	function columnFilterValue(key) {
+		return columnFiltersState.value[key] ?? "";
+	}
+	/**
+	* 渲染用列列表：先按 columnOrder 排序；
+	* 树表且 fixExpandColumn 时，将展开列强制 fixed=left（已有 fixed 则不动）。
+	*/
+	const displayColumns = computed(() => {
+		const ordered = resolveOrderedColumns(read(options.columns), columnOrderState.value);
+		if (!read(options.treeMode) || !read(options.treeFixExpandColumn)) return ordered;
+		const expandKey = read(options.treeExpandColumnKey);
+		if (!expandKey) return ordered;
+		return ordered.map((column) => {
+			if (column.key !== expandKey || column.fixed) return column;
+			return {
+				...column,
+				fixed: "left"
+			};
+		});
+	});
+	/** 持久化列宽（像素）；拖拽过程中由 RsTable 另用 DOM 直写避免整表重渲 */
+	const resolvedColumnWidths = computed({
+		get: () => internalColumnWidths.value,
+		set: (value) => {
+			internalColumnWidths.value = value;
+		}
+	});
+	/**
+	* 是否启用「稳定列宽」布局（resizable 下避免松手回弹）。
+	* fixed 布局，或每一列都有显式 width / 已测宽时为 true。
+	*/
+	const useStableColumnWidths = computed(() => {
+		if (!read(options.resizable)) return false;
+		if (read(options.columnLayout) === "fixed") return true;
+		const widths = internalColumnWidths.value;
+		return displayColumns.value.every((col) => {
+			return typeof widths[col.key] === "number" || col.width !== void 0;
+		});
+	});
+	/**
+	* 按当前 columns 重建内部列宽：保留已有测量值，合并 initialColumnWidths。
+	* columns 变化时由 watch 调用。
+	*/
+	function syncInternalColumnWidths(columns) {
+		const preserved = {};
+		for (const column of columns) {
+			const width = internalColumnWidths.value[column.key];
+			if (typeof width === "number") preserved[column.key] = width;
+		}
+		internalColumnWidths.value = createInitialColumnWidths(columns, {
+			...read(options.initialColumnWidths) ?? {},
+			...preserved
+		}, { forceAll: read(options.resizable) && useStableColumnWidths.value });
+	}
+	watch(() => read(options.columns), (columns) => {
+		syncInternalColumnWidths(columns);
+		if (!isColumnOrderControlled.value) internalColumnOrder.value = resolveColumnOrder(columns, internalColumnOrder.value);
+	}, { immediate: true });
+	return {
+		internalColumnOrder,
+		internalColumnFilters,
+		internalColumnWidths,
+		isColumnOrderControlled,
+		columnOrderState,
+		isColumnFiltersControlled,
+		columnFiltersState,
+		displayColumns,
+		resolvedColumnWidths,
+		useStableColumnWidths,
+		syncInternalColumnWidths,
+		updateColumnFilter,
+		columnFilterValue
+	};
+}
+//#endregion
+export { useRsTableColumns };