企业官网建设流程全解析

• 桌面应用
• 跨平台
• 前端

固定版式（Fixed-Layout，FXL）EPUB 在暗色/羊皮纸（sepia）主题下出现正文被主题色染色的问题，是横版排版类电子书阅读器最常见的暗色模式缺陷之一。本文以 Readest 仓库中的问题记录文档（fxl-authored-colors-5649.md）为骨架，完整还原问题 #5649 的根因分析、修复实现（已合入 #5657，merge commit437bcf9fd）与验证方法，并结合 style.ts、FoliateViewer.tsx 与测试用例的源码细节，讲解 Readest 如何在"主题化"与"尊重作者原始排版"之间建立正确的分层策略。读完本文，你将掌握：FXL 与流式（reflowable）文档在样式注入路径上的本质差异、transformStylesheet与applyFixedlayoutStyles的分工边界、color-scheme与页面背景色的耦合陷阱，以及一套可复现的浏览器手工验证流程。

一、背景：FXL EPUB 的渲染模型与样式注入路径

1.1 流式文档 vs 固定版式文档

Readest 的阅读器内核基于 Foliate。在 Foliate 的渲染模型中：

• 流式文档（reflowable）：内容按章节切分后注入 iframe，渲染器通过setStyles向文档注入全局样式，实现字号、行距、主题色等用户设置的覆盖；
• 固定版式（FXL）文档：每一页都是一个独立的 iframe（每个 section 一页），渲染器没有setStyles，因此getStyles/getColorStyles（以及其中所有*[style*="color:#000"]这类内联颜色覆盖规则）永远不会到达 FXL 文档。

这一差异直接决定了修复思路：既然setStyles对 FXL 无效，那么applyFixedlayoutStyles就成了控制 FXL 页面颜色的唯一杠杆（问题记录原文称之为 "the single lever for FXL page colors"）。这一点在 FoliateViewer.tsx 中得到印证——只有bookDoc.rendition?.layout === 'pre-paginated'（预分页布局，即 FXL）时才会调用applyFixedlayoutStyles。

1.2 两类样式处理的代码路径

二、根因剖析：为什么 FXL 文字会被主题染色

问题 #5649 的复现路径在 Chrome 中用手工构造的 EPUB 验证通过（报告者最初附带的附件是损坏的 zip）。根因由两个相互独立的原因叠加而成：

2.1 原因一：资源路径上的transformStylesheet缺少固定版式 gate

FoliateViewer.getDocTransformHandler会对每一个text/css资源执行transformStylesheet，而当时没有任何 fixed-layout 门控（见 FoliateViewer.tsx 中bookData?.isFixedLayout作为第五个参数传入的现状）。

问题在于transformStylesheet的变换集合非常"激进"，对 FXL 书来说几乎每一项都是破坏性的（源码见 style.ts 顶部的注释与 L1294-L1359 的替换链）：

• 颜色重写：color: black、color: #000000、color: #000、color: rgb(0,0,0)等硬编码颜色会被替换为var(--theme-fg-color)。对作者明确写成color:#000的 FXL 页面，这会在浅色主题下渲染成棕色（因为在浅色模式下--theme-fg-color通常接近主题前景色而非纯黑），不只是暗色模式才错；
• 字号缩放：移动端会将绝对字号除以 1.25（fontScale = isMobile ? 1.25 : 1，style.ts），把font-size: 12px这类声明改写为rem值，破坏 FXL 页面按自身视口精确排版的布局；
• vw/vh 解析：将vw/vh按阅读器视口换算为 px（L1319-L1320），而 FXL 页面是为自身页面的固定视口创作的；
• 字体族改写：font-family: serif被改写成unset（L1217-L1230）。

值得注意的是，内联<style>路径（styleTransformer，位于 style.ts）当时已经具备if (ctx.isFixedLayout) return result;的门控；缺 gate 的是外部资源路径，两条路径行为不一致正是本次修复的切入点之一。

2.2 原因二：color-scheme: dark但没有显式color

applyFixedlayoutStyles中设置了color-scheme: dark，却没有同时设置显式的文字颜色。于是书中从未着色的文字（作者没有为它们写任何 color 声明）回落到 UA 暗色默认值——白色。这一行为与主题无关：即便主题本身是深色的，文字也统一变成白，破坏了作者希望的默认渲染。

2.3 承重第三块：页面背景色覆盖（修复必须同时处理的部分）

applyFixedlayoutStyles里还有一条body { background-color: var(--theme-bg-color) }。这条规则会把主题色涂抹在 FXL页面上。需要注意结构细节：每个 FXL 页面都是独立的 iframe，letterboxing（黑边/信箱）位于 iframe 之外，因此这个背景色就是用户看到的整页底色。

于是出现了矛盾：只修复原因 1 和 2，会得到"作者写的黑色文字 + 主题深色页面背景"的组合，黑色文字落在深色背景上 =完全不可读。因此修复必须同时停止涂抹页面背景——这就是问题记录中强调的"load-bearing third piece"（承重件）的含义。

三、修复策略：按"作者原样渲染"（render as authored）策略

3.1 统一门控条件

修复的核心是引入统一的门控表达式（style.ts）：

const appRendered = !format || FIXED_LAYOUT_FORMATS.has(format);

其中FIXED_LAYOUT_FORMATS定义在 book.ts：

export const FIXED_LAYOUT_FORMATS: Set<BookFormat> = new Set(['PDF', 'CBZ']);

这个集合的语义是：由应用自己渲染页面（而非书作者排版）的格式。applyFixedlayoutStyles接收format参数（EPUB/PDF/CBZ），以此区分两条策略：

完整逻辑位于 applyFixedlayoutStyles：

const appRendered = !format || FIXED_LAYOUT_FORMATS.has(format); // ... style.textContent = ` html { --theme-bg-color: ${bg}; --theme-fg-color: ${fg}; --theme-primary-color: ${primary}; color-scheme: ${appRendered && isDarkMode ? 'dark' : 'light'}; -webkit-text-size-adjust: none; text-size-adjust: none; } body { position: relative; ${appRendered ? 'background-color: var(--theme-bg-color);' : ''} } ... `;

3.2 两条策略的取舍依据

• PDF/CBZ 保持主题化：这两类文档的"页面"由阅读器渲染（PDF 通过renderer.pageColors可进一步配合"Apply Theme to PDF"设置，见 FoliateViewer.tsx），文字不是书内 HTML，主题色覆盖是预期行为；
• FXL EPUB 完全尊重作者排版：color-scheme: light让浏览器不再对未着色文字应用暗色 UA 默认值；删除body背景色后，iframe 的基准背景渲染为白色。验证确认：删掉背景规则后页面显示为白色，不存在"透明导致透出深层暗色"的陷阱（iframe 基准背景本身是不透明的白色，而非透明）。

3.3transformStylesheet的 FXL 短路

transformStylesheet在入口处增加isFixedLayout参数，为真时原样返回 CSS（style.ts）：

