Skip to content

About

一个纯 .NET 原生、JSON 驱动的跨平台打印模板设计器与渲染引擎。类似 hiprint 的可视化模板设计体验,但为 .NET 桌面生态而生,支持 Avalonia、WPF、WinForms 、Eto.Forms、Uno Platform、WinUI宿主,同一套渲染代码保证"所见即所印"。

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

OODD CrossPrint Logo

OODD CrossPrint

一个跨平台 .NET 打印模板组件。你只需要写一份模板、接一份数据、点一下"打印"——剩下的事交给它。Avalonia、WPF、WinForms、Eto.Forms、WinUI、Uno、.NET MAUI,全部七宿主共用同一个渲染内核:画布上看到什么样,导出的 PDF 就是什么样,送进打印机还是什么样。所见即所得,不玩两套渲染。

已经在用 hiprint(vue-plugin-hiprint / Vue-Print-Designer)设计器了?太好了——它导出的模板直接吃,不需要重新画一遍。

模板里写的全是毫米和磅,没有像素这个坑。引擎画每一个像素,宿主控件只负责"把画布放到屏幕上"——这俩互不干扰。

中文 | English · 在线示例(WebAssembly实话实说网页版的基本不能用,建议下载release中的桌面端)

当前版本 1.1.0(2026-11-09)· 更新日志 · 下载 Releases


1.1.0 有什么新变化

  • 七宿主功能对齐:模板库(内置分类 + 引擎真渲染缩略图)、样式库、Toast 提示、工具箱搜索与拖放、 撤销/重做、状态栏缩放、水印编辑、分栏可拖宽,六宿主与 Avalonia 基准逐项拉平; Uno / MAUI 工具箱以点击放置兜底拖放。
  • 连续纸表格自动增高:小票表格按数据行数长高、表格下方元素整体顺移、页高自适应; PDF、批量导出、GDI 直打三条出图路径都「先增高、再算纸」,不再把明细截断在设计高度。
  • GDI 直打、表格单元格图片、按元素类型裁剪属性面板;小票 {{subtotal}} / {{total}} / {{points}} 随明细实时求和。
  • 固定护栏:长文本 200,000 字符 / 20,000 行 / 8,000 字符每行,图片 32MB / 1,600 万像素 / 单边 8192, 超限截断或拒收并给出明确告警(详见「已知限制」)。
  • 多宿主真机筛查修复:Uno / MAUI / WinUI 主题锁定、Uno 中文回落与模板库缩略图解码、词条缺口补齐。
  • 完整清单见 CHANGELOG.md;升级包时所有 OODD.CrossPrint.* 与宿主包统一为 1.1.0。

先看一眼——设计器和打印长啥样

设计器画布 打印预览

左边是设计器(Avalonia 宿主,跑的是"厨房水槽"模板——八种元素全上,连脚本都写上了)。右边是同一个模板的打印预览。两个窗口走同一条渲染路径,所以你在左边拖一下元素,右边立刻跟着变——不是"大概类似",是像素级一致。

想自己玩?上面的 在线示例 链接点进去就行,浏览器直接跑,啥都不用装。


快速开始——两条路选一条

路线 A:跑样例看看效果(推荐先玩这个)

需要 .NET SDK 8.0 以上。打开 PowerShell,cd 到仓库根目录,任选一行跑:

# Avalonia 跨平台(Windows / Linux / macOS 都能跑,推荐)
dotnet run --project samples/CrossPrint.Samples.Avalonia

# 其他都是 Windows 专属
dotnet run --project samples/CrossPrint.Samples.Wpf
dotnet run --project samples/CrossPrint.Samples.WinForms
dotnet run --project samples/CrossPrint.Samples.Eto
dotnet run --project samples/CrossPrint.Samples.WinUi
dotnet run --project samples/CrossPrint.Samples.Uno
dotnet run --project samples/CrossPrint.Samples.Maui

样例自带两份模板:kitchen-sink.template.json(八种元素全覆盖)和 hiprint-sample.js(hiprint 模板)。打开后点 文件 → 导入 hiprint 模板… 把那份 .js 丢进去就能看到 hiprint 导入效果。

路线 B:NuGet 装进你自己的项目

先看看你用的是什么 UI 框架,挑对应的宿主包。CrossPrint 把内核(渲染、数据绑定、脚本、PDF)和宿主(把画布塞到 WPF/Avalonia 窗口里)彻底分开了——内核包不依赖任何 UI 框架,只有宿主包才依赖。

