docs: 同步 i18n 移除与存储初始化防覆盖说明

- 移除已废弃的 chrome.i18n / _locales 文档引用
- 补充 UI 文案规范(features.tsx + 组件内中文)
- 记录 RouterProvider / useStorageState 初始化防覆盖机制
- 更新 syncSnapshot、themeSnapshot、restrictedUrls 工具说明

Co-authored-by: LingandRX <LingandRX@users.noreply.github.com>
This commit is contained in:
Cursor Agent
2026-06-27 02:31:19 +00:00
parent 0545910b16
commit f09d438f0f
7 changed files with 122 additions and 126 deletions
+15 -5
View File
@@ -28,36 +28,46 @@ React.StrictMode
- **当前页面**`currentPage``PageType`
- **可见页面列表**`visiblePages`
- **页面排序**`pageOrder`
- **最近使用工具**`recentlyUsedTools`(最多 3 项,供 TopBar 搜索历史使用)
- **加载状态**`isLoaded`
核心特性:
- 通过 `chrome.storage` 持久化路由状态
- 使用 `localStorage` 快照实现首屏 0 闪烁
- 使用 `localStorage` 快照`snapshot/{key}`实现首屏 0 闪烁
- 支持 popup/sidepanel/tab 三种入口的独立路由同步(通过 `syncKey``visiblePagesKey``pageOrderKey` 配置)
- 处理右键菜单待处理数据的路由跳转
- 监听 `chrome.storage.onChanged` 实现跨端同步
### 初始化与防覆盖
异步加载 storage 期间,快照值会作为首屏初始 state。加载完成后:
1. **`canPersistRef`**:仅在 `loadInitialData` 成功后才设为 `true`,在此之前不会向 storage 写入,避免默认值覆盖已有路由
2. **`hasUserNavigatedRef`**:用户调用 `navigateTo` / `goHome` 后设为 `true`,异步加载结果不会覆盖用户已选页面
3. **`mergeWithDefaults`**:将已保存的页面列表与默认列表合并,新增功能会自动出现在列表末尾
导出:
- `RouterProvider` 组件
- `useRouter()` Hook — 获取 `currentPage``visiblePages``pageOrder``navigateTo``goHome`
- `useRouter()` Hook — 获取 `currentPage``visiblePages``pageOrder``recentlyUsedTools``navigateTo``goHome`
## ThemeModeProvider.tsx
主题模式 Provider,管理:
- **主题模式**`light` / `dark` / `system`
- **解析后的主题**`resolvedTheme``light` / `dark`
- **解析后的主题**`resolvedMode``light` / `dark`
核心特性:
- 使用 `localStorage` 快照实现首屏 0 闪烁
- 使用 `themeSnapshot.ts` 读写 `localStorage` 快照实现首屏 0 闪烁
- 监听系统级暗色模式变化(`matchMedia`
- 通过 `chrome.storage` 跨端同步主题偏好
- 自动在 `document.documentElement` 上切换 `dark` class
- **`hasUserSetMode`**:用户主动切换主题后,异步 storage 加载不会覆盖用户选择
导出:
- `ThemeModeProvider` 组件
- `useThemeMode()` Hook — 获取 `themeMode``resolvedTheme``setThemeMode`
- `useThemeMode()` Hook — 获取 `mode``resolvedMode``setMode`