# Bricks 文档查看器组件技术文档
本技术文档介绍了基于 `bricks.js` 框架的三种文档文件在线预览组件：`DOCXviewer`、`EXCELviewer` 和 `PDFviewer`。这些组件支持通过 URL 加载并渲染 `.docx`、`.xlsx/.xls` 和 `.pdf` 文件，适用于网页端轻量级文档展示场景。
---
## 🔧 依赖说明
以下第三方库必须在页面中提前加载：
```html
```
> ⚠️ 注意：确保 `pdfjsLib` 已全局可用（通常由 PDF.js 提供）。
---
## 📦 组件概览
| 组件名 | 功能描述 | 支持格式 |
|----------------|------------------------------|--------------|
| `DOCXviewer` | 预览 Word 文档 (.docx) | `.docx` |
| `EXCELviewer` | 预览 Excel 表格文件 | `.xlsx`, `.xls` |
| `PDFviewer` | 预览 PDF 文档 | `.pdf` |
所有组件均继承自 `bricks.VBox`，可通过 `bricks.Factory.register()` 注册使用。
---
## 1. ✅ DOCXviewer
将 `.docx` 文件转换为 HTML 并嵌入页面显示。
### 类定义
```javascript
bricks.DOCXviewer = class extends bricks.VBox
```
### 构造函数
```javascript
constructor(opts)
```
#### 参数
- `opts` `{Object}`: 配置选项对象。
- `url` `{String}`: 指向 `.docx` 文件的远程或本地 URL。
#### 示例
```javascript
const docViewer = new bricks.DOCXviewer({
url: 'https://example.com/document.docx'
});
```
### 方法
#### `async set_url(url)`
从指定 URL 获取 `.docx` 文件，并使用 Mammoth.js 转换为 HTML 显示。
##### 流程
1. 使用 `HttpArrayBuffer` 异步获取文件二进制数据。
2. 调用 `mammoth.convertToHtml()` 将 ArrayBuffer 转为 HTML 字符串。
3. 插入到组件 DOM 容器内。
##### 参数
- `url` `{String}`: 可选，若未传则使用实例的 `this.url`。
---
## 2. ✅ EXCELviewer
支持多工作表 Excel 文件的交互式浏览。
### 类定义
```javascript
bricks.EXCELviewer = class extends bricks.VBox
```
### 构造函数
```javascript
constructor(opts)
```
#### 参数
- `opts` `{Object}`:
- `url` `{String}`: Excel 文件地址。
- （自动设置）`height: "100%"`
#### UI 结构
- 上部：横向滚动条式工作表标签栏 (`HBox`)
- 下部：内容区域 (`Filler`) 显示当前选中的 sheet
#### 示例
```javascript
const excelViewer = new bricks.EXCELviewer({
url: 'https://example.com/data.xlsx'
});
```
### 方法
#### `async set_url(url)`
加载 Excel 文件并解析所有工作表名称，生成可点击标签。
##### 步骤
1. 获取文件 ArrayBuffer。
2. 使用 `XLSX.read(data, {type: 'array'})` 解析 workbook。
3. 遍历 `SheetNames` 创建文本按钮，绑定点击事件。
#### `show_sheet_by_name(sheetname, widget)`
切换显示指定工作表的内容。
##### 功能
- 更新选中状态样式（添加 `selected` CSS 类）
- 使用 `XLSX.utils.sheet_to_html()` 生成表格 HTML
- 嵌入 `VScrollPanel` 实现垂直滚动
- 替换内容容器中的子组件
##### 内部变量
- `this.cur_sheetname`: 当前显示的工作表名
- `this.workbook`: 缓存 workbook 对象以供后续访问
---
## 3. ✅ PDFviewer
逐页渲染 PDF 文件为 Canvas 图像。
### 类定义
```javascript
bricks.PDFviewer = class extends bricks.VBox
```
### 构造函数
```javascript
constructor(opts)
```
#### 参数
- `opts` `{Object}`:
- `url` `{String}`: PDF 文件路径
- （自动设置）`width: '100%'`
#### 示例
```javascript
const pdfViewer = new bricks.PDFviewer({
url: 'https://example.com/report.pdf'
});
```
### 方法
#### `async set_url(url)`
加载 PDF 并启动渲染流程。
##### 步骤
1. 使用 `HttpArrayBuffer` 获取二进制数据。
2. 调用 `pdfjsLib.getDocument({ data: ab })` 初始化文档。
3. 遍历每一页，调用 `getPage(i)` 并异步渲染。
#### `add_page_content(page)`
将单个 PDF 页面渲染为 `