发布 BX-WORD：BoxLang 原生 Microsoft Word 自动化模块

[LOADING...]

每家企业都依赖 Word 文档运行。合同、投标邀请书、方案书、董事会报告、录用通知书、HR 手册、合规政策、发票、工作说明书、法律备忘录。今天，我们非常自豪地宣布 bx-word 1.0.0 正式发布：这是一个一流的、流畅的、可用于生产环境的模块，用于在 BoxLang 中原生创建、填充和转换 Microsoft Word 文档。它不是包装器，不是转换器，而是真正为企业团队实际工作方式设计的文档构建器。

为什么这对企业很重要

文档生成是大型组织中最隐蔽的瓶颈之一。销售团队要等法务快速起草合同，HR 等待运营生成录用通知书，财务手工排版季度报告。这些工作流都可以自动化，但前提是所使用的工具必须可信、可脚本化，并且达到企业级标准。

以下是 bx-word 的一些使用场景：

在几秒内从数据库批量生成数千份个性化合同
按计划输出带有品牌标识、符合合规要求的季度报告
接收客户提交的 Word 文档，进行转换，再重新输出用于归档
生成带密码保护的董事会文件包，包含水印和自动生成的目录
构建转换管道，在 Word、HTML、Markdown 和纯文本之间桥接，用于归档、索引和版本控制

如果你的组织任何规模地使用 Word，很可能一直在为维持它运转而支付一笔隐性成本。bx-word 的目标就是让这笔成本消失。

`word()` BIF：唯一入口

一切都通过一个 BIF 流转：word()。它返回一个支持流畅方法链的 WordDocument 构建器，并且可以通过一次调用以多种方式创建文档。

// A brand new empty document
doc = word()

// Open an existing .docx to modify
doc = word( "/path/to/existing.docx" )

// Create directly from text, Markdown, or HTML
doc = word( text = "Hello World\n\nParagraph two" )
doc = word( markdown = "## Title\n\n**bold** text" )
doc = word( html = "<h1>Title</h1><p>Content</p>" )

这就是全部心智模型。从这里开始，每个方法都会返回构建器，因此你可以无限链式调用。

三行代码创建你的第一个文档

word( "hello.docx" )
    .addHeading( "Hello, BoxLang!", 1 )
    .addParagraph( "This is my first Word document created with BoxLang." )
    .save()

三行代码。生成真实的 .docx 文件。可以干净地在 Word、Google Docs 或 LibreOffice 中打开。

构建积木

这套流畅 API 覆盖了真实商业文档所需的所有能力。

标题和格式化段落

word()
    .addHeading( "Q4 Financial Report", 1 )
    .addHeading( "Executive Summary", 2 )
    .addParagraph( "This quarter exceeded projections by 18%." )
    .addParagraph( "Key highlights below.", {
        bold      : true,
        size      : 12,
        color     : "2C3E50",
        alignment : "CENTER",
        spacingAfter : 240
    } )
    .save( "report.docx" )

从数组、查询或结构体生成表格

表格是企业最常见的需求之一，bx-word 支持三种数据结构，并会自动对表头加粗。

// From a 2D array
word().addTable( [
    [ "Product", "Price", "Stock" ],
    [ "Widget A", "$10.00", "150" ],
    [ "Widget B", "$15.00", "200" ]
] )

// From a query (column names become bold headers)
products = queryExecute( "SELECT name, price, stock FROM products" )
word().addTable( products )

// From a struct with explicit headers
word().addTable( {
    headers : [ "Month", "Revenue", "Expenses" ],
    data    : [
        [ "January", "$50,000", "$30,000" ],
        [ "February", "$55,000", "$32,000" ]
    ]
} )

嵌套列表

word().addUnorderedList( [
    "Fruits",
    { text : "Vegetables", items : [ "Carrots", "Broccoli", "Spinach" ] },
    "Grains"
] )

嵌套深度按需无限。

来自任何位置的图片

文件、字节、Base64、远程 URL。全都是一等公民。

word()
    .addImage( "/assets/logo.png", 5.0, 3.0 )
    .addImageFromUrl( "https://cdn.example.com/hero.jpg", 18.0, 5.0 )
    .addImageBase64( chartBase64, "chart.png" )
    .save( "brochure.docx" )

页面设置、页眉、页脚、超链接

word()
    .margins( 1.78, 1.78, 1.78, 1.78 )
    .pageSize( "A4" )
    .orientation( "landscape" )
    .header( "ACME Corp Confidential" )
    .footer( "Q4 2026 Report" )
    .addHyperlink( "Visit BoxLang", "https://boxlang.io" )
    .save( "formatted.docx" )

模板批量填充

这个功能一周就能回本。

取出一个由法务、HR 或市场团队设计好的、带有 {{placeholder}} 标记的现有 Word 模板，然后从任何数据源以编程方式填充。

word( "/templates/contract-template.docx" )
    .populate( {
        clientName    : "Acme Corp",
        signDate      : "2026-06-15",
        contractValue : "$150,000"
    } )
    .save( "/output/contract_acme.docx" )

从数据库进行批量生成变得非常简单：

employees = queryExecute( "SELECT name, department, start_date, salary FROM new_hires" )

for( row in employees ){
    word( "/templates/offer-letter.docx" )
        .populate( {
            employeeName : row.name,
            department   : row.department,
            startDate    : dateTimeFormat( row.start_date, "yyyy-mm-dd" ),
            salary       : dollarFormat( row.salary )
        } )
        .save( "/output/offers/offer_#row.name#.docx" )
}

这个循环可以根据数据库中的数据，生成任意数量的个性化、符合品牌形象的录用通知书。HR 可以在几秒内完成整批新员工的录用流程，而不是几小时。

