@ticatec/uniface-element 0.3.23 → 5.0.0

package/dist/data_display/tree_view/README_CN.md

@@ -0,0 +1,238 @@
+# 树形视图组件 (TreeView)
+
+分层树形组件，用于展示嵌套或平铺层次结构数据（基于 `HierarchyTree`），支持图标替换（如文件夹打开/关闭、文件类型徽章）、按需懒加载、选中项绑定和右键菜单。
+
+## 特性
+
+- **图标替换与定制**：支持 `nodeIcon` Snippet 与 `iconField` 函数，轻松实现文件夹打开（📂）/关闭（📁）状态切换及文件类型图标展示。
+- **层次数据结构**：基于 `HierarchyTree`（来自 `@ticatec/hierarchy-data`）管理层级，从扁平数据（`getKey`/`getParentKey`）自动构建树。
+- **动态展开与深层控制**：支持 `defaultExpandDepth` 初始展开深度与单击箭头切换展开。
+- **选择状态双向绑定**：支持 `bind:activeNode` 响应式绑定选中节点。
+- **异步懒加载**：支持 `lazyLoader` 按需加载子节点，加载过程中自动显示 loading 图标。
+- **右键菜单集成**：支持 `onContextMenu` 在节点上唤起 `ContextMenu` 右键菜单。
+- **可访问性**：容器带 `role="tree"`，支持 `onfocus`/`onblur` 焦点事件。
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```typescript
+import TreeView from "@ticatec/uniface-element/TreeView";
+import {HierarchyTree} from "@ticatec/uniface-element/TreeNodes";
+```
+
+## 属性 (Props)
+
+| 名称 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `tree` | `HierarchyTree<any>` | 必填 | 层次树模型实例，负责维护父子关系与节点索引 |
+| `textField` | `string \| GetText<any>` | 必填 | 节点数据中提取显示文本的字段名或函数 |
+| `iconField` | `string \| GetIcon<any>` | - | 节点图标字段名，或根据节点与展开状态返回图标（图片路径/CSS 类名）的函数 |
+| `nodeIcon` | `Snippet<[NodeIconContext]>` | - | Svelte 5 Snippet，用于完全自定义节点图标（如文件夹打开/关闭）。优先级高于 `iconField` |
+| `chevronIcon` | `Snippet<[ChevronIconContext]>` | - | Svelte 5 Snippet，用于自定义分支展开/折叠箭头；不传则使用默认的 ▾ / ▸ 字符 |
+| `style` | `string` | `''` | 容器内联样式 |
+| `class` | `string` | `''` | 容器附加 CSS 类名 |
+| `lazyLoader` | `TreeLazyLoader \| null` | `null` | 异步懒加载子节点的接口 |
+| `activeNode` | `any` | `null` | 当前选中的节点（支持 `bind:activeNode` 双向绑定） |
+| `defaultExpandDepth` | `number` | `0` | 初始展开深度（0 = 全折叠，1 = 展开根节点，依此类推） |
+| `isVisible` | `NodeVisibleFun` | - | 控制节点可见性的过滤函数 |
+| `onchange` | `OnNodeSelectionChange` | - | 节点选择变化时的回调函数（返回 `false` 可取消本次选择） |
+| `onfocus` | `(event: FocusEvent) => void` | - | 树容器获得焦点时的回调 |
+| `onblur` | `(event: FocusEvent) => void` | - | 树容器失去焦点时的回调 |
+| `onContextMenu` | `OnContextMenu` | - | 右键菜单事件的回调函数 |
+| `title` | `string` | - | 显示在树顶部的标题，点击标题会触发一次"取消选中"（`activeNode` 置为 `null`） |
+
+## 类型定义
+
+### GetText
+
+```typescript
+type GetText<T> = (item: T) => string;
+```
+
+### GetIcon
+
+```typescript
+type GetIcon<T> = (node: IHierarchyData<T>, expanded: boolean) => string | undefined;
+```
+
+### NodeIconContext / ChevronIconContext
+
+```typescript
+interface NodeIconContext {
+  node: IHierarchyData<any>;
+  expanded: boolean;
+  isBranch: boolean;
+}
+
+interface ChevronIconContext {
+  expanded: boolean;
+  loading: boolean;
+}
+```
+
+### TreeLazyLoader
+
+```typescript
+interface TreeLazyLoader {
+  /** 判断该节点是否是可展开的枝节点 */
+  isBranch: (node: IHierarchyData<any>) => boolean;
+  /** 加载子节点数据（返回纯数据对象数组，由组件内部调用 tree.appendChild 挂载） */
+  load: (node: IHierarchyData<any>) => Promise<Array<any>>;
+}
+```
+
+### OnNodeSelectionChange
+
+```typescript
+type OnNodeSelectionChange = (node: IHierarchyData<any>) => Promise<boolean>;
+```
+
+返回 `false` 可以阻止本次选中；返回 `true` 或 `undefined`/`null` 都会正常选中。
+
+### NodeVisibleFun
+
+```typescript
+type NodeVisibleFun = (node: IHierarchyData<any>) => boolean;
+```
+
+### OnContextMenu
+
+```typescript
+type OnContextMenu = (event: MouseEvent, data: any) => void;
+```
+
+回调收到的是节点的原始数据（`node.data`），不是 `IHierarchyData` 节点本身。
+
+---
+
+## 示例：基础用法
+
+```svelte
+<script lang="ts">
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import {HierarchyTree} from "@ticatec/uniface-element/TreeNodes";
+
+  const flatData = [
+    { id: '1', parentId: null, name: 'Root 1' },
+    { id: '1-1', parentId: '1', name: 'Child 1-1' },
+  ];
+
+  const tree = new HierarchyTree<any>({
+    getKey: (item) => item.id,
+    getParentKey: (item) => item.parentId
+  });
+  tree.setData(flatData);
+
+  let activeNode = $state<any>(null);
+</script>
+
+<TreeView
+  {tree}
+  textField="name"
+  defaultExpandDepth={1}
+  bind:activeNode
+/>
+```
+
+## 示例：实现文件目录树（文件夹打开/关闭 + TypeScript 图标）
+
+通过 `nodeIcon` Snippet，可以根据 `{ node, expanded }` 动态替换图标：
+
+```svelte
+<script lang="ts">
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import {HierarchyTree} from "@ticatec/uniface-element/TreeNodes";
+
+  const fileTreeData = [
+    { id: 'src', parentId: null, name: 'src', isDir: true },
+    { id: 'src/business', parentId: 'src', name: 'business', isDir: true },
+    { id: 'src/business/AccessLog.ts', parentId: 'src/business', name: 'AccessLog.ts', isDir: false, fileType: 'ts' },
+    { id: 'src/business/AccessLogDAO.ts', parentId: 'src/business', name: 'AccessLogDAO.ts', isDir: false, fileType: 'ts' },
+  ];
+
+  const fileTree = new HierarchyTree<any>({
+    getKey: (item) => item.id,
+    getParentKey: (item) => item.parentId
+  });
+  fileTree.setData(fileTreeData);
+
+  let activeFile = $state<any>(null);
+</script>
+
+{#snippet customFileIcon({ node, expanded })}
+  {#if node.data.isDir}
+    <!-- 文件夹图标 (展开: 打开文件夹 📂, 折叠: 关闭文件夹 📁) -->
+    {#if expanded}
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="#EAB308">
+        <path d="M19 20H5a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v1L19 20z" opacity="0.4"/>
+        <path d="M4 10h17l-2.5 9h-15L4 10z"/>
+      </svg>
+    {:else}
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="#CA8A04">
+        <path d="M10 4H4c-1.1 0-2 .9-2 2v12c0 1.1.9 2 2 2h16c1.1 0 2-.9 2-2V8c0-1.1-.9-2-2-2h-8l-2-2z"/>
+      </svg>
+    {/if}
+  {:else if node.data.fileType === 'ts'}
+    <!-- TS 文件徽章 -->
+    <span style="background: #3178C6; color: #fff; font-size: 9px; font-weight: 800; padding: 1px 3px; border-radius: 3px;">
+      TS
+    </span>
+  {/if}
+{/snippet}
+
+<TreeView
+  tree={fileTree}
+  textField="name"
+  defaultExpandDepth={3}
+  nodeIcon={customFileIcon}
+  bind:activeNode={activeFile}
+/>
+```
+
+## 示例：异步懒加载
+
+```svelte
+<script lang="ts">
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import {HierarchyTree} from "@ticatec/uniface-element/TreeNodes";
+  import type {IHierarchyData} from "@ticatec/uniface-element/TreeNodes";
+  import type {TreeLazyLoader} from "@ticatec/uniface-element/types";
+
+  const lazyTree = new HierarchyTree<any>({
+    getKey: (item) => item.id,
+    getParentKey: (item) => item.parentId
+  });
+  lazyTree.setData([
+    { id: 'root-1', name: '项目 A（点击展开懒加载）', hasChildren: true }
+  ]);
+
+  const lazyLoader: TreeLazyLoader = {
+    isBranch: (node: IHierarchyData<any>) => Boolean(node.data.hasChildren),
+    load: async (node: IHierarchyData<any>) => {
+      await new Promise((resolve) => setTimeout(resolve, 600));
+      return [
+        { id: `${node.data.id}-sub1`, parentId: node.data.id, name: `${node.data.name} - 模块 1` },
+        { id: `${node.data.id}-sub2`, parentId: node.data.id, name: `${node.data.name} - 模块 2` }
+      ];
+    }
+  };
+</script>
+
+<TreeView tree={lazyTree} textField="name" {lazyLoader} />
+```
+
+---
+
+## 样式定制
+
+树形视图支持以下 CSS 自定义属性：
+
+- `--uniface-treeview-chevron-color`：展开/折叠箭头的默认颜色
+- `--uniface-treeview-chevron-hover-color`：悬停时箭头的颜色
+- `--uniface-treeview-item-bg`：悬停与选中状态的行背景颜色
+- `--uniface-treeview-item-selected-color`：选中节点文字的颜色

