release: 发布 v0.4.5

新增能力:Web 与 Desktop 支持新建和保存 Markdown;桌面端注册 .md/.markdown 打开程序,支持单实例文件转交、自定义主题目录以及窗口位置、尺寸和最大化状态的延迟原子持久化与屏幕越界修正。

界面与兼容性:保留打开 Markdown 为独立主操作,将新建、保存和主题目录收纳到更多菜单;Web 移除本地素材目录入口并明确默认不支持本地素材;新文档默认使用一级标题或首行合法化生成文件名,可不保存直接导出 PDF。

渲染修复:图片、Mermaid 和 ECharts 按文档顺序串行执行媒体分页回填,每个媒体元素至多重排一次;图片以限宽后的高度作为缩放基准,只缩放媒体主体并保持标题尺寸;ECharts 冻结为 SVG 图片后参与统一分页。

示例与文档:默认示例仅保留一张网络图片,增加有效 Base64 横图、竖图、边界图片及多尺寸 Mermaid/ECharts;更新根 README、Desktop README、部署文档、四个 packages README、PROGRESS 和 AGENTS 发布规范;登记 v0.4.6 超链接导航问题。

部署与验证:构建并运行 yixiong/md-to-pdf:v0.4.5 正式镜像,Compose 健康且 PDF 冒烟无 Mermaid/ECharts 错误;生成 NSIS 安装包和免安装 ZIP,本机已升级到 NSIS v0.4.5 并清理旧 Squirrel 安装;202 项测试、类型检查、生产构建和 git diff --check 全部通过。