你在做什么 装这几个包就够了
任何宿主都需要的内核 OODD.CrossPrint.Core · OODD.CrossPrint.Engine · OODD.CrossPrint.Designer · OODD.CrossPrint.Printing
Avalonia OODD.CrossPrint.Hosts.Avalonia
WPF OODD.CrossPrint.Hosts.Wpf
WinForms OODD.CrossPrint.Hosts.WinForms
Eto.Forms OODD.CrossPrint.Hosts.Eto
WinUI 3 OODD.CrossPrint.Hosts.WinUi
Uno OODD.CrossPrint.Hosts.Uno
.NET MAUI OODD.CrossPrint.Hosts.Maui

举个实际例子(Avalonia 宿主):

dotnet add package OODD.CrossPrint.Core
dotnet add package OODD.CrossPrint.Engine
dotnet add package OODD.CrossPrint.Hosts.Avalonia

然后代码里这样用:

using CrossPrint.Core;
using CrossPrint.Hosts.Avalonia;

// 第一步:加载模板(JSON 字符串 / hiprint 文件都行)
var load = TemplateJson.Load(File.ReadAllText("template.json"),
                             TemplateJsonLoadOptions.Tolerant);

// 第二步:放一个设计画布——用户可以在上面拖元素改模板
var designer = new DesignerControl(load.Template)
{
    Data = new { orderNo = "SO-2026-0001", customer = "张三" },
};

// 或者放一个只读预览——给用户看效果但不让改
var preview = new PreviewControl(load.Template)
{
    Data = new { orderNo = "SO-2026-0001" },
};

导出 PDF:

using CrossPrint.Engine;

using var stream = File.Create("销售单.pdf");
var report = PdfExporter.Export(
    designer.Kernel.Template,
    stream,
    data: designer.Data,
    renderer: designer.Renderer);

// report 里会告诉你有没有缺失字段、图片找不到、脚本报错——不会炸整页
if (report.HasIssues) Console.WriteLine(report);

送进打印机:

using CrossPrint.Printing;

var document = new PrintDocument(designer.Kernel.Template, designer.Data);
var report = new RenderReport();

// 方式一:打印到 PDF 文件
await new PdfFilePrintTarget()
    .PrintBatchAsync([document], new PrintSettings { OutputPath = "销售单.pdf" }, report);

// 方式二:交给操作系统的打印对话框
await new SystemPrintTarget()
    .PrintBatchAsync([document], new SystemPrintOptions(), report);

设计器怎么用

所有七个宿主的设计器长得几乎一模一样:

┌──────────────────────────────────────────────────────────┐
│ 菜单栏:文件(导入 hiprint / 模板 JSON / 打印 / PDF)        │
├──────────────────────────────────────────────────────────┤
│ 工具带一:文字 线段 矩形 椭圆 图片 二维码 一维码 表格        │
│ 工具带二:样式库 | 副本 删除 | 上移 下移 置顶 置底           │
│           | 适合窗口 100% | □网格 □标尺 □安全区              │
│           | 打印 导出 PDF 预览                              │
├────────┬───────────────────────────────┬─────────────────┤
│ 纸张    │                               │ 属性面板         │
│ 工具箱  │         设计画布               │ (选中元素后     │
│        │      滚轮缩放 / 中键平移)       │   自动生成表单) │
├────────┴───────────────────────────────┴─────────────────┤
│ ▸ 模板 JSON(默认折叠,点一下展开)                          │
├──────────────────────────────────────────────────────────┤
│ 状态栏(当前缩放、选中元素的位置尺寸、绑定字段)              │
└──────────────────────────────────────────────────────────┘

添加元素

  • 方法一:左边工具箱里选中一个元素类型,点「添加到画布」(或双击 / 回车),元素落在页面正中间。
  • 方法二:直接点工具带上那排图标——文字、线段、矩形、二维码……一键添加。
  • 方法三:Ctrl+D 复制一个已经画好的元素——这是最快的,特别是表格列。

改属性

选中一个元素,右边会自动生成对应的属性表单。不同元素类型表单不一样——文字元素有字号/颜色/对齐/换行;表格元素有二维表头编辑器、尾行汇总;图片元素有填充模式、圆角。拖拽元素或缩放元素的时候不会拆掉你正在输入的那个文本框——这是细节但很重要。

右键菜单(别忽视了)

选中元素右键:副本(Ctrl+D)、删除、上移/下移/置顶/置底、水平/垂直居中、适合窗口、100%、旋转纸张、自定义纸张尺寸。

模板 JSON 面板(底部那个可以展开的)

展开后你能看到整个模板的 JSON——改完点 「应用 JSON」(或 Ctrl+Enter)替换模板。这个面板也能用来粘 hiprint 的 JSON——把 hiprint 设计器里 getJson() 返回的那个 {"panels":[…]} 原样粘进去,点应用,CrossPrint 会自动识别出 hiprint 格式并转换。

