@chenzy-design/svelte 0.3.0 → 0.4.1

package/dist/tree/meta.js

@@ -5,42 +5,58 @@
 export const meta = {
     name: 'Tree',
     category: 'show',
-    description: '树形控件：层级展示节点，支持展开/收起、单选/多选、可勾选父子联动（含半选 mixed）、内置搜索高亮。受控 value/checkedKeys/expandedKeys 均不回写，仅通过 onChange/onCheck/onExpandedChange 通知。键盘导航遵循 WAI-ARIA APG Tree View（单一 tab stop + aria-activedescendant）。',
+    description: '树形控件（严格对齐 Semi）：层级展示节点，支持展开/收起、单选/多选（multiple 驱动 checkbox 父子联动含半选 mixed）、内置搜索高亮。值通道统一走 value/onChange。受控 value/expandedKeys 均不回写，仅通过 onChange/onExpand/onSelect/onSearch 通知。键盘导航遵循 WAI-ARIA APG Tree View（单一 tab stop + aria-activedescendant）。',
     exports: ['Tree'],
     props: [
-        { name: 'treeData', type: 'TreeNodeData[]', default: '[]', desc: '树数据源；字段名可经 fieldNames 自定义' },
+        { name: 'treeData', type: 'TreeNodeData[]', default: '[]', desc: '树数据源；字段名可经 keyMaps 自定义' },
         {
-            name: 'fieldNames',
+            name: 'treeDataSimpleJson',
+            type: 'Record<string, unknown>',
+            default: 'undefined',
+            desc: '简单 JSON 形式的树数据（对齐 Semi）：扁平 { key: value } 键值对，key 同时作 key/label，value 作节点 value，嵌套对象转子树。treeData 非空时优先，忽略此项',
+        },
+        {
+            name: 'keyMaps',
             type: '{ key?: string; label?: string; children?: string }',
             default: "{ key:'key', label:'label', children:'children' }",
-            desc: '自定义节点字段名映射，适配任意后端数据（如 { key:\'id\', label:\'name\', children:\'sub\' }）。派生只读映射，回调回传原始节点',
+            desc: '自定义节点字段名映射（对齐 Semi keyMaps），适配任意后端数据（如 { key:\'id\', label:\'name\', children:\'sub\' }）。派生只读映射，回调回传原始节点',
         },
         {
             name: 'value',
-            type: 'TreeKey | TreeKey[] | null',
+            type: 'TreeKey | TreeNodeData | Array<TreeKey | TreeNodeData> | null',
             default: 'undefined',
-            desc: '受控选中；multiple 时为数组。受控时不回写',
+            desc: '受控选中值（对齐 Semi value）；单选为标量、multiple 时为选中 key 数组（含父子联动结果）。onChangeWithObject 时为节点对象形态。受控时不回写',
         },
         {
             name: 'defaultValue',
-            type: 'TreeKey | TreeKey[] | null',
+            type: 'TreeKey | TreeNodeData | Array<TreeKey | TreeNodeData> | null',
             default: 'null',
-            desc: '非受控初始选中',
+            desc: '非受控初始选中值；形态同 value',
         },
-        { name: 'multiple', type: 'boolean', default: 'false', desc: '多选模式' },
-        { name: 'checkable', type: 'boolean', default: 'false', desc: '显示勾选框' },
         {
-            name: 'checkedKeys',
-            type: 'TreeKey[]',
-            default: 'undefined',
-            desc: '受控勾选；内部用 conduct 归一。受控时不回写',
+            name: 'onChangeWithObject',
+            type: 'boolean',
+            default: 'false',
+            desc: '以对象形态收发选中项：开启后 onChange 的 value 及受控 value/defaultValue 均为节点对象（含 label/value/其它字段），对象标识优先取 key 缺省回退 value',
         },
-        { name: 'defaultCheckedKeys', type: 'TreeKey[]', default: '[]', desc: '非受控初始勾选' },
+        { name: 'multiple', type: 'boolean', default: 'false', desc: '多选模式（对齐 Semi multiple）：开启渲染 checkbox + 父子联动，值经 value/onChange 收发' },
         {
-            name: 'checkStrictly',
+            name: 'disableStrictly',
             type: 'boolean',
             default: 'false',
-            desc: 'true 时父子解耦，仅切换单节点',
+            desc: '严格禁用：disabled 节点勾选态被锁定，不能通过父/子级联动改变（区别于普通 disabled 仅禁直接点击）。仅 multiple 联动下有意义',
+        },
+        {
+            name: 'leafOnly',
+            type: 'boolean',
+            default: 'false',
+            desc: '多选时 onChange 回传的 value 只含叶子节点 key（滤掉父/半选节点）',
+        },
+        {
+            name: 'checkRelation',
+            type: "'related' | 'unRelated'",
+            default: "'related'",
+            desc: "多选父子勾选联动关系（对齐 Semi）。'related'（默认）联动含半选；'unRelated' 父子独立无半选",
         },
         {
             name: 'expandedKeys',
@@ -51,27 +67,83 @@ export const meta = {
         { name: 'defaultExpandedKeys', type: 'TreeKey[]', default: '[]', desc: '非受控初始展开' },
         { name: 'defaultExpandAll', type: 'boolean', default: 'false', desc: '初始展开全部' },
         {
-            name: 'accordion',
+            name: 'autoExpandParent',
+            type: 'boolean',
+            default: 'false',
+            desc: '自动展开父节点（对齐 Semi 默认 false）：初次挂载时把初始展开节点的祖先链并入；开启后收起父节点需先收起其展开的子节点',
+        },
+        {
+            name: 'expandAction',
+            type: "false | 'click' | 'doubleClick'",
+            default: 'false',
+            desc: "展开触发方式：false 仅点箭头；'click' 点整行展开；'doubleClick' 双击整行展开（箭头任意模式可点）",
+        },
+        {
+            name: 'autoMergeValue',
+            type: 'boolean',
+            default: 'true',
+            desc: '多选 value 自动合并父子：父节点完全选中时 onChange 回传只保留父不含子孙。仅 multiple 联动且 leafOnly=false 时有意义',
+        },
+        {
+            name: 'labelEllipsis',
+            type: 'boolean',
+            default: 'false（virtualize 时 true）',
+            desc: 'label 超长单行省略；未显式传时跟随虚拟化',
+        },
+        {
+            name: 'preventScroll',
             type: 'boolean',
             default: 'false',
-            desc: '手风琴模式：同层级最多展开一个，展开节点时自动收起同父级其它节点（不同层级互不影响）。受控 expandedKeys 同样生效，仅经 onExpandedChange 回传新集不回写',
+            desc: '组件内 focus() 时是否阻止浏览器滚动文档（作用于导出的命令式 focus 方法）',
+        },
+        { name: 'showLine', type: 'boolean', default: 'false', desc: '显示层级连接线（├/└/竖线，对齐 Semi showLine）' },
+        {
+            name: 'virtualize',
+            type: '{ itemSize: number; height?: number | string; width?: number | string }',
+            default: 'undefined',
+            desc: '列表虚拟化（对齐 Semi virtualize）：传对象即开启，itemSize（行高 px）必传；仅渲染视口内可见行，适合大数据树；开启强制关闭动画',
         },
-        { name: 'selectable', type: 'boolean', default: 'true', desc: '节点是否可选中' },
-        { name: 'showIcon', type: 'boolean', default: 'true', desc: '是否预留节点图标位' },
-        { name: 'showLine', type: 'boolean', default: 'false', desc: '显示层级连接线（├/└/竖线）' },
         {
-            name: 'virtualized',
+            name: 'filterTreeNode',
+            type: 'boolean | ((input: string, node: TreeNodeData) => boolean)',
+            default: 'false',
+            desc: '是否根据输入项筛选（对齐 Semi）：true 用内置谓词（按 treeNodeFilterProp 字段包含匹配），传函数自定义命中逻辑；命中节点祖先链自动展开',
+        },
+        {
+            name: 'treeNodeFilterProp',
+            type: 'string',
+            default: "'label'",
+            desc: '内置搜索匹配节点的哪个字段（仅内置谓词生效，传自定义谓词时由函数决定）',
+        },
+        { name: 'searchStyle', type: 'string', default: 'undefined', desc: '搜索框内联样式（透传到 input style）' },
+        { name: 'searchClassName', type: 'string', default: 'undefined', desc: '搜索框附加 class（追加到 input）' },
+        {
+            name: 'showClear',
+            type: 'boolean',
+            default: 'true',
+            desc: '搜索框有内容时显示清除按钮，点击清空（对齐 Semi showClear）',
+        },
+        {
+            name: 'showFilteredOnly',
             type: 'boolean',
             default: 'false',
-            desc: '虚拟滚动：仅渲染视口内可见节点行，适合大数据树（1000+ 节点）',
+            desc: '搜索状态下只渲染命中节点及其祖先链，隐藏其它未命中节点（默认 false 展示全树、命中高亮、祖先自动展开）',
         },
-        { name: 'height', type: 'number', default: '320', desc: '虚拟滚动视口高度（px），virtualized 时生效' },
-        { name: 'itemHeight', type: 'number', default: '32', desc: '虚拟滚动行高（px），virtualized 时生效' },
-        { name: 'filterable', type: 'boolean', default: 'false', desc: '渲染内置搜索框' },
-        { name: 'blockNode', type: 'boolean', default: 'false', desc: '整行点击选中' },
+        { name: 'blockNode', type: 'boolean', default: 'true', desc: '整行点击选中（对齐 Semi 默认 true；directory 时强制整行）' },
+        { name: 'directory', type: 'boolean', default: 'false', desc: '目录树模式：整行块 + 内置目录/文件图标 + 默认点击整行展开' },
+        { name: 'motion', type: 'boolean', default: 'true', desc: '展开/收起动画开关；virtualized 时强制关闭' },
+        { name: 'expandAll', type: 'boolean', default: 'false', desc: '展开全部：数据变化时仍生效（区别于仅初始化的 defaultExpandAll）；仅非受控展开有意义' },
+        { name: 'loadedKeys', type: 'TreeKey[]', default: 'undefined', desc: '受控已加载节点 key，配合 loadData；已加载节点展开时不再触发 loadData' },
+        { name: 'style', type: 'string', default: 'undefined', desc: '根容器内联样式（对齐 Semi style）；设 height 时列表区限高滚动' },
+        { name: 'class', type: 'string', default: 'undefined', desc: '根元素自定义类名（对齐 Semi className）' },
+        { name: 'searchPlaceholder', type: 'string', default: 'undefined', desc: '搜索框占位文案（不传用内置 i18n）' },
+        { name: 'searchRender', type: 'false | Snippet<[SearchRenderContext]>', default: 'undefined', desc: '自定义搜索框渲染；传 false 隐藏内置搜索框（仍可经 search() 方法驱动）' },
+        { name: 'onSelect', type: '(key, selected, node) => void', default: 'undefined', desc: '节点选中回调（早于 onChange）' },
+        { name: 'onDragOver', type: '(info) => void', default: 'undefined', desc: '拖拽悬停在候选目标上' },
+        { name: 'onDragLeave', type: '(info) => void', default: 'undefined', desc: '拖拽离开候选目标' },
+        { name: 'onDragEnd', type: '(info) => void', default: 'undefined', desc: '拖拽结束（无论是否成功放下）' },
+        { name: 'renderFullLabel', type: 'Snippet<[FullLabelContext]>', default: 'undefined', desc: '完全接管整行渲染（叶子分组勾选、单选高亮子节点等高级场景）' },
         { name: 'disabled', type: 'boolean', default: 'false', desc: '整树禁用' },
-        { name: 'size', type: "'small'|'default'|'large'", default: "'default'" },
-        { name: 'status', type: "'default'|'warning'|'error'", default: "'default'" },
         { name: 'emptyContent', type: 'string', default: 'undefined', desc: '空态文案' },
         { name: 'ariaLabel', type: 'string', default: 'undefined', desc: '无障碍标签' },
         {
@@ -80,72 +152,180 @@ export const meta = {
             default: 'undefined',
             desc: '异步加载子节点：展开未加载的非叶子节点时调用',
         },
+        {
+            name: 'onLoad',
+            type: "(loadedKeys: string[], info: { event: 'load'; node: TreeNodeData }) => void",
+            default: 'undefined',
+            desc: '异步加载完成回调',
+        },
         {
             name: 'draggable',
             type: 'boolean',
             default: 'false',
             desc: '启用 HTML5 拖拽排序：节点可拖动改变层级/顺序（before/inside/after）',
         },
+        {
+            name: 'autoExpandWhenDragEnter',
+            type: 'boolean',
+            default: 'true',
+            desc: '拖拽到节点内部（inside）时是否延时自动展开该节点。仅 draggable 时有意义',
+        },
+        {
+            name: 'hideDraggingNode',
+            type: 'boolean',
+            default: 'false',
+            desc: '是否隐藏拖拽跟随的 dragImg（设透明 drag image）。仅 draggable 时有意义',
+        },
+        {
+            name: 'renderDraggingNode',
+            type: '(nodeInstance: HTMLElement, node: TreeNodeData) => HTMLElement',
+            default: 'undefined',
+            desc: '自定义拖拽 dragImg 元素，优先级高于 hideDraggingNode。仅 draggable 时有意义',
+        },
+        {
+            name: 'onDoubleClick',
+            type: '(e: MouseEvent, node: TreeNodeData) => void',
+            default: 'undefined',
+            desc: '节点双击回调',
+        },
         {
             name: 'onDrop',
             type: '(info: { dragNode, dropNode, dropPosition }) => void',
             default: 'undefined',
             desc: '放下时回调；受控数据由父组件按 info 重排 treeData，组件不内部改',
         },
-        { name: 'onChange', type: '(info) => void', default: 'undefined', desc: '选中变更' },
-        { name: 'onCheck', type: '(info) => void', default: 'undefined', desc: '勾选变更' },
         {
-            name: 'onExpandedChange',
-            type: '(info) => void',
+            name: 'onDragStart',
+            type: '(node: TreeNodeData) => void',
+            default: 'undefined',
+            desc: '开始拖拽节点',
+        },
+        {
+            name: 'onDragEnter',
+            type: '(info: { dragNode: TreeNodeData; dropNode: TreeNodeData }) => void',
+            default: 'undefined',
+            desc: '拖拽进入候选目标节点',
+        },
+        {
+            name: 'onContextMenu',
+            type: '(e: MouseEvent, node: TreeNodeData) => void',
+            default: 'undefined',
+            desc: '节点右键菜单回调（对齐 Semi onContextMenu）',
+        },
+        {
+            name: 'onSearch',
+            type: '(value: string, filteredExpandedKeys: string[]) => void',
             default: 'undefined',
-            desc: '展开变更',
+            desc: '搜索关键词变化回调（对齐 Semi）；第二参为因搜索而展开的祖先链 key',
+        },
+        { name: 'onChange', type: '(value) => void', default: 'undefined', desc: '选中变更（对齐 Semi）：单选回 key，多选回选中 key 数组' },
+        {
+            name: 'onExpand',
+            type: '(expandedKeys, { expanded, node }) => void',
+            default: 'undefined',
+            desc: '展开/收起回调（对齐 Semi onExpand）',
+        },
+        { name: 'renderLabel', type: 'Snippet', default: 'undefined', desc: '自定义节点内容（对齐 Semi renderLabel）' },
+        { name: 'icon', type: 'Snippet<[{ node, expanded, isLeaf }]>', default: 'undefined', desc: '自定义节点图标（对齐 Semi icon；传入时渲染在 label 前）' },
+        {
+            name: 'expandIcon',
+            type: 'Snippet<[{ node: TreeNodeData; expanded: boolean; loading: boolean }]>',
+            default: 'undefined',
+            desc: '自定义展开/收起图标（对齐 Semi expandIcon）；参数含节点、展开态与加载态',
+        },
+        {
+            name: 'suffix',
+            type: 'Snippet<[{ node: TreeNodeData }]>',
+            default: 'undefined',
+            desc: '节点尾部操作区（渲染在 label 右侧）',
+        },
+        {
+            name: 'dragGhost',
+            type: 'Snippet<[{ node: TreeNodeData }]>',
+            default: 'undefined',
+            desc: '自定义拖拽幽灵节点',
         },
-        { name: 'label', type: 'Snippet', default: 'undefined', desc: '自定义节点内容' },
-        { name: 'icon', type: 'Snippet<[{ node, expanded, level }]>', default: 'undefined', desc: '自定义节点图标（showIcon 时渲染在 label 前）' },
     ],
     events: [
-        { name: 'onChange', desc: '选中节点变更：{ value, node, selected }' },
-        { name: 'onCheck', desc: '勾选变更：{ checked, node, halfChecked }' },
-        { name: 'onExpandedChange', desc: '展开/收起：{ expanded, node, expand }' },
+        { name: 'onChange', desc: '选中变更：单选回选中 key（或节点对象），多选回选中 key 数组' },
+        { name: 'onSelect', desc: '单个节点选中：(key, selected, node)，早于 onChange' },
+        { name: 'onExpand', desc: '展开/收起：(expandedKeys, { expanded, node })' },
         { name: 'onDrop', desc: '拖拽放下：{ dragNode, dropNode, dropPosition: before|inside|after }' },
     ],
-    slots: [{ name: 'label', desc: '自定义节点渲染：{ node, level, searchValue, selected, checked }' }],
+    slots: [
+        { name: 'renderLabel', desc: '自定义节点内容渲染：{ node, level, searchValue, selected, checked }' },
+        { name: 'renderFullLabel', desc: '整行接管渲染：FullLabelContext（data/level/style/className/expandIcon/checkStatus/expandStatus/onClick/onCheck/onExpand…）' },
+        { name: 'searchRender', desc: '自定义搜索框：SearchRenderContext（value/placeholder/onChange/onClear/showClear/disabled）' },
+        { name: 'icon', desc: '自定义节点图标：{ node, expanded, isLeaf }' },
+        { name: 'expandIcon', desc: '自定义展开图标：{ node, expanded, loading }' },
+        { name: 'suffix', desc: '节点尾部操作区：{ node }' },
+    ],
+    methods: [
+        { name: 'focus', desc: '命令式聚焦树容器（尊重 preventScroll）' },
+        { name: 'search', desc: '命令式触发搜索（对齐 Semi）：(value: string) => void，配合 searchRender=false' },
+        { name: 'scrollTo', desc: '虚拟化滚动到节点（对齐 Semi）：({ key, align? }) => void' },
+    ],
     a11y: {
         hasRole: true,
         focusable: true,
-        note: 'role=tree（aria-multiselectable）容器为单一 tab stop，焦点通过 aria-activedescendant 指向当前高亮 treeitem；每行 role=treeitem 含 aria-level/setsize/posinset/expanded/selected/disabled，可勾选时 aria-checked 支持 true/false/"mixed"（半选）。方向键导航：↑↓ 移动、→ 展开/进入子、← 折叠/回父、Home/End 首末、Enter 选中、Space 勾选或选中。',
+        note: 'role=tree（aria-multiselectable=multiple）容器为单一 tab stop，焦点通过 aria-activedescendant 指向当前高亮 treeitem；每行 role=treeitem 含 aria-level/setsize/posinset/expanded/disabled，单选时 aria-selected、多选时 aria-checked 支持 true/false/"mixed"（半选）。方向键导航：↑↓ 移动、→ 展开/进入子、← 折叠/回父、Home/End 首末、Enter 选中、Space 勾选或选中。',
     },
+    // 组件消费的 Tree token（名值对齐 Semi tree/variables.scss；孤儿 token 已按精简原则清理）。
     tokens: [
+        // Color（对齐 Semi $color-tree_option-*）
+        '--cd-color-tree-option-text-default',
+        '--cd-color-tree-option-icon-default',
+        '--cd-color-tree-option-icon-hover',
+        '--cd-color-tree-option-icon-active',
+        '--cd-color-tree-option-bg-hover',
+        '--cd-color-tree-option-selected-bg-default',
+        '--cd-color-tree-option-bg-active',
+        '--cd-color-tree-option-disabled-text-default',
+        '--cd-color-tree-option-loading-icon-default',
+        '--cd-color-tree-option-draggable-insert-border-default',
+        '--cd-color-tree-option-highlight-text',
+        '--cd-color-tree-option-line',
+        // Font / Radius
+        '--cd-font-tree-option-highlight-weight',
+        '--cd-radius-tree-checkbox-addon',
+        // Spacing（对齐 Semi $spacing-tree_*）
+        '--cd-spacing-tree-search-wrapper-padding-x',
+        '--cd-spacing-tree-search-wrapper-padding-y',
+        '--cd-spacing-tree-option-level-padding-left',
+        '--cd-spacing-tree-option-level1-padding-left',
+        '--cd-spacing-tree-option-list-padding-x',
+        '--cd-spacing-tree-option-list-padding-y',
+        '--cd-spacing-tree-icon-margin-right',
+        '--cd-spacing-tree-label-with-icon-margin-right',
+        '--cd-spacing-tree-option-draggable-padding-y',
+        '--cd-spacing-tree-option-draggable-padding-x',
+        // Width（对齐 Semi $width-tree_*）
+        '--cd-width-tree-empty-icon',
+        '--cd-width-tree-spin-icon',
+        '--cd-width-tree-option-draggable-border',
+        '--cd-width-tree-option-line',
+        // 补充档（Semi 无对应；行高/字号/焦点环/下拉节点 padding）
         '--cd-tree-node-height',
         '--cd-tree-node-height-small',
         '--cd-tree-node-height-large',
-        '--cd-tree-indent',
-        '--cd-tree-node-color',
-        '--cd-tree-node-color-disabled',
-        '--cd-tree-node-bg-hover',
-        '--cd-tree-node-bg-selected',
-        '--cd-tree-node-color-selected',
-        '--cd-tree-expand-icon-color',
-        '--cd-tree-search-highlight-bg',
-        '--cd-tree-search-highlight-color',
+        '--cd-tree-row-height',
+        '--cd-tree-node-font-size',
         '--cd-tree-focus-ring',
-        '--cd-tree-border-color',
-        '--cd-tree-border-color-warning',
-        '--cd-tree-border-color-error',
+        '--cd-tree-node-padding-x',
     ],
     responsive: false,
     examples: [
         {
             title: '基础',
-            code: '<Tree treeData={data} defaultExpandAll onChange={(i) => (v = i.value)} />',
+            code: '<Tree treeData={data} defaultExpandAll onChange={(v) => (value = v)} />',
         },
         {
-            title: '可勾选联动',
-            code: '<Tree treeData={data} checkable onCheck={(i) => (keys = i.checked)} />',
+            title: '多选联动',
+            code: '<Tree treeData={data} multiple value={keys} onChange={(v) => (keys = v)} />',
         },
         {
             title: '可搜索',
-            code: '<Tree treeData={data} filterable />',
+            code: '<Tree treeData={data} filterTreeNode />',
         },
     ],
 };