html-docx-js 浏览器端HTML转DOCX转换库详解

项目概述

html-docx-js 是一个轻量级的JavaScript库，专门用于在浏览器中将HTML文档转换为DOCX格式。该库利用了Microsoft Word的"altchunks"功能，通过嵌入MHT文档来实现在浏览器中的格式转换。

项目结构

html-docx-js 项目采用简洁的目录结构：

html-docx-js/
├── src/                    # 源代码目录
│   ├── api.coffee         # 主要API接口
│   ├── internal.coffee    # 内部处理逻辑
│   ├── utils.coffee       # 工具函数
│   ├── assets/            # 静态资源文件
│   │   ├── content_types.xml
│   │   ├── document.xml.rels
│   │   └── rels.xml
│   └── templates/         # 模板文件
│       ├── document.tpl
│       ├── mht_document.tpl
│       └── mht_part.tpl
├── test/                  # 测试文件
│   ├── index.coffee
│   ├── sample.html
│   ├── testbed.html
│   └── cat.jpg
├── CHANGELOG.md          # 更新日志
├── LICENSE              # MIT许可证
├── README.md           # 项目说明
├── package.json        # npm配置文件
├── bower.json         # bower配置文件
├── gulpfile.coffee    # Gulp构建脚本
└── coffeelint.json    # CoffeeScript代码检查配置

核心功能实现

API模块 (src/api.coffee)

API模块提供了主要的转换接口：

module.exports =
  asBlob: (html, options) ->
    zip = new JSZip()
    internal.addFiles(zip, html, options)
    internal.generateDocument(zip)

内部处理模块 (src/internal.coffee)

内部处理模块负责文档的生成和文件添加：

module.exports =
  generateDocument: (zip) ->
    # 生成Blob或Buffer格式的文档
    # 处理浏览器和Node.js环境的差异
  
  renderDocumentFile: (documentOptions = {}) ->
    # 渲染文档模板，处理页面设置选项
  
  addFiles: (zip, htmlSource, documentOptions) ->
    # 向ZIP压缩包中添加必要的文件

使用方式

基本用法

var converted = htmlDocx.asBlob(htmlContent);
saveAs(converted, 'document.docx');

高级选项配置

var options = {
  orientation: 'landscape',
  margins: {
    top: 720,      // 2.54厘米
    right: 1440,   // 5.08厘米
    bottom: 1440,
    left: 1440,
    header: 720,
    footer: 720,
    gutter: 0
  }
};

var converted = htmlDocx.asBlob(htmlContent, options);
saveAs(converted, 'customized.docx');

技术特点

跨平台兼容性

• 支持现代浏览器（Chrome、Safari、IE10+）
• 支持Node.js环境
• 自动检测环境并使用Blob或Buffer

图像支持

仅支持base64内联图像，但提供转换示例：

function convertImagesToBase64() {
  // 将外部图像转换为base64格式
}

页面设置选项

支持完整的页面布局配置：

• 页面方向（横向/纵向）
• 各边距设置（上、下、左、右、页眉、页脚、装订线）

构建和测试

项目使用Gulp作为构建工具，支持以下命令：

# 运行测试
npm test

# 构建项目
gulp build-node

# 清理构建文件
gulp clean

注意事项

1. HTML要求：必须传入完整的HTML文档，包含DOCTYPE、html和body标签
2. 浏览器限制：Safari需要额外的Flash支持才能正常保存文件
3. 格式限制：某些Office软件可能不支持altchunks功能

示例文件

项目提供了完整的示例文件 test/sample.html，展示了如何：

• 转换HTML为DOCX
• 处理图像转换
• 使用页面设置选项

html-docx-js为Web应用提供了简单可靠的HTML到DOCX转换解决方案，特别适合需要导出Word文档的在线编辑器应用场景。