---
title: "WebBuilder 控件注册"
description: "controls.json 的注册职责、设计器加载过程与分类边界。"
---

> Documentation Index
> Fetch the complete documentation index at: https://ag.879818327.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# WebBuilder 控件注册

`ILogBizSystem/src/main/webapp/wb/system/controls.json` 是 WebBuilder 的控件元数据注册表。它不仅定义 IDE 控件箱的树结构，也为 XWL 的解析和缓存提供组件的 `general`、`configs` 与 `events` 元数据。

## 注册与加载

后端 `com.wb.interact.Controls` 固定读取 `wb/system/controls.json`。`getControlTree()` 将整棵树返回给客户端；IDE 请求 `m?xwl=dev/cm/get-tree&type=ide` 时，后端会把每个叶子节点转换为带 `type` 和 `control: true` 的可插入控件节点。

IDE 的控件箱仅将 `control: true` 的节点加入 `Ide.controlMap`，拖入设计画布时读取对应节点的 `general`、`configs` 和 `events`。页面解析器与 XWL 缓存也通过 `Controls.get(type)` 查找同一份注册数据，因此调整本文件会同时影响设计器和运行时生成。

## 可视化边界

`control: true` 表示该条目可以作为模块树节点插入。是否能在当前桌面设计画布中直观渲染，还取决于 `general.design`：值为 `false` 的条目会以非设计态处理，或仅作为数据、服务、Touch、Bootstrap、图表子项等配置节点存在。

当前注册表有 134 个叶子节点，其中 38 个同时具备 `general.xtype` 且未设置 `general.design: false`。它们是本手册“可视化组件分类”页面列出的桌面画布组件。

## 元数据字段

| 字段 | 设计器用途 |
| --- | --- |
| `id` | XWL 节点的 `type`，也是控件注册表的唯一查找键。 |
| `text` / `iconCls` | 控件箱中的显示名称和图标。 |
| `general` | Ext 类、`xtype`、默认尺寸、容器能力和设计态等基础定义。 |
| `configs` | 属性面板可编辑的配置项及其编辑器类型。 |
| `events` | 事件面板可编辑的事件及其脚本类型。 |

请从 [可视化组件分类](/controls/visual-components/) 查看可拖入桌面画布的组件清单。

## 本目录

- [可视化组件分类](/controls/visual-components/)：按控件箱分类查看可在桌面画布中使用的控件。

Source: https://ag.879818327.xyz/controls/index.mdx