# @file-viewer/doc 中文文档

规范地址：https://npmcn.com/package/%40file-viewer/doc/

版本：3\.3\.3
npm 元数据更新时间：2026-10-31T11:06:29.938Z
中文译文更新时间：2026-11-14T17:39:42.224Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40file-viewer/doc
原文对照：https://npmcn.com/package/%40file-viewer/doc/?lang=original
项目主页：https://github.com/flyfish-dev/docjs
源码仓库：https://github.com/flyfish-dev/file-viewer

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：333 kB，53 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-06-28T14:17:44.605Z
- 最新版本发布：2026-10-31T11:06:29.629Z
- 近 30 天下载量：248116（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

浏览器-内生遗产 MS-DOC (.doc) parser和 HTML 渲染器取自公共 msdoc-viewer 02.0行.

## 安装

```sh
npm install @file-viewer/doc
```

也可以使用：`pnpm add @file-viewer/doc`、`yarn add @file-viewer/doc`、`bun add @file-viewer/doc`

## README

# @file-viewer/doc

[English](https://github.com/flyfish-dev/file-viewer/blob/main/packages/renderers/doc/README.md) · [简体中文](https://github.com/flyfish-dev/file-viewer/blob/main/packages/renderers/doc/README.zh-CN.md)

一个面向 **MS-DOC（`.doc` 二进制 Word）** 的 **TypeScript 严格类型** 解析与预览库。它把旧版 Word 文档解析为结构化 AST，再渲染为可直接嵌入任意项目的 `HTML + CSS`，同时提供 DOM Viewer 与 Web Worker 通道。

> 本项目处理的是 **`.doc`**，不是 `.docx`。 本包基于 npm 已公开的 `msdoc-viewer@0.2.0` 旧版源码维护，不包含新版私有文档引擎实现。

## 特性

-   **整仓 TypeScript 重构**：源码、公开 API、Worker 协议、解析 AST 全部使用 TypeScript，并开启 `strict` 模式
-   **完整声明文件产物**：构建后输出 `dist/*.d.ts`，便于社区阅读、联想、二次开发
-   **纯前端方案**：不依赖 LibreOffice、COM、ActiveX 或服务器端转换
-   **按 MS-DOC 主链路实现**：CFB/OLE → FIB → CLX/Piece Table → FKP → PAPX/CHPX/TAPX → STSH → HTML
-   **可扩展架构**：把二进制读取、属性解码、样式继承、表格布局、渲染层完全拆分
-   **支持 Web Worker**：避免大文档解析阻塞 UI 线程

## 当前能力

已经覆盖的主要能力：

-   CFB/OLE 容器读取
-   FIB（`FibBase` / `FibRgLw` / `FibRgFcLcb`）解析
-   CLX / Piece Table 文本恢复
-   FKP（PAPX / CHPX）属性读取
-   STSH 样式表解析与样式继承
-   字体表读取
-   常见字符样式：粗体、斜体、下划线、删除线、字号、颜色、高亮、大小写、上下标、字体切换
-   常见段落样式：对齐、缩进、段前后距、行距、分页控制、边框
-   表格：`sprmTDefTable`、单元格宽度、横向/纵向合并、边框、垂直对齐、nowrap、fitText
-   图片：按 MS-DOC PICF / OfficeArt BLIP 规范提取内嵌 PNG、JPEG、DIB、TIFF，并支持 EMF/WMF 转 SVG 预览
-   OLE / ObjectPool 附件提取
-   域代码的基础处理（例如超链接）
-   浏览器 Viewer 与 Worker Client

## 工程结构

```text
src/
  core/
    binary.ts        # 二进制读取器
    cfb.ts           # CFB/OLE 容器解析
    inflate.ts       # OfficeArt 压缩 metafile 的 zlib/deflate 解压
    utils.ts         # 字节、编码、范围等底层工具
  msdoc/
    fib.ts           # FIB 读取
    clx.ts           # CLX / Piece Table
    fkp.ts           # FKP 页读取
    sprm.ts          # SPRM 操作数解码
    properties.ts    # PAPX / CHPX / TAPX 到状态对象的归并
    styles.ts        # STSH / 样式继承
    fonts.ts         # 字体表
    officeart.ts     # OfficeArt 内联 shape / BLIP 辅助解析
    objects.ts       # PICF / OfficeArt 图片与 OLE / ObjectPool
    vector.ts        # EMF/WMF 转 SVG
    parser.ts        # 主解析流程，输出 AST
  render/
    html.ts          # AST -> HTML/CSS
  types.ts           # 完整类型声明与公共接口
  viewer.ts          # DOM Viewer
  worker-client.ts   # Worker 客户端
  worker.ts          # Worker 入口
  index.ts           # 公共导出

demo/
  index.html

test/
  smoke.mjs
```

## 安装

```bash
npm install @file-viewer/doc
```

历史 `msdoc-viewer` 包名会通过兼容别名继续导出同一套 API。

## 仓库开发与构建

```bash
pnpm install
pnpm --filter @file-viewer/doc type-check
pnpm --filter @file-viewer/doc build
pnpm --filter @file-viewer/doc verify:github-34
```

构建产物输出到 `dist/`：

-   `dist/index.js`
-   `dist/index.d.ts`
-   `dist/worker.js`
-   其余模块的 JS / d.ts

## 快速开始

### 1）直接解析并渲染

```ts
import { parseMsDoc, renderMsDoc } from '@file-viewer/doc';

const buffer = await file.arrayBuffer();
const parsed = parseMsDoc(buffer);
const rendered = renderMsDoc(parsed);

document.getElementById('app')!.innerHTML = `
  <style>${rendered.css}</style>
  <div class="msdoc-root">${rendered.html}</div>
`;
```

外部链接和关联图片默认阻断。确需访问可信外部资源时，应分别显式设置 `externalLinkPolicy: 'allow'` 和 `externalResourcePolicy: 'allow'`；内嵌图片及书签不受影响。

### 2）使用内置 Viewer

```ts
import { createMsDocViewer } from '@file-viewer/doc';

const container = document.getElementById('app')!;
const viewer = createMsDocViewer(container);

await viewer.load(file);
```

### 3）使用 Worker 提升体验

```ts
import { createMsDocViewer, MsDocWorkerClient } from '@file-viewer/doc';

const workerClient = MsDocWorkerClient.create(
  new URL('./node_modules/@file-viewer/doc/dist/worker.js', import.meta.url)
);

const viewer = createMsDocViewer(document.getElementById('app')!, {
  workerClient,
});

await viewer.load(file);
```

## API 概览

### `parseMsDoc(input, options?)`

把 `.doc` 解析成结构化结果：

```ts
import type { MsDocParseResult } from '@file-viewer/doc';
```

核心字段：

-   `warnings`: 解析期告警
-   `meta`: 文档元数据与统计
-   `fonts`: 字体表摘要
-   `styles`: 样式表摘要
-   `blocks`: 结构化块级 AST（段落、表格、附件）
-   `assets`: 图片 / 附件资产

### `renderMsDoc(parsed, options?)`

把 AST 渲染为：

-   `html`
-   `css`
-   `warnings`
-   `meta`
-   `assets`
-   `parsed`

### `parseMsDocToHtml(input, options?)`

一步完成解析与渲染。

### `createMsDocViewer(container, config?)`

返回一个面向浏览器的 viewer：

-   `load(input, options?)`
-   `mount(rendered)`
-   `clear()`
-   `destroy()`
-   `value`

### `MsDocWorkerClient`

为 Worker 提供强类型 RPC 包装：

-   `parse(input, options?)`
-   `render(parsed, options?)`
-   `parseToHtml(input, options?)`
-   `destroy()`

## 关键类型

所有公共类型都从根入口导出，例如：

```ts
import type {
  MsDocParseResult,
  MsDocRenderResult,
  MsDocBlock,
  ParagraphBlock,
  TableBlock,
  MsDocAsset,
  MsDocParseOptions,
  MsDocRenderOptions,
  MsDocViewer,
} from '@file-viewer/doc';
```

这意味着：

-   社区开发者可以直接消费 `AST` 与 `asset` 数据自行渲染
-   也可以在现有渲染器之外实现 Markdown、Canvas、PDF 等输出层
-   Worker 主线程通信协议也有完整类型约束，避免“隐式 any 消息格式”问题

## 严格类型与可维护性说明

这次重构的重点不只是把文件后缀改成 `.ts`，而是把整条主链路都显式类型化：

-   二进制结构：CFB/FIB/CLX/FKP
-   样式模型：字符、段落、表格状态对象
-   中间 AST：段落、行内节点、表格、附件
-   渲染结果：HTML/CSS/资产
-   Viewer / Worker 协议

同时给关键模块补充了注释，尤其是：

-   `BinaryReader` 的边界读取行为
-   Worker 请求/响应通道
-   parser 主流程
-   样式与属性归并逻辑

## 本地验证

```bash
npm run smoke
```

这个命令会：

1.  先运行 TypeScript 构建
2.  再读取 `test/test.doc`
3.  输出 `test/rendered-sample.html`

如果你要手工打开 demo：

```bash
npm run build
# 然后用任意静态服务器打开 demo/index.html
```

## 已知边界

MS-DOC 是历史包袱很重的二进制格式，虽然主链路已经完整重构，但以下场景仍建议用更多真实样本持续压测：

-   极端复杂的嵌套表格
-   非常规域代码组合
-   少见的 OLE 嵌入形式
-   某些兼容模式下的边角 sprm 变体
-   仅保存外部路径、未嵌入字节的链接图片（会给出占位提示，无法在离线环境加载本地盘路径）

这些场景并不影响当前的整体架构，后续继续扩展时可直接在现有 TS 类型体系上增量补强。

## 许可证

MIT

## 常见问题

### @file-viewer/doc 是什么？

浏览器-内生遗产 MS-DOC \(\.doc\) parser和 HTML 渲染器取自公共 msdoc-viewer 02\.0行\.

### 如何安装 @file-viewer/doc？

在项目目录运行 npm install @file-viewer/doc，或使用 pnpm add / yarn add / bun add。

### @file-viewer/doc 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @file-viewer/doc 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @file-viewer/doc 可以商用吗？

@file-viewer/doc 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @file-viewer/doc 的下载量有多少？

根据 npm 官方下载统计，@file-viewer/doc 在 2026/10/15 – 2026/11/13 这 30 天内被下载 248,116 次，日均约 8,271 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @file-viewer/doc 还在维护吗？

最新版本 3\.3\.3 发布于 2026/10/31（14 天前）；至今共发布 47 个版本，其中过去 12 个月发布了 47 个；首次发布于 2026/06/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。