Ruby SDK

majorsilence_reporting

从 Ruby 生成 PDF、Excel、CSV 等格式的 RDL 报表——通过子进程、AOT 二进制文件,或进程内 Fiddle FFI。Ruby 3.0+。无 gem 运行时依赖。

本页内容

安装
集成模式
Report(子进程)
ReportAot(AOT 二进制)
ReportNative(Fiddle)
核心 API
内存数据集
导出格式

安装

目前尚未在 RubyGems 上发布 gem。请通过 $LOAD_PATH 或 require_relative 从源代码加载:

# 将 lib 目录添加到加载路径
$LOAD_PATH.unshift '/path/to/reporting-ruby/lib'

# 一次性加载全部三个类
require 'majorsilence_reporting'

# 或单独加载各个类
require 'majorsilence_reporting/report'
require 'majorsilence_reporting/report_aot'
require 'majorsilence_reporting/report_native'

无 gem 运行时依赖。原生 FFI 模式使用 Ruby 内置的标准库 Fiddle。

集成模式

类	机制	前提条件
Report	通过 `system()` 启动 `dotnet RdlCmd.dll`。	服务器上的 .NET 运行时。
ReportAot	通过 `system()` 启动自包含的 AOT 编译 `RdlCmd` 二进制文件。	AOT 二进制文件与应用一同部署。无需 .NET 运行时。
ReportNative	通过 `Fiddle` 在进程内加载 `librdlnative.so`。使用 `RdlLibrary.load()` 获取绑定的函数表。	Ruby 启动前,原生库及相关 `.so` 文件已位于 `LD_LIBRARY_PATH`。

Report —— 子进程(dotnet)

require 'majorsilence_reporting/report'

rpt = Report.new('/path/to/report.rdl', '/path/to/RdlCmd.dll')
rpt.set_connection_string('Data Source=/path/to/data.db')
rpt.set_parameter('StartDate', '2026-01-01')

# 保存到磁盘
rpt.export('pdf', '/tmp/output.pdf')

# 或在内存中获取字节(例如用于 Rails 控制器)
data = rpt.export_to_memory('pdf')
send_data data, type: 'application/pdf', disposition: 'inline'

ReportAot —— AOT 二进制

与 Report 使用相同的 API,但指向自包含的二进制文件。无需 .NET 运行时。可解锁额外的导出格式(xlsx_table、tifb、mht)。

require 'majorsilence_reporting/report_aot'

rpt = ReportAot.new('/path/to/report.rdl', '/path/to/RdlCmd')
rpt.set_connection_string('Data Source=/path/to/data.db')

data = rpt.export_to_memory('xlsx_table')

# 在 Rack/Sinatra 响应中:
[200, { 'Content-Type' => 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' }, [data]]

ReportNative —— Fiddle FFI

通过内置的 Fiddle 库将 librdlnative.so 直接加载到 Ruby 进程中。不会启动任何子进程。

require 'majorsilence_reporting/report_native'

# 启动时只加载一次。会预加载相关的 .so/.dylib 文件并设置 RDLNATIVE_LIB_DIR。
lib = RdlLibrary.load('/path/to/librdlnative.so')

rpt = ReportNative.new(lib, '/path/to/report.rdl')
rpt.set_connection_string('Data Source=/path/to/data.db')

data = rpt.export_to_memory('pdf')   # 返回二进制 String

LD_LIBRARY_PATH 必须在 Ruby 启动前就包含原生库所在目录。RdlLibrary.load() 会设置 ENV['RDLNATIVE_LIB_DIR'] 并通过 Fiddle.dlopen 预加载相关库,但无法为正在运行的进程追溯性地更新 LD_LIBRARY_PATH。

核心 API

三个类共享同一接口:

方法	说明
set_connection_string(cs)	设置数据库连接字符串。需在 `export` 之前调用。
set_parameter(name, value)	设置一个具名报表参数。两个参数均为字符串。可根据需要多次调用。
export(type, path)	渲染报表并将输出写入磁盘上的 `path`。
export_to_memory(type)	渲染并以二进制 `String`(二进制格式)或 UTF-8 `String`(如 CSV、XML、HTML 等文本格式)形式返回输出。

内存数据集

ReportNative 支持通过 add_data() 完全在内存中提供数据——无需数据库连接。传入数据集名称和一个由哈希组成的数组,其中每个值都是字符串。

rpt.add_data('SalesData', [
  { 'Product' => 'PDF Library Pro',  'Revenue' => '1200.00', 'Units' => '3' },
  { 'Product' => 'Report Designer',   'Revenue' => '250.00',  'Units' => '1' },
  { 'Product' => 'Support (12 mo.)',  'Revenue' => '500.00',  'Units' => '1' },
])

data = rpt.export_to_memory('pdf')

add_data() 仅在 ReportNative 上可用,Report 和 ReportAot 均不支持。所有字段值都必须是字符串。数据集名称必须与 .rdl 文件中定义的数据集匹配。

导出格式

格式字符串	输出	可用范围
`pdf`	PDF	所有模式
`csv`	CSV 文本	所有模式
`xlsx`	Excel 工作簿	所有模式
`xml`	XML 数据	所有模式
`rtf`	Rich Text Format	所有模式
`tif`	TIFF 图像(彩色)	所有模式
`html`	HTML	所有模式
`xlsx_table`	Excel(表格样式)	仅 ReportAot + ReportNative
`tifb`	TIFF 图像(黑白)	仅 ReportAot + ReportNative
`mht`	MHTML 网页存档	仅 ReportAot + ReportNative