Readest 阅读器脚注隐藏样式回归排查：@namespace 声明顺序、自定义字体内联与 EPUB 命名空间选择器（Issue 4438）-平芜编程栈

Readest 阅读器脚注隐藏样式回归排查：@namespace 声明顺序、自定义字体内联与 EPUB 命名空间选择器（Issue #4438）

【免费下载链接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.项目地址: https://gitcode.com/gh_mirrors/re/readest

导读

本文围绕 Readest 在 v0.11.4 中出现的脚注/注释标记下方出现一条多余横线的回归问题（Issue #4438），完整剖析其根因链条：自定义字体@font-face内联（PR #4383）如何把藏在getPageLayoutStyles内部的@namespace声明挤出合法位置，进而导致命名空间化选择器aside[epub|type~="footnote"]静默失效。读者将掌握 CSS@namespace规则的生效前提、EPUBepub:type在 XHTML 与 HTML 解析下的本质差异，以及如何通过源码与测试断言修复这类"静默失效"型样式回归。

一、背景：阅读器为什么要隐藏脚注`<aside>`

在 EPUB 3 中，脚注正文通常以<aside epub:type="footnote">的形式内联在章节文档里（区别于noteref引用标记）。Readest 的分页阅读器并不会让这些内联脚注正文直接铺在版面上，而是由阅读器自己注入的样式把它们从阅读流中隐藏，用户点击脚注引用标记后由脚注弹层（Footnote Popup）另行展示。

1.1 隐藏规则的具体位置

阅读器向书籍 iframe 注入的整份样式表由 apps/readest-app/src/utils/style.ts 中的getStyles组装。隐藏脚注的规则位于getPageLayoutStyles函数内：

/* style.ts 第 479-485 行 */ .epubtype-footnote, aside[epub|type~="endnote"], aside[epub|type~="footnote"], aside[epub|type~="note"], aside[epub|type~="rearnote"] { display: none; }

其中epub|type~=是带命名空间的属性选择器：epub前缀绑定到 EPUB 的 OPS 命名空间（http://www.idpf.org/2007/ops），~=表示词列表匹配（epub:type的值可以是空格分隔的多个语义词，如"bodymatter rearnote"）。

1.2 双保险：Transformer 同时注入类名

除了命名空间选择器，仓库还通过内容变换阶段给脚注<aside>加一个普通类名作为兜底。见 apps/readest-app/src/services/transformers/footnote.ts：

