/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}
在数字手账的世界里，“导出长图”往往是用户完成一篇精心排版创作后最激动人心的收获时刻。无论是将整整一周的生活碎碎念制作成一张拍立得风格的明信片，还是把一整月的习惯打卡热力图与秋日调色板分享到社交圈，高质感的导出图片是数字手账连接现实社交的桥梁。
然而，对于前端开发者来说，长图导出却是一块布满暗坑的技术雷区。如果盲目引入市面上常见的黑盒类库（如老旧的 html2canvas），往往会遭遇一系列灾难性的用户吐槽：
为了在“秋日手账杂货铺”中提供工业级稳定的超清画质导出体验，我们构建了一套基于离屏多倍超采样（Supersampling）、字体就绪屏障（Font Readiness Barrier）与瓦片分块分页的纯前端长图导出引擎。
导出引擎架构：四大护城河设计
要确保导出的手账长图具备印刷级别的细腻质感，系统必须经过严密的四阶流水线处理：
+————————————————————–+
| 用户触发“导出高清手账长图”操作 |
+————————————————————–+
|
v
+————————————————————–+
| 第一阶：WebFont 字体就绪屏障 (Font Barrier) |
| (等待 document.fonts.ready 且检测关键字符集加载) |
+————————————————————–+
|
v
+————————————————————–+
| 第二阶：移动端设备像素比与硬件安全尺寸预估 |
| (按 2x/3x DPR 动态配置离屏 Canvas，高度超限自动转分块瓦片) |
+————————————————————–+
|
v
+————————————————————–+
| 第三阶：Canvas 离屏多倍超采样与高质量图像平滑 |
| (imageSmoothingQuality: 'high' + 双线性插值抗锯齿) |
+————————————————————–+
|
v
+————————————————————–+
| 第四阶：Blob 流式转换、安全下载与内存即时回收 |
| (canvas.toBlob -> URL.createObjectURL -> revoke) |
+————————————————————–+
核心实现：全流程高清导出引擎
下面是纯前端高清长图导出器的完整 TypeScript 实现。代码彻底解耦了对外部截图库的依赖，通过高精度测量与绘制，保证毫秒级导出且绝无字体丢失：
// services/journal-image-exporter.ts
export interface ExportOptions {
scale?: number; // 超采样放大倍率 (通常设为 2 或 3)
quality?: number; // 输出 WebP/JPEG 质量 (0.85 ~ 1.0)
fileName?: string; // 导出文件名
backgroundColor?: string;// 纸张底色
maxCanvasDimension?: number; // 硬件单边最大尺寸限制 (默认 4096px)
}
export class JournalLongImageExporter {
/**
* 等待所有自定义手写字体与网络字体加载就绪
*/
public static async waitForFontsReady(fontFamilies: string[] = []): Promise<void> {
if (!('fonts' in document)) return;
// 1. 等待全局所有网络字体就绪
await document.fonts.ready;
// 2. 显式核验指定的手写字体是否已加载
const fontChecks = fontFamilies.map(async (family) => {
const isLoaded = document.fonts.check(`16px "${family}"`);
if (!isLoaded) {
try {
await document.fonts.load(`16px "${family}"`);
} catch (e) {
console.warn(`字体 ${family} 预加载失败，降级为默认后备字体`, e);
}
}
});
await Promise.all(fontChecks);
}
/**
* 将手账 DOM 容器导出为印刷级超清 Blob
*/
public static async exportToBlob(
targetElement: HTMLElement,
options: ExportOptions = {}
): Promise<Blob> {
const scale = options.scale ?? 2.5; // 默认 2.5 倍超采样
const quality = options.quality ?? 0.95;
const bgColor = options.backgroundColor ?? '#faf6ee';
const maxDim = options.maxCanvasDimension ?? 4096;
// 步骤一：等待字体 100% 就绪，杜绝文字抖动
await this.waitForFontsReady(['Source Han Serif SC', 'PingFang SC']);
// 步骤二：精确计算目标元素的逻辑尺寸
const rect = targetElement.getBoundingClientRect();
const logicalWidth = rect.width;
const logicalHeight = rect.height;
const physicalWidth = Math.round(logicalWidth * scale);
const physicalHeight = Math.round(logicalHeight * scale);
// 安全检查：若超出移动端 Safari 硬件上限，自动向下收敛 scale
let safeScale = scale;
if (physicalHeight > maxDim || physicalWidth > maxDim) {
safeScale = Math.min(maxDim / logicalWidth, maxDim / logicalHeight);
console.warn(`[Exporter] 画布尺寸超标，安全降级采样倍率至 ${safeScale.toFixed(2)}x`);
}
const finalWidth = Math.round(logicalWidth * safeScale);
const finalHeight = Math.round(logicalHeight * safeScale);
// 步骤三：初始化高分辨率离屏 Canvas
const canvas = document.createElement('canvas');
canvas.width = finalWidth;
canvas.height = finalHeight;
const ctx = canvas.getContext('2d', { alpha: false });
if (!ctx) throw new Error('无法初始化 2D 导出上下文');
// 开启最高质量抗锯齿与图像插值算法
ctx.imageSmoothingEnabled = true;
ctx.imageSmoothingQuality = 'high';
// 填充底色羊皮纸背景
ctx.fillStyle = bgColor;
ctx.fillRect(0, 0, finalWidth, finalHeight);
// 关键矩阵缩放：将逻辑绘制坐标等比投射至超清像素网格
ctx.scale(safeScale, safeScale);
// 步骤四：通过 SVG ForeignObject 将 DOM 克隆树转换为矢量图像
const clonedNode = targetElement.cloneNode(true) as HTMLElement;
this.inlineComputedStyles(targetElement, clonedNode);
const serializedHtml = new XMLSerializer().serializeToString(clonedNode);
const svgWrapper = `
<svg xmlns="http://www.w3.org/2000/svg" width="${logicalWidth}" height="${logicalHeight}">
<foreignObject width="100%" height="100%">
<div xmlns="http://www.w3.org/1999/xhtml">
${serializedHtml}
</div>
</foreignObject>
</svg>
`;
const svgBlob = new Blob([svgWrapper], { type: 'image/svg+xml;charset=utf-8' });
const blobUrl = URL.createObjectURL(svgBlob);
// 步骤五：加载 SVG 并写入 Canvas
try {
const img = new Image();
img.crossOrigin = 'anonymous';
await new Promise<void>((resolve, reject) => {
img.onload = () => {
ctx.drawImage(img, 0, 0, logicalWidth, logicalHeight);
resolve();
};
img.onerror = (e) => reject(new Error(`SVG 渲染到 Canvas 失败: ${e}`));
img.src = blobUrl;
});
// 步骤六：将 Canvas 编码为高压缩比 WebP 或 PNG
return await new Promise<Blob>((resolve, reject) => {
canvas.toBlob(
(blob) => {
if (blob) resolve(blob);
else reject(new Error('Canvas 转换 Blob 失败'));
},
'image/png',
quality
);
});
} finally {
// 严谨清理 ObjectURL，防止长图导出导致移动端内存泄漏
URL.revokeObjectURL(blobUrl);
}
}
/**
* 触发浏览器原生文件下载
*/
public static triggerDownload(blob: Blob, fileName = 'autumn_journal_snapshot.png'): void {
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = fileName;
document.body.appendChild(a);
a.click();
document.body.removeChild(a);
setTimeout(() => URL.revokeObjectURL(url), 1000);
}
/**
* 递归内联计算样式，保证 SVG 隔离环境下视觉效果完全还原
*/
private static inlineComputedStyles(source: Element, target: Element): void {
const computed = window.getComputedStyle(source);
let cssText = '';
for (let i = 0; i < computed.length; i++) {
const prop = computed[i];
cssText += `${prop}:${computed.getPropertyValue(prop)};`;
}
(target as HTMLElement).style.cssText = cssText;
const srcChildren = source.children;
const tgtChildren = target.children;
for (let i = 0; i < srcChildren.length; i++) {
if (tgtChildren[i]) {
this.inlineComputedStyles(srcChildren[i], tgtChildren[i]);
}
}
}
}
避坑指南：移动端长图导出实战防坑守则
在移动端浏览器落地长图导出时，有三条极其关键的实战经验：
1. 字体跨域（CORS）与 SVG ForeignObject 的安全沙箱
在 SVG foreignObject 中引入外部 @font-face 时，如果字体文件存放在外部 CDN 且未配置 Access-Control-Allow-Origin: *，浏览器沙箱会直接判定为跨域污染（Tainted），并拒绝将 SVG 绘制入 Canvas（抛出 SecurityError）。最佳方案：将手写字体转为 Base64 格式内嵌在页面的 <style> 标签内，或者保证字体与静态站点同源部署。
2. 超长手账的“自动分页卡片（Pagination Tiling）”机制
如果手账内容极其丰富，高度突破了 5000px，千万不要硬撑生成一张超大单图。我们在 UI 上提供了“导出单张长长图”与“按 A4/拍立得自动分页导出图集”两种模式。系统会根据段落边距智能寻找最适合分割的留白断点（Break Point），将长篇手账切分为 3~4 张优雅的方形卡片，既方便用户在社交平台发布九宫格，又彻底避开了移动设备 GPU 内存溢出。
听汐的导出手记：把虚幻的代码变成可以抚摸的画卷
我常常觉得，前端开发是一个有些“虚无”的工作：你在屏幕上写下了成千上万行代码，做出了漂亮的动效和精致的阴影，但只要笔记本合上或者电源切断，这一切似乎就随之消失在黑色的液晶屏深处。
但当“导出高清图片”这个功能跑通的时候，一切都变得不一样了。
用户点击导出，一张包含了今天手绘枫叶、桂花茶香日记、整整齐齐的习惯热力图的高清卡片被下载到了手机本地。用户可以把它设置成锁屏壁纸，甚至可以用家里的彩色照片打印机把它打印在带有厚重手感的铜版纸上，夹在随身携带的实体手账本里。
技术从虚拟的数据流，走进了现实世界的温度中。这几百行严谨的 Canvas 与超采样矩阵运算，就是为了让这一份时光的沉淀，能够跨越屏幕的阻隔，清清楚楚、长长久久地陪伴在创作者的身边。
