使用指南与常见问题

欢迎查阅 WristTale 使用指南。本文档将详细介绍支持的书籍格式、文件组织方式以及常见问题的解答。

书籍格式

WristTale 采用业界标准的 Markdown + YAML Frontmatter 格式进行书籍的导入和导出。这确保了最大的兼容性、可读性以及易编辑性。

支持的文件后缀

  • 推荐：.md (Markdown)
  • 支持：.txt

格式结构

一个有效的 WristTale 书籍文件由两部分组成：

  1. 元数据：位于文件开头的 YAML Frontmatter 代码块，由 --- 包裹。
  2. 内容：书籍正文，使用 Markdown 标题（#）来标识章节。

示例

您可以点击下载示例文件参考：朝花夕拾

---
title: 朝花夕拾
author: 鲁迅
chapters: 10
---

# 小引

我常想在纷扰中寻出一点闲静来...

# 狗·猫·鼠

从去年起，仿佛听得有人说我是仇猫的...

主要特点：

  • 通用性：可以使用任何文本编辑器或 Markdown 应用（如 Obsidian, Typora, VS Code）打开和编辑。
  • 简洁：没有复杂的结构，标准的 Markdown。
  • 精准解析：使用 H1 标题 (#) 明确标识章节，避免识别错误。

纯文本文件 (.txt)

完全支持标准的纯文本文件。WristTale 使用智能正则匹配算法，根据常见的章节标题模式（如 "第1章"、"Chapter 1"）自动识别章节。

最佳实践：

  • 请确保文件编码为 UTF-8。
  • 使用标准的章节标题格式（如“第X章”），并使其独占一行。
  • 避免在标题周围添加过多的装饰符号或空行。

文件管理

WristTale 内部使用数据库管理您的书库，但在您进行手动导出或文件管理时，了解文件结构会很有帮助。

导出书籍

当您从 WristTale 导出书籍时（通过书籍菜单中的“导出”选项），文件将以 Markdown 格式 (.md) 保存。这将以标准格式保留您的所有章节编辑和元数据。

  • Android: 文件保存在您的系统 Downloads (下载) 文件夹中。
  • iOS: 文件保存在“文件”应用中“我的 iPhone”下的 WristTale 文件夹内。

导入书籍

您可以从设备的任何位置导入书籍。

  • 点击主页右上角的 + (导入) 按钮。
  • 从文件选择器中选择一个 .md 或 .txt 文件。
  • WristTale 将自动解析文件、检测章节并将其添加到您的书库中。

常见问题 (FAQ)

1. 为什么需要安装 Garmin Connect？

WristTale 基于 Connect IQ Companion SDK 开发，该框架需要 Garmin Connect Mobile 应用来发现您的手表并在手机和手表之间建立通信连接。这是佳明官方为第三方应用提供的数据同步机制。

2. WristTale 有哪些使用场景？

除了看小说，WristTale 还适合很多场景：

  • 赛事手册：将越野跑、超马的赛道指南、补给站信息和关门时间存储在手表上，比赛中随时查看。
  • 学习资料：学生可以将课程笔记、公式、复习要点存放在手表中，随时翻阅。
  • 语言学习：存储单词表、常用短语或语法笔记，充分利用碎片时间学习。
  • 参考文档：任何需要随时查阅的文本资料。

小贴士：我们强烈建议使用 AI 工具（如 ChatGPT、Claude）来整理您的文档，它们可以：

  • 去除乱码和无用的特殊符号
  • 将内容组织为清晰的章节结构
  • 优化排版，让内容在手表小屏幕上更易阅读

3. 为什么我的章节没有被正确识别？

如果您导入的是标准 .txt 文件，章节检测依赖于模式匹配。如果您的书籍使用了独特或非标准的标题格式（例如使用"一、"、"二、"而非"第一章"），自动解析器可能会遗漏。

  • 解决方法：您可以在应用内手动编辑章节标题，或者将文件转换为带有明确 # 章节标题的 Markdown 格式。

4. 我可以编辑章节标题或内容吗？

可以！长按书籍封面打开菜单，选择书籍详情，或者直接点击书籍进入预览。在预览界面，点击任意章节即可查看内容。您可以点击内容区域修改正文，或点击顶部标题栏重命名章节。

5. 文本文件应该使用什么编码？

WristTale 针对 UTF-8 编码进行了优化。如果您的文件使用其他编码（如 GBK 或 Windows-1252），可能会出现乱码。请在导入前将文件转换为 UTF-8 编码。

6. 如何理解存储统计？

手表应用中的"存储统计"功能显示的单位是字节 (byte)，而非字符数。这是因为佳明采用 UTF-8 编码存储数据：

  • 英文字符/数字：1 字节
  • 中文字符：3 字节（极少数生僻字为 4 字节）

因此，如果您存储的主要是中文内容，需要将显示的字节数除以 3来估算大致的文字数量。例如：

  • 1.5M bytes ÷ 3 ≈ 50 万字中文小说

7. 同步是如何工作的？

WristTale 将书籍分割成微小的"数据块"，通过低功耗蓝牙 (BLE) 传输到您的 Garmin 手表。

  • 保持应用开启：同步期间，手机端和手表端的应用都必须保持在前台运行。
  • 防止屏幕休眠：手机应用会尝试保持屏幕常亮，但请勿手动锁屏。
  • 传输速度：受限于蓝牙带宽，传输大部头书籍可能需要一些时间。我们建议每次同步 20-50 章。

8. 为什么同步失败了？

  • 连接问题：请确保您的手表已通过 Garmin Connect Mobile 连接到手机。
  • 应用状态：尝试强制关闭并重启手机和手表上的 WristTale 应用。
  • 测试版限制：如果您使用的是 Beta 测试版，每本书可能有 20 章的同步上限。

9. 书籍在手表上存储在哪里？

书籍存储在手表应用的私有存储空间中，无法通过 USB 文件系统直接访问。如需清理空间，请在手表应用的菜单中使用清空存储选项。

10. 支持深色模式吗？

是的，WristTale 完美支持 iOS 和 Android 的系统深色模式。手表端的阅读界面也针对 AMOLED 屏幕进行了省电优化（纯黑背景）。