以下是为提供的 JavaScript 代码编写的 **Markdown 格式技术文档**，涵盖了核心类结构、继承关系、属性、方法和使用说明。

---

# Bricks UI 组件库技术文档

`bricks.JsWidget` 是 Bricks 框架中的基础 UI 组件类，提供通用的 DOM 管理、样式设置、事件绑定、弹窗支持等功能。其他文本类组件（如 `Text`, `Title`, `Tooltip` 等）均继承自该基类或其子类。

---

## 目录

- [1. 基础结构](#1-基础结构)
- [2. `JsWidget` 类](#2-jswidget-类)
  - [构造函数](#构造函数)
  - [实例属性](#实例属性)
  - [公共方法](#公共方法)
    - [DOM 操作](#dom-操作)
    - [样式与 CSS](#样式与-css)
    - [事件处理](#事件处理)
    - [尺寸与布局](#尺寸与布局)
    - [弹窗功能](#弹窗功能)
    - [全屏控制](#全屏控制)
    - [显示/隐藏控制](#显示隐藏控制)
    - [ID 与属性管理](#id-与属性管理)
- [3. `TextBase` 类](#3-textbase-类)
- [4. 文本组件系列](#4-文本组件系列)
  - [`Text`](#text)
  - [`KeyinText`](#keyintext)
  - [`Title1` ~ `Title6`](#title1--title6)
- [5. Tooltip 组件](#5-tooltip-组件)
- [6. 工厂注册](#6-工厂注册)
- [7. 使用示例](#7-使用示例)

---

## 1. 基础结构

```js
var bricks = window.bricks || {};
```

确保 `bricks` 全局命名空间存在，并在此基础上定义各类组件。

所有组件以 ES6 Class 形式实现，支持继承和模块化扩展。

---

## 2. `JsWidget` 类

> 基础 UI 组件类，封装了 DOM 创建、样式设置、事件监听、动态尺寸调整等通用能力。

### 构造函数

```js
constructor(options)
```

#### 参数：
| 参数名 | 类型 | 说明 |
|-------|------|------|
| `options` | Object | 配置选项对象，可选 |

#### 支持的配置项：

| 属性 | 类型 | 说明 |
|------|------|------|
| `baseURI` | String | 基础资源路径 |
| `css` | String | 添加到元素的 CSS 类名（空格分隔） |
| `csses` | String | 同 `css`，兼容旧写法 |
| `tip` | String | 鼠标悬停提示文字（自动绑定 tooltip） |
| `popup` | Object | 弹窗配置对象 |
|   `.popup_event` | String | 触发弹窗的事件类型（如 `'click'`） |
|   `.popup_desc` | WidgetDesc | 弹窗内容描述（用于构建内部组件） |
|   `.popupwindow` | Boolean | 是否使用独立窗口模式弹窗 |
|   `.options` | Object | 传递给 Popup/PoupWindow 的参数 |
| `bgimage` | String (URL) | 背景图片 URL |
| `width`, `height` | String/Number | 宽高（支持像素或字符串如 `'100%'`） |
| `x`, `y` | Number | X/Y 偏移（暂未实际定位） |
| `dynsize` | Boolean | 启用字符单位动态缩放 |
| `cwidth`, `cheight` | Number | 字符宽度/高度单位（乘以 `charsize` 得到真实 px） |
| `cfontsize` | Number | 字体大小（相对于字符单位） |
| `color`, `bgcolor` | String | 文字颜色 / 背景色（`bgcolor` 映射为 `backgroundColor`） |
| `align`, `textAlign` | String | 对齐方式 |
| `margin`, `padding` 等 | Any | 支持多种标准 CSS 属性直接传入 |

> ⚠️ 注意：`opts_set_style()` 方法会将匹配的 `options` 键自动映射到 DOM 样式上。

---

### 实例属性

| 属性 | 类型 | 描述 |
|------|------|------|
| `dom_element` | HTMLElement | 关联的 DOM 元素（默认为 `<div>`） |
| `id` | String | 自动生成的唯一 ID（通过 `bricks.uuid()`） |
| `baseURI` | String | 当前组件的基础 URI |
| `opts` | Object | 传入的原始配置对象 |
| `parent` | JsWidget | 父级组件（尚未在代码中赋值） |
| `_container` | Boolean | 是否为容器组件（默认 `false`） |
| `sizable_elements` | Array | 参与字体缩放的子元素列表 |
| `user_data` | Any | 用户自定义数据存储 |
| `popup_widget` | Popup \| PopupWindow | 当前打开的弹窗实例（延迟创建） |

---

### 公共方法

#### DOM 操作

##### `.create()`
创建一个 `<div>` 作为根元素并赋值给 `this.dom_element`。

##### `.is_in_dom() → Boolean`
检查当前组件是否已插入文档树中。

##### `.showRectage() → DOMRect`
返回组件的边界矩形（调用 `getBoundingClientRect()`）。

---

#### 样式与 CSS

##### `.set_style(key, value)`
设置单个 CSS 样式属性。

```js
widget.set_style('color', 'red');
```

##### `.set_css(css, remove_flg)`
添加或移除 CSS 类名（支持多个类名空格分隔）。

```js
widget.set_css('btn primary');        // 添加类
widget.set_css('hidden', true);       // 移除类
```

##### `.set_csses(csses, remove_flg)`
同 `.set_css()`，保留向后兼容。

##### `.unset_css(css)`
移除指定 CSS 类。

##### `.set_cssObject(cssobj)`
批量设置内联样式对象（通过 `bricks.extend` 扩展）。

##### `.opts_set_style()`
根据 `options` 中的键值自动设置对应样式，支持别名映射（如 `bgcolor → backgroundColor`），并处理 `cwidth`/`cheight` 字符单位转换。

##### `.charsize_sizing()`
响应全局 `charsize` 变化的回调函数，重新计算基于字符单位的宽高和字体大小。

> 自动绑定于 `dynsize: true` 时。

##### `.set_bg_image(url)`
设置背景图，应用以下样式：
- `background-size: cover`
- `background-position: center`
- `background-repeat: no-repeat`

---

#### 事件处理

##### `.bind(eventname, handler)`
绑定 DOM 事件。

```js
widget.bind('click', () => console.log('clicked'));
```

##### `.unbind(eventname, handler)`
解绑事件。

##### `.dispatch(eventname, params)`
派发自定义事件，携带 `params` 数据。

```js
widget.dispatch('changed', { data: 'new value' });
```

> 注：`params` 会挂载在事件对象的 `.params` 属性上。

---

#### 尺寸与布局

##### `.get_width() → Number`
返回客户端宽度（`clientWidth`）。

##### `.get_height() → Number`
返回客户端高度（`clientHeight`）。

##### `.set_width(width)`
设置宽度，若传入数字则自动加 `'px'`。

##### `.set_height(height)`
同上，设置高度。

##### `.h_center()`, `.h_left()`, `.h_right()`
水平对齐：
- `h_center`: `margin: auto`
- `h_left`: `marginLeft: 0`
- `h_right`: `marginRight: 0`

##### `.ht_center()`, `.ht_left()`, `.ht_right()`
文本对齐：
- 设置 `textAlign` 样式。

---

#### 弹窗功能

##### `.popup_action() → Promise<void>`
异步处理弹窗显示/关闭逻辑：
- 若已有弹窗，则销毁；
- 否则根据 `popup.popupwindow` 决定创建 `PopupWindow` 或 `Popup`；
- 使用 `bricks.widgetBuild(popup_desc, parent, userData)` 动态构建内容；
- 显示并定位弹窗。

##### `.destroy_popup()`
销毁当前弹窗实例，清空引用。

> 绑定在弹窗的 `'dismissed'` 事件上。

> 💡 提示：`popup_desc` 应符合框架的组件描述格式。

---

#### 全屏控制

##### `.enter_fullscreen()`
请求进入全屏模式，兼容各浏览器 API（Fullscreen API）。

##### `.exit_fullscreen()`
退出全屏模式（调用 `document.exitFullscreen()`）。

---

#### 显示/隐藏控制

##### `.show()`
显示组件（`display = ''`）。

##### `.hide()`
隐藏组件（`display = 'none'`）。

##### `.toggle_hide()`
切换显隐状态。

##### `.is_hide() → Boolean`
判断是否处于隐藏状态。

---

#### ID 与属性管理

##### `.set_id(id)`
设置组件 ID，并同步到 DOM。

##### `.set_baseURI(uri)`
更新 `baseURI`，若为容器则递归通知子组件更新。

##### `.set_attribute(attr, value)`
设置 DOM 属性。

##### `.get_attribute(attr) → String`
获取 DOM 属性（⚠️ 当前实现有误，缺少 `return`）。

> ❌ 修正建议：
```js
get_attribute(attr) {
  return this.dom_element.getAttribute(attr);
}
```

##### `.selected(flag)`
添加或移除 `selected` CSS 类。

---

#### 辅助方法

##### `.observable(name, value)`
创建一个可观察对象（绑定到当前组件），用于响应式数据管理。

##### `.disabled(flag)`
启用/禁用交互（通过 `pointerEvents: none/auto` 控制）。

##### `.getUserData() → Any`
获取用户数据。

##### `.setUserData(v)`
设置用户数据。

---

## 3. `TextBase` 类

> 文本组件基类，继承自 `JsWidget`，支持国际化（i18n）、文本渲染、字体缩放。

### 构造函数

```js
constructor(options)
```

#### 特有配置项：

| 属性 | 类型 | 说明 |
|------|------|------|
| `text` | String | 初始文本内容 |
| `otext` | String | 原始文本（用于 i18n 查找） |
| `i18n` | Boolean | 是否启用国际化 |
| `rate` | Number | 字体缩放系数（默认 1） |
| `halign`, `valign` | String | 水平/垂直对齐（未在代码中使用） |
| `color`, `bgtcolor` | String | 文字/背景色（后者未使用） |

### 方法

##### `.set_attrs()`
初始化文本内容：
- 优先使用 `text`
- 若提供 `otext` 和 `i18n`，则通过 `I18n._()` 转换
- 设置 `innerHTML`

##### `.set_text(text)`
更新文本内容（同时更新 `this.text` 和 DOM）。

##### `.set_otext(otxt)`
更新原始文本，并重新国际化渲染。

##### `.set_i18n_text()`
触发国际化文本刷新（通常由语言变更事件驱动）。

---

## 4. 文本组件系列

### `Text`

> 普通文本组件，字体大小为 `1 × charsize`。

```js
new bricks.Text({ text: "Hello" })
```

- 继承 `TextBase`
- 默认 `cfontsize = 1`
- 自动调用 `charsize_sizing()`

---

### `KeyinText`

> 可输入文本组件，模拟键盘输入行为。

#### 功能：
- 监听全局 `keydown` 事件（绑定至 `bricks.app`）
- 支持：
  - 输入单字符
  - Backspace 删除末尾字符
  - Delete 清空内容
- 每次变更后派发 `changed` 事件，携带 `{ name: text }` 数据
- 默认 `name = 'data'`

#### 方法：
- `dispatch_changed()`：封装事件派发逻辑

> 📝 示例用途：简易输入框、密码输入、命令行模拟。

---

### `Title1` ~ `Title6`

> 六级标题组件，字体加粗，字号逐级递减。

| 组件 | `cfontsize` |
|------|------------|
| `Title1` | 1.96 |
| `Title2` | 1.80 |
| `Title3` | 1.64 |
| `Title4` | 1.48 |
| `Title5` | 1.32 |
| `Title6` | 1.16 |

均设置 `fontWeight: bold`，并自动适配字符尺寸。

---

## 5. Tooltip 组件

> 工具提示组件，继承自 `Text`，预设样式。

### 构造选项
- `rate: 0.8`：较小字体
- `tip: null`：避免递归绑定提示
- 添加 `modal` CSS 类
- 最小宽度 `90px`
- 自动隐藏任务调度器（`auto_task`）

### 方法

##### `.show(otext, event)`
显示提示框：
- 设置文本
- 设为可见且高 `zIndex`
- 定位到鼠标事件位置（`bricks.relocate_by_eventpos`）
- 启动 6 秒后自动隐藏（可取消）

##### `.hide()`
隐藏提示框，清除定时任务。

> ✅ 支持防抖和重复触发清理。

---

## 6. 工厂注册

所有组件通过 `bricks.Factory.register` 注册，便于动态创建：

```js
bricks.Factory.register('Tooltip', bricks.Tooltip);
bricks.Factory.register('Text', bricks.Text);
// ... 其他组件
```

支持通过名称字符串动态实例化组件。

---

## 7. 使用示例

### 创建普通文本
```js
const text = new bricks.Text({
  text: 'Welcome!',
  css: 'text-primary bold',
  width: 200,
  tip: 'This is a welcome message'
});
document.body.appendChild(text.dom_element);
```

### 创建可输入文本
```js
const input = new bricks.KeyinText({
  name: 'username',
  cwidth: 20
});
input.bind('changed', e => {
  console.log('Input changed:', e.params);
});
```

### 创建标题
```js
const title = new bricks.Title1({
  otext: 'Main Title',
  i18n: true
});
```

### 创建带弹窗的按钮（假设）
```js
const btn = new bricks.Text({
  text: 'Click Me',
  popup: {
    popup_event: 'click',
    popup_desc: { type: 'Panel', children: [...] },
    popupwindow: false
  }
});
```

### 设置背景图
```js
widget.set_bg_image('/images/bg.jpg');
```

---

## 总结

`bricks.JsWidget` 提供了一个灵活、可扩展的前端组件基类，具备以下优势：

✅ 模块化设计  
✅ 支持动态尺寸（字符单位）  
✅ 内建弹窗、tooltip、国际化支持  
✅ 易于继承和定制  
✅ 与 Bricks 框架深度集成（event bus, factory, resize observer）

适用于构建响应式、多语言、高交互性的 Web 应用界面。

--- 

> 📚 *文档版本：v1.0*  
> © 2025 Bricks Framework Team