资源管理站

QSL 卡片制作工具网络版:一个业余无线电爱好者的全栈实践

zyglz 130 0

特别声明:本文为原创,可自由转载、引用,但需署名作者且注明文章出处,如有侵权请联系!

QSL 卡片制作工具网络版:一个业余无线电爱好者的全栈实践

封面:QSL卡片制作工具

从本地 HTML 到 Cloudflare 全栈部署,一个人、一个文件、一套完整的 QSL 卡片制作与同步方案。

一、开发背景

作为一名业余无线电爱好者(BG9PZK),每次通联后都需要制作 QSL 卡片寄给对方。传统的 QSL 卡片制作要么依赖专业软件,要么用 PS 手动排版,效率低且难以在多设备间同步配置。

通联后一键出卡

于是我决定自己动手,用最纯粹的技术栈——单个 HTML 文件 + Cloudflare Worker——打造一个开箱即用、支持多端同步、可 API 调用的 QSL 卡片制作工具。

为什么选择单 HTML 文件?

  • 零依赖:不需要数据库、不需要后端框架,打开浏览器就能用
  • 易部署:扔到任何静态托管(GitHub Pages / Cloudflare Pages / 本地文件)即可运行
  • 易维护:所有逻辑在一个文件里,改完直接上传
  • 离线可用:本地版完全离线,没网也能做卡片

二、实现功能

2.1 核心制作功能

功能说明
正反面编辑正面/背面独立编辑,一键切换
通联信息按格填写对方呼号、对方QTH、日期、UTC/北京时间、频率、RST、设备、功率、天线、寄语、操作员
确认类型OUR QSO / YOUR SWL REPORT / EYE QSO(单选)
工作模式FM / SSB / CW / FT8 / 自定义模式(单选+输入)
EYE QSO 快捷一键清空除日期时间外的所有通联内容,自动填入当前时刻
回卡请求PSE / TNX QSL / VY 73! 勾选显示
备用信息 1-4自定义名称和内容,传参即显示
UTC 自动换算UTC 与北京时间(UTC+8)自动互算
对方呼号自动大写输入时自动转大写
输入+下拉联想频率、RST、设备、功率、天线、寄语、操作员支持历史记录联想

2.2 图片与元素

功能说明
自定义底图上传本地图片或粘贴图片 URL,支持铺满/完整显示两种模式
画布尺寸自定义正反面独立设置导出分辨率(默认 1800×1200),支持按底图原始尺寸
电子签名上传签名图片,可控制正反面显示、拖动位置、滚轮调大小
呼号印章上传印章图片,同上
附加图片 A/B两张附加图,独立控制正反面显示
二维码输入内容自动生成二维码,可控制正反面显示、位置、大小;说明文字可独立设置位置、大小、背景色

2.3 个人信息与颜色设置

  • QTH / ADDR / PC / TEL / EMAIL / QQ / CQ / ITU / Grid,每项独立控制显示与否
  • 正面/背面文字颜色独立设置
  • 通联信息背景色、备用信息背景色、CQ/ITU/Grid 背景色独立设置
  • 对方呼号颜色自定义

2.4 模板管理

  • 存新模板 / 更新快照 / 重命名 / 删除 / 应用
  • 每个模板有唯一 ID,支持 ?tpl=模板ID 传参套用
  • 模板完整快照(含所有配置)

2.5 多端同步

多设备云端同步

分享版(未登录):

  • GitHub Gist 同步配置
  • 首次上传自动创建私有 Gist
  • 支持"含图片"同步选项(本地版保留)

个人版(登录后):

  • Cloudflare Access 邮箱认证登录
  • Cloudflare KV 同步配置
  • 自动加载个人底图、签名、印章、呼号、二维码默认值
  • 个人图片仅存 URL(环境变量),绝不写进 HTML 源码

2.6 API 接口

API批量出卡

  • /api/card:一键出卡,支持 GET/POST,传通联参数自动生成卡片
  • /api/sync:个人版配置云端同步
  • /api/me:登录态与个人配置查询
  • /api/notice:公告获取
  • 支持 auto=1 自动下载 PNG,side=both/both2 导出合并图或两张图
  • 完整参数文档:API 使用文档

2.7 其他

  • 自动保存:所有配置自动保存到浏览器 localStorage
  • 配置导入/导出:JSON 文件备份与迁移
  • 定位模式:快捷键 E 拖动元素、滚轮调字号、X 导出当前面
  • 恢复默认布局:一键还原所有元素位置
  • 系统公告:Worker 环境变量配置,页面顶部横幅显示
  • 使用说明:内置详细使用说明 + GitHub Token 获取教程

三、主要界面

