@robot-admin/naive-ui-components 0.17.0 → 0.17.2

package/dist/useTimeSelection.d.ts

@@ -59,11 +59,10 @@ declare const __VLS_export: vue.DefineComponent<TimeProps, TimeExpose, {}, {}, {
   "onChange-end"?: ((time: number | null) => any) | undefined;
 }>, {
   placeholder: string;
-  format: string;
   mode: TimeMode;
-  attrs: Record<string, any>;
   startPlaceholder: string;
   endPlaceholder: string;
+  format: string;
   useHours: boolean;
   useMinutes: boolean;
   useSeconds: boolean;
@@ -72,6 +71,7 @@ declare const __VLS_export: vue.DefineComponent<TimeProps, TimeExpose, {}, {}, {
   secondStep: number;
   startTimeProps: Record<string, any>;
   endTimeProps: Record<string, any>;
+  attrs: Record<string, any>;
   defaultStartTime: number | null;
   defaultEndTime: number | null;
   defaultSingleTime: number | null;

package/dist/useWorkflowValidation.d.cts

@@ -118,6 +118,8 @@ interface WorkflowProps {
   departments?: Department[];
   modelValue?: WorkflowData;
   readonly?: boolean;
+  /** 是否允许循环连接，默认 true。无环审批流程应设为 false；执行规则由业务后端校验。 */
+  allowCycles?: boolean;
   theme?: 'light' | 'dark';
 }
 interface WorkflowEmits {
@@ -239,23 +241,24 @@ declare const __VLS_export: vue.DefineComponent<WorkflowProps, {
 }, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
   "update:modelValue": (value: WorkflowData) => any;
   change: (value: WorkflowData) => any;
+  "node-click": (node: WorkflowNode) => any;
   save: (data: WorkflowData) => any;
   "validate-error": (errors: ValidationError[]) => any;
-  "node-click": (node: WorkflowNode) => any;
   "edge-click": (edge: WorkflowEdge) => any;
 }, string, vue.PublicProps, Readonly<WorkflowProps> & Readonly<{
   "onUpdate:modelValue"?: ((value: WorkflowData) => any) | undefined;
   onChange?: ((value: WorkflowData) => any) | undefined;
+  "onNode-click"?: ((node: WorkflowNode) => any) | undefined;
   onSave?: ((data: WorkflowData) => any) | undefined;
   "onValidate-error"?: ((errors: ValidationError[]) => any) | undefined;
-  "onNode-click"?: ((node: WorkflowNode) => any) | undefined;
   "onEdge-click"?: ((edge: WorkflowEdge) => any) | undefined;
 }>, {
-  theme: "light" | "dark";
   readonly: boolean;
+  theme: "light" | "dark";
   users: User[];
   roles: Role[];
   departments: Department[];
+  allowCycles: boolean;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 //#endregion
@@ -1019,6 +1022,8 @@ interface WorkflowValidationOptions {
   onShowNodeConfig?: (node: WorkflowNode) => void;
   /** 验证失败时的外部回调（通常用于 emit） */
   onValidateError?: (errors: ValidationError[]) => void;
+  /** 默认允许循环以兼容通用流程；审批业务可显式关闭。 */
+  allowCycles?: boolean | (() => boolean);
 }
 /** 工作流验证 —— 封装流程校验逻辑、错误展示和节点定位 */
 declare function useWorkflowValidation(nodes: Ref<WorkflowNode[]>, edges: Ref<WorkflowEdge[]>, vueFlowRef: Ref, options?: WorkflowValidationOptions): {

package/dist/useWorkflowValidation.d.ts

@@ -118,6 +118,8 @@ interface WorkflowProps {
   departments?: Department[];
   modelValue?: WorkflowData;
   readonly?: boolean;
+  /** 是否允许循环连接，默认 true。无环审批流程应设为 false；执行规则由业务后端校验。 */
+  allowCycles?: boolean;
   theme?: 'light' | 'dark';
 }
 interface WorkflowEmits {
@@ -239,23 +241,24 @@ declare const __VLS_export: vue.DefineComponent<WorkflowProps, {
 }, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
   "update:modelValue": (value: WorkflowData) => any;
   change: (value: WorkflowData) => any;
+  "node-click": (node: WorkflowNode) => any;
   save: (data: WorkflowData) => any;
   "validate-error": (errors: ValidationError[]) => any;
-  "node-click": (node: WorkflowNode) => any;
   "edge-click": (edge: WorkflowEdge) => any;
 }, string, vue.PublicProps, Readonly<WorkflowProps> & Readonly<{
   "onUpdate:modelValue"?: ((value: WorkflowData) => any) | undefined;
   onChange?: ((value: WorkflowData) => any) | undefined;
+  "onNode-click"?: ((node: WorkflowNode) => any) | undefined;
   onSave?: ((data: WorkflowData) => any) | undefined;
   "onValidate-error"?: ((errors: ValidationError[]) => any) | undefined;
-  "onNode-click"?: ((node: WorkflowNode) => any) | undefined;
   "onEdge-click"?: ((edge: WorkflowEdge) => any) | undefined;
 }>, {
-  theme: "light" | "dark";
   readonly: boolean;
+  theme: "light" | "dark";
   users: User[];
   roles: Role[];
   departments: Department[];
+  allowCycles: boolean;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 //#endregion
@@ -1019,6 +1022,8 @@ interface WorkflowValidationOptions {
   onShowNodeConfig?: (node: WorkflowNode) => void;
   /** 验证失败时的外部回调（通常用于 emit） */
   onValidateError?: (errors: ValidationError[]) => void;
+  /** 默认允许循环以兼容通用流程；审批业务可显式关闭。 */
+  allowCycles?: boolean | (() => boolean);
 }
 /** 工作流验证 —— 封装流程校验逻辑、错误展示和节点定位 */
 declare function useWorkflowValidation(nodes: Ref<WorkflowNode[]>, edges: Ref<WorkflowEdge[]>, vueFlowRef: Ref, options?: WorkflowValidationOptions): {

package/dist/verification.d.cts

@@ -76,17 +76,17 @@ declare const __VLS_export: vue.DefineComponent<CaptchaProps, {
   reset: () => void;
   show: () => void;
 }, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {} & {
-  success: (data: CaptchaSuccessPayload) => any;
   change: (valid: boolean) => any;
   reset: () => any;
+  success: (data: CaptchaSuccessPayload) => any;
   fail: (error: string) => any;
   "verify-error": (error: unknown) => any;
   "load-error": (error: unknown) => any;
   "visible-change": (visible: boolean) => any;
 }, string, vue.PublicProps, Readonly<CaptchaProps> & Readonly<{
-  onSuccess?: ((data: CaptchaSuccessPayload) => any) | undefined;
   onChange?: ((valid: boolean) => any) | undefined;
   onReset?: (() => any) | undefined;
+  onSuccess?: ((data: CaptchaSuccessPayload) => any) | undefined;
   onFail?: ((error: string) => any) | undefined;
   "onVerify-error"?: ((error: unknown) => any) | undefined;
   "onLoad-error"?: ((error: unknown) => any) | undefined;

package/dist/verification.d.ts

@@ -76,17 +76,17 @@ declare const __VLS_export: vue.DefineComponent<CaptchaProps, {
   reset: () => void;
   show: () => void;
 }, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {} & {
-  success: (data: CaptchaSuccessPayload) => any;
   change: (valid: boolean) => any;
   reset: () => any;
+  success: (data: CaptchaSuccessPayload) => any;
   fail: (error: string) => any;
   "verify-error": (error: unknown) => any;
   "load-error": (error: unknown) => any;
   "visible-change": (visible: boolean) => any;
 }, string, vue.PublicProps, Readonly<CaptchaProps> & Readonly<{
-  onSuccess?: ((data: CaptchaSuccessPayload) => any) | undefined;
   onChange?: ((valid: boolean) => any) | undefined;
   onReset?: (() => any) | undefined;
+  onSuccess?: ((data: CaptchaSuccessPayload) => any) | undefined;
   onFail?: ((error: string) => any) | undefined;
   "onVerify-error"?: ((error: unknown) => any) | undefined;
   "onLoad-error"?: ((error: unknown) => any) | undefined;

package/docs/component-review-20261019.md

@@ -0,0 +1,55 @@
+# 表格布局、性能与组件复查
+
+日期：2026-10-19。基线为 `v0.17.0`，本轮修改通过 Changeset 登记为后续补丁，不将源码合入描述为已发布新 npm 版本。
+
+## 展开列间距的原因与默认行为
+
+原样式给非末列统一加 `min-width: 80px !important`；普通列映射又为辅助列填入业务默认宽度，展开/选择增强器随后丢弃显式元数据。宽屏自动布局还会把空余空间分给所有定宽列，不能只改一个 CSS 数字。
+
+本轮将辅助列默认宽度收敛为选择 40、展开 40、序号 50。未声明宽度的普通非固定业务列保持自然弹性，并保留首选最小宽度；辅助列与弹性业务列共存时默认采用原生 fixed 布局。显式宽度、上限、固定位置、全局列宽和原生 table-layout 不被改写。所有业务列均显式定宽时保留原生余量分配语义。
+
+相同 1440px 独立浏览器场景中，0.17.0 的三个辅助列各约 142.56px；修改后为 40/40/50px。该场景含一列未指定宽度、最小宽度 220px 的名称列，同时测试普通与固定列布局。详细配置见[表格指南](./guides/table-density.md)。
+
+## 性能改进的可验证范围
+
+| 位置           | 原问题                                        | 修改与验证                                                                          |
+| -------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
+| 程序化跨页选择 | 每选择一个键都扫描本地数据                    | 首次使用时建索引，重复查询复用；1 万行选择末尾 100 行，rowKey 调用 995,150 → 10,100 |
+| 批量展开       | 每个新键线性找行，差集反复 includes           | 惰性行键索引与 Set 差集；1 万键展开线性访问，不重复扫描                             |
+| 树行辅助遍历   | 深度递归可栈溢出                              | 迭代 DFS，保留对象身份、顺序和循环/共享节点去重                                     |
+| 表单修改检测   | 只判断是否修改仍比较所有字段                  | 首个差异短路；嵌套 Map/Set 修改仍可触发外层计算                                     |
+| 图和甘特实例   | 第三方大型对象被 Vue 深代理，同帧配置多次重建 | 原始实例浅引用，甘特主题/配置合并监听与重复初始化取消                               |
+
+以上是算法调用量和生命周期验证，不表示整表 FPS 按同比例提升。2 万深、15 万宽的辅助遍历测试不代表 Naive 原生能渲染同等规模的 DOM；实际大表仍应使用分页、虚拟滚动、稳定且唯一的 rowKey。
+
+## 其他已修复问题
+
+| 组件                     | 修改                                                                              |
+| ------------------------ | --------------------------------------------------------------------------------- |
+| Login                    | 异步校验任务锁；等待后重新核对禁用、加载、表单快照、视图与卸载状态                |
+| ImageCropper / Signature | 新读取、清空、替换与卸载使旧图片结果失效；裁剪导出在 scope 结束时结算并释放计时器 |
+| WorkFlow                 | 清理旧定位延迟；卸载、替换画布、删除节点或重置后不打开旧配置                      |
+| TagsView                 | 批量关闭保留所有 affix 固定标签                                                   |
+| Chat                     | 历史前插保留阅读位置；同条数切换会话定位；末条消息更新仅在接近底部时跟随          |
+| VideoPlayer              | 常规 WebVTT 时间行正确解析；复用字幕请求，防切换乱序、关闭后重开和卸载后写入      |
+| Barcode                  | 按真实 vendor 契约传入 options，非法内容触发 error 并支持恢复                     |
+| Draggable                | 跨列表及克隆事件返回真实业务对象，避免把 DOM 或邻项当业务数据                     |
+
+## 审查范围与后续空间
+
+后续进展：本节列出的列表窗口化、字幕索引、瀑布流图片批处理及 Code/QRCode 异步边界已在后续专项处理中完善，见[大列表与异步任务](./guides/runtime-performance.md)。下文保留本次表格复查时的记录，不能将两个阶段的测试数量混用。
+
+本轮逐项源码审读 51 个公开组件：表单/表格/树与分割、导航/标签/主题、消息/工作流、图表、媒体/编辑器、选择/拖拽、加载与其他工具组件。Map、OrgChart、FilePreview、Upload 在另一个活动工作区单独改进，本轮不覆盖或混入其未提交修改。公共 `_shared` 目录不计作业务组件。
+
+审读重点是高频计算、重复初始化、事件/observer/计时器释放、异步任务身份、公开事件和 vendor 真实接入。只有已修改路径及明确场景有新增针对性回归，不能将源码审读等同于所有组件、浏览器、第三方引擎都做了压测。
+
+仍有专项空间：WaterFall 图片布局批处理与窗口化、Chat/Transfer/GlobalSearch 等海量列表的窗口化、长字幕的时间索引、媒体运行时配置切换与大文档编辑性能。现有普通 DOM 列表并非无限数据容器；应按实际数据量和耗时/内存证据推进，不为了统一形式给所有组件加入自建虚拟滚动和更多开关。
+
+次要异步状态仍可进一步完善：Code 快速切换语言时 loading 尚无独立请求代次；QRCode 的旧 Logo 图像请求虽不会提交过期结果，底层网络加载本身没有主动取消。这些没有作为本轮已修复项。
+
+## 本轮实际校验
+
+- 完整 `bun run verify` 通过：282 项单元、173 项真实组件挂载，以及 TypeScript、Vue/组件/消费者声明、lint、构建、ESM/CJS 与 Node16/NodeNext 打包消费者契约检查。
+- 包与四个轻量入口的体积预算通过，未放宽预算；消费者契约复用本机安装的依赖版本，没有宣称重新从公开 registry 安装了尚未发布的补丁。
+- 隔离浏览器以 1440/720/420px、明暗主题和三种密度组合运行 18 组场景、36 个表格实例，核对实际辅助列宽、表头/表体对齐、业务最小宽度、展开/收起、真实选择和页面错误。对比基线使用已发布 0.17.0 的实际产物。
+- 本轮没有运行真实业务后端、没有给所有第三方引擎做性能压测，也没有以 Chromium 结果替代其他浏览器/平台验收。

package/docs/components.en.md

@@ -99,6 +99,8 @@ Image/calendar behavior notes: `C_ImageCropper` flips the actual source and rese
 
 `C_VtableGantt` merges presets and `options` without dropping untouched nested settings, replaces arrays as a whole, and ignores prototype-related keys. Its fullscreen button reflects the actual fullscreen state of that Gantt container.
 
+If Gantt initialization or rebuilding fails, a released `ganttInstance` is cleared, an error and retry button appear, and an `error` event emits an `Error`. The component instance exposes `loading`, `error`, and asynchronous `reload()` for status feedback and retries. Wait for `ganttCreated` before operating on a replacement engine instance.
+
 `C_AudioPlayer` enters the playing state and emits `play` only after the browser accepts `play()`. A rejected autoplay emits `error`, and an empty playlist cannot emit a false play event. Mute, playlist tracks, and seeking are keyboard operable.
 
 `C_CollapsePanel` and `C_TagsView` validate persisted data before restoring it, so corrupt or outdated JSON cannot break initialization. Persisted tags restore only in-app paths, and special characters in a path are no longer interpolated into CSS selectors.
@@ -107,6 +109,8 @@ Image/calendar behavior notes: `C_ImageCropper` flips the actual source and rese
 
 `C_WorkFlow` loads the supplied `modelValue` on first render and returns isolated snapshots from `getCurrentWorkflowData()`, `save`, `change`, and `node-click`, so callers cannot accidentally mutate its internal nodes. Editing conditions cannot change canvas data before Save, and incomplete conditions are not silently dropped. `readonly` blocks dragging, connecting, configuring, adding/removing, and saving while leaving preview, validation, and fit-to-view available. Node and condition IDs remain unique when created in the same tick.
 
+Workflow validation requires unique, nonempty node and edge IDs, exactly one start node, existing edge endpoints, and directed reachability from the start to every node. `allowCycles` defaults to `true` for general workflows with loops. Use `:allow-cycles="false"` for acyclic approval flows; a detected cycle blocks saving and produces a structural error that can be located on the canvas. This option supports runtime changes. Passing validation confirms graph structure and node configuration; execution, permissions, and business rules remain the responsibility of the business backend.
+
 Type verification covers TypeScript source, Vue SFC templates, and consumer examples built against the package. `C_Table` summary rendering expects an object keyed by column (`{ columnKey: { value, colSpan? } }`). `C_FormSearch` preserves existing numeric timestamp ranges and also supports formatted string ranges, binding each to the matching Naive UI value API.
 
 Runtime component dependencies are declared by this package and resolved automatically. Every consumer needs:

package/docs/components.md

@@ -99,6 +99,8 @@
 
 `C_VtableGantt` 合并预设与 `options` 时会保留未覆盖的嵌套配置、以新数组整体替换旧数组，并忽略原型相关键；全屏按钮状态仅反映该甘特图容器的实际全屏状态。
 
+甘特图初始化或重建失败时，会清空已释放的 `ganttInstance`、显示错误及重试按钮，并触发 `error` 事件（参数为 `Error`）。组件实例公开 `loading`、`error` 和异步 `reload()`，使用侧可据此展示状态或主动重试；等待 `ganttCreated` 后再操作新的底层实例。
+
 `C_AudioPlayer` 只在浏览器确认 `play()` 成功后进入播放状态并触发 `play`；自动播放被拒绝时会触发 `error`，空播放列表不会产生虚假的播放事件。静音、曲目和进度条均可用键盘操作。
 
 `C_CollapsePanel` 与 `C_TagsView` 会校验本地持久化数据结构；损坏或旧格式数据会安全回退，不会阻断组件初始化。持久化标签仅恢复站内路径，特殊字符路径的定位不会拼接 CSS 选择器。
@@ -107,6 +109,8 @@
 
 `C_WorkFlow` 会在首次渲染时加载传入的 `modelValue`，并在 `getCurrentWorkflowData()` / `save` / `change` / `node-click` 中输出隔离的数据快照，避免调用方意外修改内部节点。条件编辑弹窗在保存前不会修改画布数据，未填完整的条件不会被静默丢弃。`readonly` 禁止节点拖拽、连线、配置、增删与保存，但仍允许预览、验证和适应视图；节点与条件 ID 在同一时刻连续创建时保持唯一。
 
+流程校验要求节点与连线标识唯一且非空、恰有一个开始节点、连线两端存在，且所有节点可从开始节点按连线方向到达。`allowCycles` 默认 `true`，兼容包含回路的通用流程；无环审批流程使用 `:allow-cycles="false"`，发现循环时阻止保存并定位结构错误。该选项可动态更新；校验结果仅代表图结构与节点配置合法，审批执行、权限和业务规则仍由业务后端负责。
+
 类型验证同时覆盖 TypeScript 源码、Vue 单文件组件模板和发布后的使用侧示例。`C_Table` 合计行的 `summary.render` 应返回按列键组织的对象（`{ columnKey: { value, colSpan? } }`）；`C_FormSearch` 的日期范围兼容原有数字时间戳数组，也支持格式化字符串数组，两种值会分别绑定 Naive UI 对应的值接口。
 
 组件运行依赖已由本包声明，安装组件库时会自动解析。所有场景都需要：

package/docs/guides/runtime-performance.md

@@ -0,0 +1,38 @@
+# 大列表与异步任务
+
+组件保持按需导入和现有事件契约。以下优化默认生效；普通接入无需配置虚拟列表引擎、分页游标或滚动状态。
+
+## 自动减少列表 DOM
+
+| 组件             | 生效条件                           | 保留的语义                                                   |
+| ---------------- | ---------------------------------- | ------------------------------------------------------------ |
+| `C_Transfer`     | 左右面板分别按筛选后项数，100 项起 | 完整数据筛选、全选、禁用项、移动顺序、v-model                |
+| `C_Chat`         | 消息 200 条起；联系人 100 条起     | 图片、文件、系统消息、重发、联系人事件；实际测量变高行       |
+| `C_GlobalSearch` | 搜索结果列表                       | 完整匹配结果、上下键跨视口定位、Enter 选择、输入法与历史记录 |
+
+```vue
+<C_Transfer v-model="selectedKeys" :data="people" filterable />
+<C_Chat :messages="messages" :contacts="contacts" @send="sendMessage" />
+<C_GlobalSearch :options="searchOptions" />
+```
+
+窗口化复用 `vueuc` 的公开 `VVirtualList`，兼容本包声明的 Naive UI 2.35；不依赖 Naive 内部导入，也不提高 Naive peer 下限。只减少渲染的 DOM，数据仍完整保存在内存中，搜索仍检查完整索引。
+
+穿梭框的三档行高和自定义方式见[穿梭框指南](./transfer.md)。聊天会实测文本、图片和文件行高度，无需调用方预先计算高度。业务 ID 应唯一、稳定；聊天容器应有确定高度，例如外层 `height: 600px`。
+
+若打印、DOM 集成或自定义穿梭框行高需要完整节点，可给 `C_Transfer` 或 `C_Chat` 设置 `:virtual-scroll="false"`。不要把此开关作为加载更多数据的接口；聊天加载历史仍通过 `load-more` 事件及 `loading-history` 状态接入。
+
+## 聊天滚动与输入
+
+打开或切换会话定位最新消息。阅读历史时，新增消息不抢滚动位置；前插历史保留阅读锚点。正在底部时，流式文本、迟到图片与面板高度变化继续跟随。跨越自动窗口化门槛也保持当前阅读状态。
+
+公开 `scrollToBottom()` 可用于主动跳到最新消息。输入法 Enter 确认候选不会提前发送；普通 Enter 保持发送行为。
+
+## 图片、字幕和异步状态
+
+- 瀑布流将同帧图片测量合并为一次布局，参数变化和公开 `relayout()` 仍立即计算。替换图片来源后忽略旧测量，卸载时取消待执行帧。导出的 `useWaterFallLayout` 原有四参数用法保持同步行为。
+- 字幕载入时编译时间索引；播放与前后跳转查询使用二分查找，保留重叠字幕按原文件顺序首匹配的语义。
+- 代码语言加载只由当前请求更新 loading 和高亮。语言注册后主动更新高亮器引用，同一种语言异步加载完成也会重新着色。复制事件返回点击当时的文本。
+- 二维码渲染及每次导出分别保存配置快照。新渲染取消旧 Logo 加载，导出相互独立；卸载取消所有任务并释放 Image 事件。组件销毁期间尚未完成的导出会以 `AbortError` 拒绝，调用方按普通异步错误处理即可。
+
+这些改进不代表列表、瀑布流和编辑器可以无限增加数据。大规模业务仍应按实际场景分段加载、回收历史，并测量内存、交互延迟与目标浏览器表现。

package/docs/guides/split-pane.en.md

@@ -82,6 +82,10 @@ Existing uncontrolled usage remains supported. Moving the gutter outside the per
 
 ## Interaction
 
+A fine divider line carries a centered capsule grip (80px long, 16px thick by default). Nearby collapse buttons appear on hover or keyboard focus and stay visible while collapsed. Borders, a restrained shadow and local accent feedback use the existing `--c-primary`, `--c-bg-card`, `--c-border` and `--c-text-3` theme tokens in both orientations.
+
+The capsule itself accepts dragging without increasing the layout space reserved by `gutterSize`. Touch input gets a 24px grip thickness and permanently visible 28px buttons. Collapsed controls dock inside the container to avoid clipping. Inline SVG arrows require no remote icon request, and reduced-motion preferences disable transitions.
+
 The [W3C APG Window Splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/) informs keyboard behavior and separator semantics. Use Left/Right for left/right layouts and Up/Down for top/bottom layouts. Home/End move to the current boundaries. Enter collapses the first pane or restores an already collapsed pane. Double-click toggles the first pane.
 
 Pointer Events support mouse, pen and touch. Pointer cancellation, window blur, document hiding, disablement, direction changes and unmounting all dispose listeners and restore the previous body cursor / text selection styles. Nested splitters do not overwrite `document.onmousemove`.

package/docs/guides/split-pane.md

@@ -96,6 +96,10 @@
 
 ## 交互与无障碍
 
+手柄采用细轨道与居中胶囊握柄，默认长 80px、厚 16px，保留三点拖动提示。悬停和键盘聚焦时，在握柄两侧显示折叠入口，并以局部描边和轻阴影提示当前状态；折叠后入口持续显示。横向、纵向使用相同视觉规则，主题颜色复用 `--c-primary / --c-bg-card / --c-border / --c-text-3`。
+
+胶囊是独立的实际拖动区域，其视觉厚度不会改变 `gutterSize` 占用的布局空间。触屏下握柄厚度增至 24px、折叠按钮增至 28px，并保持按钮常驻；折叠到边缘时控件向容器内部停靠，避免被裁切。箭头使用本地 SVG，不请求远程图标。
+
 键盘交互与 separator 语义参照 [W3C APG Window Splitter](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/)。可用 `aria-label="订单主表"` 设置面板对应的可访问名称。
 
 - 拖动支持鼠标、触控笔和触屏 Pointer Events，不接管宿主的 `document.onmousemove`。

package/docs/guides/table-density.md

@@ -65,3 +65,29 @@ const config = {
 分页、树表、虚拟滚动、选择、导出继续使用各自的分组配置。它们是可组合能力，不设隐含开启多种行为的“万能模式”。
 
 多表分屏请参阅[分割面板](./split-pane.md)；表单优先级与布局示例请参阅[表单密度](./form-density.md)。
+
+## 展开、序号和弹性业务列
+
+默认辅助列宽度：选择列 `40px`、展开列 `40px`、序号列 `50px`。普通未固定的业务列不再被统一填上 `width: 180`；未指定宽度时，它按首选最小宽度吸收容器余量。有辅助列和自然弹性业务列时，默认使用原生 `fixed` 表格布局，避免空余空间把展开与序号撑大：
+
+```ts
+const columns: TableColumn<Order>[] = [
+  { type: 'selection' },
+  { type: 'expand' },
+  { type: 'index' },
+  { key: 'name', title: '订单名称', minWidth: 220 }, // 自然弹性列
+  { key: 'amount', title: '金额', width: 140 },
+]
+```
+
+不需要给每张表写辅助列 CSS。显式列 `width / minWidth / maxWidth / fixed / className / cellProps` 保持转发；`config.display.columnWidth`（包括全局配置中的显式 `180`）仍表示统一列宽。固定业务列继续使用可计算的数值默认宽度；原生 `table-layout` 属性可覆盖自动选择的布局。
+
+若所有业务列都显式指定宽度，且总宽小于容器，保留原生表格的剩余空间分配规则；这时声明的 `width` 不保证等于最后测量的像素。通常让名称或描述列保持弹性，比给所有列设宽更合适。虚拟横向滚动仍需按 Naive UI 的契约提供具体列宽。
+
+独立的列 `renderExpand` 直接转交原生表格；配置 `config.expand.onLoadData / renderContent` 后由组件的加载、失败重试和内容渲染器接管展开区。不要同时配置两套展开内容并依赖原生渲染器优先。自动横向滚动宽度按最终可见列计算，包含辅助列、动态选择列和操作列，不再额外追加固定留白。
+
+## 行拖拽的组合范围
+
+`config.rowDrag: true` 按稳定 `rowKey` 重排当前页的顶层行。树表的子行、详情展开内容及合计行不参与拖拽；移动父行时其子树数据整体保留，不改变父子关系。过滤、排序与分页后的行位置会映射回原始数据，其余页和隐藏行保持不变。使用侧继续接收 `update:data` 和 `row-move`，无须自行计算 DOM 下标。
+
+纵向 `config.virtualScroll` 或横向 `virtualScrollX` 开启时，行拖拽自动停用，避免局部窗口错误重排完整数据；退出虚拟模式后恢复。拖拽期间数据被替换或身份变化，会丢弃该次排序。行键必须唯一、稳定，数字与字符串按各自类型区分。空数据后加载、错误视图恢复等表体重新出现的场景会自动连接拖拽实例。

package/docs/guides/transfer.md

@@ -0,0 +1,11 @@
+# 穿梭框与大列表
+
+```vue
+<C_Transfer v-model="selectedKeys" :data="people" filterable />
+```
+
+左右面板分别按搜索后的项数决定渲染方式：少于 100 项使用普通列表，100 项起复用 Naive UI 同样使用的官方 `vueuc/VVirtualList`，只挂载当前视口及相邻行。全选、禁用判断和移动顺序仍以完整列表为准；滚动到视口之外的选中项不会丢失。右侧保持 `modelValue` 的顺序，新增项按左侧数据顺序追加。
+
+`size="small | medium | large"` 对应 28 / 34 / 40px 固定行高。继续通过既有 `--tf-height` 覆盖列表高度，例如 `style="--tf-height: 240px"`；无需为大列表额外设置高度或分页。
+
+若项目自行改变行高、需要打印全部项，或依赖完整列表 DOM，可显式设置 `:virtual-scroll="false"` 保留普通渲染。默认开启自动判断，常规接入无需配置。搜索仍检查全部数据；虚拟列表减少 DOM 与组件挂载量，不把筛选或数据存储变成无限容量服务。

package/docs/runtime-review-20261019.md

@@ -0,0 +1,41 @@
+# 大列表、渲染与异步任务专项复查
+
+日期：2026-10-19。本轮接续[表格与组件复查](./component-review-20261019.md)，并合并远端 `fdffe29` 中已提交的地图、组织图、预览、上传、甘特及瀑布流修复。功能变更通过 Changeset 登记，源码合入不等于发布新的 npm 版本。
+
+## 修改及可验证收益
+
+| 路径          | 实际改进                                                                            | 验证方式                                                                                                       |
+| ------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Transfer      | 每侧筛选结果 100 项起窗口化；保留完整选择和移动语义；普通接入零新增必填项           | 3000 项的真实列表仅挂载视口附近的行；三档行高 28/34/40px，筛选末项、禁用保护、移动和完整 DOM 逃生回归          |
+| GlobalSearch  | 菜单派生文本缓存；完整结果窗口化；跨视口键盘定位                                    | 1 万菜单连续 4 次搜索，label/key 各读取 1 万次；5000 匹配结果保留，键盘定位第 1201 项并返回正确 key            |
+| Chat          | 消息 200 条、联系人 100 条起自动窗口化；变高行交给公开引擎实测                      | 1000 消息、500 联系人实际 DOM 有界；文件/图片/重发事件，历史前插、流式、迟到图片、会话切换、门槛及尺寸变化回归 |
+| WaterFall     | 图片与标题/插槽高度测量合并为单帧布局；RO 条目与元素登记用 Map 查询                 | 1000 项中 100 张图片与 100 次标题测量只发布一次布局；显式 relayout/配置变化仍立即计算；三种宽度长标题无重叠    |
+| Subtitle      | 编译保留源顺序优先级的区间索引，二分查询                                            | 重叠、乱序、相同边界及反向跳转对照线性参考；10 万字幕每次查询最多 19 次区间读取                                |
+| Code / QRCode | 当前任务拥有 loading/输出；复制及导出保留输入快照；卸载取消迟到结果及 Logo 图片事件 | 真正 NCode 同语言异步重高亮、快速切换、复制快照；二维码并发导出、取消、绘图异常和卸载回归                      |
+
+DOM 数量和算法访问次数说明对应瓶颈的变化，不代表整页 FPS 或所有数据规模的同倍数改善。虚拟列表仍保留全部内存数据，实际业务应按需分段加载。
+
+## 使用侧与兼容性
+
+自动窗口化复用 `vueuc` 的公开 `VVirtualList`，通过直接依赖声明，未使用 Naive 内部导入，也未将 Naive peer 从 2.35 提高到 2.36。`C_Transfer` 与 `C_Chat` 可用 `virtualScroll=false` 保留完整 DOM。聊天 ID 应唯一稳定，容器应有确定高度。
+
+穿梭框保留 `--tf-height`。聊天变高行不要求业务填写高度；输入法 Enter 确认候选不会发送。公开 `useWaterFallLayout` 四参数调用仍同步，实际组件才显式开启批处理。二维码组件销毁时未完成的导出以 `AbortError` 拒绝；并行导出互不取消。
+
+具体接入与边界见[大列表与异步任务](./guides/runtime-performance.md)及[穿梭框指南](./guides/transfer.md)。
+
+## 代码质量与验证边界
+
+索引、任务和滚动逻辑拆分到各自小模块，模板样式跟随提取的子组件收集；保留公开事件 payload，没有放宽质量或体积预算。合并瀑布流时保留远端的标题高度修复，并将逐条查找和逐元素扫描改为索引，ref 清空、行删除、卸载都会释放观察。
+
+验证采用本机 Bun 1.4.2、Vue 3.5.42、Naive 2.45.3；额外用真实 Naive 2.35.0 包 alias 验证本轮四个相关组件，不将 mock 当兼容证明。
+
+- 合并后完整 `bun run verify`：306 项 Bun 单元、207 项组件挂载，以及 TypeScript/Vue/消费者类型、构建、55 个 ESM/CJS 组件入口、Node16/NodeNext 打包消费者契约均通过。
+- Naive 2.35.0：36 项相关挂载测试和四组件类型检查通过。
+- `bun install --frozen-lockfile --offline --ignore-scripts` 通过；包与轻量入口体积预算保持原值。消费者依赖复用本机已安装版本，未声称从公开 registry 全新安装尚未发布的版本。
+- Chromium 合成场景核对 3000 项穿梭框、5000 项搜索、1000 条聊天及 500 联系人；另验证 199/200 条切换、面板变矮、普通历史前插迟到图片和 IME。明暗主题及窄屏截图检查，未发现运行异常。
+- 使用构建后的命名导出及各组件独立 CSS 入口重复 27 项浏览器检查全部通过，确认抽取的消息、联系人和穿梭框行样式包含在按需产物中。
+- 瀑布流浏览器核对 100 图、40 个含长标题条目，在 1000/700/420px 容器下无重叠；移除条目立即解除观察，卸载无残留观察目标或 RO 循环错误。
+
+全库 lint 无错误；未修改路径及合入的既有路径仍存在复杂度/解构建议警告，本轮修改的性能模块没有新增警告。以上不替代其他浏览器、真实业务后端或全部第三方引擎的长期压测。
+
+瀑布流此次解决测量和重排，不包含其窗口化协议；媒体运行时配置切换、大文档编辑和特定业务巨量数据仍应按实际 profile 做专项。不能据本轮结果宣称组件库已无优化空间。

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "基于 Naive UI 的 Vue 3 组件库",
   "packageManager": "bun@1.3.14",
   "engines": {
@@ -132,7 +132,6 @@
     }
   },
   "dependencies": {
-    "@robot-admin/form-validate": "3.4.2",
     "@antv/x6": "^2.19.2",
     "@chenfengyuan/vue-barcode": "^2.0.2",
     "@fullcalendar/core": "^6.1.21",
@@ -141,8 +140,10 @@
     "@fullcalendar/list": "^6.1.21",
     "@fullcalendar/vue3": "^6.1.21",
     "@iconify/vue": "^5.0.1",
+    "@robot-admin/form-validate": "3.4.2",
     "@types/leaflet": "^1.9.22",
     "@visactor/vtable": "^1.26.7",
+    "@visactor/vtable-editors": "^1.26.7",
     "@visactor/vtable-gantt": "^1.26.7",
     "@vue-flow/core": "^1.48.2",
     "@wangeditor-next/editor": "6.2.0",
@@ -161,6 +162,7 @@
     "vue-cropper": "^1.1.4",
     "vue-draggable-plus": "^0.6.1",
     "vue3-puzzle-vcode": "^1.1.7",
+    "vueuc": "^0.4.66",
     "xgplayer": "3.0.26",
     "xgplayer-hls": "3.0.26",
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"