export const transformStylesheet = ( css: string, vw: number, vh: number, vertical: boolean, isFixedLayout = false, ) => { if (isFixedLayout) return css; // ...其余变换

调用方getDocTransformHandler将bookData.isFixedLayout作为第五个参数传入（FoliateViewer.tsx）：

return transformStylesheet( data, width, height, viewSettings.vertical, bookData?.isFixedLayout, );

这使资源路径与内联<style>路径（styleTransformer早已有 gate）行为对齐：FXL 书的 CSS 一字不改，颜色、字号、vw/vh、字体族全部保持作者原样。

四、验证方法：手工构造 FXL EPUB + 浏览器实测

问题记录提到两条验证手段：手工构造的复现 EPUB（在 Chrome 中实测）与 shadow-DOM 遍历流程（详见browser-verify-readest-web-recipe）。

4.1 自动化测试

修复合入时配套的测试位于 fixed-layout-styles.test.ts，它直接构造一个内存 document，调用applyFixedlayoutStyles后断言注入的 CSS 内容。测试覆盖了本次修复的核心行为：

1. FXL EPUB 页不被暗色主题化（#5649 的直接回归测试）（L110-L131）：

describe('applyFixedlayoutStyles page colors', () => { const darkTheme = makeThemeCode({ isDarkMode: true, bg: '#342e25', fg: '#ffd595' }); it('keeps book-authored pages out of dark mode so their text stays as authored (#5649)', () => { const css = fixedLayoutCss(makeViewSettings(), darkTheme, 'EPUB'); expect(css).toContain('color-scheme: light'); expect(css).not.toContain('color-scheme: dark'); }); it('does not paint the theme background over book-authored pages', () => { const css = fixedLayoutCss(makeViewSettings(), darkTheme, 'EPUB'); expect(css).not.toMatch(/body\s*{[^}]*background-color/); }); it('still themes app-rendered pages (PDF, comics) in dark mode', () => { for (const format of ['PDF', 'CBZ'] as const) { const css = fixedLayoutCss(makeViewSettings(), darkTheme, format); expect(css).toContain('color-scheme: dark'); expect(css).toMatch(/body\s*{[^}]*background-color: var\(--theme-bg-color\)/); } }); });

2. 对比度滤镜与图片反色保持可用（L68-L108）：contrast默认 100% 时不产生滤镜；大于/小于 100% 时注入filter: contrast(N%)；暗色模式叠加invertImgColorInDark时合并为filter: invert(100%) contrast(N%)——说明修复并未牺牲 FXL 下用户可调节的图片观感。

3. 移动端文字自动缩放禁用（L133-L138）：-webkit-text-size-adjust: none/text-size-adjust: none修复 Chrome for Android 对 FXL 书中按字母绝对定位文字的重排问题（#5641）。

4.2 浏览器手工验证流程

复现与验证使用的是一套"拖拽导入 + shadow-DOM 遍历"的手工流程：将构造好的 FXL EPUB 直接拖入阅读器导入，随后遍历页面 iframe 及其内部 shadow DOM，检查：

• 暗色/sepia 主题下 FXL EPUB 页面底色是否为白色、文字是否保持作者原始颜色（尤其color:#000声明）；
• 浅色主题下黑色文字是否保持纯黑（修复前会偏棕）；
• PDF/CBZ 在暗色模式下仍为深色页面背景 + 浅色文字。

注意：报告者最初上传的附件是一个损坏的 zip，无法直接用于复现，因此需要手工构造一个最小 FXL EPUB（manifest 中声明rendition:layout="pre-paginated"的固定版式 EPUB3）来精确控制页面中的颜色声明，再观察浏览器实际渲染结果。

五、已接受的权衡（trade-offs）与边界行为

修复按"尊重作者排版"优先，明确接受了两个权衡，均记录在问题文档中：

1. 暗色/sepia 主题下，FXL EPUB 页面以作者原始白色渲染——这与 Apple Books 的行为一致。主题化能力只保留给 PDF/CBZ 等由应用渲染页面的格式；
2. FXL 的外链 CSS 不再被改写，user-select: none会保持原样——此前transformStylesheet会把user-select: none改写成unset（L1321-L1325），使 FXL 页面文字可被选中；现在 FXL 的 CSS 完全不经过此变换，因此书内设置user-select: none的 FXL 页面文字不可选中。这恰好与内联<style>路径的既有行为一致（内联样式路径早已有 fixed-layout gate）。

此外，本次修复还牵涉一个联动细节：getOverlayerBlendMode（style.ts）根据"页面是否由应用渲染"决定注释高亮层的混合模式——暗色模式下应用渲染的页面（PDF/CBZ/反色图片）用screen，保持书内位图的 FXL 页面用multiply。这与appRendered的判断逻辑同源，说明"按作者原样渲染"是一条贯穿阅读器渲染管线的统一策略，而非孤立的 CSS 修补。

六、总结与排查清单

本次 #5649 修复（已作为 #5657 合并，merge commit437bcf9fd，合并日期 2026-08-13，真实设备上的 FXL 图书验证仍在进行中）的核心经验可以沉淀为以下排查清单，供处理同类"FXL 主题染色"问题时参考：

1. 确认文档类型：只有rendition.layout === 'pre-paginated'的文档走applyFixedlayoutStyles；流式文档走setStyles注入，问题定位路径完全不同；
2. 检查是否有两套样式处理路径行为不一致：transformStylesheet（资源路径）与styleTransformer（内联路径）都要有 fixed-layout gate，只补其一会出现"外链 CSS 被改写、内联不被改写"的分裂行为；
3. color-scheme与显式color必须成对考虑：设置color-scheme: dark而不给文字颜色，会让未着色文字回落到 UA 白色默认值；
4. 页面背景与文字前景是耦合的：仅修文字颜色而继续在body上涂抹主题背景色，会造成"作者黑色文字 + 深色背景"的不可读结果；判断页面是否由应用渲染（!format || FIXED_LAYOUT_FORMATS.has(format)）后，背景与color-scheme要按同一策略一起处理；
5. 用自动化测试锁住行为：applyFixedlayoutStyles是纯函数，可以直接对内存 document 断言注入的 CSS，是这类回归问题最经济可靠的验证方式。

通过这一案例可以看到，Readest 对固定版式文档确立了清晰的分层原则：PDF/CBZ 这类由应用渲染"页面"的格式继续享受完整的主题化能力，而 FXL EPUB 这类由作者精确排版"页面"的格式则完整保留作者意图——这也是对"阅读器尊重出版排版"这一产品价值观的代码级落地。

• 桌面应用
• 跨平台
• 前端