快捷键(记不住也没关系,鼠标都能点)

按什么 干啥
方向键 1mm 微调(按住 Shift 变 10mm、按住 Ctrl 变 0.1mm)
Ctrl+D 复制当前选中的元素
Delete 删掉
Esc 取消拖拽 / 清除选择
F 整页缩放到刚好塞满窗口
0 恢复 100%
Ctrl + 鼠标滚轮 缩放画布
鼠标中键拖动 平移画布(适合放大以后看细节)
Ctrl+Enter(在 JSON 面板里) 应用你改完的 JSON

JS 脚本(formatter / styler)——能跑什么、不能跑什么、给你一堆例子

这是最常被问到的部分。先说结论:

能跑业务逻辑:for/while/if/数组遍历/对象操作/正则表达式/闭包/递归/内置 Math、Date、JSON……JS 常规能力都有。不能碰外部世界:没有文件、没有网络、没有 DOM、没有 console.log、没有 C# 对象访问。这是一个纯沙箱。

CrossPrint 用 Jint(纯 .NET 实现的 JS 引擎)跑这些脚本。和 hiprint 的 formatter/styler 语义完全一致——如果你在 hiprint 里已经写过这些脚本,粘过来直接跑,不用改。

两种脚本:formatter 和 styler

formatter —— 改显示内容。接收绑定字段的原始值,返回你想显示的字符串。

styler —— 改样式。根据绑定字段的值返回样式对象(可以是 JS 对象,也可以是 CSS 字符串),比如"金额超过 1000 的那格标红加粗"。

脚本签名(参数到底传了什么)

元素级脚本(文本、条码、二维码):

function(value, options, target, templateData) { ... }
参数 是什么
value 这个元素绑定的字段的原始值。比如你绑定了 order.total,那这里就是订单总金额的数字。
options { id: "el_123", type: "text" } —— 元素自己的 id 和类型
target 和 options 一模一样(兼容 hiprint 的签名)
templateData 整份打印数据!可以点取 templateData.customer.name、templateData.order.items……想查啥查啥。

表格列级脚本(表格里每一列都可以有自己的 formatter/styler):

function(value, row, index, options, templateData) { ... }

比元素级多了两个——row 是当前行的完整对象(你可以点 row.product.name),index 是当前第几行(0 起)。

能用哪些 JS 特性

✅ 有:变量、if/else、for/while/do、switch、数组(map/filter/reduce/find/slice/splice 全有)、对象、函数、箭头函数、闭包、递归、正则表达式、解构赋值、展开运算符、模板字符串、Math.*(floor/ceil/round/random/pow/sqrt/sin/cos…)、Date(但没法拿系统时间,只能用传入的数据构造)、JSON.parse / JSON.stringify

