Thinreports Generator 技术文档

Thinreports Generator 是一个用于生成 PDF 的 Ruby 库，支持通过模板文件动态生成 PDF 文档。本文将详细介绍如何安装、使用 Thinreports Generator，并对其 API 进行说明。

1. 安装指南

1.1 环境要求

• Ruby 3.0, 3.1, 3.2, 3.3
• Prawn 2.4+

1.2 安装方式

通过 Bundler 安装

在您的应用程序的 Gemfile 中添加以下行：

gem 'thinreports'

然后执行以下命令进行安装：

$ bundle install

手动安装

您也可以通过以下命令手动安装 Thinreports：

$ gem install thinreports

2. 使用说明

2.1 快速开始

首先，您需要了解 Thinreports 的基本概念和功能。Thinreports 提供了两种模板格式：基本格式（Basic Format）和分段格式（Section Format）。您可以通过 Thinreports Basic Editor 创建模板文件（.tlf），然后使用 Thinreports Generator 动态生成 PDF。

2.2 基本格式使用示例

以下是一个使用基本格式生成 PDF 的示例：

require 'thinreports'

report = Thinreports::Report.new layout: 'report.tlf'

report.start_new_page do
  item(:title).value('Thinreports')
end

report.generate(filename: 'report.pdf')

2.3 多布局使用

您可以在一个报告中同时使用多个布局：

report = Thinreports::Report.new

report.use_layout '/path/to/default.tlf', default: true
report.use_layout '/path/to/other1.tlf', id: :other

report.start_new_page do |page|
  # 使用默认布局
end

report.start_new_page layout: :other do |page|
  # 使用其他布局
end

2.4 回调函数

您可以在生成 PDF 时使用回调函数：

report = Thinreports::Report.new layout: 'foo.tlf'

report.on_page_create do |page|
  page.item(:text).value('所有页面的文本')
end

2.5 列表功能

Thinreports 支持在 PDF 中生成列表：

report = Thinreports::Report.new layout: 'list.tlf'

report.list.header do |header|
  header.item(:text_block).value('标题')
end

10.times do |n|
  report.list.add_row do |row|
    row.item(:text_block).value(n)
  end
end

report.generate(filename: 'list.pdf')

2.6 页码设置

您可以自定义页码的起始值和样式：

report.start_page_number_from 5

report.start_new_page do |page|
  page.item(:pageno).styles(color: 'red', bold: true)
end

3. API 使用文档

3.1 报告和页面

• Thinreports::Report.new(layout: 'template.tlf')：创建一个新的报告实例。
• report.start_new_page：开始一个新页面。
• report.pages：返回所有页面。
• report.page_count：返回页面数量。

3.2 文本块和图像块

• page.item(:text_block).value('文本')：设置文本块的值。
• page.item(:image_block).src('/path/to/image.png')：设置图像块的源文件。

3.3 样式设置

• page.item(:text).style(:color, 'red')：设置文本颜色。
• page.item(:text).style(:bold, true)：设置文本加粗。

3.4 批量设置

• page.values text_block_a: 'value', text_block_b: 'value'：批量设置多个文本块的值。
• page.item(:text).styles(color: '#00000', align: :right)：批量设置文本样式。

4. 项目安装方式

4.1 通过 Docker 进行开发

您可以使用 Docker 容器进行开发，容器中包含了测试所需的库，如 diff-pdf。

$ docker pull ghcr.io/hidakatsuya/ruby-with-diff-pdf:latest
$ docker run -v $PWD:/src:cached -it ghcr.io/hidakatsuya/ruby-with-diff-pdf bash

> /src#

在容器中运行测试：

> /src# bundle install
> /src# bundle exec rake test

4.2 发布流程

1. 更新 version.rb 中的版本号。
2. 更新 CHANGELOG.md 和 README.md（如有需要）。
3. 创建发布 PR。
4. 合并 PR。
5. 确保主 CI 通过。
6. 运行 bundle exec rake release，该命令将创建版本标签，推送提交和标签，并将 .gem 文件推送到 rubygems.org。

5. 总结

Thinreports Generator 是一个功能强大的 Ruby 库，能够通过模板文件动态生成 PDF 文档。本文详细介绍了其安装、使用方法和 API 文档，帮助您快速上手并高效使用该工具。