Skip to content

feat:Add local bookmarks and passage notes - #31

Open
xiaoshuaijie wants to merge 1 commit into
devfrom
bookmarks
Open

xiaoshuaijie wants to merge 1 commit into
devfrom
bookmarks

Conversation

@xiaoshuaijie

@xiaoshuaijie xiaoshuaijie commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

概述

本 PR 为 XRobot 文档站增加一层本地阅读能力:读者可以收藏整篇文章,也可以把正文中的一段文字存成便签。书签和便签都只保存在当前浏览器的 localStorage 中,不引入账号、后端或新的埋点。

背景与问题

文档以长文为主。目前读者想回到某篇文章或某段话,只能保留浏览器标签页,或者把文字复制到别处。缺少两种能力:

  • 文章级的“继续阅读”:记住读到哪,下次直接续上。
  • 段落级的“回到原处”:记住一段摘录,下次点击就能定位。

本 PR 用纯前端方案解决这两个问题,站点仍然保持静态部署,不增加服务端状态。

改动内容

1. 导航栏收藏当前文章

  • 新增导航栏按钮 ☆ 收藏 / ★ 已收藏,注册为自定义 NavbarItem custom-bookmark。
  • 保存文章路径、标题、点击时的滚动百分比和创建/更新时间。
  • 再次点击取消收藏;该文章下的便签会保留。
  • 文章已收藏时,滚动和 pagehide 会静默更新阅读进度,书签页始终显示最新位置。

2. 划选正文存为便签

  • 在正文容器 .theme-doc-markdown 内选中至少 4 个字符,选区上方浮出 ✎ 存为便签。
  • 保存空白归一化后的摘录(最多 240 字)、文章标题、滚动百分比和时间戳。
  • 按钮的 mousedown 会阻止默认行为,避免点击时浏览器清空选区。
  • 选区跨行内 code、链接等元素时也能正常保存和回跳。

3. 右侧「本页便签」面板

  • 桌面端右侧目录下方增加 本页便签 / Notes on this page。
  • 空态提示如何划词保存;有便签时显示条数、全部 ↗ 入口和便签列表。
  • 点击便签会定位到原文段落、滚动到视口中央,并用 CSS Custom Highlight API 闪烁高亮。
  • 支持单条删除,列表和条数即时更新。

4. /bookmarks 书签页

  • 按文章分组展示:文章头 + 该文章下的便签。
  • 点击文章头按保存的百分比续读。
  • 点击便签优先按文本指纹定位,失败时退回百分比。
  • 收藏和便签可以分别删除;取消收藏不会删除便签。
  • 支持带版本的 JSON 导出/导入。
  • 英文路由为 /en/bookmarks。

5. 跳转恢复流程

  • 书签页跳转前向 sessionStorage 写入一次性恢复标记,目标页读取后删除。
  • 便签跳转:
    1. 取摘录前 40 个归一化字符作为指纹。
    2. 在正文中重建「归一化文本 ↔ text node 偏移」映射。
    3. indexOf 命中后构造 Range,滚动到视口中央。
    4. 浏览器支持时用 CSS.highlights 闪烁高亮。
  • 书签跳转:
    1. 在 0 / 350 / 1200 ms 三个时间点重试百分比滚动。
    2. 用于抵消 Docusaurus 自身的路由滚动重置和图片、Mermaid 的异步撑高。
  • 如果文章改版导致指纹匹配失败,自动退回保存的百分比。

6. 中英文与移动端

  • strings.ts 按路由提供中英文文案,覆盖导航栏、侧栏、书签页、空态、按钮和状态提示。
  • 自定义 NavbarItem 在移动端菜单中渲染自己的 <li>,因此 ☆ 收藏 和 书签 在汉堡菜单里也可用。
  • 390px 宽度下书签页、便签列表和备份操作保持可读。

7. 没有目录的文章也显示便签栏

Docusaurus 只在 toc.length > 0 时渲染右侧目录列。仓库中有 6 篇文档没有任何 ## 标题,便签面板会因此消失。

本 PR 从 Docusaurus 3.9.2 复制并调整了 DocItem/Layout:只要没有显式设置 hide_table_of_contents,桌面端就保留右栏;DocItem/TOC/Desktop 在没有标题时省略空目录,只渲染便签面板。

交互流程

划选正文 ──► NoteCapture ──► useNotes ──► localStorage["notes:v1"]
                                                  │
书签页 ◄── BookmarkList ◄─────────────────────────┘
   │
   └─ markRestore ──► BookmarkSystem ──► 文本指纹定位 / 百分比兜底

