bricks/docs/cn/tree.md

bricks.Tree 与 bricks.TreeNode 技术文档

版本：1.0
模块：Tree 组件（树形结构 UI 控件）

---

概述

bricks.Tree 是一个基于 bricks.js 框架的可交互树形组件，支持异步数据加载、节点展开/折叠、选中/勾选操作、动态增删改节点等功能。它适用于展示层级数据结构（如文件系统、组织架构等），并提供完整的前端交互逻辑和后端通信能力。

该组件由两个核心类构成：

• bricks.Tree: 树的容器类，继承自 bricks.VScrollPanel，负责管理整体布局、数据获取、工具栏及事件分发。
• bricks.TreeNode: 单个树节点类，继承自 bricks.VBox，表示树中的一个节点，包含图标、文本、子节点区域等元素。

---

类定义

bricks.TreeNode

继承关系

class TreeNode extends bricks.VBox

构造函数

constructor(tree, parent_node, data)

参数说明：

参数	类型	描述
tree	bricks.Tree	当前节点所属的树实例
parent_node	bricks.TreeNode 或 null	父节点引用；根节点为 null
data	Object	节点绑定的数据对象

初始化行为：

• 设置默认选项（宽度 100%，高度自适应）
• 初始化节点状态字段（是否为叶子节点、是否已加载子节点等）
• 设置图标 URL（根据类型或默认配置）
• 创建主内容行（HBox），绑定点击事件
• 异步创建节点内容（图标、复选框、文本或自定义视图）
• 若非叶子节点，则创建子节点容器（VBox），初始隐藏

---

bricks.Tree

继承关系

class Tree extends bricks.VScrollPanel

构造函数

constructor(options)

参数说明（options 对象）：

属性名	类型	必需	默认值	描述
row_height	String	否	'35px'	每行节点的高度
idField	String	是	-	数据中标识唯一 ID 的字段名
textField	String	是	-	显示节点文本的字段名
is_leafField	String	否	'is_leaf'	判断是否为叶子节点的字段名
typeField	String	否	-	区分节点类型的字段名（用于图标定制）
data	Array	否	-	静态数据源（本地 JSON 数组）
dataurl	String	否	-	动态获取子节点数据的 API 地址
method	String	否	'GET'	请求数据时使用的 HTTP 方法
params	Object	否	{}	发送请求时携带的额外参数
node_view	WidgetDesc | Function	否	-	自定义节点渲染模板（可通过 widgetBuild 解析）
checkField	String	否	-	控制节点勾选状态的字段名
editable	Object	否	-	编辑功能配置（增删改 URL 和字段）
node_typeicons	Object	否	内置默认图标	不同类型节点的图标配置
multitype_tree	Boolean	否	false	是否启用多类型树显示

初始化行为：

• 创建滚动面板
• 构建标题与描述（预留接口）
• 创建工具栏（如果启用了编辑模式或自定义工具）
• 初始化容器用于放置节点
• 如果有 dataurl，则异步加载根节点数据；否则使用本地 data 构建树

---

主要方法

bricks.TreeNode 方法

方法名	说明
getValue()	返回当前节点及其所有子节点的完整数据结构（递归）
get_id()	获取节点 ID（通过 idField 字段）
selected(flg)	设置节点选中状态样式
toggleExpandCollapse(event)	切换展开/收起状态（异步）
expand()	展开节点（若未加载过子节点且存在 dataurl，会先请求数据）
collapse()	收起节点
create_triple()	创建带状态切换功能的 SVG 图标（展开/收起）
change_node_type()	根据是否为叶子节点设置图标行为
create_node_content(widget)	渲染节点内部内容（图标、复选框、文本或自定义组件）
update_content()	更新节点显示内容（主要用于刷新文本或视图）
setup_icon_urls()	根据节点类型配置图标路径（支持按 type 定制）

---

bricks.Tree 方法

方法名	说明
getValue()	获取整棵树的数据结构（含所有子节点）
get_id()	获取树根节点 ID
create_toolbar()	创建顶部工具栏（添加、编辑、删除按钮及其他命令）
toolbar_command(event)	工具栏命令处理器（响应用户操作）
add_new_node()	打开模态窗添加新节点
new_node_inputed(event)	处理新增节点表单提交
append_new_subnode(node, data)	在指定节点下追加子节点
build_subnode(node, data)	构建并插入一个 TreeNode 实例
delete_node()	删除当前选中节点（弹出确认框）
delete_node_conformed(event)	确认删除后的处理逻辑
delete_subnode(node, subnode)	从父节点中移除子节点（更新数据与 DOM）
update_node()	编辑当前选中节点（打开表单）
update_node_inputed(event)	处理编辑表单提交
update_node_data(node, data)	应用新数据到节点，并刷新 UI
get_children_data(node)	通过 AJAX 获取某节点的子节点数据
create_node_children(node, data)	使用给定数据批量创建子节点
node_click_handle(node, event)	节点点击处理（控制选中状态切换）
node_selected(node, flag)	分发节点选中事件
node_checked(node, event)	处理节点勾选状态变化，维护 checked_data 列表

---

事件机制