export const footnoteTransformer: Transformer = { name: 'footnote', transform: async (ctx) => { let result = ctx.content; result = result.replace( /<aside\s+epub:type\s*=\s*"'["'](https://link.gitcode.com/i/e4beb0a99b06673f44e05f217feb84d5)>/gi, '<aside class="epubtype-footnote" epub:type="$1"$2>', ); return result; }, };

即footnote/endnote/note/rearnote四类 aside 都会被追加epubtype-footnote类，于是.epubtype-footnote { display: none }这条普通类选择器与aside[epub|type~=...]命名空间选择器构成双重保障。相关行为在 apps/readest-app/src/tests/services/transformers/transformers.test.ts 中有完整覆盖（含大小写、单引号、非脚注类型不处理等分支）。

1.3 反向规则：脚注弹层里重新显示

当用户点击脚注引用时，弹层组件会注入getFootnoteStyles()（同文件 style.ts），把隐藏规则"反转"回display: block，同时重置段落缩进、边距、链接装饰，并在body上补padding: 1em和overflow-wrap: break-word。弹层注入点见 apps/readest-app/src/app/reader/components/FootnotePopup.tsx：getStyles(viewSettings, popupTheme, getLoadedFonts())用于弹层主文档样式。

二、回归现象与根因：@namespace 被 @font-face 挤出合法位置

2.1 现象：脚注标记下方多出一条横线

#4438 报告：v0.11.4 中，脚注/注释标记下方出现一条多余的横线。这条线不是阅读器画的，而是书籍自带的 CSS——书籍给aside定义了border: 3px #333 double——因为隐藏aside的规则失效了，aside 及其边框重新进入阅读流，从注释标记下"露"出来。

2.2 根因链条

问题出在getStyles的样式表组装顺序上，完整链条如下：

PR #4383（提交e8675fb7e）引入自定义字体内联：为了让用户自定义字体在 iframe 首次绘制时就生效，避免先回退到 serif/sans-serif 再闪烁切换，getStyles把已加载字体的@font-face规则内联进样式表，组装从${pageLayoutStyles}...变为${customFontFaces}\n${pageLayoutStyles}...。注入点见 apps/readest-app/src/app/reader/components/FoliateViewer.tsx：

view.renderer.setStyles?.(getStyles(viewSettings, undefined, getLoadedFonts()));

@namespace原本藏在getPageLayoutStyles内部：命名空间声明不是独立于各样式块的全局规则，而是作为getPageLayoutStyles生成的字符串的一部分，位于该块开头。
CSS 规范的硬性要求被违反：CSS Namespaces 规范规定，@namespace规则只有在先于所有样式规则与所有@font-face规则出现时才被采纳；位置靠后的@namespace会被静默忽略（不是报错，而是直接当作无效规则丢弃）。内联的@font-face被拼接到pageLayoutStyles之前，相当于把@namespace往后推了若干行，使其不再位于样式表最前端，于是整个命名空间声明失效。
命名空间选择器随之被丢弃：@namespace失效后，aside[epub|type~="footnote"]中的epub前缀没有可绑定的命名空间，该选择器整体失效（浏览器无法解析出匹配元素），规则被丢弃。display: none不生效，书籍样式里的border随之显现，形成"注释标记下方一条横线"的观感。

2.3 为什么只有加载了自定义字体的用户受影响

customFontFaces由getCustomFontFaces(customFonts)生成（style.ts）：只有带blobUrl的已加载字体会产出@font-face规则，否则为空字符串。因此：

未启用自定义字体：customFontFaces为空串，拼装结果里@namespace仍是第一个规则，一切正常；
启用了自定义字体：@font-face被拼在@namespace之前，触发静默失效。

这就是该回归"挑用户"的原因——只有加载了自定义字体的用户才会踩中，极难在常规测试中暴露。

三、修复方案：把 @namespace 提升到样式表绝对最前端

修复思路简单而彻底：@namespace必须是整个样式表的第一条规则，不再把它埋在getPageLayoutStyles内部，让任何后续追加的块（无论@font-face还是别的）都无法再"挤掉"它。

3.1 修复后的实际代码

apps/readest-app/src/utils/style.ts：

// The `@namespace` declaration must lead the stylesheet: a `@namespace` rule // placed after any style or `@font-face` rule is invalid and silently ignored, // which drops the namespaced `aside[epub|type~="footnote"]` selector and lets // the footnote aside's border show as a stray horizontal line (#4438). Keep it // ahead of the inlined custom `@font-face` rules. const epubNamespace = `@namespace epub "http://www.idpf.org/2007/ops";`; return `${epubNamespace}\n${customFontFaces}\n${pageLayoutStyles}\n${paragraphLayoutStyles}\n${fontStyles}\n${colorStyles}\n${translationStyles}\n${warichuStyles}\n${rubyStyles}\n${userStylesheet}`;

同时从getPageLayoutStyles中移除原先的@namespace声明，使getPageLayoutStyles只负责页面布局相关规则。

3.2 修复后的完整规则顺序

getStyles最终产出的样式表顺序为（自上而下）：

顺序	片段	作用
1	`@namespace epub "http://www.idpf.org/2007/ops";`	声明 EPUB 命名空间（必须最前）
2	`customFontFaces`	用户自定义字体的`@font-face`规则（带 blobUrl 的已加载字体）
3	`pageLayoutStyles`	页面布局：边距变量、书写模式、脚注隐藏、链接点击区放大等
4	`paragraphLayoutStyles`	段落布局：行距、字距、缩进、两端对齐、连字符（`useBookLayout`开启时为空）
5	`fontStyles`	`--serif`/`--sans-serif`/`--monospace`字体族变量与字号、字重
6	`colorStyles`	主题色变量、暗色模式、图片反色/混合模式、E-Ink 适配等
7	`translationStyles`	翻译原文/译文区块样式
8	`warichuStyles`	割注（夹注）双行内联注释
9	`rubyStyles`	Word Lens 词表`rt`注音样式
10	`userStylesheet`	用户自定义 CSS（追加在最后）

3.3 为什么 @font-face 不必在 font-family 使用处之前

一个常见的直觉误区是"@font-face必须写在引用它的font-family声明之前"，这也是旧测试会断言错误顺序的原因。事实上，CSS 规范规定@font-face规则与源位置无关，解析器会先收集全部@font-face规则，再解析样式规则中的font-family引用；只有同名（同 family）字体的重复定义才依赖声明顺序（后者覆盖前者）。

因此把@font-face放在--serif/--sans-serif列表（buildFontFamilyLists生成的字体族链）之前，仍然能保证首次绘制时字体已解析——这正是 PR #4383 想保留的"首屏不闪烁"意图。修复后的顺序@namespace → @font-face → 页面布局 → 字体变量同时满足了两个约束：命名空间在最前，@font-face仍在引用它的字体族变量之前。

四、测试验证：从"断言错误顺序"到"断言正确顺序"

4.1 旧测试的"帮凶"角色

文档特别指出一个讽刺的细节：既有的 apps/readest-app/src/tests/utils/style-get-styles.test.ts在错误的假设上直接断言了错误的顺序——它认为@font-face必须先于使用它的font-family规则，于是断言了@font-face出现在@namespace之前的"buggy 顺序"。这个测试不仅没拦住回归，反而把回归顺序固化为"预期"，等于给 bug 上了保险。

4.2 修复后的测试断言

该测试文件现在包含两条针对 #4438 的回归断言：

// style-get-styles.test.ts 第 932-943 行 it('keeps @namespace epub ahead of every @font-face rule (#4438)', () => { const vs = makeViewSettings(); const css = getStyles(vs, theme, [makeCustomFont()]); // A `@namespace` rule is only honored when it precedes all style and // `@font-face` rules; a misplaced one is silently ignored, ... expect(css).toContain('@namespace epub'); expect(css).toContain('@font-face'); expect(css.indexOf('@namespace epub')).toBeLessThan(css.indexOf('@font-face')); });

// style-get-styles.test.ts 第 945-952 行 it('still inlines custom @font-face ahead of the font-family declarations', () => { const vs = makeViewSettings(); const css = getStyles(vs, theme, [makeCustomFont()]); // ... the custom `@font-face` rules should still precede the // `--serif`/`--sans-serif` font lists that reference them. expect(css.indexOf('@font-face')).toBeLessThan(css.indexOf('--serif:')); });

第一条用indexOf位置比较锁死@namespace epub必须在任何@font-face之前；第二条锁死@font-face仍在--serif:字体族变量之前，两者合起来恰好完整刻画了修复后的目标顺序。此外，useBookLayout相关的集成测试也断言了样式表包含@namespace epub（该文件第 443 行）。

4.3 相关测试配套

围绕脚注隐藏机制，仓库还有两处防御性测试：

apps/readest-app/src/tests/reader/utils/footnote-target-visibility.test.ts：阅读器自己的样式会隐藏内联脚注正文，因此脚注弹层的"跳转"按钮必须基于目标是否真实渲染来门控。isLinkTargetVisible会拒绝被祖先隐藏（.duokan-footnote-content）、元素自身display: none、visibility: hidden的目标，但对未渲染章节内的目标放行（避免为检查而加载章节卡住弹层）。
apps/readest-app/src/tests/document/tts.test.ts：TTS 朗读会跳过aside epub:type="footnote"/endnote/rearnote（含词列表"bodymatter rearnote"形式），而sidebar类型保留，防止语音把脚注正文读进正文里。

五、复现陷阱：XHTML 解析与 HTML 解析的本质差异

排查此类问题最大的坑在于：epub:type是只有文档按 XHTML/XML 解析时才存在的命名空间属性。

Readest 的书籍渲染基于 foliate，EPUB 内容以XHTML文档加载，因此epub前缀有命名空间绑定，[epub|type~="footnote"]才能匹配；
而浏览器测试环境（如 Playwright）的page.setContent默认按HTML解析，此时epub:type只是一个普通属性（没有命名空间概念），[epub|type~=...]永远不会匹配任何元素——用setContent复现脚注隐藏逻辑会得出"规则无效"的错误结论。

正确的复现姿势是让页面按 XHTML 解析：通过page.goto加载data:application/xhtml+xml形式的文档。这个陷阱说明：凡是涉及命名空间选择器的测试，必须先确认测试文档的解析模式（MIME type）与生产环境一致，否则测试结论与线上行为可能完全相反。

六、style.ts：阅读器样式中枢的高风险区

getStyles所在的 style.ts 是阅读器样式注入的中枢，累积了大量针对书籍作者 CSS 的"脏修复"，是仓库中回归高发区之一。本文的 #4438 之外，同文件还承载着同类问题的历史教训：

#4419 表格暗色模式染色：blockquote, table *的暗色 tint 仅在用户开启颜色覆盖（overrideColor）时施加，否则普通表格及书籍用于竖向排版的隐形分隔单元格会被染上与页面背景不同的色块（测试见 style-get-styles.test.ts）；
#4446 背景纹理遮挡：body.theme-dark必须保持透明，否则不透明背景会盖住宿主背景纹理（同文件第 678-694 行的测试）；
#5250 图片反色被覆盖：同一img规则内两条filter声明会让后一条丢弃invert(100%)，mix-blend-mode: multiply又会在深色背景上"擦除"图片（该文件第 560-600 行的专项测试组）。

这些案例共同揭示一条经验：在 style.ts 这类以"字符串拼接 + 条件分支"组织的大型样式生成器中，规则拼接顺序本身就是业务逻辑，任何新增前置片段（如@font-face内联）都必须重新审视它是否破坏了对顺序敏感的规则（@namespace、同一选择器内的级联、同族@font-face覆盖等）。

七、小结

Issue #4438 是一次典型的"静默失效型"CSS 回归：不是样式写错，而是规则顺序被新功能悄悄改变，导致一条合法规则被规范静默丢弃，只在特定用户子集（加载自定义字体）上显现。修复与防护要点可归纳为：

@namespace必须恒为样式表首条规则：已从getPageLayoutStyles中移出，在getStyles返回时硬编码为第一行；
@font-face与font-family的先后无关紧要：规范会先收集全部@font-face，只有同族重定义才依赖顺序；自定义字体内联仍保持在--serif/--sans-serif之前以满足首屏意图；
命名空间选择器的测试必须使用 XHTML 解析：epub:type仅在 XML 解析下有命名空间语义，复现与断言都要用data:application/xhtml+xml；
测试要与修复同步更新：旧测试曾把 bug 顺序当预期，回归测试的价值取决于它断言的是"正确行为"而非"当前行为"。

对阅读器类应用而言，这条修复路径具有很强的普适参考价值：任何向书籍文档注入全局样式的场景，都要警惕新片段对@namespace、级联顺序、同族字体覆盖等顺序敏感特性的潜在破坏。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Readest 阅读器脚注隐藏样式回归排查：@namespace 声明顺序、自定义字体内联与 EPUB 命名空间选择器（Issue 4438）