html-to-word-js

v1.0.0

Published

9 months ago

一个将HTML转换为DOCX文档的TypeScript库，支持标题、段落、文本格式化、列表等常见HTML元素

0High
0Medium
0Low

heyuanjie

html docx converter document typescript html-to-docx word-document docx-generator browser

HTML to Word

一个功能强大的 HTML 到 Word 文档转换器，专为浏览器环境设计，支持丰富的样式和格式，能够将 HTML 内容准确转换为 DOCX 格式的 Word 文档。

✨ 主要特性

🌐 浏览器专用 - 专为浏览器环境设计，不支持 Node.js
📦 多格式支持 - 支持 IIFE、UMD 和 ES 模块格式
🎨 完整的样式支持 - 支持颜色、字体、大小、对齐、缩进等所有常用样式
📄 文档属性设置 - 支持设置创建者、标题、主题、关键词等文档元数据
🖼️ 图片处理 - 支持 base64、blob URL 和远程图片
📊 表格支持 - 完整的表格样式和格式化
🔗 超链接 - 支持可点击的超链接
📏 分割线 - 支持 HR 标签生成水平分割线
☑️ 复选框 - 支持 checkbox 标签生成复选框
📄 页眉页脚 - 支持自定义页眉页脚内容和样式
📝 字符间距 - 支持字符间距缩放功能
🎯 精确转换 - 保持原始 HTML 的样式和格式

🚀 快速开始

安装

从 NPM 安装

# 使用 npm
npm install html-to-word-js

# 使用 yarn
yarn add html-to-word-js

# 使用 pnpm
pnpm add html-to-word-js

注意：此库专为浏览器环境设计，不支持 Node.js 环境。

📖 使用方法

基本用法

ES 模块方式（推荐）

// 浏览器环境使用
import { convertHtmlToDocxBuffer } from 'html-to-word-js';

const html = `
  <h1 style="color: #2E86C1; font-size: 24pt;">文档标题</h1>
  <p style="color: #34495E; font-size: 14pt;">这是一个段落。</p>
`;

const result = await convertHtmlToDocxBuffer(html);
// result.buffer 包含 DOCX 文件数据 (Uint8Array)

IIFE 方式（浏览器直接使用）

<!DOCTYPE html>
<html>
<head>
    <title>HTML to Word 示例</title>
    <script src="https://unpkg.com/html-to-word-js@latest/dist/browser/index.js"></script>
</head>
<body>
    <button onclick="convertToWord()">转换为 Word</button>
    
    <script>
        async function convertToWord() {
            const html = `
                <h1 style="color: #2E86C1;">文档标题</h1>
                <p style="color: #34495E;">这是一个段落。</p>
            `;
            
            try {
                const result = await window.HtmlToWordConverter.convertHtmlToDocxBuffer(html);
                
                // 创建下载链接
                const blob = new Blob([result.buffer], {
                    type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
                });
                const url = window.URL.createObjectURL(blob);
                const a = document.createElement('a');
                a.href = url;
                a.download = 'document.docx';
                a.click();
                window.URL.revokeObjectURL(url);
            } catch (error) {
                console.error('转换失败:', error);
            }
        }
    </script>
</body>
</html>

UMD 方式

<!DOCTYPE html>
<html>
<head>
    <title>HTML to Word 示例</title>
    <script src="https://unpkg.com/html-to-word-js@latest/dist/umd/index.umd.js"></script>
</head>
<body>
    <button onclick="convertToWord()">转换为 Word</button>
    
    <script>
        async function convertToWord() {
            const html = `
                <h1 style="color: #2E86C1;">文档标题</h1>
                <p style="color: #34495E;">这是一个段落。</p>
            `;
            
            try {
                const result = await HtmlToWordConverter.convertHtmlToDocxBuffer(html);
                
                // 创建下载链接
                const blob = new Blob([result.buffer], {
                    type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
                });
                const url = window.URL.createObjectURL(blob);
                const a = document.createElement('a');
                a.href = url;
                a.download = 'document.docx';
                a.click();
                window.URL.revokeObjectURL(url);
            } catch (error) {
                console.error('转换失败:', error);
            }
        }
    </script>
