# OODD.CrossPrint
**Repository Path**: OODD-DevNet/OODD.CrossPrint
## Basic Information
- **Project Name**: OODD.CrossPrint
- **Description**: 一个纯 .NET 原生、JSON 驱动的跨平台打印模板设计器与渲染引擎。类似 hiprint 的可视化模板设计体验,但为 .NET 桌面生态而生,支持 Avalonia、WPF、WinForms、Eto.Forms、Uno Platform、WinUI 宿主,同一套渲染代码保证"所见即所印"。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-11-02
- **Last Updated**: 2026-11-13
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# OODD CrossPrint
一个跨平台 .NET 打印模板组件。**你只需要写一份模板、接一份数据、点一下"打印"**——剩下的事交给它。Avalonia、WPF、WinForms、Eto.Forms、WinUI、Uno、.NET MAUI,全部七宿主共用同一个渲染内核:画布上看到什么样,导出的 PDF 就是什么样,送进打印机还是什么样。**所见即所得,不玩两套渲染。**
已经在用 hiprint(vue-plugin-hiprint / Vue-Print-Designer)设计器了?太好了——**它导出的模板直接吃**,不需要重新画一遍。
> 模板里写的全是毫米和磅,没有像素这个坑。引擎画每一个像素,宿主控件只负责"把画布放到屏幕上"——这俩互不干扰。
**中文** | [English](README.en.md) · [在线示例(WebAssembly实话实说网页版的基本不能用,建议下载release中的桌面端)](https://oodd-devnet.github.io/OODD.CrossPrint/)
> **当前版本 1.1.0**(2026-11-09)· [更新日志](CHANGELOG.md) · [下载 Releases](https://github.com/OODD-DevNet/OODD.CrossPrint/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](CHANGELOG.md);升级包时所有 `OODD.CrossPrint.*` 与宿主包统一为 `1.1.0`。
---
## 先看一眼——设计器和打印长啥样
左边是设计器(Avalonia 宿主,跑的是"厨房水槽"模板——八种元素全上,连脚本都写上了)。右边是同一个模板的打印预览。两个窗口走同一条渲染路径,所以你在左边拖一下元素,右边立刻跟着变——不是"大概类似",是**像素级一致**。
想自己玩?上面的 **在线示例** 链接点进去就行,浏览器直接跑,啥都不用装。
---
## 快速开始——两条路选一条
### 路线 A:跑样例看看效果(推荐先玩这个)
需要 **.NET SDK 8.0 以上**。打开 PowerShell,cd 到仓库根目录,任选一行跑:
```powershell
# 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 宿主):
```powershell
dotnet add package OODD.CrossPrint.Core
dotnet add package OODD.CrossPrint.Engine
dotnet add package OODD.CrossPrint.Hosts.Avalonia
```
然后代码里这样用:
```csharp
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:
```csharp
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);
```
送进打印机:
```csharp
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](https://github.com/sebastienros/jint)(纯 .NET 实现的 JS 引擎)跑这些脚本。**和 hiprint 的 formatter/styler 语义完全一致**——如果你在 hiprint 里已经写过这些脚本,粘过来直接跑,不用改。
### 两种脚本:formatter 和 styler
**formatter** —— 改显示内容。接收绑定字段的原始值,返回你想显示的字符串。
**styler** —— 改样式。根据绑定字段的值返回样式对象(可以是 JS 对象,也可以是 CSS 字符串),比如"金额超过 1000 的那格标红加粗"。
### 脚本签名(参数到底传了什么)
**元素级脚本**(文本、条码、二维码):
```javascript
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):
```javascript
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——金额格式化**
```javascript
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 字符串)**
```javascript
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%),想在文字里同时显示原价和折后价:
```javascript
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 的标红加粗**
```javascript
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 字符串:
```javascript
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'),想给每个状态不同的颜色:
```javascript
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——序号列**
表格里加一列"序号",不想让后端在数据里多塞一个字段:
```javascript
function(value, row, index) {
return String(index + 1);
}
// value 是空的(因为这列没绑定字段),row 是当前行,index 从 0 开始
```
---
**示例 7:表格列 styler——第 3 行开始标灰**
```javascript
function(value, row, index) {
if (index >= 2) {
return { color: '#999999' };
}
return null;
}
```
---
**示例 8:formatter——条形码数字自校验(EAN-13)**
```javascript
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、直接粘贴的 `