package/dist/data_display/tree_view/TreeNodeView.svelte

@@ -0,0 +1,207 @@
+<script lang="ts">
+    import iconLoading from "../../assets/loading.gif";
+    import type { OnContextMenu } from "../../overlay/context-menu/ContextMenuItem";
+    import type { IHierarchyData } from "../../lib";
+    import type { OnNodeSelectionChange } from "../../types";
+    import type { Snippet } from 'svelte';
+    import type { GetIcon, NodeIconContext, ChevronIconContext } from './TreeView.svelte';
+
+    type GetText<T> = (item: T) => string;
+
+    interface Props {
+        node: IHierarchyData<any>;
+        textField: string | GetText<any>;
+        iconField?: string | GetIcon<any>;
+        nodeIcon?: Snippet<[NodeIconContext]>;
+        chevronIcon?: Snippet<[ChevronIconContext]>;
+        activeNode: any;
+        isBranch: boolean;
+        expanded: boolean;
+        loading?: boolean;
+        onToggle: () => void;
+        onNodeSelectionChange: OnNodeSelectionChange;
+        onContextMenu?: OnContextMenu;
+    }
+
+    let {
+        node,
+        textField,
+        iconField,
+        nodeIcon,
+        chevronIcon,
+        activeNode,
+        isBranch,
+        expanded,
+        loading = false,
+        onToggle,
+        onNodeSelectionChange,
+        onContextMenu
+    }: Props = $props();
+
+    let nodeText = $derived(
+        typeof textField == 'string'
+            ? node.data?.[textField] ?? ''
+            : textField(node.data)
+    );
+
+    let nodeIconValue = $derived.by(() => {
+        if (!iconField) return undefined;
+        if (typeof iconField === 'string') {
+            return node.data?.[iconField];
+        }
+        return iconField(node, expanded);
+    });
+
+    let isSelected = $derived(
+        activeNode === node ||
+        activeNode === node.data ||
+        (activeNode != null && typeof activeNode === 'object' && ('data' in activeNode ? activeNode.data === node.data : false))
+    );
+
+    const handleIconClick = async (e: MouseEvent) => {
+        e.stopPropagation();
+        e.preventDefault();
+        await onToggle();
+    }
+
+    const handleRowClick = async () => {
+        await onNodeSelectionChange(node);
+    }
+
+    const handleContextMenu = (event: MouseEvent) => {
+        onContextMenu?.(event, node);
+    }
+</script>
+
+<div class="tree-node" class:expanded style="padding-left: {node.level * 16}px">
+    <div class="node-item" class:selected={isSelected} onclick={handleRowClick} aria-hidden="true"
+         oncontextmenu={handleContextMenu}>
+
+        <div class="item-chevron">
+            {#if isBranch}
+                {#if loading}
+                    <img alt="loading" class="chevron-img" src={iconLoading}/>
+                {:else if chevronIcon}
+                    <span aria-hidden="true" onclick={handleIconClick} class="chevron-btn">
+                        {@render chevronIcon({ expanded, loading })}
+                    </span>
+                {:else}
+                    <span aria-hidden="true" onclick={handleIconClick} class="chevron-btn default-arrow">
+                        {expanded ? '▾' : '▸'}
+                    </span>
+                {/if}
+            {:else}
+                <span class="chevron-spacer"></span>
+            {/if}
+        </div>
+
+        {#if nodeIcon}
+            <div class="node-type-icon">
+                {@render nodeIcon({ node, expanded, isBranch })}
+            </div>
+        {:else if nodeIconValue}
+            <div class="node-type-icon">
+                {#if typeof nodeIconValue === 'string' && (nodeIconValue.startsWith('data:') || nodeIconValue.startsWith('http') || nodeIconValue.startsWith('/') || nodeIconValue.endsWith('.png') || nodeIconValue.endsWith('.svg') || nodeIconValue.endsWith('.gif'))}
+                    <img src={nodeIconValue} alt="" class="type-icon-img" />
+                {:else}
+                    <i class={nodeIconValue}></i>
+                {/if}
+            </div>
+        {/if}
+
+        <span class="item-text">{nodeText}</span>
+    </div>
+</div>
+
+<style>
+    .tree-node {
+        position: relative;
+        width: 100%;
+        padding: 2px 8px 2px 0;
+        box-sizing: border-box;
+
+        .node-item {
+            position: relative;
+            white-space: nowrap;
+            display: flex;
+            height: 30px;
+            box-sizing: border-box;
+            align-items: center;
+            border-radius: 6px;
+            z-index: 5;
+            padding: 0 4px;
+            cursor: pointer;
+
+            .item-chevron {
+                box-sizing: border-box;
+                width: 18px;
+                height: 18px;
+                flex: 0 0 auto;
+                display: flex;
+                align-items: center;
+                justify-content: center;
+
+                .chevron-btn {
+                    cursor: pointer;
+                    font-size: 14px;
+                    line-height: 1;
+                    color: var(--uniface-treeview-chevron-color, #6b7280);
+                    user-select: none;
+                    transition: color 0.15s ease;
+
+                    &:hover {
+                        color: var(--uniface-treeview-chevron-hover-color, #111827);
+                    }
+                }
+
+                .chevron-spacer {
+                    width: 18px;
+                }
+
+                .chevron-img {
+                    width: 14px;
+                    height: 14px;
+                }
+            }
+
+            .node-type-icon {
+                flex: 0 0 auto;
+                display: flex;
+                align-items: center;
+                justify-content: center;
+                margin-left: 2px;
+                margin-right: 6px;
+
+                .type-icon-img {
+                    width: 16px;
+                    height: 16px;
+                    object-fit: contain;
+                }
+            }
+
+            .item-text {
+                display: inline-block;
+                flex: 1 1 auto;
+                box-sizing: border-box;
+                cursor: pointer;
+                overflow: hidden;
+                text-overflow: ellipsis;
+                font-size: 13px;
+                line-height: 1.4;
+            }
+
+            &:hover {
+                background-color: var(--uniface-treeview-item-bg, #EEF4FF);
+            }
+
+            &.selected {
+                background-color: var(--uniface-treeview-item-bg, #EEF4FF);
+            }
+
+            &.selected .item-text {
+                color: var(--uniface-treeview-item-selected-color, #0061FF);
+                font-weight: 600;
+            }
+        }
+    }
+</style>

package/dist/data_display/tree_view/TreeNodeView.svelte.d.ts

@@ -0,0 +1,23 @@
+import type { OnContextMenu } from "../../overlay/context-menu/ContextMenuItem";
+import type { IHierarchyData } from "../../lib";
+import type { OnNodeSelectionChange } from "../../types";
+import type { Snippet } from 'svelte';
+import type { GetIcon, NodeIconContext, ChevronIconContext } from './TreeView.svelte';
+type GetText<T> = (item: T) => string;
+interface Props {
+    node: IHierarchyData<any>;
+    textField: string | GetText<any>;
+    iconField?: string | GetIcon<any>;
+    nodeIcon?: Snippet<[NodeIconContext]>;
+    chevronIcon?: Snippet<[ChevronIconContext]>;
+    activeNode: any;
+    isBranch: boolean;
+    expanded: boolean;
+    loading?: boolean;
+    onToggle: () => void;
+    onNodeSelectionChange: OnNodeSelectionChange;
+    onContextMenu?: OnContextMenu;
+}
+declare const TreeNodeView: import("svelte").Component<Props, {}, "">;
+type TreeNodeView = ReturnType<typeof TreeNodeView>;
+export default TreeNodeView;

package/dist/data_display/tree_view/TreeView.svelte

@@ -0,0 +1,217 @@
+<script lang="ts">
+
+    import { untrack, type Snippet } from 'svelte';
+    import {SvelteSet} from "svelte/reactivity";
+    import type {TreeLazyLoader, NodeVisibleFun, OnNodeSelectionChange} from "../../types";
+    import TreeNodeView from "./TreeNodeView.svelte";
+    import type {OnContextMenu} from "../../overlay/context-menu/ContextMenuItem";
+    import type {HierarchyTree, IHierarchyData} from "../../lib";
+
+    type GetText<T> = (item: T) => string;
+
+    export type GetIcon<T> = (node: IHierarchyData<T>, expanded: boolean) => string | undefined;
+
+    export interface NodeIconContext {
+        node: IHierarchyData<any>;
+        expanded: boolean;
+        isBranch: boolean;
+    }
+
+    export interface ChevronIconContext {
+        expanded: boolean;
+        loading: boolean;
+    }
+
+    interface Props {
+        tree: HierarchyTree<any>;
+        textField: string | GetText<any>;
+        iconField?: string | GetIcon<any>;
+        nodeIcon?: Snippet<[NodeIconContext]>;
+        chevronIcon?: Snippet<[ChevronIconContext]>;
+        style?: string;
+        lazyLoader?: TreeLazyLoader | null;
+        activeNode?: any;
+        class?: string;
+        isVisible?: NodeVisibleFun;
+        onchange?: OnNodeSelectionChange;
+        onfocus?: (event: FocusEvent) => void;
+        onblur?: (event: FocusEvent) => void;
+        onContextMenu?: OnContextMenu;
+        title?: string;
+        /** 初始展开多少层（0 = 全部折叠，1 = 展开根节点，依此类推）。默认 0。 */
+        defaultExpandDepth?: number;
+    }
+
+    let {
+        tree,
+        textField,
+        iconField,
+        nodeIcon,
+        chevronIcon,
+        style = '',
+        lazyLoader = null,
+        activeNode = $bindable<any>(null),
+        class: className = '',
+        isVisible,
+        onchange,
+        onfocus,
+        onblur,
+        onContextMenu,
+        title = undefined,
+        defaultExpandDepth = 0
+    }: Props = $props();
+
+    // 展开 / 已加载 / 加载中的 key 集合。SvelteSet 让 .add/.delete 触发响应式更新。
+    let expanded = new SvelteSet<string | number>();
+    let loaded = new SvelteSet<string | number>();
+    let loading = new SvelteSet<string | number>();
+
+    // tree 变化时重置状态（旧 key 对新树无意义）
+    $effect(() => {
+        const currentTree = tree;
+        const depth = defaultExpandDepth;
+        untrack(() => {
+            expanded.clear();
+            loaded.clear();
+            loading.clear();
+            if (depth > 0 && currentTree) {
+                currentTree.walk((node) => {
+                    if (!node.isLeaf && node.level < depth) {
+                        expanded.add(currentTree.getKey(node.data));
+                    }
+                });
+            }
+        });
+    });
+
+    let visibleNodes = $derived(tree.getVisibleList(expanded));
+
+    const isBranch = (node: IHierarchyData<any>): boolean => {
+        return lazyLoader == null ? !node.isLeaf : lazyLoader.isBranch(node);
+    };
+
+    const onNodeSelectionChange = async (node: IHierarchyData<any>): Promise<boolean> => {
+        let accept: boolean | undefined = (await onchange?.(node));
+        accept = accept == null ? true : accept;
+        if (accept == null || accept == true) {
+            activeNode = node;
+        }
+        return accept;
+    }
+
+    const handleToggle = async (node: IHierarchyData<any>) => {
+        const key = tree.getKey(node.data);
+        if (!isBranch(node)) return;
+
+        // 首次展开 + lazy：先 fetch 子节点
+        if (lazyLoader != null && !loaded.has(key) && node.isLeaf) {
+            loading.add(key);
+            try {
+                const children = await lazyLoader.load(node);
+                for (const childData of children) {
+                    tree.appendChild(node, childData);
+                }
+                loaded.add(key);
+                if (children.length === 0) {
+                    // 空子节点 —— 不展开（用户点击不会有视觉变化）
+                    return;
+                }
+            } catch (err) {
+                console.error('Failed to load lazy node:', err);
+                return;
+            } finally {
+                loading.delete(key);
+            }
+        }
+
+        if (expanded.has(key)) {
+            expanded.delete(key);
+        } else {
+            expanded.add(key);
+        }
+    }
+
+    const handleTitleClick = async () => {
+        let accept: boolean | undefined = (await onchange?.(null as any));
+        accept = accept == null ? true : accept;
+        if (accept == null || accept == true) {
+            activeNode = null;
+        }
+    }
+
+</script>
+
+<div class="uniface-tree-view {className}" {style} {onfocus} {onblur} role="tree" tabindex="0">
+    {#if title}
+        <div class="tree-view-title" role="button" tabindex="0" onclick={handleTitleClick}
+             onkeydown={(e) => { if (e.key === 'Enter' || e.key === ' ') handleTitleClick(); }}>
+            <span class="title-text">{title}</span>
+        </div>
+    {/if}
+    <div class="tree-view-content">
+        {#each visibleNodes as node (tree.getKey(node.data))}
+            {#if isVisible == null || isVisible(node)}
+                <TreeNodeView
+                    {node}
+                    {textField}
+                    {iconField}
+                    {nodeIcon}
+                    {chevronIcon}
+                    {activeNode}
+                    isBranch={isBranch(node)}
+                    {onContextMenu}
+                    {onNodeSelectionChange}
+                    expanded={expanded.has(tree.getKey(node.data))}
+                    loading={loading.has(tree.getKey(node.data))}
+                    onToggle={() => handleToggle(node)}
+                />
+            {/if}
+        {/each}
+    </div>
+</div>
+
+<style>
+    .uniface-tree-view {
+        position: relative;
+        display: flex;
+        flex-direction: column;
+        background-color: var(--uniface-color-surface, #ffffff);
+        color: var(--uniface-default-text-color, #374151);
+        box-sizing: border-box;
+        overflow: hidden;
+        height: 100%;
+
+        .tree-view-title {
+            flex: 0 0 auto;
+            padding: 12px 16px;
+            background-color: var(--uniface-color-surface, #ffffff);
+            border-bottom: 1px solid var(--uniface-color-border-secondary, #e5e7eb);
+            cursor: pointer;
+            user-select: none;
+            z-index: 10;
+            overflow: hidden;
+
+            .title-text {
+                font-size: 16px;
+                font-weight: 600;
+                color: var(--uniface-default-text-color, #374151);
+                white-space: nowrap;
+                overflow: hidden;
+                text-overflow: ellipsis;
+                display: block;
+                max-width: 100%;
+            }
+
+            &:hover {
+                background-color: var(--uniface-treeview-item-bg, #EEF4FF);
+            }
+        }
+
+        .tree-view-content {
+            flex: 1;
+            overflow: auto;
+            padding-right: 8px;
+            user-select: none;
+        }
+    }
+</style>