</body>
</html>

高级用法

import { convertHtmlToDocxBuffer } from 'html-to-word-js';

const html = `
  <h1>我的文档</h1>
  <p>这是文档内容。</p>
`;

const options = {
  // 页面设置
  margins: {
    top: 2.54,    // 上边距 (厘米)
    right: 2.54,  // 右边距 (厘米)
    bottom: 2.54, // 下边距 (厘米)
    left: 2.54    // 左边距 (厘米)
  },
  // 图片设置
  maxImageWidth: 600,  // 图片最大宽度 (像素)
  maxImageHeight: 400, // 图片最大高度 (像素)
  // 文档属性
  properties: {
    creator: '张三',
    title: '我的文档标题',
    subject: '文档主题',
    description: '文档描述',
    keywords: '关键词1,关键词2',
    revision: 1,
    lastModifiedBy: '张三'
  }
};

const result = await convertHtmlToDocxBuffer(html, options);
// result.buffer 是 Uint8Array 类型，可直接用于下载

🎨 支持的 HTML 标签和样式

基础标签

| 标签 | 说明 | 样式支持 | |------|------|----------| | <h1> - <h6> | 标题 | 颜色、字体、大小、缩进 | | <p>, <div> | 段落 | 颜色、字体、大小、缩进、对齐 | | <strong>, <b> | 粗体 | 颜色、字体、大小 | | <em>, <i> | 斜体 | 颜色、字体、大小 | | <u> | 下划线 | 颜色、字体、大小 | | <span style="text-decoration: line-through"> | 中划线 | 颜色、字体、大小 | | <a> | 超链接 | 颜色、字体、大小 | | <ul>, <ol>, <li> | 列表 | 颜色、字体、大小、缩进 | | <small>, <big> | 字体大小 | 自动调整 | | <sub>, <sup> | 上下标 | 自动调整 | | <img> | 图片 | 尺寸、缩进 | | <table>, <tr>, <td>, <th> | 表格 | 完整样式支持，合并单元格 | | <br> | 换行 | - | | <hr> | 分割线 | 边框样式 | | <input type="checkbox"> | 复选框 | 选中状态、样式 |

样式属性

颜色和背景

<p style="color: #FF0000;">红色文字</p>
<p style="color: rgb(0, 255, 0);">绿色文字</p>
<p style="background-color: #FFFF00;">黄色背景</p>

字体样式

<p style="font-family: 'Arial'; font-size: 16pt; font-weight: bold;">
  粗体 Arial 字体，16pt 大小
</p>

