bricks/docs/cn/html.md

bricks.Html 组件技术文档

概述

bricks.Html 是 Bricks 框架中的一个基础 UI 组件，用于将原始 HTML 内容动态插入到 DOM 中。它继承自 bricks.JsWidget，是构建更复杂组件或直接渲染静态/动态 HTML 内容的轻量级工具。

---

类定义

bricks.Html = class extends bricks.JsWidget

• 继承自: bricks.JsWidget
• 用途: 渲染传入的 HTML 字符串到组件的根 DOM 元素中。
• 注册名称: 'Html'（通过 bricks.Factory 注册）

---

构造函数

constructor(opts)

初始化 Html 组件实例。

参数

参数名	类型	说明
opts	Object	配置选项对象，继承自 JsWidget 并扩展以下字段。

opts 属性

属性名	类型	必填	说明
html	String	是	要插入到组件内部的 HTML 字符串内容。该内容将直接设置为 innerHTML。

示例

const htmlWidget = new bricks.Html({
  html: '<div class="info">这是一段 <strong>HTML</strong> 内容</div>'
});

---

功能说明

• 在构造函数中调用 super(opts) 初始化父类 JsWidget 的基本功能（如 DOM 创建、事件绑定等）。
• 使用 this.dom_element.innerHTML = opts.html 将传入的 HTML 字符串注入组件的根元素。

⚠️ 安全提示：由于使用了 innerHTML，若 html 字段包含用户输入，可能存在 XSS 安全风险。建议在使用前对 HTML 内容进行过滤或转义。

---

工厂注册

bricks.Factory.register('Html', bricks.Html);

• 将 Html 组件注册到 Bricks 的工厂系统中，允许通过配置方式（如 JSON 描述）创建该组件。
• 注册名称为 'Html'，可在模板或布局定义中使用。

工厂创建示例（假设支持 JSON 配置）

{
  "type": "Html",
  "html": "<p>通过工厂创建的 HTML 组件</p>"
}

---

使用示例

基本用法

// 创建一个包含 HTML 内容的组件
const myHtmlComponent = new bricks.Html({
  html: `
    <h3>欢迎使用 Bricks Html 组件</h3>
    <ul>
      <li>支持任意合法 HTML</li>
      <li>可嵌入富文本内容</li>
    </ul>
  `
});

// 将组件添加到页面某容器中
document.getElementById('container').appendChild(myHtmlComponent.dom_element);

---

注意事项

1. 安全性：避免将不可信的用户输入直接赋值给 html 字段。
2. 脚本执行：通过 innerHTML 插入的 <script> 标签默认不会执行，如需执行需额外处理。
3. 样式隔离：插入的内容会继承父级样式，建议使用 CSS 类名控制样式作用域。

---

相关类

• bricks.JsWidget —— 所有 JavaScript 组件的基类。
• bricks.Factory —— 组件工厂，用于注册和实例化组件。

---

版本信息

• 框架: Bricks UI Framework
• 模块: bricks.Html
• 最后更新: 可根据实际项目填写

---

✅ 适用于快速渲染静态 HTML 内容场景，是构建富文本展示、帮助文档、动态提示等模块的理想选择。