3.1 主界面

  • 顶部:标题、公告横幅、AUTO-SAVE 状态、登录/退出按钮
  • 左侧:正面/背面切换、使用说明、确认类型/工作模式、通联信息表单
  • 右侧:实时预览、导出按钮、保存/导入配置、定位模式
  • 底部:个人信息与颜色设置、模板管理、在线同步

3.2 通联信息表单

按格填写,顺序清晰:对方呼号 → 日期时间 → 频率/RST → 设备/功率/天线 → 对方QTH → 寄语 → 操作员。

3.3 功能面板

折叠式面板,节省空间:回卡请求、电子签名、呼号印章、附加图片A/B、二维码、个人信息与颜色设置、背面底图、模板管理、在线同步。

3.4 效果展示(个人版)

登录个人版后,自动加载个人底图和配置,通联信息实时叠加显示在卡片上。

四、如何使用

4.1 快速上手(3 步出卡)

  1. 填通联信息:填写对方呼号、日期时间、频率等字段
  2. 预览确认:右侧实时预览,确认无误
  3. 导出:点"导出当前面"或"导出合并图"保存 PNG

4.2 登录个人版

  1. 点右上角"登录"
  2. 通过 Cloudflare Access 邮箱验证
  3. 自动加载个人配置(底图、签名、印章、呼号、二维码)
  4. 同步走 Cloudflare KV,多设备一致

4.3 GitHub 同步(分享版)

  1. 展开"在线同步"面板
  2. 填写 GitHub Token(获取方法)
  3. 点"上传":首次自动创建私有 Gist 并回填 Gist ID
  4. 换设备后填同样的 Token + Gist ID,点"下载"即可同步

4.4 API 一键出卡

https://qsl.ttdd.top/api/card?call=BG5XYZ&date=20260904&freq=145.5&mode=FM&auto=1

打开链接自动生成并下载 PNG 卡片。

五、技术实现

5.1 技术栈

  • 前端:纯 HTML + CSS + 原生 JavaScript(零框架、零构建)
  • Canvas 渲染:html2canvas 导出 PNG
  • 二维码:qrcode.js 纯前端生成
  • 后端:Cloudflare Worker(单文件 JS)
  • 存储:Cloudflare KV(个人版配置)、GitHub Gist(分享版配置)
  • 认证:Cloudflare Access(零信任邮箱认证)
  • 托管:Cloudflare Pages(静态 HTML)

5.2 隐私设计

  • 个人图片只存 URL:通过 Worker 环境变量注入,绝不写进 HTML 源码
  • 分享版完全脱敏:未登录时使用占位图,不含任何个人信息
  • 本地上传图片仅存本地:localStorage + 导出配置带图,不上传服务器
  • Cloudflare Access 保护:个人版端点仅本人邮箱可访问

六、部署方式

6.1 文件结构

/  (Cloudflare Pages 根目录)
├── index.html      ← 主页面(分享版+个人版合并)
├── api-doc.html    ← API 使用文档
└── _worker.js      ← Cloudflare Worker(或单独部署)

6.2 Worker 环境变量

变量说明
FRONT_IMG / BACK_IMG正反面底图 URL
SIG_IMG / STAMP_IMG签名/印章图片 URL
IMGA_IMG / IMGB_IMG附加图 A/B URL
MY_CALL我的呼号
QR_TEXT / QR_CAP二维码默认内容/说明
ANNOUNCEMENT系统公告

6.3 Cloudflare Access 配置

  • 创建应用保护 /api/me 和 /api/sync
  • 策略:仅允许本人邮箱
  • /api/card 和 /api/notice 保持公开

七、总结

这个项目从一个简单的本地 HTML 工具开始,逐步演进为支持多端同步、API 调用、个人/分享双模式的完整应用。整个过程中坚持几个原则:

  1. 单文件优先:能不拆就不拆,降低维护成本
  2. 隐私第一:个人信息绝不进公开源码
  3. 渐进增强:本地版离线可用,网络版锦上添花
  4. API 友好:所有功能都能通过参数调用,方便自动化

项目地址:https://qsl.ttdd.top
API 文档:https://qsl.ttdd.top/api-doc.html
呼号:BG9PZK · 73!

公众号

评论列表 (已有0条评论)

消灭零回复

发表评论 (已有0条评论)

icon_lol.gif2016zhh.gif2016fendou.gif2016lengh.gificon_exclaim.gif2016gg.gif2016yhh.gificon_cry.gif2016bs.gif2016qd.gif2016bz.gificon_eek.gif2016ka.gif2016zhem.gificon_confused.gif2016qq.gif2016db.gif2016jk.gif2016tuu.gif2016zk.gif2016kk.gificon_neutral.gif