Crate nagisa_render

Expand description

把一段带格式的文本 / 一份用构建器拼出的文档,排版渲染成图片字节。

给的是图片字节,不碰任何协议——送到 QQ 由调用方包一层(如 Segment::image_bytes)。管线:源(标记文本 | 构建器)→ 文档模型 Document → 版式(cosmic-text 整形 / 断行 / 字体回退 / CJK+拉丁+emoji 混排)→ 光栅(tiny-skia)→ 图片字节。

§两种写法

标记文本(类 Markdown,适合「一大段文字」):

use nagisa_render::{render_markup, RenderOptions};

let png = render_markup("# 标题\n\n正文 **加粗**、[彩色]{color=#e00}、==高亮==。", &RenderOptions::default())?;

Rust 构建器(类型安全,适合从数据生成卡片):

use nagisa_render::{render_document, Doc, RenderOptions};

let doc = Doc::new()
    .heading(1, |h| h.text("月度报告"))
    .paragraph(|p| { p.text("环比 ").bold("+12%").text("。"); })
    .table(|t| { t.head(["项", "值"]).row(["发言", "3450"]); })
    .build();
let png = render_document(&doc, &RenderOptions::default())?;

两种写法产出同一个 Document;也可以 parse_markup 拿到 Document 再用构建器接着改。

§能排什么

标题、段落、粗 / 细 / 任意字重、斜 / 下划 / 删除、颜色 / 高亮、字号 / 字族(黑 / 宋 / 楷 / 等宽)、文字阴影、链接(图片点不了,取文字按强调色渲染)、行内与块级代码(语言标签渲染在盒角)、有序 / 无序列表(可嵌套)、任务列表(- [ ] / - [x] → □ / ✓)、引用、分割线、图片(缩放 / 对齐 / 图注 + 装饰层:角标 / 边框 / 水印 / 圆角裁切 / 投影,见 ImageBuilder)、左中右两端对齐、多栏并排(Columns)、表格(Table:自适应列宽 / 限宽 / 铺满可用宽(expand)/ 按列行格上色 / 紧凑度与网格可调)。标记语言对应是 Markdown 基底加少量扩展(==高亮==、[文字]{属性}、::: 围栏、GFM 表格),见 parse_markup; 构建器见 Doc。

§输出与配置

都在 RenderOptions:

格式 OutputFormat:Png(默认,通用)/ PngFast(更快、略大)/ Webp(无损, 文字图体积最小且快;单边 > 16383px 报错)/ WebpOrPng(WebP 优先,超 WebP 上限自动落 PNG)。文字图建议 .webp(),长图怕超限用 .webp_or_png()。
清晰度 scale:.fast() / .standard() / .sharp()(默认 2×)/ .ultra(),或 .with_scale(f)。越大越清晰、也越慢越大。
主题 Theme:亮 / 暗预设 + 自定义配色 / 字族 / 字号。
字体 FontHandle:内置兜底(黑体 + 等宽正斜,细 / 常规 / 粗皆真字形,zstd 压缩内嵌、首次使用时解压)+ 自备数据(data(),裸字节或 zstd 压缩皆可)+ 自定义目录 + 系统,四来源合并。衬线 / 楷体角色不随包内置(默认字族名 Noto Serif SC / LXGW WenKai GB, 自备对应字体即生效),缺字体时回退黑体。
页眉 / 页脚 PageChrome:与文档无关的固定标识(品牌 / 署名 / 出处),配在选项上所有出图统一带;富文本、左右分栏(trailing)、满幅色带(band)皆可。

入口:render_markup / render_document(→ 图片字节)、render_to_rgba(→ RGBA 图, 供进一步合成)、measure_document(只排版量尺寸不绘制,按高度上限把长内容切成多张图时先量再渲)。

Structs§

