nagisa-render 0.3.0

nagisa 的文本排版引擎:标记/构建器文档 → 图片
Documentation

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

给的是图片字节,不碰任何协议——送到 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 图, 供进一步合成)。