#### 文本装饰
```html
<p style="text-decoration: underline;">下划线文字</p>
<p style="text-decoration: line-through;">中划线文字</p>
<p style="text-decoration: underline line-through;">下划线+中划线文字</p>

对齐和缩进

<p style="text-align: center;">居中对齐</p>
<p style="text-indent: 2em;">首行缩进</p>
<p style="margin-left: 20px;">左边距</p>

行高

<p style="line-height: 1.5;">1.5倍行距</p>
<p style="line-height: 24pt;">固定行距24磅</p>

边框

<p style="border: 1px solid red;">红色边框</p>
<p style="border: 2px dashed blue;">蓝色虚线边框</p>

🖼️ 图片支持

支持的格式

Base64 图片 - 完全支持
Blob URL - 完全支持
远程图片 - 完全支持

使用示例

<!-- Base64 图片 -->
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChAE/ycPkJQAAAABJRU5ErkJggg==" alt="图片" />

<!-- 远程图片 -->
<img src="https://example.com/image.jpg" alt="远程图片" />

<!-- Blob URL 图片 -->
<img src="blob:http://localhost:3000/abc123" alt="Blob图片" />

<!-- 带样式的图片 -->
<img src="data:image/png;base64,..." style="width: 300px; margin-left: 20px;" />

📊 表格支持

基本表格

<table style="border: 1px solid #333;">
  <thead>
    <tr>
      <th style="color: blue; text-align: center;">产品</th>
      <th style="color: red; text-align: center;">价格</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>笔记本</td>
      <td style="text-align: right;">¥8,999</td>
    </tr>
  </tbody>
</table>

合并单元格表格

<table border="1" style="width: 100%;">
  <thead>
    <tr>
      <th colspan="3" style="text-align: center; background-color: #4CAF50; color: white;">销售报表</th>
    </tr>
    <tr>
      <th>产品</th>
      <th>数量</th>
      <th>金额</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td rowspan="2" style="background-color: #f9f9f9;">笔记本电脑</td>
      <td>10</td>
      <td>¥89,990</td>
    </tr>
    <tr>
      <td>5</td>
      <td>¥44,995</td>
    </tr>
  </tbody>
  <tfoot>
    <tr>
      <td colspan="2" style="text-align: right; font-weight: bold;">总计:</td>
      <td style="font-weight: bold;">¥134,985</td>
    </tr>
  </tfoot>
</table>

表格样式

支持背景色、边框样式
支持单元格格式化
支持表头和表体
支持合并单元格（colspan、rowspan）
自动添加表格边框

🔗 超链接

<a href="https://example.com" style="color: blue; text-decoration: underline;">
  点击访问网站
</a>

📏 分割线 (HR 标签)

<!-- 基本分割线 -->
<hr>

<!-- 带样式的分割线 -->
<hr style="border: 2px solid red; margin: 20px 0;">

<!-- 带CSS类的分割线 -->
<style>
.custom-hr {
  border: 3px dashed blue;
  margin: 30px 0;
}
</style>
<hr class="custom-hr">

☑️ 复选框 (Checkbox)

<!-- 基本复选框 -->
<input type="checkbox" label="未选中的选项" />
<input type="checkbox" checked label="已选中的选项" />

<!-- 带样式的复选框 -->
<input type="checkbox" checked label="重要选项" style="color: red; font-weight: bold;" />

<!-- 问卷调查示例 -->
<p>请选择您喜欢的编程语言：</p>
<input type="checkbox" label="JavaScript" />
<input type="checkbox" checked label="TypeScript" />
<input type="checkbox" label="Python" />

<!-- 用户协议 -->
<input type="checkbox" checked label="我已阅读并同意用户协议" style="color: #E74C3C; font-weight: bold;" />

📄 页眉页脚 (Header & Footer)

const options = {
  header: {
    content: '<h3 style="color: #2E86C1;">公司名称</h3><p>文档标题</p>',
    style: {
      fontSize: 16,
      fontFamily: 'Arial',
      color: '2E86C1',
      alignment: 'center'
    }
  },
  footer: {
    content: '<p style="text-align: center;">第 <strong>1</strong> 页</p>',
    style: {
      fontSize: 14,
      fontFamily: 'Arial',
      color: '666666',
      alignment: 'center'
    }
  }
};

页眉页脚功能特点

HTML内容支持: 支持完整的HTML格式，包括段落、标题、样式等
样式自定义: 支持字体大小、字体名称、颜色、对齐方式等
文本样式: 支持粗体、斜体、下划线等文本样式
标签支持: 支持 p、div、span、h1-h6、strong、em、u 等标签
样式优先级: HTML内联样式优先于配置中的样式设置
应用场景: 公司文档、报告、合同等需要统一页眉页脚的文档

样式优先级说明

页眉页脚支持样式优先级处理，确保灵活性和精确控制：

1. HTML内联样式优先

<!-- 这个段落会保持右对齐，忽略配置中的对齐设置 -->
<p style="text-align: right;">右对齐的页眉</p>

<!-- 这个段落会使用配置中的对齐设置 -->
<p>使用配置对齐的页眉</p>

2. 配置样式补充

const options = {
  header: {
    content: `
      <p style="text-align: center;">居中对齐（HTML样式优先）</p>
      <p>左对齐（使用配置样式）</p>
      <h3>标题（使用配置样式）</h3>
    `,
    style: {
      alignment: 'left' // 只应用到没有text-align的元素
    }
  }
};

3. 混合使用示例

const options = {
  header: {
    content: `
      <h3 style="text-align: center;">公司名称（居中）</h3>
      <p>文档标题（使用配置对齐）</p>
      <p style="text-align: right;">日期：2024-01-01（右对齐）</p>
    `,
    style: {
      fontSize: 16,
      alignment: 'left' // 只应用到没有text-align的元素
    }
  }
};

📝 中划线功能

支持 text-decoration: line-through 样式，可以创建中划线文字：

<!-- 基本中划线 -->
<p style="text-decoration: line-through;">中划线文字</p>

<!-- 带颜色的中划线 -->
<p style="text-decoration: line-through; color: red;">红色中划线文字</p>

<!-- 组合样式 -->
<p style="text-decoration: line-through; font-weight: bold; color: blue;">蓝色粗体中划线</p>

<!-- 部分文字中划线 -->
<p>正常文字 <span style="text-decoration: line-through;">中划线部分</span> 正常文字</p>

<!-- 下划线+中划线组合 -->
<p style="text-decoration: underline line-through;">下划线+中划线文字</p>

中划线功能特点

✅ 支持完整段落中划线
✅ 支持部分文字中划线
✅ 支持与其他样式组合（粗体、斜体、颜色等）
✅ 支持与下划线同时使用
✅ 支持在表格、列表等元素中使用

📝 字符间距缩放

使用 data-scale 属性调整字符间距，等同于 CSS 样式 transform: scaleX 和 transform-origin: left：

<!-- 使用 data-scale 属性 -->
<p>
  正常间距文字 
  <span data-scale="55" style="color: red;">55%间距缩放</span> 
  <span data-scale="120" style="color: blue;">120%间距缩放</span>
</p>

<!-- 等价的 CSS 样式 -->
<p>
  正常间距文字 
  <span style="transform: scaleX(0.55); transform-origin: left; color: red;">55%间距缩放</span> 
  <span style="transform: scaleX(1.2); transform-origin: left; color: blue;">120%间距缩放</span>
</p>

字符间距缩放特点

✅ data-scale="55" 等同于 transform: scaleX(0.55); transform-origin: left
✅ data-scale="120" 等同于 transform: scaleX(1.2); transform-origin: left
✅ 保持字体大小不变，仅调整字符之间的间距
✅ 支持任意正数百分比值
✅ 可以与所有其他样式组合使用
✅ 在 DOCX 中转换为字符间距缩放效果

📄 文档属性设置

支持的属性

creator - 创建者
title - 文档标题
subject - 文档主题
description - 文档描述
keywords - 关键词 (用逗号分隔)
revision - 修订版本 (数字)
lastModifiedBy - 最后修改者

使用示例

const options = {
  properties: {
    creator: '张三',
    title: '项目报告',
    subject: '季度总结',
    description: '2024年第一季度项目进展报告',
    keywords: '项目,报告,总结',
    revision: 1,
    lastModifiedBy: '张三'
  }
};

🌐 环境支持

浏览器环境 ✅

✅ 支持所有图片格式 (base64, blob URL, 远程图片)
✅ 支持所有样式功能
✅ 支持实时转换
✅ 支持完整的 HTML 到 DOCX 转换功能

Node.js 环境 ❌

❌ 不支持 Node.js 环境
❌ 无法处理 blob URL 和远程图片
❌ 缺少浏览器特定的 API 支持

注意：此库专为浏览器环境设计，不支持在 Node.js 中运行。

🔧 配置选项

HtmlToWordOptions 接口

interface HtmlToWordOptions {
  // 页面方向
  orientation?: 'portrait' | 'landscape';
  
  // 页边距 (厘米)
  margins?: {
    top?: number;
    right?: number;
    bottom?: number;
    left?: number;
  };
  
  // 图片最大尺寸 (像素)
  maxImageWidth?: number;
  maxImageHeight?: number;
  
  // 文档属性
  properties?: {
    creator?: string;
    description?: string;
    title?: string;
    subject?: string;
    keywords?: string;
    revision?: number;
    lastModifiedBy?: string;
  };
  // 页眉设置
  header?: {
    content?: string; // 页眉内容 (HTML字符串)
    style?: {
      fontSize?: number; // 字体大小 (半点)
      fontFamily?: string; // 字体名称
      color?: string; // 字体颜色 (hex)
      bold?: boolean; // 是否粗体
      italic?: boolean; // 是否斜体
      alignment?: 'left' | 'center' | 'right'; // 文本对齐方式
    };
  };
  // 页脚设置
  footer?: {
    content?: string; // 页脚内容 (HTML字符串)
    style?: {
      fontSize?: number; // 字体大小 (半点)
      fontFamily?: string; // 字体名称
      color?: string; // 字体颜色 (hex)
      bold?: boolean; // 是否粗体
      italic?: boolean; // 是否斜体
      alignment?: 'left' | 'center' | 'right'; // 文本对齐方式
    };
  };
}

📦 API 参考

convertHtmlToDocxBuffer

function convertHtmlToDocxBuffer(
  html: string,
  options?: HtmlToWordOptions
): Promise<{
  buffer: Uint8Array;  // 浏览器环境返回 Uint8Array
  warnings: string[];
}>

htmlToDocx

function htmlToDocx(
  html: string,
  options?: HtmlToDocxOptions
): Promise<{
  document: Document;
  warnings: string[];
}>

docxToBuffer

function docxToBuffer(
  document: Document
): Promise<Uint8Array>  // 浏览器环境返回 Uint8Array

📝 注意事项

环境要求: 此库仅支持浏览器环境，不支持 Node.js
图片处理: 支持 base64、blob URL 和远程图片格式
样式继承: 支持 CSS 样式继承和优先级
错误处理: 转换过程中会收集警告信息
性能: 大文档转换可能需要较长时间
兼容性: 生成的 DOCX 文件兼容 Microsoft Word、WPS 等
CDN 使用: 可以通过 unpkg 或 jsDelivr 等 CDN 直接使用

🚀 快速开始示例

最简单的使用方式

<!DOCTYPE html>
<html>
<head>
    <title>HTML to Word 快速开始</title>
    <script src="https://unpkg.com/html-to-word-js@latest/dist/browser/index.js"></script>
</head>
<body>
    <h1>HTML to Word 转换器</h1>
    <textarea id="htmlInput" rows="10" cols="50">
        <h1 style="color: #2E86C1;">我的文档</h1>
        <p style="color: #34495E;">这是一个段落。</p>
        <ul>
            <li>列表项 1</li>
            <li>列表项 2</li>
        </ul>
    </textarea>
    <br>
    <button onclick="convert()">转换为 Word 文档</button>
    
    <script>
        async function convert() {
            const html = document.getElementById('htmlInput').value;
            
            try {
                const result = await window.HtmlToWordConverter.convertHtmlToDocxBuffer(html);
                
                // 下载文件
                const blob = new Blob([result.buffer], {
                    type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
                });
                const url = window.URL.createObjectURL(blob);
                const a = document.createElement('a');
                a.href = url;
                a.download = '我的文档.docx';
                a.click();
                window.URL.revokeObjectURL(url);
                
                console.log('转换成功！');
                if (result.warnings.length > 0) {
                    console.log('警告信息:', result.warnings);
                }
            } catch (error) {
                console.error('转换失败:', error);
            }
        }
    </script>
</body>
</html>

在 React 项目中使用

import React, { useState } from 'react';
import { convertHtmlToDocxBuffer } from 'html-to-word-js';

function WordConverter() {
  const [html, setHtml] = useState('');
  const [loading, setLoading] = useState(false);

  const handleConvert = async () => {
    if (!html.trim()) {
      alert('请输入HTML内容');
      return;
    }

    setLoading(true);
    try {
      const result = await convertHtmlToDocxBuffer(html);
      
      // 下载文件
      const blob = new Blob([result.buffer], {
        type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
      });
      const url = window.URL.createObjectURL(blob);
      const a = document.createElement('a');
      a.href = url;
      a.download = '文档.docx';
      a.click();
      window.URL.revokeObjectURL(url);
      
      if (result.warnings.length > 0) {
        console.log('警告信息:', result.warnings);
      }
    } catch (error) {
      console.error('转换失败:', error);
      alert('转换失败，请检查控制台');
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <textarea
        value={html}
        onChange={(e) => setHtml(e.target.value)}
        placeholder="请输入HTML内容..."
        rows={10}
        cols={50}
      />
      <br />
      <button onClick={handleConvert} disabled={loading}>
        {loading ? '转换中...' : '转换为Word'}
      </button>
    </div>
  );
}

export default WordConverter;

在 Vue 项目中使用

<template>
  <div>
    <textarea
      v-model="html"
      placeholder="请输入HTML内容..."
      rows="10"
      cols="50"
    ></textarea>
    <br />
    <button @click="convertToWord" :disabled="loading">
      {{ loading ? '转换中...' : '转换为Word' }}
    </button>
  </div>
</template>

<script>
import { convertHtmlToDocxBuffer } from 'html-to-word-js';

export default {
  data() {
    return {
      html: '',
      loading: false
    };
  },
  methods: {
    async convertToWord() {
      if (!this.html.trim()) {
        alert('请输入HTML内容');
        return;
      }

      this.loading = true;
      try {
        const result = await convertHtmlToDocxBuffer(this.html);
        
        // 下载文件
        const blob = new Blob([result.buffer], {
          type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
        });
        const url = window.URL.createObjectURL(blob);
        const a = document.createElement('a');
        a.href = url;
        a.download = '文档.docx';
        a.click();
        window.URL.revokeObjectURL(url);
        
        if (result.warnings.length > 0) {
          console.log('警告信息:', result.warnings);
        }
      } catch (error) {
        console.error('转换失败:', error);
        alert('转换失败，请检查控制台');
      } finally {
        this.loading = false;
      }
    }
  }
};
</script>

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

HTML to Word

✨ 主要特性

🚀 快速开始

安装

从 NPM 安装

📖 使用方法

基本用法

ES 模块方式（推荐）

IIFE 方式（浏览器直接使用）

UMD 方式

高级用法

🎨 支持的 HTML 标签和样式

基础标签

样式属性

颜色和背景

字体样式

对齐和缩进

行高

边框

🖼️ 图片支持

支持的格式

使用示例

📊 表格支持

基本表格

合并单元格表格

表格样式

🔗 超链接

📏 分割线 (HR 标签)

☑️ 复选框 (Checkbox)

📄 页眉页脚 (Header & Footer)

页眉页脚功能特点

样式优先级说明

1. HTML内联样式优先

2. 配置样式补充

3. 混合使用示例

📝 中划线功能

中划线功能特点

📝 字符间距缩放

字符间距缩放特点

📄 文档属性设置

支持的属性

使用示例

🌐 环境支持

浏览器环境 ✅

Node.js 环境 ❌

🔧 配置选项

HtmlToWordOptions 接口

📦 API 参考

convertHtmlToDocxBuffer

htmlToDocx

docxToBuffer

📝 注意事项

🚀 快速开始示例

最简单的使用方式

在 React 项目中使用

在 Vue 项目中使用

🤝 贡献

📄 许可证

🔗 相关链接