发布产物:Setup.exe SHA-256 9CBD6362E15AA745185805E753D5A7749434E0E142E6CE0F66463E6A19468F1D;ZIP SHA-256 97B2D44E72F626A3396E5AB5B330FFB7F9BECAF945A1707808C876940A82E850;当前 Windows 产物未配置代码签名。
This commit is contained in:
SkyJourney
2026-07-28 13:31:42 +08:00
parent ac54ce46be
commit 925b0d1485
35 changed files with 3125 additions and 603 deletions
+2 -2
View File
@@ -6,7 +6,7 @@ import {
describe("应用版本", () => {
it("从统一构建版本生成标题徽标", () => {
expect(APP_VERSION).toBe("0.4.4");
expect(APP_VERSION_LABEL).toBe("v0.4.4");
expect(APP_VERSION).toBe("0.4.5");
expect(APP_VERSION_LABEL).toBe("v0.4.5");
});
});
+62
View File
@@ -0,0 +1,62 @@
import { describe, expect, it } from "vitest";
import {
createMarkdownFileName,
deriveMarkdownBaseName,
ensureMarkdownFileName,
legalizeMarkdownBaseName
} from "../src/document-file";
describe("Markdown 默认文件名", () => {
it("优先使用 Front Matter 与代码围栏之外的一级标题", () => {
expect(
deriveMarkdownBaseName(`---
title: 元数据标题
---
第一行正文
\`\`\`markdown
# 围栏标题
\`\`\`
# 2026 年研发周报:第 31 周`)
).toBe("2026 年研发周报 第 31 周");
});
it("没有一级标题时使用第一行非空正文", () => {
expect(
createMarkdownFileName(
"\n\n> **本周完成** [API 重构](https://example.com)\n后续内容"
)
).toBe("本周完成 API 重构.md");
});
it("四字符围栏不会被较短的同类围栏提前关闭", () => {
expect(
deriveMarkdownBaseName(`\`\`\`\`markdown
# 围栏内标题
\`\`\`
# 仍在围栏内
\`\`\`\`
# 正文标题`)
).toBe("正文标题");
});
it("清理非法字符并规避 Windows 保留名称", () => {
expect(legalizeMarkdownBaseName('季度总结:<测试> / "版本"')).toBe(
"季度总结 测试 版本"
);
expect(legalizeMarkdownBaseName("CON")).toBe("文档 CON");
});
it("空文档使用回退文件名并限制名称长度", () => {
expect(createMarkdownFileName(" \n")).toBe("未命名文档.md");
expect(legalizeMarkdownBaseName("文".repeat(150))).toHaveLength(100);
});
it("保留已有 Markdown 扩展名", () => {
expect(ensureMarkdownFileName("报告.markdown", "# 报告")).toBe(
"报告.markdown"
);
expect(ensureMarkdownFileName("报告", "# 报告")).toBe("报告.md");
});
});
+26 -4
View File
@@ -8,6 +8,7 @@ describe("ECharts 单页高度适配", () => {
it("将超高 SVG 和宿主同步缩放到单页内容区", () => {
const root = document.createElement("div");
root.innerHTML = `
<h2 style="margin: 10px 0">大型图表</h2>
<figure class="md-echarts">
<div class="md-echarts-host" style="height: 2000px">
<svg width="1000" height="2000"></svg>
@@ -15,22 +16,43 @@ describe("ECharts 单页高度适配", () => {
</figure>
`;
fitOversizedEChartsToPage(root, defaultExportConfig);
const figure = root.querySelector<HTMLElement>(".md-echarts");
const title = root.querySelector<HTMLElement>("h2");
const host = root.querySelector<HTMLElement>(
".md-echarts-host"
);
const svg = root.querySelector<SVGSVGElement>("svg");
if (title) {
title.getBoundingClientRect = () => ({
x: 0,
y: 0,
top: 0,
left: 0,
right: 700,
bottom: 40,
width: 700,
height: 40,
toJSON: () => ({})
});
}
fitOversizedEChartsToPage(root, defaultExportConfig);
expect(figure?.dataset.pageHeightFitted).toBe("true");
expect(title?.style.breakAfter).toBe("avoid-page");
expect(figure?.style.breakAfter).toBe("page");
expect(figure?.style.pageBreakAfter).toBe("always");
expect(figure?.nextElementSibling).toHaveProperty(
"dataset.mediaPageBreak",
"true"
);
expect(Number.parseFloat(host?.style.height ?? "0")).toBeCloseTo(
1000.5748,
960.5748,
3
);
expect(host?.style.aspectRatio).toBe("");
expect(svg?.getAttribute("viewBox")).toBe("0 0 1000 2000");
expect(Number.parseFloat(svg?.style.height ?? "0")).toBeCloseTo(
1000.5748,
960.5748,
3
);
});
+329
View File
@@ -0,0 +1,329 @@
// @vitest-environment happy-dom
import { describe, expect, it } from "vitest";
import {
applyMediaBackfillCandidates,
calculateMediaBackfillScale,
findMediaBackfillCandidates,
getMediaBackfillIdsInDocumentOrder,
prepareMediaBackfillBlocks
} from "../src/media-page-backfill";
import { getPrecedingMediaTitleHeight } from "../src/diagram-page-fit";
function rect(width: number, height: number) {
return {
x: 0,
y: 0,
top: 0,
left: 0,
right: width,
bottom: height,
width,
height,
toJSON: () => ({})
};
}
function positionedRect(
top: number,
width: number,
height: number
) {
return {
...rect(width, height),
y: top,
top,
bottom: top + height
};
}
describe("媒体分页空白回填", () => {
it("全页适配时保留前置标题高度并避免标题孤行", () => {
const root = document.createElement("div");
root.innerHTML = `
<h2 style="margin: 10px 0 12px">媒体标题</h2>
<div class="mermaid"></div>
`;
const title = root.querySelector<HTMLElement>("h2")!;
const block = root.querySelector<HTMLElement>(".mermaid")!;
title.getBoundingClientRect = () =>
positionedRect(100, 600, 40);
expect(getPrecedingMediaTitleHeight(block)).toBe(40);
expect(title.style.getPropertyValue("break-after")).toBe(
"avoid-page"
);
expect(title.style.getPropertyPriority("break-after")).toBe(
"important"
);
});
it("按限宽后的基准高度计算额外缩放率", () => {
expect(
calculateMediaBackfillScale({
remainingHeight: 420,
fixedHeight: 30,
baselineVisualHeight: 430
})
).toBeCloseTo(388 / 430, 6);
});
it("缩小超过阈值或无需缩小时不回填", () => {
expect(
calculateMediaBackfillScale({
remainingHeight: 300,
fixedHeight: 30,
baselineVisualHeight: 430
})
).toBeUndefined();
expect(
calculateMediaBackfillScale({
remainingHeight: 500,
fixedHeight: 30,
baselineVisualHeight: 430
})
).toBeUndefined();
});
it("记录图片限宽后的实际基准尺寸", () => {
const root = document.createElement("div");
root.innerHTML = `
<figure class="md-document-image-block">
<img class="md-document-image">
<figcaption>标题</figcaption>
</figure>
`;
const image = root.querySelector("img")!;
image.getBoundingClientRect = () => rect(640, 480);
expect(prepareMediaBackfillBlocks(root)).toBe(1);
const figure = root.querySelector<HTMLElement>("figure")!;
expect(figure.dataset.mediaBackfillKind).toBe("image");
expect(figure.dataset.mediaBaselineWidth).toBe("640");
expect(figure.dataset.mediaBaselineHeight).toBe("480");
});
it("保持媒体元素在源文档中的串行处理顺序", () => {
const root = document.createElement("div");
root.innerHTML = `
<figure data-media-backfill-id="media-2"></figure>
<div><figure data-media-backfill-id="media-1"></figure></div>
<figure></figure>
`;
expect(getMediaBackfillIdsInDocumentOrder(root)).toEqual([
"media-2",
"media-1"
]);
});
it("根据上一页剩余区域生成一次回填候选", () => {
const root = document.createElement("div");
root.innerHTML = `
<div class="pagedjs_page">
<div class="pagedjs_page_content">
<div
class="pagedjs_page_content_flow"
data-ref="previous-content"
>上一页内容</div>
</div>
</div>
<div class="pagedjs_page">
<div class="pagedjs_page_content">
<h2 data-ref="media-title">图片标题</h2>
<figure
class="md-document-image-block"
data-media-backfill-id="media-1"
data-media-baseline-width="600"
data-media-baseline-height="400"
>
<img class="md-document-image">
</figure>
</div>
</div>
`;
const pageContents = root.querySelectorAll<HTMLElement>(
".pagedjs_page_content"
);
const previousFlow =
pageContents[0]!.firstElementChild as HTMLElement;
const title = root.querySelector<HTMLElement>("h2")!;
const block = root.querySelector<HTMLElement>("figure")!;
const image = root.querySelector<HTMLImageElement>("img")!;
pageContents[0]!.getBoundingClientRect = () =>
positionedRect(100, 700, 1_000);
previousFlow.getBoundingClientRect = () =>
positionedRect(100, 700, 550);
pageContents[1]!.getBoundingClientRect = () =>
positionedRect(100, 700, 1_000);
title.getBoundingClientRect = () =>
positionedRect(100, 600, 40);
block.getBoundingClientRect = () =>
positionedRect(150, 600, 330);
image.getBoundingClientRect = () =>
positionedRect(150, 600, 300);
expect(findMediaBackfillCandidates(root)).toEqual([
{ id: "media-1", scale: 0.92 }
]);
});
it("显式分页的媒体块不会回填到上一页", () => {
const root = document.createElement("div");
root.innerHTML = `
<div class="pagedjs_page">
<div class="pagedjs_page_content"></div>
</div>
<div class="pagedjs_page">
<div class="pagedjs_page_content">
<h2 data-ref="media-title" style="break-before: page">
图片标题
</h2>
<figure
class="md-document-image-block"
data-ref="media-block"
data-media-backfill-id="media-1"
data-media-baseline-width="600"
data-media-baseline-height="400"
>
<img class="md-document-image">
</figure>
</div>
</div>
`;
const pageContents = root.querySelectorAll<HTMLElement>(
".pagedjs_page_content"
);
const title = root.querySelector<HTMLElement>("h2")!;
const block = root.querySelector<HTMLElement>("figure")!;
const image = root.querySelector<HTMLImageElement>("img")!;
pageContents[0]!.getBoundingClientRect = () =>
positionedRect(100, 700, 1_000);
pageContents[1]!.getBoundingClientRect = () =>
positionedRect(100, 700, 1_000);
title.getBoundingClientRect = () =>
positionedRect(100, 600, 40);
block.getBoundingClientRect = () =>
positionedRect(150, 600, 330);
image.getBoundingClientRect = () =>
positionedRect(150, 600, 300);
expect(findMediaBackfillCandidates(root)).toEqual([]);
});
it("忽略媒体之前其他内容的显式分页规则", () => {
const root = document.createElement("div");
root.innerHTML = `
<div class="pagedjs_page">
<div class="pagedjs_page_content">
<div data-ref="previous-content">上一页内容</div>
</div>
</div>
<div class="pagedjs_page">
<div class="pagedjs_page_content">
<h1 data-ref="earlier-heading" style="break-before: page">
本页章节
</h1>
<h2 data-ref="media-title">图片标题</h2>
<figure
class="md-document-image-block"
data-ref="media-block"
data-media-backfill-id="media-1"
data-media-baseline-width="600"
data-media-baseline-height="400"
>
<img class="md-document-image">
</figure>
</div>
</div>
`;
const pageContents = root.querySelectorAll<HTMLElement>(
".pagedjs_page_content"
);
const previousFlow = root.querySelector<HTMLElement>(
"[data-ref='previous-content']"
)!;
const earlierHeading = root.querySelector<HTMLElement>("h1")!;
const title = root.querySelector<HTMLElement>("h2")!;
const block = root.querySelector<HTMLElement>("figure")!;
const image = root.querySelector<HTMLImageElement>("img")!;
pageContents[0]!.getBoundingClientRect = () =>
positionedRect(100, 700, 1_000);
previousFlow.getBoundingClientRect = () =>
positionedRect(100, 700, 550);
pageContents[1]!.getBoundingClientRect = () =>
positionedRect(100, 700, 1_000);
earlierHeading.getBoundingClientRect = () =>
positionedRect(100, 600, 40);
title.getBoundingClientRect = () =>
positionedRect(150, 600, 40);
block.getBoundingClientRect = () =>
positionedRect(200, 600, 330);
image.getBoundingClientRect = () =>
positionedRect(200, 600, 300);
expect(findMediaBackfillCandidates(root)).toEqual([
{ id: "media-1", scale: 0.92 }
]);
});
it("将候选缩放应用到图片和 ECharts 主体", () => {
const root = document.createElement("div");
root.innerHTML = `
<h2>图片标题保持原尺寸</h2>
<figure
class="md-document-image-block"
data-media-backfill-id="media-1"
data-media-backfill-kind="image"
data-media-baseline-width="800"
data-media-baseline-height="600"
>
<img class="md-document-image">
</figure>
<figure
class="md-echarts"
data-media-backfill-id="media-2"
data-media-backfill-kind="echarts"
data-media-baseline-width="700"
data-media-baseline-height="500"
>
<div class="md-echarts-host"><svg></svg></div>
</figure>
<div
class="mermaid"
data-media-backfill-id="media-3"
data-media-backfill-kind="mermaid"
data-media-baseline-width="600"
data-media-baseline-height="400"
>
<svg></svg>
</div>
`;
expect(
applyMediaBackfillCandidates(root, [
{ id: "media-1", scale: 0.9 },
{ id: "media-2", scale: 0.88 },
{ id: "media-3", scale: 0.9 }
])
).toBe(3);
const title = root.querySelector<HTMLElement>("h2")!;
const image = root.querySelector<HTMLImageElement>(
"img.md-document-image"
)!;
const host = root.querySelector<HTMLElement>(".md-echarts-host")!;
const svg = root.querySelector<SVGSVGElement>("svg")!;
const mermaidSvg = root.querySelector<SVGSVGElement>(
".mermaid svg"
)!;
expect(title.getAttribute("style")).toBeNull();
expect(image.style.width).toBe("720px");
expect(image.style.height).toBe("540px");
expect(host.style.width).toBe("616px");
expect(host.style.height).toBe("440px");
expect(svg.style.width).toBe("616px");
expect(svg.style.height).toBe("440px");
expect(mermaidSvg.style.width).toBe("540px");
expect(mermaidSvg.style.height).toBe("360px");
});
});
+81
View File
@@ -0,0 +1,81 @@
import { inflateSync } from "node:zlib";
import { describe, expect, it } from "vitest";
import { sampleMarkdown } from "../src/sample-markdown";
function readPngDimensions(base64: string) {
const png = Buffer.from(base64, "base64");
expect(png.subarray(0, 8)).toEqual(
Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])
);
const width = png.readUInt32BE(16);
const height = png.readUInt32BE(20);
const bitDepth = png[24] ?? 0;
const colorType = png[25] ?? 0;
const samplesPerPixel =
colorType === 0 || colorType === 3
? 1
: colorType === 2
? 3
: colorType === 4
? 2
: 4;
const idatParts: Buffer[] = [];
let offset = 8;
while (offset + 12 <= png.length) {
const length = png.readUInt32BE(offset);
const type = png.toString("ascii", offset + 4, offset + 8);
if (type === "IDAT") {
idatParts.push(
png.subarray(offset + 8, offset + 8 + length)
);
}
offset += 12 + length;
}
const decoded = inflateSync(Buffer.concat(idatParts));
const rowBytes = Math.ceil(
(width * bitDepth * samplesPerPixel) / 8
);
expect(decoded.length).toBe((rowBytes + 1) * height);
return { width, height };
}
describe("默认示例 Markdown", () => {
it("仅保留一张网络图片并提供三种 Base64 图片尺寸", () => {
expect(
sampleMarkdown.match(/https?:\/\/[^\s)]+/gu)
).toHaveLength(1);
expect(
sampleMarkdown.match(/data:image\/png;base64,/gu)
).toHaveLength(3);
expect(sampleMarkdown).toContain("1600×900");
expect(sampleMarkdown).toContain("900×1800");
expect(sampleMarkdown).toContain("1200×880");
});
it("所有内嵌 PNG 均可完整解压且尺寸符合描述", () => {
const images = Array.from(
sampleMarkdown.matchAll(
/data:image\/png;base64,([A-Za-z0-9+/=]+)/gu
),
(match) => readPngDimensions(match[1] ?? "")
);
expect(images).toEqual([
{ width: 1600, height: 900 },
{ width: 900, height: 1800 },
{ width: 1200, height: 880 }
]);
});
it("覆盖 Mermaid、ECharts 分档和串行媒体场景", () => {
expect(
sampleMarkdown.match(/```mermaid/gu)
).toHaveLength(3);
expect(
sampleMarkdown.match(/```echarts/gu)
).toHaveLength(4);
expect(sampleMarkdown).toContain("height: 40mm");
expect(sampleMarkdown).toContain("height: 58mm");
expect(sampleMarkdown).toContain("height: 85mm");
expect(sampleMarkdown).toContain("## 串行媒体块");
});
});