外掛

外掛是 docx-kit 的主要擴充機制，無需修改核心編譯器即可添加新節點型別，同時保留統一的建置流程與型別安全的選項物件。

工作方式

每個內建或自訂外掛都遵循相同生命週期：

匯入外掛工廠函式或外掛實例。
使用 .use(...) 註冊。
使用 .plugin(name, options) 呼叫。

import { calloutPlugin, createDocx } from 'docx-kit'

const doc = createDocx()
  .use(calloutPlugin())
  .plugin('callout', {
    type: 'success',
    title: 'Published',
    content: 'The release notes were exported successfully.',
  })

內建外掛範圍

目前工作區包含 25 個內建外掛：

參照與術語: crossReference, bibliography, glossary
內容區塊：badge、callout、checklist、codeBlock、divider、watermark
報告結構：coverPage、letterhead、toc、pageNumber
結構化業務資料：dataTable、metricCard、propertyTable、timeline、invoice、meetingMinutes、changelog
媒體與嵌入：barcode、echarts、figure、qrcode
審批流程：signatureBlock

完整參考見外掛章節。

包結構

每個內建外掛都在 packages-plugins/ 下作為獨立套件發佈：

text

packages-plugins/
  cross-reference/
  bibliography/
  glossary/
  badge/
  barcode/
  callout/
  changelog/
  checklist/
  code-block/
  cover-page/
  data-table/
  divider/
  echarts/
  figure/
  invoice/
  letterhead/
  meeting-minutes/
  metric-card/
  page-number/
  property-table/
  qrcode/
  signature-block/
  timeline/
  toc/
  watermark/

這樣可以獨立維護外掛的發佈、測試、同儕相依套件與文件。

同儕相依套件

部分外掛將體積較大的執行階段相依設為可選：

外掛	可選原因
`@docxkit/plugin-barcode`	僅產生條碼圖片時需要 `bwip-js`
`@docxkit/plugin-code-block`	僅語法著色時需要 `highlight.js`
`@docxkit/plugin-echarts`	僅使用圖表呈現時需要 `echarts`
`@docxkit/plugin-qrcode`	僅產生二維碼圖片時需要 `qrcode`

缺少可選同儕相依套件時，外掛會優雅降級，或拋出帶有解決建議的執行階段錯誤。

自訂外掛

需要業務或文件流程專屬節點型別時，使用 definePlugin()。

import { definePlugin } from 'docx-kit'
import { Paragraph } from 'docx'

interface DisclaimerOptions {
  text: string
}

const disclaimerPlugin = definePlugin<'disclaimer', DisclaimerOptions>({
  name: 'disclaimer',
  render(options) {
    return new Paragraph(options.text)
  },
})

好的自訂外掛應當：

接收小而明確的選項物件
回傳常規 docx 節點或節點陣列
在呈現函式附近完成驗證
避免隱藏無關的文件修改

文件外掛必須回傳 Paragraph、Table、TableOfContents 等 docx FileChild 區塊物件，或一維區塊物件陣列（允許空陣列）。DSL 節點需透過 await context.compileNode(node) 轉換。字串、行內 run、null 與巢狀陣列會在編譯階段產生 PLUGIN_RENDER_FAILED。

外掛配套工具

@docxkit/create-plugin：建立外掛套件鷹架
@docxkit/pdk：外掛測試輔助工具
@docxkit/loader：從 inline、npm、URL 或本地來源載入外掛
@docxkit/registry：發現帶 docx-kit 關鍵字的外掛
@docxkit/mcp：向 AI Agent 提供支援外掛的文件產生工具

各部分所在位置見 Monorepo 結構與套件總覽。

外掛 ​

工作方式 ​

內建外掛範圍 ​

包結構 ​

同儕相依套件 ​

自訂外掛 ​

外掛配套工具 ​

外掛

工作方式

內建外掛範圍

包結構

同儕相依套件

自訂外掛

外掛配套工具