数据模型

localStorage 键:

  • bookmarks:v1:{ [path]: Bookmark }
  • notes:v1:{ [id]: Note }
interface Bookmark {
  path: string;
  title: string;
  scrollPercent: number;
  createdAt: number;
  updatedAt: number;
}

interface Note {
id: string; // 路径 + 时间戳 + 随机后缀
path: string;
title: string;
quote: string; // 空白归一化,最多 240 字
scrollPercent: number;
createdAt: number;
updatedAt: number;
}

备份文件:

{
  "app": "site-bookmarks",
  "version": 2,
  "exportedAt": "2026-10-19T...",
  "bookmarks": [],
  "notes": []
}

导入规则:

  • 书签:同一路径,updatedAt 更新的一方胜出。
  • 便签:按 id 去重,updatedAt 更新的一方胜出。
  • v1 旧备份没有 notes 字段时仍然可以导入,只合并书签。

文件说明

模块 文件
存储与数据模型 src/features/bookmarks/useNotes.ts、useBookmarks.ts、types.ts、readingKeys.ts
文本匹配与高亮 src/features/bookmarks/noteText.ts、noteDom.ts
恢复与进度跟随 src/features/bookmarks/restore.ts
UI 组件 src/components/bookmarks/ArticleNotes.tsx、NoteCapture.tsx、BookmarkButton.tsx、BookmarkList.tsx、BookmarksNavLink.tsx、BookmarkSystem.tsx
书签页 src/pages/bookmarks.tsx、src/pages/bookmarks.module.css
Docusaurus 接入 src/theme/Root/index.tsx、src/theme/NavbarItem/ComponentTypes.tsx、src/theme/DocItem/TOC/Desktop/index.tsx、src/theme/DocItem/Layout/index.tsx
配置与样式 docusaurus.config.js、src/css/custom.css、src/components/bookmarks/bookmarks.module.css、src/theme-modules.d.ts

验证

构建

  • npm run build 中英文均构建通过。
  • 产物中存在 /bookmarks.html 与 /en/bookmarks.html。

浏览器手工验证

  • 选中一段正文 → 点击 ✎ 存为便签 → 右侧出现便签。
  • 刷新页面 → 便签和收藏状态仍然存在。
  • 点击收藏 → 显示 ★ 已收藏;刷新后状态保持。
  • /bookmarks → 正确显示文章分组、便签行和导入导出入口。
  • 点击便签 → 回到 /docs/intro,CSS.highlights.has('note-flash') 为 true。
  • 选区跨行内 code → 便签仍能准确定位。
  • 书签百分比恢复:保存 50% → 实际恢复约 scrollY = 511 / 1022。
  • 自动跟随进度:滚动到约 45% 后刷新,存储的百分比会更新。
  • 导出备份 → 清空 localStorage → 导入 → 书签和便签恢复。
  • /en/docs/intro、/en/bookmarks 均显示英文文案。
  • 390px 宽度下,移动端菜单包含 ☆ 收藏 和 书签,书签页布局正常。
  • 没有 ## 标题的文档仍然显示便签面板。

类型检查

npx tsc --noEmit 没有新增错误。src/pages/index.tsx 和 src/pages/qq.tsx 中的两个 Layout title 属性报错是本次改动之前就存在的。

兼容性与风险

  • 没有新增依赖、接口、数据库、Cookie 或分析埋点。
  • 隐私模式或存储配额满时,写入会静默失败,不影响正常阅读。
  • CSS Custom Highlight 属于渐进增强;不支持的浏览器仍然会滚动到便签位置,只是没有高亮。
  • DocItem/Layout 是不安全 swizzle,升级 Docusaurus 时需要重点复查。
  • 项目 Babel preset 会把 [...map.values()] 宽松编译成 [].concat(iterator),因此代码里统一使用 Array.from 处理 Map 迭代器。
  • 摘录内容只作为 React 文本渲染,不使用 innerHTML,没有 HTML 注入风险。
  • 数据量受 localStorage 容量限制;单条摘录截断到 240 字,正常使用不会达到上限。

不在本次范围

  • 云端同步或用户账号。
  • 富文本、批注和编辑历史。
  • 跨便签全文搜索。
  • 相同段落的自动去重。

Checklist

  • 中英文文案
  • 桌面端和移动端入口
  • 无标题文章也显示便签栏
  • 生产构建(zh + en)
  • 无后端、无新增依赖
  • 手工端到端验证
  • 补充截图
  • Reviewer 审核通过

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant