组件：树形框

树形框组件用于以树状结构展示层级数据，支持节点展开/折叠、复选框选择、自定义图标、右键菜单等功能。它适用于文件目录浏览、组织架构展示、分类导航、权限配置等需要呈现父子层级关系的场景。树形框提供了灵活的节点管理方式，支持动态添加、删除、更新节点，并提供了丰富的交互事件。

典型使用场景：

• 文件目录浏览器（文件夹与文件的层级展示）
• 组织架构图（公司部门、员工层级）
• 分类导航（商品分类、文章栏目）
• 权限管理（菜单权限、功能权限的树形分配）
• 配置项管理（系统设置的分组与子项）

📌 继承自视图的成员速查

本组件继承自 视图 类，可直接使用以下属性和方法：

属性： ID、左边、顶边、右边、底边、宽度、高度、背景、背景颜色、背景图像、文本、文本颜色、字体、字体大小、字体粗细、行高、边框、边框圆角、边框宽度、光标样式、显示模式、透明度、外边距、外边距底、外边距左、外边距右、外边距顶、最大高度、最大宽度、最小高度、最小宽度、内边距、内边距底、内边距左、内边距右、内边距顶、定位、CLASS、InnerHTML、OuterHTML、内容水平对齐方式、首行缩进、可视、显示层级、内联样式、禁用

方法： 追加内联样式(样式文本)、置内联样式(名称,值)、取内联样式值(名称)、取Style对象()、添加事件(事件名称, 回调函数)、删除事件(事件名称, 回调函数)、获取焦点()、清除焦点()、添加样式类(类名称)、移除样式类(类名称)、取样式类列表()、取样式类()、执行单击()、取属性值(属性名)、取属性节点(属性名)、取布局参数()、取渲染宽度()、取渲染高度()、取渲染顶边()、取渲染左边()、左侧对齐到(目标组件,偏移量)、右侧对齐到(目标组件,偏移量)、顶边对齐到(目标组件,偏移量)、底边对齐到(目标组件,偏移量)、右侧对齐到左(目标组件, 偏移量)、左侧对齐到右(目标组件, 偏移量)、底边对齐到顶(目标组件, 偏移量)、顶边对齐到底(目标组件, 偏移量)、有指定属性(属性名)、有属性()、内容可编辑()、包含CSS类(类名)、取命名空间()、取下个节点()、取下个元素()、取节点名称()、取节点类型()、取父节点()、取父元素()、取上个节点()、取上个元素()、销毁()、删除属性(属性名)、删除属性节点(属性名)、置属性值(属性名, 属性值)、置属性节点(属性节点)、取标签名()、移动(左边 顶边, 宽度, 高度)、取原生对象()、置被单击回调(回调函数)、置被双击回调(回调函数)、置鼠标被进入回调(回调函数)、置鼠标被移出回调(回调函数)、置鼠标被移动回调(回调函数)、置鼠标被按下回调(回调函数)、置鼠标被抬起回调(回调函数)、置鼠标滚轮被滚动回调(回调函数)、置键盘被按下回调(回调函数)、置按键被抬起回调(回调函数)、置按键被压下回调(回调函数)、置被失去焦点回调(回调函数)、置被获得焦点回调(回调函数)

事件： 被单击(源对象,事件源)、被双击(源对象,事件源)、鼠标被进入(源对象,事件源)、鼠标被移出(源对象,事件源)、鼠标被移动(源对象,事件源)、鼠标被按下(源对象,事件源)、鼠标被抬起(源对象,事件源)、鼠标滚轮被滚动(源对象,事件源)、键盘被按下(源对象,事件源)、按键被抬起(源对象,事件源)、按键被压下(源对象,事件源)、被失去焦点(源对象,事件源)、被获得焦点(源对象,事件源)

💡 完整成员列表及详细说明请参考：视图 类

常用操作速查

样式美化参考

树形框的外观可通过继承的视图属性和 CSS 类进行美化：

• 整体容器：设置 宽度、高度、背景颜色、边框、边框圆角（建议 "8px"）等。
• 字体样式：通过 字体大小（建议 "14px"）、文本颜色、字体粗细 控制节点文本外观。
• 内边距：使用 内边距 让节点列表与边框保持距离。
• 节点缩进：树形框默认会根据层级自动缩进，缩进量由组件内部控制。
• 复选框：通过 显示复选框 属性控制是否显示节点前的复选框，复选框样式可由 CSS 自定义。
• 节点图标：可通过 置节点图标 为特定类型的节点设置自定义图标，或直接在添加节点时指定 icon 属性。

CSS 美化示例（在项目 CSS 文件中定义）：

.my-tree .tree-node {
    padding: 4px 8px;
    border-radius: 4px;
    cursor: pointer;
}
.my-tree .tree-node:hover {
    background-color: #f5f5f5;
}
.my-tree .tree-node.selected {
    background-color: #e6f7ff;
    color: #1890ff;
}

在代码中应用样式类：树形框1.添加样式类("my-tree")

基础示例

创建一个简单的组织架构树，包含两个部门及其成员，并显示复选框。

变量 树形框1 = 创建 树形框()
树形框1.左边 = 50
树形框1.顶边 = 50
树形框1.宽度 = 300
树形框1.高度 = 300
树形框1.字体大小 = "14px"
树形框1.边框 = "1px solid #d9d9d9"
树形框1.边框圆角 = "8px"
树形框1.内边距 = "8px"
树形框1.显示复选框 = 真

' 添加根节点（无父节点，父节点传空）
变量 根节点 = 树形框1.添加分组节点("公司总部", 空, [], 假, "root")

' 添加部门节点
变量 部门1 = 树形框1.添加分组节点("研发部", 根节点, [], 假, "dev")
树形框1.添加文本节点("张三", 部门1, "u1", "", 真)
树形框1.添加文本节点("李四", 部门1, "u2", "", 假)

变量 部门2 = 树形框1.添加分组节点("市场部", 根节点, [], 真, "mkt")  ' 默认折叠
树形框1.添加文本节点("王五", 部门2, "u3", "", 假)
树形框1.添加文本节点("赵六", 部门2, "u4", "", 真)

' 设置单击回调
树形框1.置节点被单击回调((源对象, 节点对象) => {
    弹出提示("点击了：" + 节点对象.text)
})

' 设置复选框回调
树形框1.置节点被选中回调((源对象, 节点对象, 选中状态) => {
    调试输出("节点 " + 节点对象.text + " 选中状态：" + 选中状态)
})

' 展开所有节点
树形框1.展开全部()
添加组件(树形框1)

综合示例：文件目录浏览器

本示例模拟一个文件目录树，支持文件夹的展开/折叠，文件节点的单击打开操作，并带有右键菜单。

' ========== 创建树形框 ==========
变量 文件树 = 创建 树形框()
文件树.左边 = 30
文件树.顶边 = 30
文件树.宽度 = 350
文件树.高度 = 450
文件树.背景颜色 = "#ffffff"
文件树.边框 = "1px solid #e8e8e8"
文件树.边框圆角 = "8px"
文件树.内边距 = "8px"
文件树.字体大小 = "14px"
文件树.显示复选框 = 假  ' 本例不使用复选框
添加组件(文件树)

' 设置节点图标（按类型）
文件树.置节点图标("folder", "📁")
文件树.置节点图标("file", "📄")

' ========== 构建目录树 ==========
' 根节点（我的电脑）
变量 根 = 文件树.添加分组节点("我的电脑", 空, [], 假, "root")

' 系统盘 (C:)
变量 盘C = 文件树.添加分组节点("C:", 根, [], 假, "c")
文件树.添加文本节点("Windows", 盘C, "c1", "", 假, "folder")
文件树.添加文本节点("Program Files", 盘C, "c2", "", 假, "folder")
文件树.添加文本节点("Users", 盘C, "c3", "", 假, "folder")
    ' Users 下的子文件夹
    变量 usersFolder = 文件树.添加分组节点("Users", 盘C, [], 假, "c3_sub")
    文件树.添加文本节点("Administrator", usersFolder, "u1", "", 假, "folder")
    文件树.添加文本节点("Public", usersFolder, "u2", "", 假, "folder")

' 数据盘 (D:)
变量 盘D = 文件树.添加分组节点("D:", 根, [], 真, "d")  ' 默认折叠
文件树.添加文本节点("Documents", 盘D, "d1", "", 假, "folder")
文件树.添加文本节点("Downloads", 盘D, "d2", "", 假, "folder")
文件树.添加文本节点("readme.txt", 盘D, "d3", "", 假, "file")

' ========== 事件回调 ==========
' 节点单击（打开文件/文件夹）
文件树.置节点被单击回调((源对象, 节点对象) => {
    如果(节点对象.type == "file")
        弹出提示("打开文件：" + 节点对象.text)
    否则
        弹出提示("进入文件夹：" + 节点对象.text)
    结束 如果
})

' 右键菜单
文件树.置右键菜单([
    {文本: "新建文件夹", 回调: (节点对象) => {
        弹出提示("在 " + 节点对象.text + " 下新建文件夹")
    }},
    {文本: "重命名", 回调: (节点对象) => {
        弹出提示("重命名：" + 节点对象.text)
    }},
    {文本: "删除", 回调: (节点对象) => {
        弹出提示("删除：" + 节点对象.text)
    }}
])

' ========== 展开全部 ==========
文件树.展开全部()

' ========== 底部信息栏 ==========
变量 信息标签 = 创建 标签()
信息标签.左边 = 30
信息标签.顶边 = 495
信息标签.文本 = "当前选中：无"
信息标签.字体大小 = "12px"
信息标签.文本颜色 = "#999"
添加组件(信息标签)

' 监听节点选中（通过单击回调也可以更新选中信息，但树形框本身有选中状态）
' 这里我们通过获取选中节点来更新（由于没有单选选中事件，我们可以在单击回调中更新）
' 修改节点单击回调，增加更新信息标签
文件树.置节点被单击回调((源对象, 节点对象) => {
    信息标签.文本 = "当前选中：" + 节点对象.text
    如果(节点对象.type == "file")
        弹出提示("打开文件：" + 节点对象.text)
    否则
        弹出提示("进入文件夹：" + 节点对象.text)
    结束 如果
})

属性详解

显示复选框

• 类型： 逻辑型
• 说明： 设置是否在每个节点前显示复选框。当为 真 时，节点前会出现复选框，用户可勾选/取消勾选，并触发 置节点被选中回调。默认为 假。

函数详解

置节点图标(节点类型, 图标URL)

• 功能： 为指定类型的节点设置默认图标。图标可以是图片 URL 或 Emoji 字符。
• 参数：
  • 节点类型：文本型，用于匹配节点的 type 属性。
  • 图标URL：文本型，图标地址或 Emoji 字符。
• 返回值： 无。
• 示例： 树形框1.置节点图标("folder", "📁")

添加节点(节点对象, 父节点)

• 功能： 向树中添加一个节点，可以指定完整的节点配置。该函数提供了最大的灵活性。
• 参数：
  • 节点对象：对象，必须包含以下字段：
    • id：文本型，唯一标识（必须）
    • text：文本型，显示文本（必须）
    • type：文本型，节点类型，用于匹配图标（可选）
    • icon：文本型，直接指定节点的图标（可选，优先级高于类型图标）
    • checked：逻辑型，复选框状态（可选）
    • collapsed：逻辑型，是否折叠（可选，默认 假）
    • children：数组，子节点列表（可选）
  • 父节点：对象，父节点对象（由之前的添加函数返回），若为 空 则表示根节点。
• 返回值： 创建的节点对象（可用于后续操作）。
• 示例：

  变量 新节点 = 树形框1.添加节点({
      id: "n123",
      text: "新项目",
      type: "folder",
      children: []
  }, 父节点)
  

添加文本节点(文本, 父节点, ID, 图标URL, 复选框状态)

• 功能： 快捷添加一个叶子节点（无子节点）。
• 参数：
  • 文本：必填，显示文本。
  • 父节点：父节点对象，若为 空 则添加到根。
  • ID：可选，节点唯一标识，若省略则自动生成。
  • 图标URL：可选，节点图标。
  • 复选框状态：可选，逻辑型，默认 假。
• 返回值： 创建的节点对象。
• 示例： 树形框1.添加文本节点("张三", 部门1, "u1", "", 真)

添加分组节点(文本, 父节点, 子节点数组, 是否折叠, ID, 图标URL, 复选框状态)

• 功能： 快捷添加一个可包含子节点的分组节点。
• 参数：
  • 文本：必填。
  • 父节点：父节点对象。
  • 子节点数组：可选，预先添加的子节点数组。
  • 是否折叠：可选，逻辑型，默认 假（展开）。
  • ID：可选。
  • 图标URL：可选。
  • 复选框状态：可选。
• 返回值： 创建的节点对象。

展开指定节点(节点ID)

• 功能： 展开指定 ID 的节点（如果该节点是分组节点且当前折叠）。
• 参数： 节点ID（文本型）。
• 返回值： 无。

折叠指定节点(节点ID)

• 功能： 折叠指定 ID 的节点。
• 参数： 节点ID（文本型）。
• 返回值： 无。

展开全部()

• 功能： 展开树中所有节点。
• 返回值： 无。

折叠全部()

• 功能： 折叠树中所有节点。
• 返回值： 无。

获取选中节点()

• 功能： 获取当前选中的节点（通常指被单击选中的节点）。
• 返回值： 节点对象，若无选中则返回 空。

获取节点状态(节点ID)

• 功能： 获取指定节点的展开状态和复选框状态。
• 参数： 节点ID（文本型）。
• 返回值： 对象，包含 collapsed（是否折叠）和 checked（是否选中）属性。若节点不存在则返回 空。

查找节点(文本)

• 功能： 在树中搜索包含指定文本的节点，并高亮显示（滚动到可视区域）。
• 参数： 文本（文本型）。
• 返回值： 找到的第一个节点对象，若无则返回 空。

置右键菜单(菜单项数组)

• 功能： 为树节点设置右键上下文菜单。当用户在节点上右键点击时，弹出菜单。
• 参数： 菜单项数组，每个元素为对象，包含 文本（显示文字）和 回调（点击时的回调函数，参数为当前右键点击的节点对象）。
• 返回值： 无。
• 示例：

  树形框1.置右键菜单([
      {文本: "编辑", 回调: (节点) => { 弹出提示("编辑：" + 节点.text) }},
      {文本: "删除", 回调: (节点) => { 弹出提示("删除：" + 节点.text) }}
  ])
  

清空()

• 功能： 清空树中所有节点。
• 返回值： 无。

置节点被单击回调(回调函数)

• 功能： 设置节点被单击时的回调函数。
• 参数： 回调函数，格式为 (源对象, 节点对象) => { ... }。
  • 源对象：树形框组件本身。
  • 节点对象：被单击的节点对象。
• 返回值： 无。

置节点被选中回调(回调函数)

• 功能： 设置节点复选框状态变化时的回调函数。
• 参数： 回调函数，格式为 (源对象, 节点对象, 选中状态) => { ... }。
  • 源对象：树形框组件本身。
  • 节点对象：状态变化的节点。
  • 选中状态：逻辑型，表示新的选中状态。
• 返回值： 无。

事件说明

节点被单击(源对象, 节点对象)

• 功能： 与 置节点被单击回调 等效，适用于设计文件（.spldg）中定义的组件。
• 示例：

  事件 树形框1.节点被单击(源对象, 节点对象)
      调试输出("单击：" + 节点对象.text)
  结束 事件
  

节点被选中(源对象, 节点对象, 选中状态)

• 功能： 与 置节点被选中回调 等效，适用于设计文件。
• 示例：

  事件 树形框1.节点被选中(源对象, 节点对象, 选中状态)
      调试输出("节点 " + 节点对象.text + " 选中：" + 选中状态)
  结束 事件
  

⚠️ 注意事项

1. 节点 ID 唯一性：每个节点的 id 应保持唯一，否则可能导致操作混乱（如展开指定节点时无法准确定位）。
2. 父节点引用：添加节点时，父节点 参数必须传入由同一树形框先前创建函数返回的节点对象，不能传入 空 以外的任意对象。
3. 复选框回调：只有 显示复选框 为 真 时，复选框才会显示，置节点被选中回调 才会在用户勾选/取消勾选时触发。
4. 展开/折叠状态：使用 添加分组节点 时可通过 是否折叠 参数控制初始状态，也可后续通过 展开指定节点/折叠指定节点 动态控制。
5. 右键菜单：菜单项的回调函数参数为当前右键点击的节点对象，可据此执行针对该节点的操作。
6. 查找节点：查找节点 只高亮显示第一个匹配的节点，不会展开路径，若节点在折叠的父节点下，可能无法看到。
7. 性能考虑：树形框适用于节点数量较大的场景（如数百个节点），但若节点数量极大（数千以上），建议考虑分页或异步加载。
8. 节点数据更新：若需修改已有节点的属性（如文本、图标），目前没有直接的更新方法，建议删除旧节点并重新添加，或通过 添加节点 时传入完整结构覆盖。
9. 根节点：树可以没有根节点（即添加节点时父节点传 空 会有多个顶层节点），也可以创建一个根节点作为统一入口。
10. 样式定制：节点缩进、图标大小等细节由组件内部控制，可通过 CSS 类覆盖，但需了解内部 DOM 结构。

相关文档

• 文档框架基础类_视图 —— 视图类提供的所有通用属性和方法
• 文档列表类组件_列表框 —— 其他列表类组件
• 文档文本类组件_标签 —— 配合树形框显示节点信息
• 文档轻语言网站：轻语言语法速查 —— 拉姆达表达式、对象操作等
• 文档综合演示：文件目录树 —— 实际应用示例