# PrintService

**Repository Path**: mygule/PrintService

## Basic Information

- **Project Name**: PrintService
- **Description**: 本地 WebSocket 打印服务中间件 — 电商 ERP/WMS 免弹窗静默打印解决方案。浏览器通过 WebSocket JSON 协议提交 Base64 编码的图片或 PDF，后台调用 Windows 原生 Spooler API 直接打印，全程无对话框弹窗。支持多打印机选择、自定义纸张尺寸、FIFO 任务队列、实时状态跟踪、PDF/图片打印，适用于快递面单、物流标签、商品条码等批量打印场景。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-19
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 打印服务 (PrintService)

> **本地 WebSocket 打印服务中间件** — 免弹窗静默打印，浏览器通过 WebSocket 提交 Base64 图片/PDF，后台直接打印。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
![.NET 8](https://img.shields.io/badge/.NET-8.0-512BD4)
![Platform](https://img.shields.io/badge/Platform-Windows-blue)
![C#](https://img.shields.io/badge/C%23-12-239120)

---

## 解决的问题

电商 ERP、WMS 等 Web 系统在打印快递单、标签、面单时，通常需要弹出浏览器打印对话框或调用 ActiveX/NPAPI 插件。这些方案存在以下痛点：

- **浏览器打印弹窗** — 需要用户手动确认，无法批量自动化
- **ActiveX 仅支持 IE** — 现代浏览器已废弃 NPAPI
- **部署复杂** — 现有方案兼容性差、配置繁琐

## 解决方案

本组件在用户电脑上运行一个**本地 WebSocket 服务**，浏览器通过简单 JSON 协议提交 Base64 编码的图片或 PDF，服务端调用 Windows 原生打印 API **静默打印**，全程无弹窗。

```
浏览器 (JavaScript) ──WebSocket──► 打印服务 (WPF 桌面端) ──► Windows Print Spooler ──► 打印机
```

## 快速开始

### 前提条件

- Windows 10/11 x64
- [.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)（开发时需要）
- 一台已安装好的打印机

### 下载与运行

1. 从 [Releases](../../releases) 下载最新版本
2. 运行 `PrintService.exe`
3. 在系统托盘中右键图标 → **启动服务**
4. 在浏览器中通过 WebSocket 连接 `ws://localhost:16888` 即可提交打印任务

### 从源码构建

```bash
# 克隆仓库
git clone https://github.com/yourname/PrintService.git
cd PrintService

# 还原依赖
dotnet restore

# 构建
dotnet build -c Release

# 运行
.\src\PrintService\bin\Release\net8.0-windows\win-x64\PrintService.exe
```

## 浏览器端接入

```javascript
const ws = new WebSocket('ws://localhost:16888');

ws.onopen = () => {
    // 提交打印任务（Base64 图片）
    ws.send(JSON.stringify({
        action: 'print',
        printer: 'HP LaserJet MFP',
        type: 'image',
        paperSize: '100x150mm',
        copies: 1,
        // 你的 Base64 图片数据（支持 data:image/png;base64, 前缀）
        content: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ...'
    }));
};

ws.onmessage = (event) => {
    const resp = JSON.parse(event.data);
    if (resp.action === 'accepted') {
        console.log(`任务已提交: ${resp.jobId}`);
    } else if (resp.action === 'result') {
        console.log(`打印${resp.status === 'completed' ? '成功' : '失败'}: ${resp.message}`);
    }
};
```

## 功能特性

| 功能 | 说明 |
|------|------|
| 🚀 **免弹窗静默打印** | 直接调用系统打印 API，无任何对话框 |
| 🔗 **WebSocket 接口** | 标准 JSON 协议，任意语言/框架均可对接 |
| 🖼️ **Base64 图片打印** | 直接传递 Base64 编码的图片数据，无需临时文件 |
| 📄 **PDF 打印支持** | 支持 Base64 编码的 PDF 文件静默打印 |
| 📋 **任务队列管理** | FIFO 队列，实时状态跟踪 |
| 🖨️ **多打印机支持** | 自由选择打印机，自定义纸张尺寸 |
| ⚙️ **桌面 UI 管理** | 任务列表可视化，右键重打/删除 |
| 📎 **系统托盘常驻** | 后台运行，不干扰工作 |
| 📝 **结构化日志** | Serilog 记录，方便排查问题 |
| 🔓 **MIT 开源** | 免费使用，自由修改 |

## WebSocket 协议

完整协议文档请参阅 [docs/API.md](docs/API.md)。

### 核心动作

| 动作 | 方向 | 说明 |
|------|------|------|
| `print` | 浏览器 → 服务 | 提交 Base64 图片/PDF 打印任务 |
| `accepted` | 服务 → 浏览器 | 任务接收回执 |
| `result` | 服务 → 浏览器 | 打印结果推送 |
| `query` | 浏览器 → 服务 | 查询任务状态 |
| `get_printers` | 浏览器 → 服务 | 获取打印机列表 |

## 项目结构

```
PrintService/
├── src/PrintService/           # WPF 主项目
│   ├── Models/                 # 数据模型
│   ├── Services/               # 核心服务（打印引擎/队列/WebSocket）
│   ├── Protocol/               # WebSocket 协议解析
│   ├── ViewModels/             # MVVM ViewModel
│   ├── Views/                  # WPF 窗口
│   ├── Helpers/                # 辅助类（日志/配置）
│   ├── Tray/                   # 系统托盘
│   └── Resources/              # 样式和图标
├── tests/                      # 单元测试 (xUnit)
├── docs/                       # 文档
├── scripts/                    # 部署脚本
├── .github/workflows/          # CI 配置
├── .gitignore
├── PrintService.sln
└── README.md
```

## 技术栈

- **桌面框架**: WPF (.NET 8)
- **开发语言**: C# 12
- **WebSocket**: System.Net.WebSockets
- **打印引擎**: System.Drawing.Printing (PrintDocument)
- **日志**: Serilog + 文件输出
- **依赖注入**: Microsoft.Extensions.DependencyInjection
- **配置**: JSON 文件 (ConfigManager)
- **测试**: xUnit + Moq

## 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 提交 Pull Request

请确保添加/更新对应的单元测试。

## 开源协议

本项目采用 **MIT 协议** 开源，详见 [LICENSE](LICENSE)。