数据展示有已知边界

NnTree 树

选择、展开和可选虚拟滚动。

示例

API

Props

名称	类型	默认值	说明
treeData	TreeNodeData[]	[]	树数据，结构见下文。
selectedKeys	unknown[]	[]	受控已选键，配合 v-model:selected-keys。键比较使用 Object.is。
expandedKeys	unknown[]	[]	受控展开键，配合 v-model:expanded-keys。
blockNode	boolean	false	节点内容占满可用宽度。
virtual	boolean	false	请求虚拟滚动；还必须提供正数 height 才会实际启用。
height	number	—	虚拟滚动视口高度，单位 px。非正数会禁用虚拟模式。
itemHeight	number	24	虚拟模式的固定行高，非正数回退 24。
overscan	number	4	虚拟窗口前后额外渲染行数；向下取整，非正数按 0。
multiple	boolean	false	多选时点击切换单个键；单选时再次点击已选节点会清空。

TreeNodeData

interface TreeNodeData {
    key?: unknown;
    eventKey?: unknown; // key 缺失时使用
    title?: unknown;
    children?: TreeNodeData[];
    isLeaf?: boolean;
    disabled?: boolean;
    selectable?: boolean; // false 时不可选择
    disableExpand?: boolean;
    dataRef?: unknown;
    [key: string]: unknown; // 也会传给 title 插槽
}

节点键依次取 key、eventKey、按位置生成的 nn-tree-0-1。有非空 children 时推断为非叶节点；显式 isLeaf 优先，其余没有子节点的项默认为叶节点。

Events

事件	参数	说明
update:selectedKeys	(keys: unknown[])	可选节点被点击或通过键盘选择时触发。
select	(keys: unknown[], info: TreeSelectInfo)	返回新键数组和选择详情。
update:expandedKeys	(keys: unknown[])	展开状态变化时触发。
expand	(keys: unknown[], info: TreeExpandInfo)	返回新键数组和展开详情。
rightClick	({ event: MouseEvent, node: TreeEventNode })	节点触发 contextmenu 时触发；不会阻止浏览器默认菜单。

interface TreeEventNode extends TreeNodeData {
    key: unknown;
    eventKey: unknown;
    dataRef: unknown; // 优先 node.dataRef，否则原节点对象
}

interface TreeSelectInfo {
    selected: boolean;
    selectedNodes: TreeNodeData[];
    node: TreeEventNode;
    event: 'select';
    nativeEvent: MouseEvent | KeyboardEvent;
}

interface TreeExpandInfo {
    expanded: boolean;
    node: TreeEventNode;
    nativeEvent: MouseEvent | KeyboardEvent;
}

Slots

名称	作用域参数	说明
title	TreeNodeData 的全部字段	自定义每个节点标题。

Expose

名称	签名	说明
scrollTo	({ key, align?: 'auto' | 'top' | 'bottom', offset?: number }) => Promise<void>	将当前可见节点滚入视口。
refreshVirtualLayout	() => Promise<boolean>	虚拟模式下重新测量并恢复滚动位置；未启用时返回 false。
focus	() => void	聚焦当前 roving tab stop 节点。

当前限制

• selectedKeys 和 expandedKeys 都是受控数据；父组件不处理更新事件时，视觉状态不会改变。
• disabled 阻止选择，但不会自动阻止展开；需要同时设置 disableExpand。
• 虚拟模式假定所有行高度固定为 itemHeight。多行标题或自定义高度会造成窗口计算偏差。
• scrollTo 只能定位当前可见节点；折叠祖先下的节点不会被自动展开。
• 未提供稳定 key/eventKey 时，位置生成键会随树结构变化。