gogcli 的 `gog calendar calendars` 命令详解：日历列表、分页机制与面向 Agent 的脚本化输出
2026/9/16 21:55:43
简介：HTML二维码生成源码包，面向需要快速实现二维码功能的Web前端开发者。基于原生JavaScript与jQuery编写，可根据任意网址内容实时生成二维码，并支持调整大小、颜色、样式等美化参数，让二维码更具视觉辨识度。代码逻辑独立，无需复杂依赖，打开HTML即可直接运行或预览效果。
包体共42个文件，约10.68MB，其中以JS脚本（21个）为核心，承担二维码生成与渲染逻辑；附有3个CSS样式文件和3个HTML演示页面，便于修改外观和快速上手；另含图片、字体图标及一个MP4演示视频，直观展示动态操作过程。目录结构清晰，内置readme说明，方便按需调用。
目前已有769人学习下载，适合个人站点链接推广、活动海报信息嵌入等场景，也可作为二维码功能二次开发的基础模板。
1. 为什么「html二维码生成」值得自己写一遍
带个输入框，点一下按钮，页面上就直接出现一张二维码，扫码后跳转到链接或者显示一段文本。这个功能看起来不大，真正落到 HTML 页面里却绕不开中文乱码、图片模糊、容器残留、白边太小这一堆细节；如果全部放在浏览器本地完成，不依赖后端、不请求第三方接口，一个静态文件就能跑起来。
二维码生成本质上是把文本变成点阵，然后在页面上把 0/1 矩阵渲染出来，这决定了它天然适合放在前端做。这篇内容就顺着「html二维码生成（附源码）」这条路径，把编码原理、页面实现、参数调优和批量输出的做法一次讲清楚。适合前端开发、技术运营以及做内部工具链的工程师直接拿来改。
2. 二维码生成没有图片引擎：HTML 里的绘制是「矩阵排版」
2.1 二维码图像从哪来：编码、纠错与掩码
二维码不是用绘图函数一笔一笔画出来的，它本质是一段文本经过编码、纠错、掩码三步处理后得到的 0/1 矩阵。编码阶段先把内容按模式切分：纯数字用数字模式，ASCII 字符用字母数字模式，中文等非 ASCII 内容用字节模式；每个模式有自己的位宽和容量，库会根据内容长度自动切换。紧接着是纠错码，QR 标准使用里德-所罗门码，容错级别越高，能修复的污损面积越大，但可存放的原始数据就越少。
最后一步是掩码。把矩阵和 8 种预设掩膜做异或，挑出黑白分布最均匀的一种，避免出现大面积同色块干扰扫码定位。完成这一套运算后，所有逻辑都落入一个二维数组，数组里 1 的位置画黑块、0 留白。整个「画图」过程其实就是遍历数组填格子，这也是在 HTML 页面里实现二维码生成的全部成本。
2.2 canvas / SVG / img：三种载体的取舍
前端渲染二维码，常见就三条路：用 canvas 画像素、用 SVG 输出矢量图、或者先用 canvas 生成再通过 dataURL 喂给 img。选型直接影响清晰度、下载方式和跨端传输的便利程度。
| 渲染载体 | 清晰度表现 | 资源依赖 | 适用场景 |
|---|---|---|---|
| table 布局 | 弱，单元多时 DOM 节点膨胀 | 无 | 早期实现，不推荐再用 |
| canvas | 像素图，放大易模糊 | 无 | 屏幕显示、实时更新 |
| SVG | 矢量，无限缩放不模糊 | 无 | 打印、高 DPI 大图 |
| img(dataURL) | 取决于生成时像素尺寸 | 无 | 下载、上传、跨端传递 |
实际开发里最常用的组合是：先用 canvas 绘制，随后通过canvas.toDataURL('image/png')生成 base64 字符串，再塞给 img 标签。这样既能在页面上预览，又能直接提交表单或触发下载，不需要额外的文件服务器。
2.3 依赖库怎么选
常见选择有两个：一个是 qrcode.js 风格，构造函数直接接受容器 DOM 和配置项，渲染过程全包；另一个是只输出矩阵的核心库，拿到 0/1 数组后由自己用 canvas 或 SVG 绘制。前者集成最快，后者适合需要完全自定义渲染的场景，比如电纸屏、嵌入式终端这类特殊环境。
我一般选前者，因为参数集中，页面集成快。用法也简单，下载一份 qrcode.min.js 放到 html 同目录，用 script 标签加载即可：
var qr = new QRCode(container, { text: 'hello', width: 256, correctLevel: QRCode.CorrectLevel.M });这种写法把容器、文本、尺寸集中在同一个配置对象里，比起先创建实例再单独调 setText 的老 API 直观很多，后面接表单、接批量逻辑都更容易扩展。
3. 最小可用的 html 二维码生成页面：源码结构与逐行解释
3.1 完整源码骨架
先给一个可以直接运行的页面，把它保存成index.html，再放一个qrcode.min.js在同目录，双击打开就能用：
<!doctype html> <html lang="zh-cn"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>HTML 二维码生成</title> </head> <body> <input type="text" id="text" value="hello" placeholder="输入链接或文本" /> <button id="btn">生成二维码</button> <div id="qr"></div> <script src="./qrcode.min.js"></script> <script> var qr = new QRCode(document.getElementById('qr'), { text: document.getElementById('text').value, width: 256, height: 256, colorDark: '#000000', colorLight: '#ffffff', correctLevel: QRCode.CorrectLevel.H }); document.getElementById('btn').onclick = function () { qr.makeCode(document.getElementById('text').value); }; </script> </body> </html>meta charset=utf-8 放在 head 最前面，保证中文输入在页面加载和表单取值时都不会乱码；lang="zh-cn" 对浏览器翻译功能和读屏工具更友好。页面逻辑只有三段：读取输入框的值、new 一个二维码实例、点击按钮时更新实例内容。
3.2 每个参数的作用与调整逻辑
| 参数 | 作用 | 调整建议 |
|---|---|---|
| width / height | 整体像素宽高 | 屏幕用 256，打印用 430 以上 |
| colorDark / colorLight | 前景色和背景色 | 黑配白最稳，浅色容易识别失败 |
| correctLevel | 纠错级别 L/M/Q/H | 贴 logo 用 H，内容长用 M |
| text | 二维码承载的内容 | URL、文本、联系方式都可以 |
new QRCode(el, options)把实例绑定到容器，初始化时渲染一次；之后更新内容调用makeCode(text)，不需要重建实例。qrcode.js 在 makeCode 时会清理容器中的旧绘制，所以单实例更新没有问题；但不同实例绑定同一个容器时容易出现双份节点，最稳的写法是始终只维护一个qr变量。
3.3 从 canvas 到 img：把生成结果变成可下载图片
QRCode 在支持 canvas 的浏览器里默认输出 canvas 节点，所以拿到容器里的 canvas，再导出 dataURL 就能得到一张可下载的 PNG：
var container = document.getElementById('qr'); var canvas = container.querySelector('canvas'); var img = new Image(); img.src = canvas.toDataURL('image/png'); var a = document.createElement('a'); a.href = img.src; a.download = 'qrcode.png'; a.click();toDataURL把当前 canvas 内容编码成 base64 的 PNG 字符串，浏览器把它当作图片源就能正常显示。a.download触发下载时会用指定文件名，不需要跳页或弹窗。这里有个前提：canvas 没有被跨域图片污染，否则toDataURL会抛 SecurityError；本地直接打开 html 没有跨域问题，部署到线上时如果绘制过跨域素材，需要给那些图片设置 crossOrigin 属性。
4. 调参、修坑、去掉 title：生产环境里真正要动的几个点
4.1 纠错级别、尺寸与颜色：按场景定参数
真实场景里二维码经常出现在易拉宝、快递单、投屏 PPT 上，参数不能一套走天下。纸质打印推荐 Q 级纠错，深色背景浅色图案的高对比方案；屏幕投屏则建议 H 级并放大整体尺寸。
| 参数 | 建议值 | 说明 |
|---|---|---|
| correctLevel | M 或 H | H 抗污损，M 容量大；内容超 200 字符时优先 M |
| width / height | 256 屏幕，430+ 打印 | 打印按 300 DPI 推算，尺寸不够会糊 |
| colorLight | #ffffff | 必须纯白，不能透明 |
| colorDark | #000000 | 深色最好，避免红色等浅色 |
| margin | 库默认 4 模块 | 没有该参数时用 CSS padding 补偿 |
我一般会预留「预览」和「下载」两个按钮：预览用小尺寸，下载用大尺寸，同一份数据通过 makeCode 重新生成即可，速度差异几乎感知不到。
4.2 中文与带参数链接的编码处理
页面 charset 设置为 utf-8 后，直接 makeCode 中文一般没问题，因为二维码库内部按字节模式编码 UTF-8 字符。真正容易踩坑的是 URL 带中文参数的情况：扫码后打开的地址可能保留原始中文，也可能变成百分号编码，取决于目标服务器的解析方式。最稳妥的做法是在拼接 URL 时主动 encodeURIComponent：
var url = 'https://example.com/search?q=' + encodeURIComponent('二维码'); qr.makeCode(url);另外像 apk 安装包分发这种场景，把下载地址直接生成二维码，扫码后手机浏览器就能开始下载；这类地址往往带 query 参数，生成时保证整串 URL 完整保留，不要截断。如果二维码内容是多行文本，扫码后 App 通常会按多行接收；需要传给后端时，记得把真实换行转成\\n再入参。
4.3 容器残留、缓存与模糊
生产环境里出问题最多的不是选型，而是这三个小地方。
容器残留：如果每次点击都 new 一个 QRCode 实例绑定到同一个 div，新码叠旧码，越点越乱。防御写法是 new 之前先执行container.innerHTML = ''，保证容器只属于当前一次渲染。
缓存：同一段文本生成的 dataURL 完全一样，浏览器认为 src 没变，onload 不触发，img 也不刷新。正确做法是重新调用 makeCode 重建内容，而不是在 dataURL 后面拼时间戳——base64 字符串不允许加查询参数，拼了也无效。更不要为了刷新把随机数写进二维码文本，那会让每次扫出来都是不同的内容。
模糊：canvas 是位图，在高 DPI 屏幕或放大打印时会发虚。常见做法是生成 512 或 1024 尺寸，再通过 CSS 把显示尺寸压到 256：
<img src="data:image/png;base64,xxx" style="width:256px;height:256px;" />这样二维码的实际像素密度比显示密度高，扫码时更容易识别。
4.4 页面 title 能不能去掉
很多人问 qrcode 生成的二维码图片能不能去掉 title。答案很直接：生成的二维码图片里根本没有 title，title 是 HTML 文档的属性，不进图片。会看到 title 的地方只有两个：生成器页面的浏览器标签栏，以及扫码后落地页的标题。落地页的 title 由对方服务器控制，你在当前页面改不了。
如果只是希望生成后截屏分享时标签栏显得干净，可以在截图前临时替换 document.title，截完再恢复：
function generateWithTempTitle(url, tempTitle) { var old = document.title; document.title = tempTitle || '二维码'; setTimeout(function () { qr.makeCode(url); // 截图逻辑放在这里 document.title = old; }, 0); }setTimeout 起一个宏任务，让浏览器先完成二维码绘制再执行截图；恢复 title 必须放在截图之后，否则抓到的还是旧标题。这个技巧只在当前页面生命周期内有效，刷新后 title 会回到 html 里写死的值。
5. 批量生成与扫码验证：把源码改造成内部工具
5.1 批量生成多个二维码
单页生成一个码只能算 demo，内部工具往往要一次生成几十个商品链接或工单编号。批量时不要复用单个容器，每次 new 一个独立 div，让每个实例持有自己的 canvas：
var list = [ 'https://example.com/item/1', 'https://example.com/item/2', 'https://example.com/item/3' ]; list.forEach(function (url) { var wrap = document.createElement('div'); wrap.style.display = 'inline-block'; wrap.style.margin = '8px'; new QRCode(wrap, { text: url, width: 256, height: 256, correctLevel: QRCode.CorrectLevel.M }); document.body.appendChild(wrap); });遍历时每个 wrap 都是新 DOM，实例绑定各自的容器，互不干扰，也就不存在清理问题。批量导出图片时，用document.querySelectorAll('#panel canvas')收集所有 canvas，再逐个 toDataURL 就能拿到完整列表。
再进一步可以把生成过程封装成一个返回 dataURL 的函数：
function qrDataUrl(text, size) { size = size || 256; var holder = document.createElement('div'); new QRCode(holder, { text: text, width: size, height: size, correctLevel: QRCode.CorrectLevel.M }); return holder.querySelector('canvas').toDataURL('image/png'); }调用方拿到字符串后可以塞进 img、提交表单或拼接下载列表，不需要关心 canvas 内部结构。做导出功能时，先让用户批量预览，再统一调用这个函数生成待下载列表，比一个一个生成再下载省事得多。
5.2 验证扫码结果的方法
参数怎么调，最终以真机扫码为准。第一轮用微信或系统相机扫屏幕，确认链接能打开、文本不串行；第二轮拉开 30cm 到 50cm 的距离再扫，验证最小识别尺寸；第三轮把二维码贴到 A4 纸上打出来，激光和喷墨各扫一次，看 colorLight 是否够白、白边是否够宽。打印后识别失败时，优先把纠错级别升到 H，并给容器加 4 个模块宽度的白色 padding，再考虑调大 width。
单个页面生成超过 50 个二维码时，DOM 节点数量会明显上升，建议分批渲染或分页处理。这套 html 二维码生成的源码，改动点都集中在 makeCode 的参数和容器策略上，后续接表单、接接口都从这两处扩展。
本文还有配套的精品资源，点击获取