Badge: 图片角标:圆角底板 + 短文字,贴在图的一角。
BadgeBuilder: 角标微调构建器。
BlockImage: 块级图片。
Cell: 单元格:行内内容(按列宽自动换行)+ 可选背景填色。
ColSpec: 列规格:对齐 + 可选限宽。
Color: RGBA 颜色(每通道 8 位,非预乘)。
Column: 一栏:块内容 + 宽度权重(按权重瓜分可用宽,默认 1.0)。
Columns: 多栏容器:各栏并排,行高取最高栏。
ColumnsBuilder: 并排栏构建器。
Doc: 文档 / 块序列构建器。也用作引用、列表项的内层块容器。
Document: 一份文档:从上到下排布的块序列。
DotMark: 着重点参数。
FontHandle: 可克隆的共享字体句柄:内部持有加好字体的 FontSystem 与一个 SwashCache,各用 Mutex 包(cosmic-text 整形 / 取字形位图都要 &mut)。克隆只增引用计数。
ImageBorder: 图片边框(沿图缘描边;有圆角时随圆角)。
ImageBuilder: 块级图片构建器。
ImageDecor: 图片装饰层 —— 叠在图面上的附加呈现,不改变布局尺寸(阴影溢出照画)。
Insets: 四边内边距(逻辑像素)。
List: 列表。
ListBuilder: 列表构建器。
ListItem: 列表项:内容是块序列,故支持多段与嵌套子列表。
PageChrome: 页眉 / 页脚条:一行小字(可富文本)+ 可选的与内容之间的细分割线。参与布局高度 (measure_document 自然包含),不归文档内容管——同一品牌标识配在 RenderOptions 上,所有出图统一带。
ParaBuilder: 段落 / 标题的行内内容构建器(也用于图注)。
Progress: 进度条:value 按比例填充,余下露出底槽。
ProgressBuilder: 进度条构建器(Doc::progress 的闭包参数)。
RenderOptions: 渲染入参。链式覆写;default() = 960 逻辑宽、亮色、scale 2、PNG、默认字体句柄。
RingMark: 圈注参数。半径给定后圈的大小与文字宽窄无关——日历里「1」和「10」能圈出同样大的圈。
Shadow: 阴影(文字与图片共用):偏移 + 软化半径 + 颜色,尺寸皆逻辑像素。不参与布局(不撑大占位),溢出块界照画。
StyleBuilder: 文字样式构建器(给 ParaBuilder::styled)。
Table: 表格。cols 给各列对齐与可选限宽(短于列数时,缺的列按默认:左对齐 + 自适应)。
TableBuilder: 表格构建器(纯文字单元格)。
TableGrid: 网格线开关,默认全开。
TableStyle: 表格的紧凑度与网格样式。
TextStyle: 可叠加的文字样式。span 嵌套时逐字段合并。
Theme: 视觉主题:配色 + 字族 + 字号体系。预设见 Theme::light / Theme::dark。
Watermark: 图片水印:无底板的半透明文字。
WatermarkBuilder: 水印微调构建器。

Enums§

Align: 水平对齐。
Anchor: 图面上的锚点位置(角标 / 水印的停靠处)。
Block: 块级元素。
Error: 排版引擎错误。
FontRole: 字族角色。Named 直接按字族名匹配,匹配不到回退 Sans。
Highlight: 高亮底色来源。
ImageSource: 图片来源。引擎不联网:URL 由调用方下好,以 Bytes 传入。
Inline: 行内元素。
Length: 长度:绝对像素,或相对内容宽的百分比。
ListKind: 列表种类。
OutputFormat: 输出图片格式。文字图首选 Webp(最小 + 快);Png 通用兜底;PngFast 要 PNG 又要快。

Functions§

measure_document: 只排版、不绘制:返回这份文档渲出来的图片尺寸(物理像素,即已含 scale)。供调用方做内容装箱——如按高度上限把长列表切成多张图,定好切分再真正渲染。
parse_markup: 解析标记文本为文档。
render_document: 把一份文档排版渲染成图片字节(格式见 RenderOptions::format)。
render_markup: 解析标记文本并渲染成图片字节(格式由 RenderOptions::format 决定,默认 PNG)。
render_to_rgba: 渲染成(去预乘的)RGBA 图,供进一步合成,不编码。

Type Aliases§

Result: 引擎内部用的 Result 别名。