❌ 没有:fetch、XMLHttpRequest、fs、require/import、window、document、console(hiprint 里本来也没有)、setTimeout/setInterval(打印是同步的,不允许异步)、new Date() 不带参数时不会给你当前时间、任何 CLR(C#)类型的实例化或访问——Jint 默认不开放 CLR 互操作

安全约束(这些不是 bug,是故意这样的)

约束 值 为什么
单次执行超时 250ms 打印不能因为一个死循环卡 10 秒
最大语句数 100,000 防止 while(true){} 绕开超时
最大递归深度 64 层 防止递归爆栈
脚本缓存 256 条 LRU 同一份脚本源码第二次执行不用重新解析

超了会怎么样? 什么都不会发生——脚本被跳过,元素显示原始值/默认样式,报告里记一条警告。渲染永不中断。你不会看到"脚本超时导致整页打印失败"这种鬼事。

一堆真实能用的脚本示例

好,看代码。


示例 1:formatter——金额格式化

function(value) {
    if (value == null || value === '') return '¥0.00';
    // value 可能是数字也可能是字符串
    var n = typeof value === 'number' ? value : parseFloat(value);
    if (isNaN(n)) return String(value);
    return '¥' + n.toFixed(2).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
}
// 输入: 1234567.8  → 输出: "¥1,234,567.80"
// 输入: null       → 输出: "¥0.00"
// 输入: "hello"    → 输出: "hello"(数字解析失败就原样返回)

示例 2:formatter——日期格式化(绑定值是 ISO 字符串)

function(value) {
    if (!value) return '';
    var d = new Date(value);
    if (isNaN(d.getTime())) return String(value);
    var y = d.getFullYear();
    var m = String(d.getMonth() + 1).padStart(2, '0');
    var day = String(d.getDate()).padStart(2, '0');
    return y + '年' + m + '月' + day + '日';
}
// 输入: "2026-11-02T08:30:00Z"  → 输出: "2026年11月02日"

示例 3:formatter——根据模板数据联动

一个元素绑定了 item.discount(折扣,比如 0.15 代表 15%),想在文字里同时显示原价和折后价:

function(discount, options, target, templateData) {
    // templateData.order.originalPrice 是原价
    var original = templateData.order.originalPrice || 0;
    var disc = typeof discount === 'number' ? discount : parseFloat(discount) || 0;
    var final = original * (1 - disc);
    return '原价 ¥' + original.toFixed(2) + ' → 折后 ¥' + final.toFixed(2);
}
// 显示: "原价 ¥100.00 → 折后 ¥85.00"

示例 4:styler——金额超过 1000 的标红加粗

function(value) {
    var n = typeof value === 'number' ? value : parseFloat(value);
    if (!isNaN(n) && n > 1000) {
        return { color: '#c0392b', fontWeight: 'bold' };
    }
    // 返回 null / undefined / 空对象 → 不改变样式
    return null;
}

同一个 styler,也可以写成 CSS 字符串:

function(value) {
    var n = typeof value === 'number' ? value : parseFloat(value);
    if (!isNaN(n) && n > 1000) {
        return 'color:#c0392b;font-weight:bold';
    }
    return '';
}

两种写法效果一样,挑你顺手的。


示例 5:styler——状态徽章

订单状态字段('pending' / 'paid' / 'shipped' / 'cancelled'),想给每个状态不同的颜色:

function(value) {
    var map = {
        'pending':   { color: '#856404', backgroundColor: '#fff3cd' },
        'paid':      { color: '#0f5132', backgroundColor: '#d1e7dd' },
        'shipped':   { color: '#084298', backgroundColor: '#cfe2ff' },
        'cancelled': { color: '#842029', backgroundColor: '#f8d7da', textDecoration: 'line-through' },
    };
    return map[value] || null;
}

示例 6:表格列 formatter——序号列

表格里加一列"序号",不想让后端在数据里多塞一个字段:

function(value, row, index) {
    return String(index + 1);
}
// value 是空的(因为这列没绑定字段),row 是当前行,index 从 0 开始

示例 7:表格列 styler——第 3 行开始标灰

function(value, row, index) {
    if (index >= 2) {
        return { color: '#999999' };
    }
    return null;
}

示例 8:formatter——条形码数字自校验(EAN-13)

function(value) {
    if (!value || value.length !== 13 || !/^\d+$/.test(value)) return value;
    // EAN-13 校验算法,算对了原样返回,算错了标红提示
    var sum = 0;
    for (var i = 0; i < 12; i++) {
        sum += (i % 2 === 0 ? 1 : 3) * parseInt(value[i], 10);
    }
    var check = (10 - (sum % 10)) % 10;
    if (check === parseInt(value[12], 10)) return value;
    return value + ' ⚠️';  // 校验位不对就加个警告符号
}

styler 能返回哪些样式属性

JS 对象形态(camelCase)和 CSS 字符串形态(kebab-case)都能。完整列表:

JS 对象键 CSS 等价 例子
color color '#ff0000' 或 'red'
backgroundColor background-color '#f5f5f5'
fontSize font-size '12pt' / '16px' / '4.2mm'(无单位按 px 算)
fontWeight font-weight 'bold' / 'normal' / '700'(≥700 就算粗体)
fontStyle font-style 'italic' / 'normal'
textDecoration text-decoration 'underline' / 'line-through' / 'none'(可同时写 'underline line-through')
letterSpacing letter-spacing '2pt'
lineHeight line-height '1.5'(无单位倍数)
textAlign text-align 'left' / 'center' / 'right' / 'justify'
verticalAlign vertical-align 'top' / 'middle' / 'bottom'
padding padding '2mm 4mm'(简写,支持 1-4 个值)
paddingLeft / Top / Right / Bottom padding-* '2mm'
borderColor border-color '#333'
borderWidth border-width '0.5mm'
borderStyle border-style 'solid' / 'dashed' / 'dotted'

不认识的键会被静默忽略——和 CSS 容错一个口径,不会因为写了个 typo 就炸。

返回值约定

返回 formatter 效果 styler 效果
字符串 替换显示文本 解析为 CSS 样式
JS 对象(styler) —— 解析为样式
null / undefined 保留原值 不改变样式
数字 / 布尔 String() 后替换显示 ——
异常 保留原值 + 报告记警告 不改变样式 + 报告记警告

最后那个异常很重要——如果你的脚本语法写炸了或者跑起来抛异常,CrossPrint 不会让整页变成空白,只会当这个脚本不存在,用原始值画出来,然后在渲染报告里写清楚是什么错了(TypeError: value.toFixed is not a function 这种)。你可以在设计器底部的状态栏看到这些警告。


hiprint 模板导入——支持什么、不支持什么

先说最爽的部分:90% 的 hiprint 模板丢进来直接用,不需要改。几何(pt→mm 自动换算)、元素类型、数据绑定、formatter/styler 脚本、表格二维表头、条码、二维码——全支持。

下面说的是那剩下 10%。不支持的能力不会被静默丢弃——导入器会在结果里列一条问题清单,告诉你"这里原来有个 HTML 元素,CrossPrint 用占位框代替了",绝对不会悄悄吃掉你花了一下午画的东西。

支持的 hiprint 元素和属性(完整清单)

hiprint 元素类型 CrossPrint 里变成什么 备注
text / longText TextElement pt 自动转 mm;fontSize 转 pt;formatter/styler 脚本原样保留
hline / vline LineElement borderWidth / borderStyle / borderColor 全支持
rect / oval RectangleElement / EllipseElement border 统一样式(不支持分边线型);backgroundColor 填充
image ImageElement 识别 data URL(含 SVG)、裸 Base64、直接粘贴的 <svg…> 源码、http(s) 外链;其余本地路径/业务键需要宿主提供 IImageResolver,否则渲染成占位框
table / tableCustom(旧版) TableElement 二维表头 colspan/rowspan 全部展开;扁平 fields 数组也能读;每列的 formatter/styler 脚本保留
barcode BarcodeElement 10 种码制全覆盖:Code128、EAN-13、EAN-8、UPC-A、UPC-E、ITF、Codabar、Code39、Code93、MSI
qrcode QrCodeElement 四种纠错等级 L/M/Q/H;码下标题(caption)+ 对齐 + 字体
html RectangleElement(虚线框占位) 不渲染 HTML,画一个虚线灰色框告诉你这里原来有个 HTML 元素

支持的 hiprint 面板级属性

hiprint 属性 CrossPrint 处理方式
width / height 面板尺寸(mm),自动匹配预设纸张(A4 等)或标记为 Custom
panelPageRule: "none" 标记为连续纸(高度 0,跟随内容长度)
paperHeader / paperFooter 转换为可打印区留白(上下 margins)
formatter / styler(元素级) 原样入库,渲染期由 Jint 执行
testData 收集为设计态预览数据,画布上绑定字段显示测试值
transform: "rotate(Ndeg)" 提取 N 作为元素旋转角度
zIndex 直接映射
qrCodeLevel / qrcodeLevel 0→L, 1→M, 2→Q, 3→H
barcodeType / barcodeMode 10 种码制映射
borderRadius(rect/oval) 直接映射为圆角
textAlign / textContentVerticalAlign 映射为 HorizontalAlign / VerticalAlign
textContentWrap nowrap/clip → 不换行;ellipsis → 不换行+省略号;其他 → 自动换行
contentPadding / contentPaddingLeft … 映射为 TextOptions 四个内边距
textDecoration underline / line-through 支持;overline 不支持
fit(image) contain / cover / fill / none 全支持;scale-down 按 contain 处理
columns(table) 二维表头展开;支持扁平数组 [{title, field, width}]
fields(table,旧写法) 单行列定义
rowspan / colspan 直接展开到网格
tableSummary / tableSummaryTitle / tableSummaryText / tableSummaryNumFormat / tableSummaryColspan 全部支持,尾行汇总
checked: false 标记为隐藏列,导入时忽略
tableTextType 影响表头单元格文本处理(保持原样)
水印 watermarkOptions 图片水印 → 覆盖整页的最底层图片元素;文字水印 → 最底层低灰度居中文本元素。也可用 CrossPrint 原生平铺文字水印(模板字段 watermark,设计器纸张面板可配置)
页码 paperNumber* 启用自动页码脚注(模板字段 paperNumber,每页「第 X / Y 页」,与手工绑定 {{pageNo}}/{{pageCount}} 的文本元素可并存)
长文本自动续页 longText 内容超出元素框自动续到下一页,后面元素顺延
强制分页 pageBreak 通用分页:本元素之后强制分页
按页选择性打印 showInPage / unShowInPage 通用分页:按页显示/过滤
每页重复打印 fixed 通用分页:每页重复(页眉/页脚/常驻水印)

不支持的 hiprint 能力(导入时会告警)

hiprint 能力 会发生什么 严重级别 替代方案
面板打印偏移 leftOffset/topOffset 忽略 ⚠️ Warning CrossPrint 不支持整张纸偏移
HTML 元素 变成虚线灰色占位框 ⚠️ Warning 改成文本 + 图片 + 表格组合
插件自定义元素 跳过(整张元素消失) ⚠️ Warning 用内置元素重画(或 HiprintCustomElementRegistry 注册转换器)
条形码固定模块宽 barWidth 等比拉伸到元素宽度(扫描不受影响) ℹ️ Info ——
图片外链 URL(非 data:) 需要宿主提供 IImageResolver,否则占位框 ℹ️ Info 要么转 base64 内嵌,要么实现 resolver
表格级 formatter/styler 丢掉(只保留列级) ℹ️ Info 用列级脚本逐列处理
分组表头 {title, columns:[...]} 展开子列,丢失分组标题 ℹ️ Info 单行表头没有分组概念
多面板模板 一次只导入一个面板(第 0 个) ℹ️ Info 用 HiprintImportOptions.PanelIndex 逐个导入
非 rotate 的 transform 忽略 ℹ️ Info 只支持 rotate(Ndeg)
分边线型 borderLeft / borderTop … 统一成一套描边 ℹ️ Info ——
文本上划线 textDecoration: overline 忽略 ℹ️ Info ——
longTextIndent 忽略 ℹ️ Info ——

导入器能吃什么格式

四种格式都行,不用挑:

  1. 严格 JSON——{"panels":[{"width":210,"height":297,"printElements":[...]}]}
  2. hiprint getJson() 输出——{"json":{"panels":[...]}}(外面包了一层 json 键)
  3. JS 对象字面量——{ panels: [{ width: 210, printElements: [...] }] }(没加引号的键也认)
  4. 整个 .js 模块文件——export const json = {...} 或 module.exports = {...} 都能扒出来
using CrossPrint.Core.Hiprint;

var result = HiprintTemplateImporter.Import(File.ReadAllText("my-hiprint-template.js"));

var template = result.Template;                  // 交给设计器 / 渲染 / 打印
foreach (var issue in result.Issues)             // 遍历所有降级/忽略告警
    Console.WriteLine(issue);

// result.Panels 里是源模板所有面板的概要——如果有多个面板(多联单),
// 可以告诉用户选哪一个,然后用 PanelIndex 分别导入

模板格式——你自己写模板也可以

单位

全部毫米(WidthMm、XMm、YMm、WidthMm…),字体全部磅(SizePt)。没有像素,不需要管 DPI,不会出现"我在 96dpi 机器上画 100px 到 300dpi 打印出来不是一回事"这种坑。

数据绑定

文本元素里写 {{order.customer.name}},运行时自动从数据对象里取值。表格写 table.field: "items" 就从 data.items 数组展开每一行。

数据源可以是:

  • 任意 POCO(普通 C# 对象,属性/字段都认,大小写不敏感)
  • Dictionary<string, object?>
  • System.Text.Json 的 JsonElement / JsonNode

绑定失败不抛异常——值替换为空串,报告里记一条"字段 xxx 找不到"。

模板 JSON 最小示例

这是一个只有 A4 纸 + 一个文本元素 + 一个表格的最小模板:

{
  "paper": { "preset": "A4", "widthMm": 210, "heightMm": 297, "orientation": 0 },
  "margins": { "topMm": 5, "bottomMm": 5, "leftMm": 5, "rightMm": 5 },
  "elements": [
    {
      "id": "title",
      "typeKey": "text",
      "xMm": 10, "yMm": 8, "widthMm": 80, "heightMm": 10,
      "text": { "content": "销售单 No.{{orderNo}}", "fontSizePt": 18, "bold": true }
    },
    {
      "id": "items",
      "typeKey": "table",
      "xMm": 10, "yMm": 25, "widthMm": 190, "heightMm": 80,
      "table": {
        "field": "items",
        "columns": [
          { "title": "序号", "formatter": "function(v,r,i){return i+1;}" },
          { "title": "商品", "field": "name" },
          { "title": "单价", "field": "price",
            "formatter": "function(v){return '¥'+(+v).toFixed(2);}",
            "styler": "function(v){return +v>1000?'color:#c0392b;font-weight:bold':null;}" },
          { "title": "数量", "field": "qty" },
          { "title": "小计", "formatter": "function(v,r){return '¥'+((+r.price)*(+r.qty)).toFixed(2);}" }
        ]
      }
    }
  ]
}

最低框架要求

组件 目标框架 备注
CrossPrint.Core / Engine / Designer / Printing net8.0; net461 双目标;net461 侧依赖 Jint 3.1.6 与 System.Text.Json 6.0.9 的 netstandard2.0 目标
CrossPrint.I18n net8.0 / netstandard2.0 / net461 三目标,net461 宿主也能引用
CrossPrint.Hosts.Avalonia net8.0 Avalonia 11.x 要求
CrossPrint.Hosts.Wpf net8.0-windows
CrossPrint.Hosts.WinForms net8.0-windows
CrossPrint.Hosts.Eto net8.0
CrossPrint.Hosts.WinUi net8.0-windows10.0.19041.0
CrossPrint.Hosts.Uno net8.0-desktop
CrossPrint.Hosts.Maui net8.0-windows10.0.19041.0 仅 Windows 目标

核心层与 I18n 提供 net461 目标,方便老 WPF/WinForms 项目直接引用;七个宿主适配层统一走 .NET 8。 net461 侧编译时,System.Memory 等 4.6.x 传递包会给出"未针对 net461 测试"的 TFM 警告(不阻断构建); 其运行时行为以 .NET 8 为准,CI 与完整测试套件只覆盖 net8.0。

界面语言

所有样例共用 CrossPrint.I18n 的内嵌中英文资源(Strings.zh-CN.json / Strings.en-US.json)。 启动时按 环境变量 CROSSPRINT_LANG → 程序目录 ui-culture.txt → 操作系统语言 的顺序确定界面语言; 在菜单的语言 / Language里可以切换"跟随系统 / 中文 / English",选择会写入 ui-culture.txt 并自动重启程序生效(界面文字在窗口构造时固定,重启比给每条标签做可重入绑定更可靠)。

# 临时指定,不落盘
$env:CROSSPRINT_LANG = "en-US"

在线示例怎么部署

Avalonia Browser 样例编译出来是纯静态文件(大约 40MB,第一次加载要等 .NET WASM 运行时加载完),扔到任何静态托管就行:

dotnet workload install wasm-tools
dotnet publish samples/CrossPrint.Samples.Avalonia.Browser -c Release
# 产物在 samples/CrossPrint.Samples.Avalonia.Browser/bin/Release/net8.0-browser/publish/wwwroot

子路径部署(比如 GitHub Pages 的 /OODD.CrossPrint/)——仓库里已经在 index.html 设好 <base href="./"> 了,不用你改。

仓库自带 GitHub Actions workflow(.github/workflows/pages-demo.yml),push 到 main 自动发布。


已知限制(最后再讲一遍,避免踩坑)

  • 二维码静区按 4 模块绘制。极少数扫码器特别严格的话可能有问题——但大部分手机扫没问题。
  • 表格跨页与长文本续页是自动的,普通元素不是——表格数据行超高一页装不下会自动切窗口续页,longText 溢出会续排;但普通元素(矩形、图片……)摆到纸外就是被裁掉,没有"整体元素自动挪到下一页"的通用排版。
  • 原生水印是平铺文字——模板字段 watermark(设计器纸张面板可配置)。图片水印没有原生平铺能力,用覆盖整页的最底层图片元素代替。
  • 图片大小是固定的,不会自适应宽高——图片元素的 WidthMm / HeightMm 由模板(设计器里手动拖框)固定,ImageFitMode(Contain / Fill / Cover / None)只决定图片在这块固定框里怎么缩放绘制,绝不会按图片原始尺寸回改元素宽高、也不会随内容自动增高。想让图片变大就改元素尺寸。
  • 图片资源有固定上限(超限直接跳过并记渲染告警,不降采样、不改尺寸):单文件字节 ≤ 32 MB;解码后总像素 ≤ 16,000,000(约 4000×4000);解码后单边 ≤ 8192 px。字节小但解出来是几亿像素的畸形 PNG 会在解码后被拒收,避免渲染线程 OOM。常量见 ImageAcquisition.MaxBytes / MaxDecodedPixels / MaxDecodedSide。
  • SVG 支持的五种填法与「图标级」子集——「内嵌图片」/「图片资源值」可填:data:image/svg+xml;base64,…、百分号编码的 data:image/svg+xml,…、SVG 字节的裸 Base64、https://…/logo.svg 外链,以及直接粘贴的 <svg…>…</svg> 源码文本(字段绑定值、表格图片列单元格、hiprint 导入的 src 同样支持)。引擎按元素框尺寸走内置矢量光栅器,不引第三方 SVG 库;带 UTF-8 BOM、XML 声明或前置注释也能解析。⚠ 只实现图标级子集(形状 / 分组 / use / text / transform / 样式 / 渐变 / viewBox),不支持 filter、feDropShadow、clipPath、mask、pattern、textPath、marker:例如带 <filter id="shadow"> 的窗户 SVG 会正常画出窗框和四个窗格,但阴影被忽略(其余图形照常绘制,不是解析失败)。想要阴影请改用半透明矩形自行叠加。
  • 超长文本有固定护栏——单元素内容 ≤ 200,000 字符、折行 ≤ 20,000 行、单行 ≤ 8,000 字符,超出截断并在渲染报告记 TextTooLong。想完整打印长文请勾「内容超出自动续页」(continueOnOverflow)并开通用分页,或用表格/多条文本元素拆分。常量见 TextRenderer.MaxContentChars / MaxLines / MaxCharsPerLine。
  • 表格列图片的数据类型可显式声明——TableColumn.CellImageSource(设计器「图片数据类型」下拉,仅「渲染方式 = 图片」的列可见):Auto(默认,自动识别 data: URI / 裸 Base64 / http(s) 外链 / 宿主 IImageResolver 资源键,旧模板零迁移)、Url(链接图片)、Base64(Base64 图片)。显式指定后按该类型强制解析,类型不符只记 ImageSourceMismatch 渲染告警并跳过该格,不会悄悄当成另一种类型处理。它只决定「单元格值怎么解释」,也不做图片跨页;图片/码的绘制尺寸另由 CellContentWidthMm / CellContentHeightMm 控制(见下条)。
  • 表格单元格图片/码有固定内容尺寸护栏——渲染方式为「图片 / 一维码 / 二维码」的列可用「内容宽 (mm)」「内容高 (mm)」(TableColumn.CellContentWidthMm / CellContentHeightMm,默认 0 = 跟随单元格):按声明尺寸居中绘制,恒夹在单元格内,硬上限宽 210 mm / 高 100 mm(TableColumn.MaxCellContentWidthMm / MaxCellContentHeightMm);「内容高」同时作为该列的行高下限。关键是防撑爆:非文本列的绑定值不再参与文本折行测量,几十 KB 的 data: URI / 裸 base64 不会被折成上百行把行高、连续纸页高、打印单拉成长卷;载荷原样交给图片/码渲染器。旧模板缺省 0,绘制尺寸不变。
  • 连续纸水印会跟着纸长往下铺——连续纸是「一页很长」(不分页),表格按内容自动增高后页高 = 最底元素下缘 + 2 mm;水印为斜纹网格平铺,纵向行数直接由这个增高后的页高决定,不是固定在模板设计的 Y 上、也不是只在首页画一枚。PDF / GDI / PDF 文件 / PNG 四条出图链路都用增高后的同一份工作模板算纸盒与位图(PNG 此前按未增高模板裁切长单,已修)。设计态画布预览仍按设计高度显示,不随内容增高——预览显示设计尺寸是既定边界。
  • WASM 版没有文件对话框(浏览器安全沙箱),hiprint 导入走底部的模板 JSON 面板粘贴。
  • 复杂脚本(阿拉伯文 / 天城文 / 藏文)在 Linux 上可能要自己点名原生库——引擎用 HarfBuzz 做连字与词形式(词首/词中/词尾)替换,HarfBuzzSharp 的托管包只把 Win32/macOS 原生库写成自己的依赖。Avalonia 宿主不用管(Avalonia.Skia 会间接带上);纯库消费方(控制台、WPF/WinForms/Eto/WinUI/Uno/MAUI)在 Linux 上给宿主应用加一行 <PackageReference Include="HarfBuzzSharp.NativeAssets.Linux" />。缺它不报错,但阿拉伯文会退回"每个字母都是独立形式",看着像坏了又没抛异常。取证与四条口径见 docs/rendering-spec.md §3.3。
  • .NET Framework 4.x 只在核心层——Core / Engine / Designer / Printing / I18n 提供 net461 目标(Jint 3.1.6 与 System.Text.Json 6.0.9 都有 netstandard2.0 目标),但七个宿主适配层统一要求 .NET 8(Avalonia 11 / WinUI 3 / MAUI 8 本身就不支持 net461)。net461 目标只保证编译兼容,测试与 CI 覆盖的是 net8.0。

文档

许可

Apache License 2.0。不引入 AGPL 或商业授权依赖。

About

一个纯 .NET 原生、JSON 驱动的跨平台打印模板设计器与渲染引擎。类似 hiprint 的可视化模板设计体验,但为 .NET 桌面生态而生,支持 Avalonia、WPF、WinForms 、Eto.Forms、Uno Platform、WinUI宿主,同一套渲染代码保证"所见即所印"。

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages