@veltra/desktop 1.0.8 → 1.0.10

package/src/components/tree/use-check.ts

@@ -16,12 +16,36 @@ interface UseCheckReturned {
   toggleCheck: (node: TreeNode, check: boolean, ctrlKey?: boolean) => void
 }
 
+/**
+ * 展开目标节点的所有祖先。返回是否发生了实际展开。
+ */
+function expandAncestors(node: TreeNode): boolean {
+  let changed = false
+  node.bubbleSet((n) => {
+    if (n.parent) {
+      if (n.parent.expanded) return false
+      n.parent.expanded = true
+      changed = true
+    }
+  })
+  return changed
+}
+
 export function useCheck(options: Options): UseCheckReturned {
   const { emit, props, nodeDict, getFlattedNodes } = options
 
   const checkedData = new Set<Record<string, any>>()
 
-  function checkNode(node: TreeNode) {
+  /**
+   * 上一次回显使用的 value 集合（仅限 props.checked）。
+   * 用于在相同 `nodeDict` 下走差集回显，避免每次全量清空再重建。
+   */
+  let lastCheckedSet = new Set<unknown>()
+  /** 最近一次参与差集比较的 nodeDict 引用；引用变化时视为整棵树重建。 */
+  let lastDict: Map<any, TreeNode> | null = null
+
+  function checkNode(node: TreeNode): void {
+    if (node.checked) return
     node.checked = true
     if (node.parent) {
       node.parent.childrenCheckCount++
@@ -29,7 +53,8 @@ export function useCheck(options: Options): UseCheckReturned {
     checkedData.add(node.data)
   }
 
-  function uncheckNode(node: TreeNode) {
+  function uncheckNode(node: TreeNode): void {
+    if (!node.checked) return
     node.checked = false
     if (node.parent) {
       node.parent.childrenCheckCount--
@@ -45,27 +70,56 @@ export function useCheck(options: Options): UseCheckReturned {
   // 回显
   watch(
     [() => props.checked, nodeDict],
-    ([c, nodeDict]) => {
+    ([c, dict]) => {
       // 事件已经触发模型变更了，所以不再进行下面的计算
       if (checkedByEvent || !props.checkable) return
-
-      if (!nodeDict.size) return
-      checkedData.clear()
-
-      c?.forEach((v) => {
-        const node = nodeDict.get(v)
-        if (node) {
-          checkNode(node)
-          node.bubbleSet((node) => {
-            if (node.parent) {
-              if (node.parent.expanded) return false
-              node.parent.expanded = true
+      if (!dict.size) return
+
+      const nextSet = new Set<unknown>(c ?? [])
+
+      // 森林重建（dict 引用变化）→ 走全量清空重建路径，
+      // 因为所有 TreeNode 实例都是新的，上一轮缓存的 lastCheckedSet 失效。
+      const dictChanged = dict !== lastDict
+      if (dictChanged) {
+        checkedData.clear()
+        lastCheckedSet = new Set()
+      }
+
+      let mutated = false
+
+      // 取消：上一轮有但本轮没有的 value
+      for (const v of lastCheckedSet) {
+        if (!nextSet.has(v)) {
+          const node = dict.get(v)
+          if (node) {
+            uncheckNode(node)
+            mutated = true
+          }
+        }
+      }
+
+      // 新增：本轮有但上一轮没有的 value
+      let ancestorsExpanded = false
+      for (const v of nextSet) {
+        if (!lastCheckedSet.has(v) || dictChanged) {
+          const node = dict.get(v)
+          if (node) {
+            checkNode(node)
+            mutated = true
+            if (expandAncestors(node)) {
+              ancestorsExpanded = true
             }
-          })
+          }
         }
-      })
+      }
 
-      getFlattedNodes()
+      lastCheckedSet = nextSet
+      lastDict = dict
+
+      // 只在真实发生变化时才触发扁平化，避免空转。
+      if (mutated || ancestorsExpanded) {
+        getFlattedNodes()
+      }
     },
     { immediate: true }
   )
@@ -134,11 +188,13 @@ export function useCheck(options: Options): UseCheckReturned {
 
     const checkedArr = Array.from(checkedData)
 
-    emit(
-      'update:checked',
-      checkedArr.map((item) => o(item).get(props.valueKey!)),
-      checkedArr
-    )
+    const valueKey = props.valueKey!
+    const nextValues = checkedArr.map((item) => o(item).get(valueKey) as unknown)
+
+    // 与外部 checked 保持差集缓存同步，避免下一次 watch 回调把刚勾选的值又误判为“新增”。
+    lastCheckedSet = new Set(nextValues)
+
+    emit('update:checked', nextValues as any[], checkedArr)
 
     nextTick(() => {
       checkedByEvent = false

package/src/components/tree/use-tree-nodes.ts

@@ -1,5 +1,5 @@
 import { Forest } from '@cat-kit/core'
-import { computed, shallowRef, type ShallowRef, type ComputedRef } from 'vue'
+import { computed, shallowRef, triggerRef, watch, type ShallowRef, type ComputedRef } from 'vue'
 
 import type { TreeProps } from '../../types'
 import { TreeNode } from './tree-node'
@@ -13,12 +13,29 @@ interface UseTreeNodesReturned {
   forest: ComputedRef<Forest<Record<string, unknown>, any>>
   getFlattedNodes: () => void
   nodeDict: ComputedRef<Map<string | number, TreeNode>>
+  /** 强制刷新 `nodes` 的订阅者（供字段级别变化但列表引用不变时手动触发）。 */
+  triggerNodes: () => void
 }
+
 export function useTreeNodes(options: Options): UseTreeNodesReturned {
   const { props } = options
 
-  /** 森林 */
-  const forest = computed(() => {
+  // forest / nodeDict 保持为 shallowRef 而非 computed：
+  // - computed 会因为任一 prop 变化（尤其是内联 disabledNode 函数）而整棵重建，
+  //   丢失 expanded/checked/visible 等运行时状态；
+  // - 显式 watch 仅在真正影响结构的输入变化时才重建，行为可控、可测量。
+  const forestRef = shallowRef<Forest<Record<string, unknown>, any>>(
+    new Forest<Record<string, unknown>, any>({
+      data: [],
+      childrenKey: props.childrenKey ?? 'children'
+    })
+  )
+
+  const nodeDictRef = shallowRef<Map<string | number, TreeNode>>(new Map())
+
+  const nodes = shallowRef<TreeNode[]>([])
+
+  function buildForest(): Forest<Record<string, unknown>, any> {
     const { disabledNode, expandAll = false, valueKey, labelKey } = props
     const childrenKey = props.childrenKey ?? 'children'
 
@@ -26,9 +43,8 @@ export function useTreeNodes(options: Options): UseTreeNodesReturned {
       data: Record<string, any>,
       index: number,
       depth: number,
-      _f: Forest<Record<string, unknown>, any>,
       parent?: TreeNode
-    ) {
+    ): TreeNode {
       const node = new TreeNode({
         data,
         index,
@@ -42,47 +58,82 @@ export function useTreeNodes(options: Options): UseTreeNodesReturned {
     }
 
     return new Forest<Record<string, unknown>, any>({
-      data: props.data! as Record<string, unknown>[],
+      data: (props.data ?? []) as Record<string, unknown>[],
       childrenKey,
       createNode: disabledNode
-        ? (data, index, depth, f, parent) => {
-            const node = createNode(
-              data as Record<string, any>,
-              index,
-              depth,
-              f,
-              parent as TreeNode
-            )
+        ? (data, index, depth, _f, parent) => {
+            const node = createNode(data as Record<string, any>, index, depth, parent as TreeNode)
             if (data) {
-              node.disabled = disabledNode(data, node) ?? false
+              node.disabled = disabledNode(data as Record<string, any>, node) ?? false
             }
             return node
           }
-        : (data, index, depth, f, parent) =>
-            createNode(data as Record<string, any>, index, depth, f, parent as TreeNode)
+        : (data, index, depth, _f, parent) =>
+            createNode(data as Record<string, any>, index, depth, parent as TreeNode)
     })
-  })
-
-  /** 碾平后的节点 */
-  const nodes = shallowRef<TreeNode[]>([])
+  }
 
-  /**
-   * 节点的字典，key为指定的valueKey的值
-   */
-  const nodeDict = computed(() => {
-    const dict = new Map<string | number, TreeNode>()
+  function rebuildForest(): void {
+    const nextForest = buildForest()
+    const nextDict = new Map<string | number, TreeNode>()
 
-    forest.value.dfs((node) => {
-      dict.set(node.key, node)
+    // 构建森林的同时一次 DFS 同步填充字典，
+    // 避免旧版 “forest computed → nodeDict computed” 两次完整遍历。
+    nextForest.dfs((node) => {
+      nextDict.set(node.key, node)
     })
 
-    return dict
-  })
+    forestRef.value = nextForest
+    nodeDictRef.value = nextDict
+
+    getFlattedNodes()
+  }
+
+  /** 按展开与可见性扁平化：仅一次 DFS。 */
+  function getFlattedNodes(): void {
+    const result: TreeNode[] = []
+    const roots = forestRef.value.roots as TreeNode[]
+
+    const stack: TreeNode[] = []
+    for (let i = roots.length - 1; i >= 0; i--) {
+      stack.push(roots[i]!)
+    }
+
+    while (stack.length) {
+      const node = stack.pop()!
+      if (!node.visible) continue
+      result.push(node)
+      if (node.expanded && node.children && node.children.length) {
+        for (let i = node.children.length - 1; i >= 0; i--) {
+          stack.push(node.children[i]!)
+        }
+      }
+    }
+
+    nodes.value = result
+  }
 
-  /** 获取碾平后的节点 */
-  function getFlattedNodes() {
-    nodes.value = forest.value.flattenVisible((n) => n.expanded).filter((n) => n.visible)
+  function triggerNodes(): void {
+    triggerRef(nodes)
   }
 
-  return { nodes, forest, getFlattedNodes, nodeDict }
+  watch(
+    [
+      () => props.data,
+      () => props.disabledNode,
+      () => props.childrenKey,
+      () => props.valueKey,
+      () => props.labelKey,
+      () => props.expandAll
+    ],
+    () => {
+      rebuildForest()
+    },
+    { immediate: true }
+  )
+
+  const forest = computed(() => forestRef.value)
+  const nodeDict = computed(() => nodeDictRef.value)
+
+  return { nodes, forest, getFlattedNodes, nodeDict, triggerNodes }
 }

package/src/types/file-viewer.ts

@@ -0,0 +1,69 @@
+import type { DeconstructValue } from '@veltra/utils'
+import type { ShallowRef } from 'vue'
+
+/** 预览器类别：xlsx 与 csv 归一为 sheet */
+export type FileViewerKind = 'image' | 'video' | 'pdf' | 'sheet' | 'docx' | 'text'
+
+/** 单个预览文件定义 */
+export interface FileViewerItem {
+  /** 唯一 id；未提供时组件内部按索引生成 */
+  id?: string
+  /** 展示名（通常为原始文件名） */
+  name: string
+  /**
+   * 文件源：
+   * - string: URL（支持 http(s):、blob:、data:）
+   * - File / Blob / ArrayBuffer / Uint8Array: 二进制原始数据
+   */
+  src: string | File | Blob | ArrayBuffer | Uint8Array
+  /** 类型；缺省时根据 name 后缀推断 */
+  kind?: FileViewerKind
+  /** MIME type，仅用于原生 <video> / <img> / 下载时的类型提示 */
+  mime?: string
+  /** 文件大小（字节），可选，仅用于侧栏展示 */
+  size?: number
+}
+
+/** 文件预览组件属性 */
+export interface FileViewerProps {
+  /** 待预览的文件列表 */
+  files: FileViewerItem[]
+  /** 当前激活文件 id（配合 v-model） */
+  modelValue?: string
+  /** 侧栏宽度（CSS length 或 false 隐藏侧栏），默认 280px */
+  sidebarWidth?: string | number | false
+  /** sheet 场景单文件最大渲染行数，默认 50000；0 表示不截断 */
+  sheetMaxRows?: number
+  /** 是否显示下载按钮，默认 true */
+  downloadable?: boolean
+  /**
+   * 全屏模态模式开关（支持 v-model:open）。
+   *
+   * - `undefined`（缺省）：内嵌模式，组件在原位置渲染
+   * - `true` / `false`：进入模态模式，Teleport 到 body，按本值控制显隐
+   */
+  open?: boolean
+  /** 模态模式下点击背景是否关闭，默认 true */
+  closeOnClickBackdrop?: boolean
+  /** 模态模式下按 ESC 是否关闭，默认 true */
+  closeOnEsc?: boolean
+}
+
+/** 文件预览组件事件 */
+export interface FileViewerEmits {
+  (e: 'update:modelValue', id: string): void
+  (e: 'update:open', value: boolean): void
+  (e: 'change', file: FileViewerItem): void
+  (e: 'error', err: { file: FileViewerItem; error: unknown }): void
+}
+
+/** 文件预览组件暴露的属性和方法(组件内部使用) */
+export interface _FileViewerExposed {
+  activeId: ShallowRef<string | undefined>
+  activate: (id: string) => void
+  next: () => void
+  prev: () => void
+}
+
+/** 文件预览组件暴露的属性和方法(组件外部使用, 引用的值会被自动解构) */
+export type FileViewerExposed = DeconstructValue<_FileViewerExposed>

package/src/types/index.ts

@@ -77,3 +77,4 @@ export * from './auto-complete'
 export * from './switch'
 export * from './steps'
 export * from './rich-text-editor'
+export * from './file-viewer'

package/src/types/tabs.ts

@@ -1,4 +1,4 @@
-import type { ComponentProps } from '@veltra/utils'
+import type { ComponentProps, ComponentSize } from '@veltra/utils'
 
 export type TabItem = {
   /**
@@ -12,44 +12,138 @@ export type TabItem = {
   key: string
   /** 是否禁用 */
   disabled?: boolean
+  /**
+   * 单个标签是否可关闭
+   * @description 未显式设置时，沿用组件级 `closable` 属性
+   */
+  closable?: boolean
+}
+
+/** 水平标签栏（top/bottom）属性 */
+export interface TabsHorizontalProps {
+  /** 组件尺寸 */
+  size?: ComponentSize
+  /** 当前激活的标签 key */
+  modelValue?: string
+  /** 标签项 */
+  items: TabItem[]
+  /**
+   * 是否可关闭
+   * @description 作为所有 TabItem 未显式 `closable` 时的默认值；禁用项不显示关闭按钮
+   * @default false
+   */
+  closable?: boolean
+  /**
+   * 是否填充父容器宽度
+   * @description 开启时 header 容器占满父容器宽度，背景完整铺开；tab-item 自身宽度保持不变
+   * @default false
+   */
+  block?: boolean
+  /**
+   * 是否开启圆角胶囊风格
+   * @default false
+   */
+  rounded?: boolean
+  /**
+   * 位置
+   * @default 'top'
+   */
+  position?: 'top' | 'bottom'
+}
+
+/** 垂直标签栏（left/right）属性 */
+export interface TabsVerticalProps {
+  /** 组件尺寸 */
+  size?: ComponentSize
+  /** 当前激活的标签 key */
+  modelValue?: string
+  /** 标签项 */
+  items: TabItem[]
+  /**
+   * 是否可关闭
+   * @description 作为所有 TabItem 未显式 `closable` 时的默认值；禁用项不显示关闭按钮
+   * @default false
+   */
+  closable?: boolean
+  /**
+   * 是否开启圆角胶囊风格
+   * @default false
+   */
+  rounded?: boolean
+  /**
+   * 位置
+   * @default 'left'
+   */
+  position?: 'left' | 'right'
+}
+
+/** 水平标签栏事件 */
+export interface TabsHorizontalEmits {
+  (e: 'update:modelValue', value: string): void
+  (e: 'click', item: TabItem, index: number): void
+  (e: 'close', item: TabItem, index: number): void
+}
+
+/** 垂直标签栏事件 */
+export interface TabsVerticalEmits {
+  (e: 'update:modelValue', value: string): void
+  (e: 'click', item: TabItem, index: number): void
+  (e: 'close', item: TabItem, index: number): void
 }
 
 /** 标签页组件组件属性 */
 export interface TabsProps extends ComponentProps {
+  /** 当前激活的标签 key */
   modelValue?: string
   /** 标签项 */
   items: TabItem[]
+  /**
+   * 是否可关闭
+   * @description 作为所有 TabItem 未显式 `closable` 时的默认值；禁用项不显示关闭按钮
+   * @default false
+   */
+  closable?: boolean
+  /**
+   * 是否填充父容器宽度（仅在 position=top/bottom 时生效）
+   * @description 开启时 header 容器占满父容器宽度，背景完整铺开；tab-item 自身宽度保持不变
+   * @default false
+   */
+  block?: boolean
+  /**
+   * 是否开启圆角胶囊风格
+   * @default false
+   */
+  rounded?: boolean
   /** 显示位置 */
   position?: 'left' | 'right' | 'top' | 'bottom'
-  /** 是否可以动态编辑 */
-  editable?: boolean
   /**
    * 是否保活
    * @default false
    */
   keepAlive?: boolean
-  /** 是否允许拖拽排序 */
-  // sortable?: boolean
-  // beforeLeave?: (
-  //   prev: string | number,
-  //   next: string | number
-  // ) => void | boolean | Promise<void | boolean>
 }
 
 /** 标签页组件组件定义的事件 */
 export interface TabsEmits {
-  (e: 'update:modelValue', value: string | number): void
-  (e: 'update:items', items: TabItem[]): void
-  (e: 'update:active', active: string | number): void
-  (e: 'delete', item: TabItem, index: number): void
-  (e: 'create'): void
+  (e: 'update:modelValue', value: string): void
   (e: 'click', item: TabItem, index: number): void
+  (e: 'close', item: TabItem, index: number): void
 }
 
-/** 标签页组件组件暴露的属性和方法(组件内部使用) */
+/** 标签页组件暴露的属性和方法(组件内部使用) */
 export interface _TabsExposed {}
 
-/** 标签页组件组件暴露的属性和方法(组件外部使用, 引用的值会被自动解构) */
-export interface TabsExposed {
-  delete(key: number | string): void
-}
+/** 标签页组件暴露的属性和方法(组件外部使用, 引用的值会被自动解构) */
+export interface TabsExposed {}
+
+/** 水平标签栏暴露的属性和方法(组件内部使用) */
+export interface _TabsHorizontalExposed {}
+
+/** 水平标签栏暴露的属性和方法(组件外部使用) */
+export interface TabsHorizontalExposed {}
+
+/** 垂直标签栏暴露的属性和方法(组件内部使用) */
+export interface _TabsVerticalExposed {}
+
+/** 垂直标签栏暴露的属性和方法(组件外部使用) */
+export interface TabsVerticalExposed {}

package/src/types/tree.ts

@@ -76,7 +76,12 @@ export interface TreeEmit {
 
 export interface TreeNodeProps {
   node: TreeNode
-  measureElement?: (el: any) => void
+  /**
+   * 虚拟项索引：对应 `nodes` 数组中的绝对位置。
+   * 需要传入以便在节点卸载时正确通知 `Virtualizer` 解绑，避免 size=0 的脏测量。
+   */
+  index?: number
+  measureElement?: (index: number, el: Element | null) => void
 }
 
 /** 树组件暴露的属性和方法(组件内部使用) */