@robot-admin/naive-ui-components 0.16.0 → 0.17.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (225) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/README.md +12 -9
  3. package/README_EN.md +12 -9
  4. package/dist/C_ActionBar.css +56 -48
  5. package/dist/C_ActionBar2.cjs +1 -1
  6. package/dist/C_ActionBar2.js +1 -1
  7. package/dist/C_AntV2.cjs +1 -1
  8. package/dist/C_AntV2.js +3 -3
  9. package/dist/C_Barcode.css +6 -6
  10. package/dist/C_Barcode2.cjs +1 -1
  11. package/dist/C_Barcode2.js +1 -1
  12. package/dist/C_Chat.css +269 -185
  13. package/dist/C_Chat2.cjs +1 -1
  14. package/dist/C_Chat2.js +1 -1
  15. package/dist/C_Code.css +26 -26
  16. package/dist/C_Code2.cjs +1 -1
  17. package/dist/C_Code2.js +1 -1
  18. package/dist/C_Draggable2.cjs +1 -1
  19. package/dist/C_Draggable2.js +1 -1
  20. package/dist/C_FilePreview.css +96 -57
  21. package/dist/C_FilePreview2.cjs +1 -1
  22. package/dist/C_FilePreview2.js +1 -1
  23. package/dist/C_Form.base.css +295 -277
  24. package/dist/C_Form.css +295 -277
  25. package/dist/C_Form.d.cts +2 -1
  26. package/dist/C_Form.d.ts +2 -1
  27. package/dist/C_FormModal.css +10 -10
  28. package/dist/C_FormModal2.cjs +1 -1
  29. package/dist/C_FormModal2.js +1 -1
  30. package/dist/C_FormSearch.css +67 -68
  31. package/dist/C_FormSearch.d.cts +2 -1
  32. package/dist/C_FormSearch.d.ts +2 -1
  33. package/dist/C_FormSearch2.cjs +1 -1
  34. package/dist/C_FormSearch2.js +1 -1
  35. package/dist/C_FullCalendar2.cjs +1 -1
  36. package/dist/C_FullCalendar2.js +1 -1
  37. package/dist/C_GlobalSearch.css +140 -118
  38. package/dist/C_GlobalSearch2.cjs +1 -1
  39. package/dist/C_GlobalSearch2.js +1 -1
  40. package/dist/C_ImageCropper.css +12 -10
  41. package/dist/C_ImageCropper2.cjs +1 -1
  42. package/dist/C_ImageCropper2.js +1 -1
  43. package/dist/C_Login.css +79 -79
  44. package/dist/C_Login2.cjs +1 -1
  45. package/dist/C_Login2.js +1 -1
  46. package/dist/C_Map.css +10 -10
  47. package/dist/C_Map2.cjs +1 -1
  48. package/dist/C_Map2.js +1 -1
  49. package/dist/C_OrgChart.css +28 -4
  50. package/dist/C_OrgChart2.cjs +1 -1
  51. package/dist/C_OrgChart2.js +1 -1
  52. package/dist/C_QRCode2.cjs +1 -1
  53. package/dist/C_QRCode2.js +1 -1
  54. package/dist/C_Signature.css +15 -15
  55. package/dist/C_Signature2.cjs +1 -1
  56. package/dist/C_Signature2.js +1 -1
  57. package/dist/C_SplitPane.cjs +1 -1
  58. package/dist/C_SplitPane.css +251 -109
  59. package/dist/C_SplitPane.js +1 -1
  60. package/dist/C_SplitPane2.cjs +1 -1
  61. package/dist/C_SplitPane2.js +1 -1
  62. package/dist/C_Table.base.css +491 -563
  63. package/dist/C_Table.cjs +1 -1
  64. package/dist/C_Table.css +491 -563
  65. package/dist/C_Table.d.cts +3 -2
  66. package/dist/C_Table.d.ts +4 -2
  67. package/dist/C_Table.js +1 -1
  68. package/dist/C_TagsView2.cjs +1 -1
  69. package/dist/C_TagsView2.js +1 -1
  70. package/dist/C_Transfer.css +93 -84
  71. package/dist/C_Transfer2.cjs +1 -1
  72. package/dist/C_Transfer2.js +1 -1
  73. package/dist/C_Tree.css +72 -125
  74. package/dist/C_Tree.d.cts +3 -2
  75. package/dist/C_Tree.d.ts +15 -2
  76. package/dist/C_Tree2.cjs +1 -1
  77. package/dist/C_Tree2.js +1 -1
  78. package/dist/C_Upload.css +5 -5
  79. package/dist/C_Upload2.cjs +1 -1
  80. package/dist/C_Upload2.js +1 -1
  81. package/dist/C_VideoPlayer2.cjs +4 -3
  82. package/dist/C_VideoPlayer2.js +4 -3
  83. package/dist/C_VtableGantt.css +29 -28
  84. package/dist/C_VtableGantt2.cjs +1 -1
  85. package/dist/C_VtableGantt2.js +1 -1
  86. package/dist/C_WaterFall.css +29 -29
  87. package/dist/C_WaterFall2.cjs +1 -1
  88. package/dist/C_WaterFall2.js +1 -1
  89. package/dist/C_WorkFlow2.cjs +1 -1
  90. package/dist/C_WorkFlow2.js +1 -1
  91. package/dist/Card.cjs +1 -1
  92. package/dist/Card.js +1 -1
  93. package/dist/Custom.cjs +1 -1
  94. package/dist/Custom.js +1 -1
  95. package/dist/Dynamic.cjs +1 -1
  96. package/dist/Dynamic.js +1 -1
  97. package/dist/Steps.cjs +1 -1
  98. package/dist/Steps.js +1 -1
  99. package/dist/Tabs.cjs +1 -1
  100. package/dist/Tabs.js +1 -1
  101. package/dist/constants.d.cts +2 -2
  102. package/dist/constants.d.ts +2 -2
  103. package/dist/constants2.d.cts +2 -2
  104. package/dist/constants2.d.ts +2 -2
  105. package/dist/constants3.d.cts +2 -2
  106. package/dist/constants3.d.ts +2 -2
  107. package/dist/constants4.d.cts +4 -4
  108. package/dist/constants4.d.ts +4 -4
  109. package/dist/constants5.d.cts +3 -7
  110. package/dist/constants5.d.ts +3 -7
  111. package/dist/data.d.cts +10 -10
  112. package/dist/data.d.ts +10 -10
  113. package/dist/density.cjs +1 -0
  114. package/dist/density.d.cts +15 -0
  115. package/dist/density.d.ts +15 -0
  116. package/dist/density.js +1 -0
  117. package/dist/helpers.cjs +1 -1
  118. package/dist/helpers.js +1 -1
  119. package/dist/index.cjs +1 -1
  120. package/dist/index.d.cts +3 -3
  121. package/dist/index.d.ts +5 -3
  122. package/dist/index.js +1 -1
  123. package/dist/index.vue.d.cts +5 -5
  124. package/dist/index.vue.d.ts +5 -5
  125. package/dist/index10.vue.d.cts +5 -5
  126. package/dist/index10.vue.d.ts +3 -3
  127. package/dist/index11.vue.d.cts +3 -3
  128. package/dist/index11.vue.d.ts +5 -5
  129. package/dist/index12.vue.d.cts +5 -5
  130. package/dist/index13.vue.d.ts +5 -5
  131. package/dist/index14.vue.d.cts +5 -5
  132. package/dist/index14.vue.d.ts +9 -9
  133. package/dist/index15.vue.d.cts +9 -9
  134. package/dist/index15.vue.d.ts +3 -3
  135. package/dist/index16.vue.d.cts +3 -3
  136. package/dist/index17.vue.d.ts +1 -1
  137. package/dist/index18.vue.d.cts +1 -1
  138. package/dist/index18.vue.d.ts +7 -7
  139. package/dist/index19.vue.d.cts +7 -7
  140. package/dist/index19.vue.d.ts +5 -5
  141. package/dist/index2.vue.d.cts +2 -2
  142. package/dist/index2.vue.d.ts +2 -2
  143. package/dist/index20.vue.d.cts +6 -2
  144. package/dist/index20.vue.d.ts +6 -2
  145. package/dist/index21.vue.d.cts +2 -2
  146. package/dist/index21.vue.d.ts +2 -2
  147. package/dist/index22.vue.d.cts +2 -2
  148. package/dist/index22.vue.d.ts +2 -2
  149. package/dist/index23.vue.d.cts +2 -2
  150. package/dist/index23.vue.d.ts +2 -2
  151. package/dist/index25.vue.d.cts +5 -5
  152. package/dist/index25.vue.d.ts +5 -5
  153. package/dist/index27.vue.d.cts +2 -2
  154. package/dist/index27.vue.d.ts +2 -2
  155. package/dist/index28.vue.d.cts +7 -3
  156. package/dist/index28.vue.d.ts +7 -3
  157. package/dist/index3.vue.d.cts +3 -3
  158. package/dist/index3.vue.d.ts +3 -3
  159. package/dist/index4.vue.d.cts +5 -5
  160. package/dist/index5.vue.d.ts +2 -2
  161. package/dist/index6.vue.d.cts +2 -2
  162. package/dist/index6.vue.d.ts +7 -4
  163. package/dist/index7.vue.d.cts +7 -4
  164. package/dist/index7.vue.d.ts +2 -2
  165. package/dist/index8.vue.d.cts +2 -2
  166. package/dist/index8.vue.d.ts +4 -6
  167. package/dist/index9.vue.d.cts +4 -6
  168. package/dist/index9.vue.d.ts +5 -5
  169. package/dist/mapUtils.d.cts +4 -4
  170. package/dist/mapUtils.d.ts +4 -4
  171. package/dist/presets.d.cts +4 -1
  172. package/dist/presets.d.ts +4 -1
  173. package/dist/style.css +1763 -1566
  174. package/dist/useCalendarEvents.d.cts +10 -9
  175. package/dist/useCalendarEvents.d.ts +10 -9
  176. package/dist/useCollapsePanel.d.cts +3 -3
  177. package/dist/useCollapsePanel.d.ts +3 -3
  178. package/dist/useCropperCore.d.cts +9 -9
  179. package/dist/useCropperCore.d.ts +9 -9
  180. package/dist/useDraggableLayout.d.cts +15 -13
  181. package/dist/useDraggableLayout.d.ts +15 -13
  182. package/dist/useDynamicFormState.d.cts +5 -2
  183. package/dist/useDynamicFormState.d.ts +5 -2
  184. package/dist/useEdgeInteraction.d.cts +3 -3
  185. package/dist/useEdgeInteraction.d.ts +3 -3
  186. package/dist/useFullscreen.d.cts +4 -0
  187. package/dist/useFullscreen.d.ts +4 -0
  188. package/dist/useGlobalSearch.d.cts +9 -4
  189. package/dist/useGlobalSearch.d.ts +9 -4
  190. package/dist/useInfiniteScroll.d.cts +4 -1
  191. package/dist/useInfiniteScroll.d.ts +4 -1
  192. package/dist/useQRCode.d.cts +3 -3
  193. package/dist/useQRCode.d.ts +3 -3
  194. package/dist/useSearchState.d.cts +8 -6
  195. package/dist/useSearchState.d.ts +8 -6
  196. package/dist/useSignatureHistory.d.cts +7 -7
  197. package/dist/useSignatureHistory.d.ts +7 -7
  198. package/dist/useSplitResize.d.cts +50 -61
  199. package/dist/useSplitResize.d.ts +50 -61
  200. package/dist/useTableQuery.cjs +3 -3
  201. package/dist/useTableQuery.d.cts +237 -13
  202. package/dist/useTableQuery.d.ts +237 -13
  203. package/dist/useTableQuery.js +3 -3
  204. package/dist/useTimeSelection.d.cts +2 -2
  205. package/dist/useTimeSelection.d.ts +2 -2
  206. package/dist/useWorkflowValidation.d.cts +3 -3
  207. package/dist/useWorkflowValidation.d.ts +3 -3
  208. package/dist/verification.d.cts +5 -5
  209. package/dist/verification.d.ts +5 -5
  210. package/docs/component-review-20261019.md +55 -0
  211. package/docs/guides/form-density.en.md +42 -0
  212. package/docs/guides/form-density.md +59 -0
  213. package/docs/guides/runtime-performance.md +38 -0
  214. package/docs/guides/split-pane.en.md +103 -0
  215. package/docs/guides/split-pane.md +126 -0
  216. package/docs/guides/table-density.md +87 -0
  217. package/docs/guides/transfer.md +11 -0
  218. package/docs/guides/tree.md +157 -0
  219. package/docs/guides/usage.en.md +2 -0
  220. package/docs/guides/usage.md +2 -0
  221. package/docs/runtime-review-20261019.md +41 -0
  222. package/docs/wl-ui-produce-coverage.md +62 -0
  223. package/package.json +4 -2
  224. package/dist/useTreeOperations.d.cts +0 -185
  225. package/dist/useTreeOperations.d.ts +0 -185