内部触发事件（通过 dispatch 分发）

事件名	触发时机	参数说明
node_selected	节点被选中或取消选中	包含节点原始数据 + selected: true/false
check_changed	节点勾选状态改变	节点数据对象
[command]	工具栏执行命令（如 add, delete）	命令参数 + 元数据（referer、title 等）

示例监听方式：

tree.bind('node_selected', function(e){
    console.log('Selected node:', e.params);
});

---

图标与资源管理

图标策略

• 支持三种状态图标：

  • open: 展开状态图标
  • close: 收起状态图标
  • leaf: 叶子节点图标

• 图标来源优先级：

  1. node_typeicons[type] —— 按节点类型指定
  2. 回退到 default_type
  3. 使用内置默认图标集

this.node_typeicons = {
    folder: {
        open: '/static/imgs/open-folder.svg',
        close: '/static/imgs/close-folder.svg',
        leaf: '/static/imgs/file.svg'
    },
    default_type: 'folder'
}

• 使用 bricks_resource(path) 解析静态资源路径。

---

编辑功能（EditableTree）

当配置 editable 选项时，启用增删改功能：

editable: {
    fields: [ /* 表单字段定义 */ ],
    add_url: '/api/node/add',
    delete_url: '/api/node/delete',
    update_url: '/api/node/update'
}

功能流程

操作	流程
添加节点	弹出 ModalForm → 提交 → 调用 add_url → 成功后插入新节点
删除节点	确认对话框 → 调用 delete_url → 移除 DOM 与数据
修改节点	加载当前数据至表单 → 提交 → 调用 update_url → 局部刷新 UI

注意：表单数据自动附加 idField 和 parentField（如有父节点）

---

数据结构要求

节点数据格式示例

{
    "id": "n1",
    "name": "项目A",
    "type": "project",
    "is_leaf": false,
    "children": [
        {
            "id": "n11",
            "name": "子任务1",
            "is_leaf": true
        }
    ]
}

关键字段映射（可配置）

配置项	默认字段
idField	id
textField	name（需在 opts.textField 中指定）
is_leafField	is_leaf
typeField	（可选）type

---

使用示例

静态树（本地数据）

var tree = new bricks.Tree({
    idField: 'id',
    textField: 'name',
    is_leafField: 'is_leaf',
    data: [
        { id: '1', name: '父节点', is_leaf: false, children: [
            { id: '2', name: '子节点', is_leaf: true }
        ]}
    ]
});
tree.open();

动态树（远程加载）

var tree = new bricks.Tree({
    idField: 'id',
    textField: 'label',
    dataurl: '/api/tree/nodes',
    params: { app: 'doc' },
    row_height: '40px'
});
document.body.appendChild(tree.dom_element);

可编辑树

var editableTree = new bricks.Tree({
    idField: 'id',
    textField: 'title',
    dataurl: '/api/tree',
    editable: {
        fields: [
            { name: 'title', label: '标题', type: 'text' },
            { name: 'type', label: '类型', type: 'select', options: [...] }
        ],
        add_url: '/api/node/add',
        delete_url: '/api/node/delete',
        update_url: '/api/node/update'
    }
});

---

异步加载机制

• 使用 schedule_once(fn, delay) 延迟执行以避免阻塞主线程
• 子节点数据仅在首次展开时请求一次（children_loaded 标志位控制）
• 支持无限层级嵌套

---

工具栏（Toolbar）

自动构建于树上方（如果启用了编辑或自定义工具）：

• 支持图标+文字按钮
• 可扩展自定义命令
• 命令可通过以下方式注入数据：
  • selected_data: true → 传入选中节点数据
  • checked_data: true → 传入所有勾选节点
  • 否则传入上下文数据（选中 > 勾选 > params）

---

注册组件

bricks.Factory.register('Tree', bricks.Tree);
bricks.Factory.register('EditableTree', bricks.EditableTree); // 假设存在别名

允许通过描述符动态创建：

bricks.widgetBuild({ widgettype: 'Tree', ...options }, parent);

---

已知限制与注意事项

1. 性能优化建议：对于超大数据集（>1000 节点），建议启用虚拟滚动或懒加载优化。
2. 复选框过滤问题：checked_data 过滤逻辑目前仅比较 id，应确保唯一性。
3. FormData 处理：对 FormData 类型做了特殊处理（.append()），兼容性强。
4. 图标路径错误排查：注意 bricks_resource() 是否正确解析路径。
5. 循环引用风险：TreeNode 持有 tree 和 parent_node 引用，注意内存释放。

---

附录：依赖函数说明

函数	来源	用途
bricks.extend(a, b)	utils	对象浅合并
bricks.uuid()	utils	生成唯一 ID
bricks_resource(path)	global	解析资源路径
schedule_once(fn, delay)	scheduler	延迟执行函数
formdata2object(fd)	utils	将 FormData 转为普通对象
new bricks.HttpJson()	net	封装 JSON 请求

---

版本历史

• v1.0：初版发布，支持基本树形结构、异步加载、编辑操作、事件系统

---

文档维护者：Bricks Framework Team
最后更新：2025年4月5日