Crate nagisa_render 

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

给的是图片字节,不碰任何协议——送到 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)、面板(Panel:底色 / 边框 / 圆角 / 内边距 / 投影的卡片容器,作并排栏整栏时自动拉齐行高;::: panel {bg=…} / Doc::panel)、表格(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 上,所有出图统一带。

Panel

面板:带装饰的块容器。作并排栏某栏唯一块时,装饰盒拉齐到本行最高栏(卡片排整齐)。

PanelBuilder

面板构建器(Doc::panel / ColumnsBuilder::panel 的闭包参数):装饰方法在本体, 内容方法经 Deref 落到内层 Doc(先配装饰再加内容,内容方法返回 &mut Doc, 链上接不回装饰方法)。

PanelDecor

面板装饰。bg 与 border 都缺省时按主题给「浅底 + 细边」的默认卡片样。

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 别名。