Package Exports

doc2hx

Readme

Doc2HX

HTML 与 Word 双向转换器。支持标题、段落、列表、表格、图片、超链接、上标下标、加粗/斜体/下划线/删除线/高亮等格式，以及节点级样式自定义。

快速开始

npm install doc2hx

import { exportToWord } from 'doc2hx'

exportToWord(document.querySelector('#content'), {
  fileName: 'export.docx',
  default: {
    fontFamily: 'Microsoft YaHei',
    fontSize: '14pt',
    lineHeight: 1.5,
    nodes: {
      h1: { fontSize: '18pt', textAlign: 'center', fontWeight: 'bold' },
      h2: { fontSize: '16pt', fontWeight: 'bold' },
      p:  { fontSize: '14pt', textIndent: '2em', lineHeight: 1.5 }
    }
  }
})

API

`exportToWord(elementList, config)`

参数	类型	必填	说明
`elementList`	`Element \| Element[]`	是	要导出的 DOM 元素，支持单元素或多元素数组
`config.fileName`	`string`	否	导出文件名，默认 `'export.docx'`
`config.exclude`	`string[]`	否	排除选择器数组，匹配的元素及其子元素不导出
`config.quoteSelector`	`string`	否	参考文献根选择器，默认 `'#quoteList'`
`config.default`	`DefaultStyles`	否	样式配置，见下方配置属性

// 多元素导出
exportToWord([el1, el2], { fileName: 'combined.docx' })

// 排除引用块和侧边栏
exportToWord(el, {
  exclude: ['blockquote', '.sidebar', '#footer']
})

`doc2Html(file, options)`

参数	类型	说明
`file`	`File \| Blob`	Word 文件
`options.convertImage`	`{ getSrc(file) => Promise<string> }`	图片上传回调
`options.styleMaps`	`string[]`	mammoth 样式映射规则

import { doc2Html } from 'doc2hx'

const fragment = await doc2Html(file, {
  convertImage: {
    getSrc: async (imageFile) => {
      // 上传图片到服务器，返回 URL
      return '/api/images/xxx.png'
    }
  }
})
document.body.appendChild(fragment)

配置属性

全局配置

在 default 顶层设置，作为所有节点的兜底样式。

属性	类型	默认值	示例
`fontFamily`	`string`	`'Microsoft YaHei'`	`'SimSun'`、`'SimHei'`、`'Arial'`
`fontSize`	`string`	`'14pt'`	`'12pt'`、`'16px'`、`'2em'`
`lineHeight`	`number`	`1.5`	`1.0`、`2.0`
`textIndent`	`string`	`'0px'`	`'2em'`、`'48px'`、`'1cm'`
`color`	`string`	`'#000000'`	`'red'`、`'#333'`、`'rgb(255,0,0)'`
`fontWeight`	`string \| number`	—	`'bold'`、`700`、`'normal'`
`fontStyle`	`string`	—	`'italic'`、`'normal'`
`textDecoration`	`string`	—	`'underline'`、`'line-through'`、`'none'`
`textAlign`	`string`	—	`'left'`、`'center'`、`'right'`、`'justify'`
`backgroundColor`	`string`	—	`'#ffff00'`、`'yellow'`

节点级配置 (`nodes`)

nodes 的 key 是标签名，value 是该标签的样式对象。支持的属性与全局配置完全一致。

nodes: {
  h1: { fontSize: '22pt', textAlign: 'center', fontWeight: 'bold', color: '#cc0000' },
  h2: { fontSize: '16pt', fontWeight: 'bold' },
  p:  { fontSize: '14pt', textIndent: '2em', lineHeight: 1.5 },
  li: { fontSize: '14pt' },
  th: { fontFamily: 'SimHei', backgroundColor: '#e6e6e6', fontWeight: 'bold' },
  td: { fontSize: '12pt' },
  a:  { color: '#0066cc' },
  mark: { backgroundColor: '#ffcc99' }
}

支持的标签名

块级：h1 h2 h3 h4 h5 h6 p div table th td ul ol li
内联：span strong b em i u s strike del mark sup sub a br img

样式优先级

最终样式按以下 6 级优先级 从高到低计算：

1. 元素内联 style 属性
2. 用户 nodes[tag] 配置
3. 用户全局 default 配置
4. 库默认节点配置
5. CSS 类 computedStyle
6. 库全局默认配置

<!-- 内联永远最高：即使 nodes.h1.fontSize='18pt'，这里仍用 48px -->
<h1 style="font-size: 48px">大标题</h1>

单位换算

字号 → docx 半磅

单位	换算	示例
`pt`	`× 2`	`14pt` → `28`
`px`	`÷ 1.333 × 2`	`48px` → `72`

缩进 → twip

单位	换算	示例
`pt`	`× 20`	`120pt` → `2400`
`em`	`× fontSizePt × 20`	`2em`(14pt) → `560`
`px`	`÷ 96 × 1440`	`48px` → `720`
`cm`	`÷ 2.54 × 1440`	`1cm` → `566`

行距 → docx 行距值

倍数	结果
`1.0`	`240`
`1.5`	`360`
`2.0`	`480`

颜色

支持 hex、rgb/rgba、140+ CSS 命名颜色。所有颜色最终转为 6 位 hex 传入 docx。

常用命名色：red green blue yellow pink orange purple brown gold silver gray white black cyan magenta 等。

color: 'red'           // → ff0000
color: '#cc0000'       // → cc0000
color: 'rgb(255,0,0)'  // → ff0000

库默认值

未配置时的内置默认值：

标签	fontSize	textAlign	fontWeight
`h1`	`16pt`	`center`	`bold`
`h2`	`14pt`	—	`bold`
`h3`~`h6`	`12pt`	—	`bold`

全局默认：fontFamily: 'Microsoft YaHei'，fontSize: '14pt'，lineHeight: 1.5，color: '#000000'

特殊功能

参考文献

id="quoteList" 的容器自动识别为参考文献区域，内部 h2 强制居中，p 段间距为 0。

<div id="quoteList">
  <h2>参考文献</h2>
  <p>[1] 张三. 某研究[J]. 2024.</p>
</div>

排除元素

exportToWord(el, {
  exclude: ['blockquote', '.no-export', '#sidebar']
})

章节列表编号重置

不同 h1~`h6或带id` 的容器之间的有序列表独立编号，每个章节从 1 开始。

类型定义

import type { DefaultStyles, NodeStyle } from 'doc2hx'

interface NodeStyle {
  fontSize?: string;
  fontFamily?: string;
  color?: string;
  fontWeight?: string | number;
  fontStyle?: string;
  textDecoration?: string;
  textAlign?: 'left' | 'center' | 'right' | 'justify';
  lineHeight?: number;
  textIndent?: string;
  backgroundColor?: string;
}

interface DefaultStyles extends NodeStyle {
  nodes?: Record<string, NodeStyle>;
}

构建产物

npm run build 生成：

文件	格式	用途
`doc2hx.es.js`	ESM	现代浏览器 / bundler
`doc2hx.umd.js`	UMD	传统浏览器 `window.Doc2Hx`
`index.d.ts`	TypeScript	类型声明

浏览器兼容性

Chrome 60+ · Firefox 60+ · Safari 12+ · Edge 79+

依赖 window.getComputedStyle，需在浏览器环境运行。

许可证

MIT

doc2hx