Readest 阅读器「Additional Margin (%)」设置项解析从 Column Gap 更名到页面边距的底层实现【免费下载链接】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 仓库中的项目记忆文档 column-gap-additional-margins-5301.mdIssue #5301展开深入讲解分页视图下额外边距这一布局设置项的语义来源、更名原因、源码实现位置以及 i18n 字符串更名在 Readest 中的完整操作链路。读完本文你将理解gapPercent与左右边距margin之间的联动关系、为何该设置不能被命名为gutter并掌握如何在 LayoutPanel.tsx 与 commandRegistry.ts 两处定位同一设置项的实操方法。一、背景Issue #5301 发生了什么Readest 的分页阅读视图曾经在布局设置中提供一项名为Column Gap (%)列间距百分比的设置用户通过滑动数字输入框即可调整。在 Issue #5301对应分支fix/rename-column-gap-to-additional-margins中这一可见标签被正式更名为Additional Margin (%)额外边距百分比。项目记忆文档明确指出这次改动只涉及用户可见的文案标签底层的设置键与存储字段完全不变。维度改动前改动后可见标签i18n key 对应文案Column Gap (%)Additional Margin (%)设置 IDdata-setting-idsettings.layout.pageGapsettings.layout.pageGap不变底层存储字段viewSettings.gapPercentviewSettings.gapPercent不变涉及的源码文件LayoutPanel.tsx、commandRegistry.ts同一批文件仅改labelKey与_()文案也就是说这是一次名实相符的命名纠偏功能行为、持久化字段、设置项 ID 均未变动唯独把暴露给用户的名称改成了更准确、更可发现的描述。二、为什么叫 Column Gap 是误导实现细节决定命名记忆文档给出了更名的两个核心原因二者都源于分页引擎Foliate的真实实现Column Gap 是 CSS/分页层面的实现细节对用户不可见。分页视图在排版上始终至少是一个 CSS column列。所谓gap在分页布局里并不是两个相邻可见列之间的间距而是对单列分页页面左右两侧页边距的扩展。也就是说用户看到的左/右边距 固定边距margin 这个百分比宽度带来的额外留白。该值有意与左/右边距绑定无法独立调节。为了保持左右页面特别是对开双页/横向排版的对称性Readest 不允许用户单独调整中间 gutter书脊槽的宽度。因此把该项命名为 gutter书脊槽同样不准确——它实际表现的是一段额外边距additional margin。由此可以得出一个关键的用户侧结论如果发现左右页边距到 144px 上限后仍不够宽提高Additional Margin (%)就是唯一途径。记忆文档特别点明更名前用户无法自行发现这个用法——这正是更名的直接动因并关联参考了 Issue #3909。从源码可以进一步印证分页至少一列这一事实在 FoliateViewer.tsx 中布局生效时通过viewRef.current?.renderer.setAttribute(gap, ${viewSettings.gapPercent}%);把百分比值直接写入渲染器的gap属性而在 LayoutPanel.tsx 中用户拖动滑块时同样即时调用useEffect(() { if (gapPercent viewSettings.gapPercent) return; saveViewSettings(envConfig, bookKey, gapPercent, gapPercent, false, false); view?.renderer.setAttribute(gap, ${gapPercent}%); ... }, [gapPercent]);gap是 Foliate 渲染器的分页属性分页模式下它控制相邻列/页面之间的间距而单列分页时该间距即表现为页面左右两侧的附加留白。这与记忆文档的表述完全一致。三、在源码中定位这个设置项的两处落点记忆文档明确指出该字符串i18n key出现在两个位置这也是排查任何布局设置项时值得复用的定位思路。3.1 设置面板LayoutPanel.tsx文件src/components/settings/LayoutPanel.tsx在Page分组BoxedList title{_(Page)}内该设置项是一个带data-setting-idsettings.layout.pageGap的NumberInput第 718–725 行NumberInput label{_(Additional Margin (%))} value{gapPercent} onChange{setGapPercent} min{0} max{30} >{ id: settings.layout.pageGap, labelKey: _(Additional Margin (%)), keywords: [page, margin, additional, gap, spacing, gutter, column], section: Page, },id与设置面板中的data-setting-id完全一致这是两处面板 命令面板指向同一设置的锚点labelKey同步改为新文案保证命令面板/搜索显示与设置面板一致keywords保留了gap、spacing、gutter、column等历史与近义关键词确保旧用户用旧术语也能搜到该设置——这是本次更名得以平滑过渡的关键设计。3.3 底层类型与默认值设置项的持久化字段定义在 src/types/book.ts 的BookLayout接口中gapPercent: number;其默认值位于 src/services/constants.ts 的DEFAULT_BOOK_LAYOUTgapPercent: 5, // 默认 5%结合LayoutPanel中 0–30 的范围可以推断默认情况下左右两侧各附加约 5% 的额外边距用户可在 0%–30% 之间以 1% 步进调整。四、i18n 字符串更名的完整操作链路记忆文档给出了在 Readest 中重命名一个_()键的完整流程这是本项目特有的开发规范也是任何涉及界面文案变更的改动必须遵守的步骤改源码中的两处引用LayoutPanel.tsx的label与commandRegistry.ts的labelKey以及必要时 keywords。运行 i18n 提取pnpm i18n:extract翻译所有语言文件提取后public/locales/*/translation.json各语言目录如zh-CN、de、fr等中会出现新的__STRING_NOT_TRANSLATED__占位符需要逐一替换为对应语言的译文。Readest 支持 30 种语言参见 public/locales 目录因此这一步是更名成本的主要来源。清理提取过程中混入的无关散键记忆文档特别提醒pnpm i18n:extract会把所有未翻译字符串一并扫出——当时就顺带暴露了来自 Issue #5245 的Skeuomorphic Book Covers键。为了避免 PR 失焦这些无关键应当被丢弃/排除只保留与当前改动相关的键。这套流程说明Readest 的 i18n 是源码键 → 提取 → 逐语言翻译的流水线模式任何可见文案的改动都必须走完整条流水线否则新语言包中会出现未翻译占位符。五、从源码结构可进一步确认的实现细节以下结论基于对仓库源码的阅读属于可从代码结构推断的层面gapPercent只在分页非滚动流程中生效在 LayoutPanel.tsx 中写入gap属性后会根据viewSettings.scrolled恢复flowscrolled说明滚动模式与分页模式的渲染属性由同一处统一管理该设置与边距设置共用saveViewSettings持久化管线且第四个参数传false不同步到全局/云端意味着gapPercent属于按书per-book保存的阅读视图设置而非全局设置记忆文档中关联的page-margin-live-update-4898页边距实时更新问题与本次更名同属边距类设置的即时反馈与命名主题说明 Readest 在持续打磨边距设置的交互与语义一致性。六、对开发者与用户的实战启示对用户想加宽左右留白先调Left/Right Margin (px)到上限 144px仍不够再调Additional Margin (%)0–30%默认值为 5%绝大多数场景无需改动竖排vertical与横排horizontal模式均适用。对开发者尤其贡献者定位任何布局设置先搜settings.layout.*前缀的data-setting-id它同时存在于 LayoutPanel.tsx 与 commandRegistry.ts两处 ID 必须一致修改可见文案时务必走pnpm i18n:extract 全语言翻译流程并留意提取出的无关散键命名遵循面向用户语义、不暴露实现细节的原则——正如本次从 Column Gap 到 Additional Margin 的调整避免用 CSS 实现术语命名面向读者的设置项。综上Issue #5301 是一次典型的语义纠偏型改动零行为变更却大幅提升了设置项的可发现性与可理解性。理解它背后的分页实现逻辑gap 即单列分页的额外边距、与左右边距绑定保持对称你就掌握了 Readest 分页留白体系的完整图景。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考