nagisa_render/
lib.rs

1//! 把一段带格式的文本 / 一份用构建器拼出的文档,排版渲染成图片字节。
2//!
3//! 给的是图片字节,不碰任何协议——送到 QQ 由调用方包一层(如 `Segment::image_bytes`)。
4//! 管线:源(标记文本 | 构建器)→ 文档模型 [`Document`] → 版式(cosmic-text 整形 / 断行 /
5//! 字体回退 / CJK+拉丁+emoji 混排)→ 光栅(tiny-skia)→ 图片字节。
6//!
7//! # 两种写法
8//!
9//! 标记文本(类 Markdown,适合「一大段文字」):
10//!
11//! ```ignore
12//! use nagisa_render::{render_markup, RenderOptions};
13//!
14//! let png = render_markup("# 标题\n\n正文 **加粗**、[彩色]{color=#e00}、==高亮==。", &RenderOptions::default())?;
15//! ```
16//!
17//! Rust 构建器(类型安全,适合从数据生成卡片):
18//!
19//! ```ignore
20//! use nagisa_render::{render_document, Doc, RenderOptions};
21//!
22//! let doc = Doc::new()
23//!     .heading(1, |h| h.text("月度报告"))
24//!     .paragraph(|p| { p.text("环比 ").bold("+12%").text("。"); })
25//!     .table(|t| { t.head(["项", "值"]).row(["发言", "3450"]); })
26//!     .build();
27//! let png = render_document(&doc, &RenderOptions::default())?;
28//! ```
29//!
30//! 两种写法产出同一个 [`Document`];也可以 [`parse_markup`] 拿到 `Document` 再用构建器接着改。
31//!
32//! # 能排什么
33//!
34//! 标题、段落、粗 / 细 / 任意字重、斜 / 下划 / 删除、颜色 / 高亮、字号 / 字族(黑 / 宋 /
35//! 楷 / 等宽)、链接(图片点不了,取文字按
36//! 强调色渲染)、行内与块级代码(语言标签渲染在盒角)、有序 / 无序列表(可嵌套)、任务列表
37//! (`- [ ]` / `- [x]` → `□` / `✓`)、引用、分割线、图片(缩放 / 对齐 / 图注)、左中右两端
38//! 对齐、多栏并排([`Columns`])、表格([`Table`]:自适应列宽 / 限宽 / 按列行格上色 /
39//! 紧凑度与网格可调)。标记语言对应是 Markdown 基底加少量扩展(`==高亮==`、`[文字]{属性}`、
40//! `::: 围栏`、GFM 表格),见 [`parse_markup`];构建器见 [`Doc`]。
41//!
42//! # 输出与配置
43//!
44//! 都在 [`RenderOptions`]:
45//!
46//! - **格式** [`OutputFormat`]:`Png`(默认,通用)/ `PngFast`(更快、略大)/ `Webp`(无损,
47//!   文字图体积最小且快;单边 > 16383px 报错)/ `WebpOrPng`(WebP 优先,超 WebP 上限自动落 PNG)。
48//!   文字图建议 `.webp()`,长图怕超限用 `.webp_or_png()`。
49//! - **清晰度** `scale`:`.fast()` / `.standard()` / `.sharp()`(默认 2×)/ `.ultra()`,或
50//!   `.with_scale(f)`。越大越清晰、也越慢越大。
51//! - **主题** [`Theme`]:亮 / 暗预设 + 自定义配色 / 字族 / 字号。
52//! - **字体** [`FontHandle`]:内置兜底(黑体 + 等宽正斜,细 / 常规 / 粗皆真字形,zstd 压缩
53//!   内嵌、首次使用时解压)+ 自备数据(`data()`,裸字节或 zstd 压缩皆可)+ 自定义目录 +
54//!   系统,四来源合并。衬线 / 楷体角色不随包内置(默认字族名 Noto Serif SC / LXGW WenKai GB,
55//!   自备对应字体即生效),缺字体时回退黑体。
56//!
57//! 入口:[`render_markup`] / [`render_document`](→ 图片字节)、[`render_to_rgba`](→ RGBA 图,
58//! 供进一步合成)。
59#![forbid(unsafe_code)]
60
61mod build;
62mod error;
63mod font;
64mod layout;
65mod markup;
66mod model;
67mod paint;
68mod theme;
69
70pub use build::{
71    ColumnsBuilder, Doc, ImageBuilder, ListBuilder, ParaBuilder, StyleBuilder, TableBuilder,
72};
73pub use error::{Error, Result};
74pub use font::FontHandle;
75pub use markup::parse as parse_markup;
76pub use model::ImageSource;
77pub use model::{
78    Align, Block, BlockImage, Cell, ColSpec, Color, Column, Columns, Document, FontRole, Highlight,
79    Inline, Length, List, ListItem, ListKind, Table, TableGrid, TableStyle, TextStyle,
80};
81pub use theme::{Insets, OutputFormat, RenderOptions, Theme};
82
83/// 解析标记文本并渲染成图片字节(格式由 [`RenderOptions::format`] 决定,默认 PNG)。
84pub fn render_markup(src: &str, opts: &RenderOptions) -> Result<Vec<u8>> {
85    render_document(&markup::parse(src)?, opts)
86}
87
88/// 把一份文档排版渲染成图片字节(格式见 [`RenderOptions::format`])。
89pub fn render_document(doc: &Document, opts: &RenderOptions) -> Result<Vec<u8>> {
90    let layout = layout::layout_document(doc, opts)?;
91    paint::paint(&layout, opts)
92}
93
94/// 渲染成(去预乘的)RGBA 图,供进一步合成,不编码。
95pub fn render_to_rgba(doc: &Document, opts: &RenderOptions) -> Result<image::RgbaImage> {
96    let layout = layout::layout_document(doc, opts)?;
97    paint::paint_rgba(&layout, opts)
98}
nagisa_render/lib.rs

nagisa_render/
lib.rs
