1. 产品
  2.   字处理
  3.   Ruby
  4.   Sablon
 
  

开源 Ruby 库，用于生成 Word DOCX 文件

一个强大的免费 Ruby API，使软件开发者能够轻松创建 Word DOCX 文档。它允许设计文档's Layout, Apply Styles, and Use Mail Merge Fields as Placeholders for Dynamic Content.

什么是 Sablon 库？

在软件开发领域，生成动态文档（如报告、发票或信件）是常见需求。虽然许多库可以从零创建文档，但它们通常需要陡峭的学习曲线和繁琐的编码才能确保格式正确。这时，强大的开源 Ruby 库 Sablon 横空出世。Sablon 通过利用 Microsoft Word 的熟悉度和 Ruby 的强大能力，革新了文档生成，使您能够以最少的工作量创建复杂且美观的文档。它支持诸如 Word Docx 创建、通过 MailMerge 字段插入内容、先进的格式化支持、在模板中添加批注、可配置的 HTML 与 CSS 转换等诸多功能。

从根本上说，Sablon 是一个针对 .docx 文件的文档模板处理器。它利用 Word 内置的邮件合并功能，使您能够在熟悉的环境中创建模板。您可以设计文档布局、应用样式，并使用邮件合并字段作为动态内容的占位符。随后，Sablon 将该模板与数据上下文（Ruby 哈希）结合，生成最终的、填充数据的 Word 文档。这种方法将呈现层（Word 模板）与数据层（您的 Ruby 代码）分离，使文档生成过程干净且易于维护。其语法对熟悉 Ruby 和模板语言的用户非常直观。它对设计师友好，内容与设计完全分离。设计师可以直接在 Word 中工作，而无需接触代码。

Previous Next

Sablon 入门

推荐的安装方式是使用 RubyGems 安装 Sablon。请使用以下命令进行顺利安装。

通过 RubyGems 安装文档


gem 'sablon'
You can also download it directly from GitHub.

使用 Ruby 在 Word 字段中插入内容

最基本的功能是插入动态内容。开源 Ruby 库 Sablon 使用 Word 内置的字段语法来定义占位符。在您的 Word 模板中，插入一个字段代码，指明您希望动态内容出现的位置。Sablon 将用您的值替换该字段。下面的示例演示了软件开发者如何动态插入内容来向用户致意。

如何通过 Ruby 动态插入文本内容到 Word 文档文件？

require 'sablon'

template = Sablon.template(File.expand_path('~/template.docx'))
context = {
  name: "Sarah Connor"
}

template.render_to_file(File.expand_path('~/output.docx'), context)

Template:

Hello, «name»! Welcome to our platform.

Output:
Hello, Sarah Connor! Welcome to our platform.

HTML 转 WordML 转换

Sablon 的一大亮点是能够将 HTML 转换为 WordProcessingML（.docx 文件使用的 XML 格式）。当您需要从数据库或富文本编辑器中插入富文本内容（如格式化段落、列表或表格）时，这极其有用。Sablon 将把 HTML 字符串转换为 Word 文档中适当格式的章节，保留标题、粗体和斜体文本以及列表格式。以下是一个简单示例，演示如何加载现有模板并在 Ruby 应用中将 HTML 内容转换为 Word Docx 文件。

如何通过 Ruby 库将 HTML 内容转换为 Word Docx 文件？

require "sablon"

template = Sablon.template(File.expand_path("template.docx"))

html_content = "
这是一个子标题
这是一个包含 粗体 和 斜体 文本的段落。
  • 第一项
  • 第二项
"

context = {
  article_content: Sablon.content(:html, html_content)
}

template.render_to_file(File.expand_path("output.docx"), context)

Conditional Rendering

使用 Ruby 动态插入图像

开源的 Sablon 库加入了一个有用的功能，使用 Ruby 库可以在 Word Docx 文档中动态插入图像。只需几行代码，开发者即可动态向文档中插入图像。您可以指定图像文件，Sablon 会将其嵌入文档中。以下示例演示了如何实现图像的动态插入。

如何通过 Ruby 库动态插入图像到 Word Docx？


// You would have a placeholder image in your template with a special filename like «=company_logo».

context = {
  company_logo: Sablon.content(:image, "path/to/your/logo.png")
}

使用 Ruby 的条件渲染

Sablon 库支持条件块，允许用户根据变量的存在与否或其值来显示或隐藏 Word 文档的部分内容。这对于根据特定条件定制文档非常理想。例如，下面的示例展示了用户如何设置指令来隐藏或显示 Word 文档中的特定信息。如果 show_extra_info 为 true，则位于 if 和 endIf 标签之间的内容将被包含在最终文档中；如果为 false 或 nil，则该内容将被移除。

如何使用 Ruby 显示或隐藏 Word Docx 文档的部分内容？


context = {
  show_extra_info: true # or false
}
 中国人