程式碼區塊（Code Block）

使用等寬字型呈現原始碼，支援可選行號與 highlight.js 語法高亮。

匯入

import { codeBlockPlugin, type CodeBlockOptions } from 'docx-kit'

選項

選項	型別	預設值	說明
code	string	必填	原始碼字串
language	string	—	語法高亮語言標識符，需要 highlight.js
showLineNumbers	boolean	false	在每行前顯示行號

範例

基本程式碼區塊

import { createDocx, codeBlockPlugin } from 'docx-kit/node'

const doc = createDocx()
  .use(codeBlockPlugin())
  .h1('Code Example')
  .plugin('codeBlock', {
    code: `function hello(name: string): string {
  return \`Hello, \${name}!\`
}

console.log(hello('World'))`,
    language: 'typescript',
  })
  .save('code.docx')

顯示行號

const doc = createDocx()
  .use(codeBlockPlugin())
  .h1('Algorithm')
  .plugin('codeBlock', {
    code: `def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

for i in range(10):
    print(fibonacci(i))`,
    language: 'python',
    showLineNumbers: true,
  })
  .save('code-lines.docx')

純文字（無高亮）

const doc = createDocx()
  .use(codeBlockPlugin())
  .h1('Configuration')
  .plugin('codeBlock', {
    code: `# Server Configuration
host = 0.0.0.0
port = 8080
max_connections = 1000
timeout = 30s`,
  })
  .save('plain-code.docx')

多個程式碼區塊

const doc = createDocx()
  .use(codeBlockPlugin())
  .h1('API Examples')

  .h2('JavaScript')
  .plugin('codeBlock', {
    code: `const response = await fetch('/api/users')
const users = await response.json()
console.log(users.length)`,
    language: 'javascript',
    showLineNumbers: true,
  })

  .h2('TypeScript')
  .plugin('codeBlock', {
    code: `interface User {
  id: number
  name: string
  email: string
}

async function getUsers(): Promise<User[]> {
  const res = await fetch('/api/users')
  return res.json()
}`,
    language: 'typescript',
    showLineNumbers: true,
  })

  .save('api-examples.docx')

語法高亮相依

安裝 highlight.js 啟用語法高亮：

pnpm add highlight.js

未安裝時，程式碼仍使用等寬字型，但不顯示語法顏色。

樣式自訂

工廠的 { styles } 設定實例預設值，options.styles 覆寫單次呼叫。外掛套件與 docx-kit 入口匯出 CodeBlockConfig 和 CodeBlockStyles。優先順序：內建/主題預設值 → 初始化 styles → 通用 style → 單次部位 styles。巢狀欄位合併，陣列整體替換，undefined 沿用預設，0 / false 生效；支援單位與 $colors.primary 等主題 token。

部位	樣式型別	範圍
code, lineNumber	TextStyleRule	文字排版
paragraph	ParagraphStyleRule	段落背景、框線、對齊、間距及分頁

code 同時作用於一般文字與醒目提示 token；明確指定的色彩會覆寫語法配色。整列背景使用 paragraph.backgroundColor。

codeBlockPlugin({
  styles: { code: { color: '#2563EB', fontSize: 14 } },
})

單次呼叫在 options.styles 中使用相同部位名稱。JSON DSL、AI 工具 schema 與 MCP 驗證共用這些契約；未知部位與放錯部位的屬性會被拒絕。