Peach: Local-first video metadata scraper and media manager.
kind: reference
新手教程
教程中心集中提供开始使用、界面导览与设置导览。首次设置仍负责初次配置;教程按需要阅读,不要求逐章完成。
| 路径 | 入口 | 阅读方式 |
|---|---|---|
| 开始使用 | 媒体目录、扫描任务、馆藏 | 直接进入对应页面;更多接入方式按需展开 |
| 界面导览 | 首页快速导览与四个主题 | 选择章节后直接开始,不经过章节介绍页 |
| 设置导览 | 常用设置与四个主题 | 在实际设置界面高亮说明,复杂选项在步骤内展开 |
三个标签页共用引导区、图标槽和弹层。主题只负责整理章节,搜索覆盖章节与字段说明。导览支持继续、上一步、跳过和退出。邀请、完成状态和章节进度保存在本机账本的 profile.settings_json.tutorial_progress,同一实例的局域网设备共用;不读取浏览器中的旧预览进度。
启动、打开教程和页面重新获得焦点时读取服务端状态;进行中的导览不被另一台设备打断。保存按章节步骤在事务内更新,不提交整份客户端快照。读取或保存失败明确提示,不用空进度假装同步成功。
web_tutorial.CAMPAIGN 是独立的教程提示版本,与应用版本号无关。普通升级保持不变;发布明确需要重新介绍的新教程时才修改。新提示版本恢复邀请和入口,同时保留已读章节;仅改文案、样式或修复定位不触发再次提示。
教程中心首次发布使用 tutorial-center-1:升级到包含该教程的版本后,所有实例在打开应用时重新显示入口提示,包括已关闭或完成旧教程的实例。任一设备处理提示后,同一账本的其他设备沿用该状态;后续普通升级不重复提示。
首次邀请压暗背景并框选右上角指南针,说明贴近入口;点击指南针或「打开教程」进入教程中心。点击遮罩、关闭按钮、按 Esc 或选择「稍后再说」关闭邀请并记录已提示。完成 4 步快速导览后收起右上角入口,不要求阅读所有分类;稍后再说或中途退出时仍保留入口。设置 → Peach 配置 → 应用与维护中的「新手教程 → 重新打开」恢复入口并打开教程,保留已读进度。
「跳过本章」退出整段导览,不前进到下一步,也不计为完成;保留已读进度,之后可以继续。每章完成、跳过或关闭后,关闭导览打开的设置弹层,恢复开始前的页面并返回教程窗口,保留原标签和搜索条件。从偏好设置里开始时,返回其背景页面;直接打开设置地址时返回首页。
章节的全部步骤已读才计为完成,目标缺失的步骤不计入。已完成章节显示勾选与「已完成」,引导区按钮改为次要样式的「再看一遍」。重看不清除已读进度。
详情、评分、播放和字幕步骤使用馆藏中的真实视频打开详情。导览期间只展示播放器控件,不请求主视频流、不自动播放、不记录观看,也不修改保存的播放偏好。完成或退出时关闭详情,不保留播放小窗,返回教程。已有小窗播放时先提示关闭,避免替换正在观看的内容。
步骤中的「打开方式」显示平时进入该功能的点击路径。名称复用页面和设置定义;入口层级、隐藏入口的恢复方式与手机侧栏提示由教程维护,自动换页不会代替这些说明。
定位与维护
- 偏好设置复用控件 ID,配置组件使用
data-guide-target稳定标记。移动组件或改显示文案时保留其标记。 - 设置路由从应用的设置定义生成。新增功能、删除功能或改变语义仍需同步教程内容,不能从屏幕位置推断功能含义。
- 高亮尺寸与说明位置来自实际 DOM,复用 Driver.js 的定位与 refresh API。活动步骤在布局、滚动、视口或目标节点变化后重新定位;手机布局优先选择当前可见入口。
- 目标尚未加载时限时等待。无内容、受权限限制或目标已移除时显示缺失说明,允许跳过,不将别的控件当作目标。
- 退出或切换步骤时清理旧定位。设置提交、播放、下载和删除仍由对应页面执行;教程不代替用户操作。
代码入口
frontend/src/onboarding/guide-catalog.ts:章节、目标和说明;配置页各分区不挂导览说明,字段说明写在设置行里。frontend/src/onboarding/guide-state.ts:邀请和阅读进度,不改安装完成状态。frontend/src/onboarding/guide-driver.ts:路由切换、目标查找、几何跟踪与 Driver.js 适配。frontend/src/react/onboarding/:目录、引导区、步骤说明和偏好设置的章节入口。
验证覆盖直接开始、退出、路由及目标缺失、移动端候选切换、滚动、节点替换与定位清理。界面预览与确认遵守 界面验收预览。