@@ -0,0 +1,157 @@
1
+ # C_Tree:树状态与原生能力
2
+
3
+ `C_Tree` 在 Naive UI Tree 上提供搜索、工具栏、菜单/文件/组织预设和节点操作。过滤、级联勾选、半选、键盘、拖拽与虚拟滚动继续由 `NTree` 实现。
4
+
5
+ ## 最小接入与密度
6
+
7
+ ```vue
8
+ <C_Tree
9
+ v-model:selected-keys="selected"
10
+ :data="departments"
11
+ density="compact"
12
+ :addable="false"
13
+ :refreshable="false"
14
+ @node-select="loadDepartmentRecords"
15
+ />
16
+ ```
17
+
18
+ 默认字段仍是 `id`、`name`、`children`,已有调用不需要改数据。`data` 接受普通业务对象数组,不要求业务 interface 添加字符串索引签名或强制转型。身份、标题和子级字段由 `keyField/labelField/childrenField` 映射;事件与方法继续提供原生节点上下文,不会为了适配复制或修改输入数据。`density="default | compact | comfortable"` 与表单、搜索表单、表格使用同一协议;对应树节点高度为 34/28/40px,工具栏控件使用 medium/small/large。
19
+
20
+ 主题颜色来自 `NConfigProvider`。长标题省略并保留原生 title;操作在悬停和键盘聚焦时显示,在触屏/窄屏始终显示。工具栏按容器宽度换行,不需要为左树右表侧栏写固定搜索宽度。
21
+
22
+ ## 官方能力放进一个 treeProps
23
+
24
+ ```vue
25
+ <C_Tree
26
+ v-model:selected-keys="selected"
27
+ v-model:expanded-keys="expanded"
28
+ v-model:checked-keys="checked"
29
+ v-model:search-pattern="keyword"
30
+ :data="departments"
31
+ :tree-props="{
32
+ keyField: 'uuid',
33
+ labelField: 'title',
34
+ childrenField: 'nodes',
35
+ disabledField: 'inactive',
36
+ checkable: true,
37
+ cascade: true,
38
+ checkStrategy: 'child',
39
+ showIrrelevantNodes: false,
40
+ expandOnClick: true,
41
+ }"
42
+ />
43
+ ```
44
+
45
+ 除 `data` 以外,`treeProps` 使用已安装 Naive UI 的 `TreeProps` 类型。`multiple`、`allowDrop`、`nodeProps`、`overrideDefaultNodeClickBehavior`、`getChildren`、`renderSwitcherIcon`、`indeterminateKeys` 等均直接交给官方组件。无需给每个功能新增包装层属性,也不需要再封装一层业务树。
46
+
47
+ **配置优先级**:显式包装层属性 > `treeProps` > `mode` 预设 > 包装层默认值。这个优先级适用于重叠的字段、拖拽、连线、默认状态与受控状态。`actions: []` 能明确关闭预设操作;`draggable: false`、`showLine: false` 能覆盖菜单预设。图标 `typeMap/colorMap` 按键合并。`treeProps.themeOverrides` 能覆盖密度对应的原生节点高度。
48
+
49
+ 新增状态不受控时,保留 `defaultSelectedKeys/defaultExpandedKeys/defaultCheckedKeys` 的初始化语义;后续要响应外部变更请使用三个 `v-model`。官方的 `watchProps` 也被保留。外部替换数据时,包装层保留 key 状态,不裁剪暂时不在当前数据中的受控 key,适用于分批加载和恢复选择。
50
+
51
+ `defaultExpandAll`、工具栏和实例 `expandAll()` 只展开已经加载的父节点,避免一次操作递归拉取整棵后端树。非受控“全部展开”期间新出现的已加载父节点会加入展开;手动折叠后不再自动打开。受控时新增节点的展开 keys 由父组件维护。搜索展开和清空后恢复交给 Naive UI。
52
+
53
+ `searchPattern` 是真正受控值:空字符串表示清空。未提供时搜索框使用内部状态。若在 `treeProps.pattern` 中控制关键词,同样通过 `update:searchPattern` 接收输入。
54
+
55
+ ## 事件与方法
56
+
57
+ 三个 `update:selectedKeys`、`update:expandedKeys`、`update:checkedKeys` 都保留官方的 `(keys, options, meta)`。`meta` 保留操作节点和 select/unselect、expand/collapse/filter、check/uncheck 动作;实例命令没有具体操作节点时 `meta.node` 为 null。已有 `node-select`、`node-action`、`node-drop`、`add`、`refresh` 保留。
58
+
59
+ `treeProps` 内的官方回调仍会调用一次。不要把同一个业务副作用同时绑定到包装事件和原生回调。
60
+
61
+ 实例提供:
62
+
63
+ - `expandAll()`、`collapseAll()`、`selectNode(key)`、`clearSelection()`。
64
+ - `setCheckedKeys(keys)`、`clearChecked()`;输入 keys 交给官方级联/半选规则,不自行模拟“全选所有后端节点”。
65
+ - `getSelectedNode()`、`getCheckedData()`、`getIndeterminateData()`。
66
+ - 官方 `scrollTo()` 的所有重载,以及 `expandedKeys/selectedKeys/checkedKeys` 引用。
67
+
68
+ `getCheckedData()` 返回官方的完整已勾选数据;`checkStrategy` 影响更新回调 keys,二者不能假设恒等。受控模式下实例方法发出更新建议,最终状态仍由父组件接受的值决定。
69
+
70
+ ## 渲染与空态
71
+
72
+ ```vue
73
+ <C_Tree :data="nodes" :tree-props="{ nodeProps: bindContextMenu }">
74
+ <template #label="{ option, selected, checked }">
75
+ <span>{{ option.name }}</span>
76
+ </template>
77
+ <template #suffix="{ option }"><NodeActions :node="option" /></template>
78
+ <template #empty><EmptyState title="暂无匹配的部门" /></template>
79
+ <template #toolbar-actions><NButton @click="reload">刷新部门</NButton></template>
80
+ </C_Tree>
81
+ ```
82
+
83
+ `label/prefix/suffix` 插槽优先于 `treeProps.renderLabel/renderPrefix/renderSuffix`,最后使用包装层默认渲染。原生节点的 `prefix/suffix` 函数也会保留。上下文信息是官方的 `{ option, selected, checked }`。状态标签和预设按钮属于默认渲染,自定义插槽可完全接管。
84
+
85
+ ## 异步加载:保持官方协议和数据所有权
86
+
87
+ 在 `treeProps.onLoad` 中返回 Promise,未加载节点设为 `isLeaf: false`。成功时由使用侧更新响应式树数据;包装层不修改传入数组,也不把 Promise 返回值擅自塞到 children。官方负责同节点加载去重与加载图标。
88
+
89
+ ```vue
90
+ <C_Tree
91
+ :data="nodes"
92
+ :tree-props="{ onLoad: loadChildren }"
93
+ @load-error="showLoadFailure"
94
+ />
95
+ ```
96
+
97
+ 拒绝会触发 `load-error(error, node)`,并转为官方支持的 `false` 结果,结束加载状态且不产生无人处理的 Promise rejection。按官方交互折叠后再次展开即可重试。替换根数据或卸载后,旧加载失败不再向当前页面报错。
98
+
99
+ **后端请求的取消和过期写入由请求所有者处理**。包装层无法取消使用侧闭包中已经发出的请求,也无法拦截闭包直接修改数据的行为。切换公司、切换查询、换根节点或卸载时,应取消旧请求,并在提交数据前检查请求代次。例如:
100
+
101
+ ```ts
102
+ let generation = 0
103
+ let abort = new AbortController()
104
+
105
+ function invalidateLoads() {
106
+ generation++
107
+ abort.abort()
108
+ abort = new AbortController()
109
+ }
110
+
111
+ async function loadChildren(node: TreeNodeData) {
112
+ const current = generation
113
+ const signal = abort.signal
114
+ try {
115
+ const children = await fetchChildren(node.id, { signal })
116
+ if (signal.aborted || generation !== current) return false
117
+ // 在使用侧基于最新数据不可变更新;不要写回已替换的旧节点引用。
118
+ nodes.value = replaceNodeChildren(nodes.value, node.id, children)
119
+ } catch (error) {
120
+ if (signal.aborted || generation !== current) return false
121
+ throw error
122
+ }
123
+ }
124
+
125
+ onBeforeUnmount(invalidateLoads)
126
+ ```
127
+
128
+ 示例中的 `fetchChildren/replaceNodeChildren` 是应用自身的请求和树数据更新方法。空结果应写入 `children: []` 并将该节点置为 `isLeaf: true`。搜索已加载数据不能替代服务端全树搜索,未加载节点的权限全选也需要后端契约。
129
+
130
+ ## 大树与验证边界
131
+
132
+ ```vue
133
+ <C_Tree
134
+ style="height: 480px"
135
+ :data="nodes"
136
+ density="compact"
137
+ :tree-props="{ virtualScroll: true, animated: false }"
138
+ />
139
+ ```
140
+
141
+ 空数据或隐藏无关节点时的零搜索匹配会自动退回普通原生树,保证最低版本的虚拟列表也显示官方空态。匹配探针使用已有索引且不会生成另一棵树;自定义 filter 应保持纯函数。
142
+
143
+ 必须给容器确定的高度。组件不额外设置行 margin/min-height,虚拟列表测量与 `themeOverrides.nodeHeight` 使用同一高度。自定义插槽若换行或使用可变高度,需改为非虚拟模式,或保证内容不会超过配置高度。
144
+
145
+ 辅助遍历采用共享迭代索引,避免深层递归及宽树的展开参数溢出;没有深度 watch 和跨数据集的历史节点缓存。这不意味着浏览器渲染无限量节点:大树仍应开启虚拟滚动并按需加载。
146
+
147
+ 已验证自定义字段、冻结输入、受控/非受控状态、原生级联/禁用勾选、模式覆盖、插槽/原生事件、失败重试、同节点加载去重、替换/卸载后的过期失败、主题与密度高度。15 万个同层节点及 2 万层数据仅验证包装层辅助索引的迭代安全,**不是 NTree 的渲染承诺**。输入交给官方前仍需保证唯一 key、合法且无环的树结构。浏览器拖拽、超大数据真实帧率和具体业务权限树需在应用中验证。
148
+
149
+ ## 官方依据
150
+
151
+ 核对日期:2026-10-19。已对 Naive UI 2.35.0、2.44.1、2.45.3 分别运行同一组 14 项真实挂载契约;最低版与 2.44.1 的原生类型也单独核对。构建使用 Naive UI 2.45.3;原生选项是否可用取决于使用侧安装版本,不能把当前官网的新选项默认视为所有 `^2.35.0` 版本都支持。
152
+
153
+ - [Naive UI Tree API(官方源码文档)](https://github.com/tusen-ai/naive-ui/blob/main/src/tree/demos/zhCN/index.demo-entry.md)
154
+ - [Naive UI Tree 实现](https://github.com/tusen-ai/naive-ui/blob/main/src/tree/src/Tree.tsx)
155
+ - [官方异步加载示例](https://github.com/tusen-ai/naive-ui/blob/main/src/tree/demos/zhCN/async.vue)
156
+
157
+ `wl-ui-produce` 目前是 Element Plus 技术栈,其本地 `C_Tree` 提供 Tab、搜索、节点插槽和选中高亮。截至本次只读检索未发现 `src/views` 对该本地树的直接调用,不能据此宣称真实业务已完成迁移。标签切换仍由应用的 `NTab`/`C_Tabs` 组合,后端树权限、全量搜索与数据请求保留在页面逻辑中。
@@ -4,6 +4,8 @@
4
4
 
5
5
  Import strategies, component configuration and integration examples.
6
6
 
7
+ Focused guides: [form density](./form-density.en.md), [table density and edit modes](./table-density.md), [split panes](./split-pane.en.md), [tree capabilities](./tree.md), and [production project coverage review](../wl-ui-produce-coverage.md). Some focused guides are currently available in Chinese.
8
+
7
9
  ## On this page
8
10
 
9
11
  - [Import strategies](#import-strategies)
@@ -4,6 +4,8 @@
4
4
 
5
5
  按需导入、组件配置与业务场景的详细接入示例。
6
6
 
7
+ 专项指南:[表单与搜索密度](./form-density.md) · [表格密度与编辑模式](./table-density.md) · [分割面板与多表布局](./split-pane.md) · [树与原生能力透传](./tree.md) · [真实项目覆盖调研](../wl-ui-produce-coverage.md)。
8
+
7
9
  ## 本页导航
8
10
 
9
11
  - [导入方式](#导入方式)
@@ -0,0 +1,41 @@
1
+ # 大列表、渲染与异步任务专项复查
2
+
3
+ 日期:2026-10-19。本轮接续[表格与组件复查](./component-review-20261019.md),并合并远端 `fdffe29` 中已提交的地图、组织图、预览、上传、甘特及瀑布流修复。功能变更通过 Changeset 登记,源码合入不等于发布新的 npm 版本。
4
+
5
+ ## 修改及可验证收益
6
+
7
+ | 路径 | 实际改进 | 验证方式 |
8
+ | ------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
9
+ | Transfer | 每侧筛选结果 100 项起窗口化;保留完整选择和移动语义;普通接入零新增必填项 | 3000 项的真实列表仅挂载视口附近的行;三档行高 28/34/40px,筛选末项、禁用保护、移动和完整 DOM 逃生回归 |
10
+ | GlobalSearch | 菜单派生文本缓存;完整结果窗口化;跨视口键盘定位 | 1 万菜单连续 4 次搜索,label/key 各读取 1 万次;5000 匹配结果保留,键盘定位第 1201 项并返回正确 key |
11
+ | Chat | 消息 200 条、联系人 100 条起自动窗口化;变高行交给公开引擎实测 | 1000 消息、500 联系人实际 DOM 有界;文件/图片/重发事件,历史前插、流式、迟到图片、会话切换、门槛及尺寸变化回归 |
12
+ | WaterFall | 图片与标题/插槽高度测量合并为单帧布局;RO 条目与元素登记用 Map 查询 | 1000 项中 100 张图片与 100 次标题测量只发布一次布局;显式 relayout/配置变化仍立即计算;三种宽度长标题无重叠 |
13
+ | Subtitle | 编译保留源顺序优先级的区间索引,二分查询 | 重叠、乱序、相同边界及反向跳转对照线性参考;10 万字幕每次查询最多 19 次区间读取 |
14
+ | Code / QRCode | 当前任务拥有 loading/输出;复制及导出保留输入快照;卸载取消迟到结果及 Logo 图片事件 | 真正 NCode 同语言异步重高亮、快速切换、复制快照;二维码并发导出、取消、绘图异常和卸载回归 |
15
+
16
+ DOM 数量和算法访问次数说明对应瓶颈的变化,不代表整页 FPS 或所有数据规模的同倍数改善。虚拟列表仍保留全部内存数据,实际业务应按需分段加载。
17
+
18
+ ## 使用侧与兼容性
19
+
20
+ 自动窗口化复用 `vueuc` 的公开 `VVirtualList`,通过直接依赖声明,未使用 Naive 内部导入,也未将 Naive peer 从 2.35 提高到 2.36。`C_Transfer` 与 `C_Chat` 可用 `virtualScroll=false` 保留完整 DOM。聊天 ID 应唯一稳定,容器应有确定高度。
21
+
22
+ 穿梭框保留 `--tf-height`。聊天变高行不要求业务填写高度;输入法 Enter 确认候选不会发送。公开 `useWaterFallLayout` 四参数调用仍同步,实际组件才显式开启批处理。二维码组件销毁时未完成的导出以 `AbortError` 拒绝;并行导出互不取消。
23
+
24
+ 具体接入与边界见[大列表与异步任务](./guides/runtime-performance.md)及[穿梭框指南](./guides/transfer.md)。
25
+
26
+ ## 代码质量与验证边界
27
+
28
+ 索引、任务和滚动逻辑拆分到各自小模块,模板样式跟随提取的子组件收集;保留公开事件 payload,没有放宽质量或体积预算。合并瀑布流时保留远端的标题高度修复,并将逐条查找和逐元素扫描改为索引,ref 清空、行删除、卸载都会释放观察。
29
+
30
+ 验证采用本机 Bun 1.4.2、Vue 3.5.42、Naive 2.45.3;额外用真实 Naive 2.35.0 包 alias 验证本轮四个相关组件,不将 mock 当兼容证明。
31
+
32
+ - 合并后完整 `bun run verify`:306 项 Bun 单元、207 项组件挂载,以及 TypeScript/Vue/消费者类型、构建、55 个 ESM/CJS 组件入口、Node16/NodeNext 打包消费者契约均通过。
33
+ - Naive 2.35.0:36 项相关挂载测试和四组件类型检查通过。
34
+ - `bun install --frozen-lockfile --offline --ignore-scripts` 通过;包与轻量入口体积预算保持原值。消费者依赖复用本机已安装版本,未声称从公开 registry 全新安装尚未发布的版本。
35
+ - Chromium 合成场景核对 3000 项穿梭框、5000 项搜索、1000 条聊天及 500 联系人;另验证 199/200 条切换、面板变矮、普通历史前插迟到图片和 IME。明暗主题及窄屏截图检查,未发现运行异常。
36
+ - 使用构建后的命名导出及各组件独立 CSS 入口重复 27 项浏览器检查全部通过,确认抽取的消息、联系人和穿梭框行样式包含在按需产物中。
37
+ - 瀑布流浏览器核对 100 图、40 个含长标题条目,在 1000/700/420px 容器下无重叠;移除条目立即解除观察,卸载无残留观察目标或 RO 循环错误。
38
+
39
+ 全库 lint 无错误;未修改路径及合入的既有路径仍存在复杂度/解构建议警告,本轮修改的性能模块没有新增警告。以上不替代其他浏览器、真实业务后端或全部第三方引擎的长期压测。
40
+
41
+ 瀑布流此次解决测量和重排,不包含其窗口化协议;媒体运行时配置切换、大文档编辑和特定业务巨量数据仍应按实际 profile 做专项。不能据本轮结果宣称组件库已无优化空间。
@@ -0,0 +1,62 @@
1
+ # wl-ui-produce 场景覆盖调研
2
+
3
+ 调研日期:2026-10-18 至 2026-10-19。参考项目快照:`034832469bc8a45765988f67f9f2ce75e03cf005`。
4
+ 这是源代码和场景能力核对,没有在参考项目替换组件、改动业务流程、调用后端写接口或完成迁移验收。
5
+
6
+ ## 结论
7
+
8
+ 本库可组合出常规管理端查询、录入、表格、主从分屏和树工作台。**不能宣称完整覆盖任何场景,也不能把 Naive UI 组件直接等同于 Element Plus + 平台 BaseTable / AG Grid。**
9
+ 建议先在独立试验页面验证最常见的“查询 + 工具栏 + 主从表 + 录入弹窗”,保留应用领域逻辑。Element Plus 适配仍采用独立包,保持本库零 Element Plus / common-core 运行依赖。
10
+
11
+ ## 调研证据和范围
12
+
13
+ - 静态检索 `src/views/produce` 下 42 个 Vue 视图文件;这不是 42 个页面逐个运行验收。
14
+ - 阅读 `c_steelListPanel`、`c_steelMasterDetail`、`c_steelWorkstation`、`c_listModal` 与炼钢 `shared/{types,runtime,query,page-factory}`。
15
+ - 抽查钢水转移、配料、跟踪、退火、委外多表和 `reports/components/ReportView.vue` 的布局及接口边界。
16
+ - `jh-drag-row` 实际出现于 3 个 Vue 文件:主从包装、退火和委外;当前 `src` 未发现 `jh-drag-col` 标签调用。左右分屏来自项目规范和组件语义,不冒充已上线页面事实。
17
+ - 参考项目本地 `C_Tree` 是 Element Tree 封装,未发现视图实际使用它;树的覆盖判断依据其声明、Naive 官方协议和本库回归,不作为生产页面迁移证明。
18
+
19
+ ## 能力矩阵
20
+
21
+ “可组合”指本库已有 UI 能力;仍需页面传入真实数据、请求和业务规则。“需适配”不代表应把平台协议硬塞进通用组件。
22
+
23
+ | 参考场景 | 本库路径 | 判定与边界 |
24
+ | ---------------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------- |
25
+ | 文本、多选、日期区间查询、重置、折叠 | `C_FormSearch` + `useTableQuery` | 可组合;搜索和分页共用请求控制器,防止重复查询 |
26
+ | 公司/字典、日期时间、时间、炉号上下一笔、远程选项 | `C_Form` 行内/自定义字段,应用字段适配器 | 需适配;`C_FormSearch` 默认字段族仍是 input/select/date-range/spacer,不伪称原生覆盖所有查询控件 |
27
+ | 普通录入、网格、分组、Tab、步骤、动态表单 | `C_Form` + `C_FormModal` | 可组合;字段转换、DECIMAL精度、跨字段规则和接口载荷归业务契约 |
28
+ | 常规列表、远程分页、筛选、排序、选择、批量操作、编辑 | `C_Table` + `C_ActionBar` | 可组合;`density` 与编辑模式简写降低页面配置量,行唯一键必需 |
29
+ | 多表主从、上下/左右嵌套分屏 | `C_SplitPane` + `C_Table flex-height` | 可组合;补受控百分比和像素最小尺寸。页面提供完整高度链、各表独立分页/选择/请求 |
30
+ | 长工作台、多个固定高度结果区 | 页面布局 + 表格/折叠/Tab | 可组合;页面负责滚动所有权,不应把整页滚动压到任一分割面板中 |
31
+ | 选择物料、跨页选择、回填、去重、选中顺序 | 弹窗 + 查询/表格/选择API | 需应用组合;映射、顺序和业务校验仍由物料选择器控制 |
32
+ | 树选择、复选、权限树、拖拽、虚拟滚动、懒加载 | `C_Tree` + `treeProps` | 有对应UI能力;权限计算、拖拽落库、异步取消和授权仍在应用层 |
33
+ | 字典状态、业务按钮语义、可见性、忙碌锁 | 列 render/formatter + `C_ActionBar` | 需映射;平台 `danger`、ActionType 与本库 `error` 等契约不能直接复用 |
34
+ | 本地当前页/选中记录导出 | `C_Table config.export` | 可组合;远程数据源不等于全量数据 |
35
+ | 后端全量导出、模板打印、月结报表 | 应用下载服务/报表组件 | 需专用适配;本地导出和 DOM 打印不等于 MachReport 模板引擎、服务端报表和审计 |
36
+ | AG Grid 高级表格能力 | 保留现有 BaseTable/AG Grid,逐项验收 | 没有证明等价;透视、复杂分组聚合、Excel范围复制/粘贴、服务端行模型等不可推断由 NDataTable 自动覆盖 |
37
+ | 单点登录、租户公司、模块联邦、页面权限、字典网关 | 现有宿主/生态适配层 | 超出通用UI组件责任;保持现有平台边界 |
38
+ | 保存幂等、提交结果不确定、冻结/审批/跨表事务 | 领域服务 + 后端 | 不由UI组件实现;保留真实接口、重试标识和权限约束 |
39
+
40
+ ## 分割手柄是否是一回事
41
+
42
+ 两者都通过拖动分隔线调整相邻面板,可以嵌套。差别在于旧调用习惯:平台用 `top-height` / `left-width` 像素初值,本库 `size` / `defaultSize` 表达去除手柄后的第一面板百分比;百分比不能机械当成像素。
43
+
44
+ 本轮补齐 `v-model:size`、`minFirstSize` / `minSecondSize` 像素下限、响应式边界、ResizeObserver、取消/失焦/卸载清理、键盘操作和折叠状态插槽。折叠时允许合法零尺寸;窗口小于两侧最小尺寸之和时按比例降级,避免负尺寸或溢出。持久化由页面按用户与页面隔离。
45
+
46
+ `c_steelListPanel` 自己监听尺寸并调用表格布局方法,说明表格响应尺寸不应耦合进 Split。Naive `flex-height` 表格仍需父层提供明确可计算的高度,并在 flex 中间层设置 `min-height: 0`;Tab、模态框和隐藏面板要分别验证初始化与重新显示。
47
+
48
+ 详见[分割面板用法](./guides/split-pane.md),Robot_Admin 的分割演示提供嵌套多表验证入口。
49
+
50
+ ## 推荐收敛方式
51
+
52
+ 1. 组件库维护通用交互与声明协议;查询/表单/表格共用密度,不复制三套尺寸常量。
53
+ 2. 应用层提供小型字段与列适配函数,把公司、字典、数字精度和UI状态转换到目标组件;不把炼钢字段写进库。
54
+ 3. 每张表拥有独立行键、查询控制器、选择与持久化key。主表变更时,页面负责清空从表、取消旧请求和重置从表分页。
55
+ 4. 先验证数据密集、多表、Tab隐藏重显、窄窗口、暗色和错误重试,再评估迁移成本。需要AG Grid高级能力的页面保留原表格引擎。
56
+ 5. Element Plus 适配包单独建设与测试,共享纯协议与算法,避免一个运行包同时拉入两套组件库。
57
+
58
+ ## 参考项目工具回执
59
+
60
+ runId:`4aff6f97-9128-4573-b98f-e135f308a9e9`。
61
+
62
+ Kit 2.29.0 的 `convention-audit` 对主从组件目录检查4个关联文件,0 error,1条操作列建议,验证状态 `partial`;未执行全量类型检查。UI 1.18.0 的 `ops/audit` 使用 `legacy-jh-ag` 扫描该Vue文件,0 error / 0 warning,1条标签宽度提示,状态 `passed`。两包无范围或规则缺口,宿主发现状态仍为 `unverified`。这些回执不代表 `wl-ui-produce` 全项目无缺陷。
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "publishConfig": {
4
4
  "access": "public"
5
5
  },
6
- "version": "0.16.0",
6
+ "version": "0.17.1",
7
7
  "description": "基于 Naive UI 的 Vue 3 组件库",
8
8
  "packageManager": "bun@1.3.14",
9
9
  "engines": {
@@ -132,7 +132,6 @@
132
132
  }
133
133
  },
134
134
  "dependencies": {
135
- "@robot-admin/form-validate": "3.4.2",
136
135
  "@antv/x6": "^2.19.2",
137
136
  "@chenfengyuan/vue-barcode": "^2.0.2",
138
137
  "@fullcalendar/core": "^6.1.21",
@@ -141,8 +140,10 @@
141
140
  "@fullcalendar/list": "^6.1.21",
142
141
  "@fullcalendar/vue3": "^6.1.21",
143
142
  "@iconify/vue": "^5.0.1",
143
+ "@robot-admin/form-validate": "3.4.2",
144
144
  "@types/leaflet": "^1.9.22",
145
145
  "@visactor/vtable": "^1.26.7",
146
+ "@visactor/vtable-editors": "^1.26.7",
146
147
  "@visactor/vtable-gantt": "^1.26.7",
147
148
  "@vue-flow/core": "^1.48.2",
148
149
  "@wangeditor-next/editor": "6.2.0",
@@ -161,6 +162,7 @@
161
162
  "vue-cropper": "^1.1.4",
162
163
  "vue-draggable-plus": "^0.6.1",
163
164
  "vue3-puzzle-vcode": "^1.1.7",
165
+ "vueuc": "^0.4.66",
164
166
  "xgplayer": "3.0.26",
165
167
  "xgplayer-hls": "3.0.26",
166
168
  "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
@@ -1,185 +0,0 @@
1
- import * as vue from "vue";
2
- import { Ref } from "vue";
3
-
4
- //#region src/components/C_Tree/types.d.ts
5
- type TreeMode = "menu" | "file" | "org" | "custom";
6
- type StatusType = "success" | "warning" | "error" | "info";
7
- type ButtonType = "primary" | "info" | "warning" | "error" | "default";
8
- interface TreeOption {
9
- [key: string]: any;
10
- id?: string | number;
11
- key?: string | number;
12
- label?: string;
13
- children?: TreeOption[];
14
- }
15
- interface DropInfo {
16
- node: TreeOption;
17
- dragNode: TreeOption;
18
- dropPosition: "before" | "inside" | "after";
19
- event: DragEvent;
20
- }
21
- interface TreeNodeData {
22
- [key: string]: any;
23
- id: string | number;
24
- name: string;
25
- type?: string;
26
- children?: TreeNodeData[];
27
- }
28
- interface StatusConfig {
29
- field: string;
30
- values: Record<string | number, {
31
- text: string;
32
- type: StatusType;
33
- }>;
34
- }
35
- interface ActionConfig {
36
- key: string;
37
- text: string;
38
- icon: string;
39
- type?: ButtonType;
40
- show?: (node: TreeNodeData) => boolean;
41
- confirm?: string;
42
- }
43
- interface IconConfig {
44
- default?: string;
45
- typeMap?: Record<string, string>;
46
- colorMap?: Record<string, string>;
47
- }
48
- interface TreeProps {
49
- data: TreeNodeData[];
50
- mode?: TreeMode;
51
- keyField?: string;
52
- labelField?: string;
53
- childrenField?: string;
54
- searchPattern?: string;
55
- searchable?: boolean;
56
- searchPlaceholder?: string;
57
- draggable?: boolean;
58
- showLine?: boolean;
59
- showToolbar?: boolean;
60
- addable?: boolean;
61
- addText?: string;
62
- refreshable?: boolean;
63
- iconField?: string;
64
- iconConfig?: IconConfig;
65
- statusConfigs?: StatusConfig[];
66
- actions?: ActionConfig[];
67
- defaultExpandAll?: boolean;
68
- defaultExpandedKeys?: (string | number)[];
69
- defaultSelectedKeys?: (string | number)[];
70
- }
71
- interface TreeExpose {
72
- expandAll: () => void;
73
- collapseAll: () => void;
74
- selectNode: (key: string | number) => void;
75
- getSelectedNode: () => TreeNodeData | null;
76
- expandedKeys: Ref<(string | number)[]>;
77
- selectedKeys: Ref<(string | number)[]>;
78
- }
79
- interface TreeEmits {
80
- "node-select": [node: TreeNodeData | null, selectedKeys: (string | number)[]];
81
- "node-action": [action: string, node: TreeNodeData];
82
- "node-drop": [info: DropInfo];
83
- add: [parentNode?: TreeNodeData];
84
- refresh: [];
85
- }
86
- //#endregion
87
- //#region src/components/C_Tree/index.vue.d.ts
88
- declare var __VLS_13: {};
89
- type __VLS_Slots = {} & {
90
- 'toolbar-actions'?: (props: typeof __VLS_13) => any;
91
- };
92
- declare const __VLS_base: vue.DefineComponent<TreeProps, TreeExpose, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
93
- refresh: () => any;
94
- add: (parentNode?: TreeNodeData | undefined) => any;
95
- "node-select": (node: TreeNodeData | null, selectedKeys: (string | number)[]) => any;
96
- "node-action": (action: string, node: TreeNodeData) => any;
97
- "node-drop": (info: DropInfo) => any;
98
- }, string, vue.PublicProps, Readonly<TreeProps> & Readonly<{
99
- onRefresh?: (() => any) | undefined;
100
- onAdd?: ((parentNode?: TreeNodeData | undefined) => any) | undefined;
101
- "onNode-select"?: ((node: TreeNodeData | null, selectedKeys: (string | number)[]) => any) | undefined;
102
- "onNode-action"?: ((action: string, node: TreeNodeData) => any) | undefined;
103
- "onNode-drop"?: ((info: DropInfo) => any) | undefined;
104
- }>, {
105
- showToolbar: boolean;
106
- mode: TreeMode;
107
- draggable: boolean;
108
- actions: ActionConfig[];
109
- defaultExpandedKeys: (string | number)[];
110
- labelField: string;
111
- keyField: string;
112
- childrenField: string;
113
- searchPattern: string;
114
- searchable: boolean;
115
- searchPlaceholder: string;
116
- showLine: boolean;
117
- addable: boolean;
118
- addText: string;
119
- refreshable: boolean;
120
- iconField: string;
121
- iconConfig: IconConfig;
122
- statusConfigs: StatusConfig[];
123
- defaultExpandAll: boolean;
124
- defaultSelectedKeys: (string | number)[];
125
- }, {}, {}, {}, string, vue.ComponentProvideOptions, false, {}, any>;
126
- declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
127
- declare const _default: typeof __VLS_export;
128
- type __VLS_WithSlots<T, S> = T & {
129
- new (): {
130
- $slots: S;
131
- };
132
- };
133
- //#endregion
134
- //#region src/components/C_Tree/data.d.ts
135
- declare const presetConfigs: Record<TreeMode, Partial<TreeProps>>;
136
- //#endregion
137
- //#region src/components/C_Tree/composables/useTreeOperations.d.ts
138
- type EmitFn = {
139
- (event: 'node-select', node: TreeNodeData | null, selectedKeys: (string | number)[]): void;
140
- (event: 'node-action', action: string, node: TreeNodeData): void;
141
- (event: 'node-drop', info: DropInfo): void;
142
- (event: 'add', parentNode?: TreeNodeData): void;
143
- (event: 'refresh'): void;
144
- };
145
- /**
146
- *
147
- */
148
- declare function useTreeOperations(props: TreeProps, emit: EmitFn): {
149
- internalSearchPattern: vue.Ref<string, string>;
150
- expandedKeys: vue.Ref<(string | number)[], (string | number)[]>;
151
- selectedKeys: vue.Ref<(string | number)[], (string | number)[]>;
152
- isAllExpanded: vue.ComputedRef<boolean>;
153
- treeData: vue.ComputedRef<TreeOption[]>;
154
- currentSearchPattern: vue.ComputedRef<string>;
155
- renderPrefix: ({
156
- option
157
- }: {
158
- option: TreeOption;
159
- }) => vue.VNode<vue.RendererNode, vue.RendererElement, {
160
- [key: string]: any;
161
- }>;
162
- renderLabel: ({
163
- option
164
- }: {
165
- option: TreeOption;
166
- }) => vue.VNode<vue.RendererNode, vue.RendererElement, {
167
- [key: string]: any;
168
- }>;
169
- renderSuffix: ({
170
- option
171
- }: {
172
- option: TreeOption;
173
- }) => vue.VNode<vue.RendererNode, vue.RendererElement, {
174
- [key: string]: any;
175
- }>;
176
- toggleExpandAll: () => void;
177
- handleExpandedKeysChange: (keys: (string | number)[]) => void;
178
- handleSelectedKeysChange: (keys: (string | number)[]) => void;
179
- handleDrop: (info: DropInfo) => void;
180
- handleAdd: () => void;
181
- handleRefresh: () => void;
182
- expose: TreeExpose;
183
- };
184
- //#endregion
185
- export { ButtonType as a, StatusConfig as c, TreeExpose as d, TreeMode as f, TreeProps as h, ActionConfig as i, StatusType as l, TreeOption as m, presetConfigs as n, DropInfo as o, TreeNodeData as p, _default as r, IconConfig as s, useTreeOperations as t, TreeEmits as u };