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] → □ / ✓)、引用、分割线、图片(缩放 / 对齐 / 图注)、左中右两端对齐、多栏并排(Columns)、表格(Table:自适应列宽 / 限宽 / 按列行格上色 / 紧凑度与网格可调)。标记语言对应是 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, 自备对应字体即生效),缺字体时回退黑体。

入口:render_markup / render_document(→ 图片字节)、render_to_rgba(→ RGBA 图, 供进一步合成)。

Structs§

BlockImage: 块级图片。
Cell: 单元格:行内内容(按列宽自动换行)+ 可选背景填色。
ColSpec: 列规格:对齐 + 可选限宽。
Color: RGBA 颜色(每通道 8 位,非预乘)。
Column: 一栏:块内容 + 宽度权重(按权重瓜分可用宽,默认 1.0)。
Columns: 多栏容器:各栏并排,行高取最高栏。
ColumnsBuilder: 并排栏构建器。
Doc: 文档 / 块序列构建器。也用作引用、列表项的内层块容器。
Document: 一份文档:从上到下排布的块序列。
FontHandle: 可克隆的共享字体句柄:内部持有加好字体的 FontSystem 与一个 SwashCache,各用 Mutex 包(cosmic-text 整形 / 取字形位图都要 &mut)。克隆只增引用计数。
ImageBuilder: 块级图片构建器。
Insets: 四边内边距(逻辑像素)。
List: 列表。
ListBuilder: 列表构建器。
ListItem: 列表项:内容是块序列,故支持多段与嵌套子列表。
ParaBuilder: 段落 / 标题的行内内容构建器(也用于图注)。
RenderOptions: 渲染入参。链式覆写;default() = 720 逻辑宽、亮色、scale 2、PNG、默认字体句柄。
StyleBuilder: 文字样式构建器(给 ParaBuilder::styled)。
Table: 表格。cols 给各列对齐与可选限宽(短于列数时,缺的列按默认:左对齐 + 自适应)。
TableBuilder: 表格构建器(纯文字单元格)。
TableGrid: 网格线开关,默认全开。
TableStyle: 表格的紧凑度与网格样式。
TextStyle: 可叠加的文字样式。span 嵌套时逐字段合并。
Theme: 视觉主题:配色 + 字族 + 字号体系。预设见 Theme::light / Theme::dark。

Enums§

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

Functions§

parse_markup: 解析标记文本为文档。
render_document: 把一份文档排版渲染成图片字节(格式见 RenderOptions::format)。
render_markup: 解析标记文本并渲染成图片字节(格式由 RenderOptions::format 决定,默认 PNG)。
render_to_rgba: 渲染成(去预乘的)RGBA 图,供进一步合成,不编码。

Type Aliases§

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