除了 populate()，你还可以使用字面量 replaceText() 来处理旧模板，以及使用 setBookmark() 处理命名区域。

多格式桥梁

文档很少只存在于一种格式。客户从网页表单提交 HTML，编辑人员使用 Markdown，搜索索引需要纯文本，归档需要 Word。

bx-word 在它们之间搭建了桥梁。

// Receive HTML from a web form
submittedHtml = form.content

// Convert to Word for the archive
doc = word()
    .setTitle( form.title )
    .setAuthor( form.author )
    .fromHTML( submittedHtml )

doc.save( "/archive/#form.title#.docx" )

// Also emit Markdown for version control
fileWrite( "/archive/#form.title#.md", doc.toMarkdown() )

// And plain text for the search index
searchService.index( form.title, doc.toText() )

doc.close()

一个文档，四种呈现形式，零外部服务。

企业级功能

当法务或合规团队在旁监督时，这些功能至关重要。

水印

草稿或机密文档的每一页都会自动打上标记。

word()
    .addHeading( "Q4 Financial Report", 1 )
    .addParagraph( "Sensitive data." )
    .addWatermark( "CONFIDENTIAL" )
    .save( "confidential-report.docx" )

密码保护

word()
    .addHeading( "Board Packet", 1 )
    .addParagraph( "Restricted content." )
    .protect( "boardOnly2026!" )
    .save( "board-packet.docx" )

分节符实现混合版式

叙述部分使用纵向，宽财务表格使用横向，附录再回到纵向。

word()
    .orientation( "portrait" )
    .addHeading( "Executive Summary", 1 )
    .addParagraph( "..." )
    .addSectionBreak()
    .orientation( "landscape" )
    .addHeading( "Financial Detail", 1 )
    .addTable( wideFinancialData )
    .addSectionBreak()
    .orientation( "portrait" )
    .addHeading( "Appendix", 1 )
    .save( "mixed-orientation.docx" )

合规元数据

这些文档属性会显示在 Word 的“信息”面板中，并随文件传递。

word()
    .setTitle( "Q4 Financial Report" )
    .setAuthor( "Finance Department" )
    .setSubject( "Quarterly financial summary FY2026" )
    .setKeywords( "finance, quarterly, report, 2026" )

面向真实工作流的流畅辅助方法

两个小方法在生产代码中价值巨大。

`tap()` 用于审计与日志

在不中断调用链的情况下，钩入日志、审计或副作用处理。

word()
    .addHeading( "Contract", 1 )
    .tap( ( doc ) => auditLog.info( "Contract draft initiated for client #clientId#" ) )
    .populate( contractData )
    .tap( ( doc ) => auditLog.info( "Contract populated, #len( doc.toText() )# chars" ) )
    .save( outputPath )

`when()` 用于条件内容

在单个流畅表达式中为不同层级、角色或地区输出不同内容。

word()
    .addHeading( "Sales Report", 1 )
    .addParagraph( "Standard content for all recipients." )
    .when( user.hasRole( "executive" ), ( doc ) => doc
        .addHeading( "Executive Detail", 2 )
        .addTable( executiveMetrics )
    )
    .when( region == "EU", ( doc ) => doc
        .addParagraph( "GDPR-compliant addendum applies.", { italic : true } )
    )
    .save( "report.docx" )

不再需要分支辅助函数。条件逻辑与内容定义在同一个位置。

实际示例

以下是从实时查询生成的完整 Q4 销售报告，包含元数据、样式化标题、表格和摘要部分：

salesData = queryExecute( "
    SELECT product_name, units_sold, unit_price,
           ( units_sold * unit_price ) as revenue
    FROM sales
    WHERE quarter = 'Q4'
    ORDER BY revenue DESC
" )

word( "q4-sales-report.docx" )
    .margins( 1.5, 1.5, 1.5, 1.5 )
    .setTitle( "Q4 2026 Sales Report" )
    .setAuthor( "Sales Department" )
    .setSubject( "Quarterly sales summary" )
    .header( "ACME Corp | Q4 2026 Sales Report" )
    .footer( "Confidential" )
    .addHeading( "Q4 2026 Sales Report", 1 )
    .addParagraph( "Generated on " & dateTimeFormat( now(), "yyyy-mm-dd HH:nn" ), {
        italic : true,
        size   : 10,
        color  : "808080"
    } )
    .addParagraph( "The following report summarizes sales performance for Q4 2026.", {
        spacingAfter : 240
    } )
    .addTable( salesData )
    .addPageBreak()
    .addHeading( "Summary", 2 )
    .addParagraph( "All products met or exceeded quarterly targets.", { bold : true } )
    .save()

这是一个由真实数据库查询生成的、可直接提交董事会的完整文档，大约二十行 BoxLang 代码。

许可证与 60 天试用

bx-word 是一个 BoxLang+ 模块，在我们的 Plus、Plus Plus 和 Starter 许可层级下可用。这是一项商业级能力，附带了企业所需的支持与长期维护承诺。

我希望你的团队在做出承诺之前先验证价值。每个安装都包含 60 天免费试用，你可以构建真实工作流、衡量影响，并带着真实数据进入预算讨论。试用期间不限制任何功能，全部能力开放使用。

如果你已拥有 BoxLang+ 许可证，可以直接开始使用。

安装

$ bash

box install bx-word

要求：

BoxLang Runtime 1.14.0 或更高版本
BoxLang+ 许可证（或使用 60 天试用）

开始使用

完整文档见：https://boxlang.ortusbooks.com/boxlang-+-++/modules/bx-word

如有问题、反馈，或希望讨论企业级部署，请通过 support@ortussolutions.com 联系我们，或加入我们的 Slack 社区。

原文《发布 BX-WORD：为 BoxLang 提供原生 Microsoft Word 自动化能力》首发于 foojay。

分类导航