Bookshelf Token占位符终极清单：%title到条件判断一次学会

如果你在用 KOReader 的 Bookshelf 插件打造个性化书架，那 Token 占位符 就是最强的定制工具：它让顶部面板、状态行和列表视图的每一行文字都能由 %title、%author、%book_pct 这类占位符动态填充，还能配合 [if:...]...[/if] 条件判断按阅读状态、电量、语言等数据"见招拆招"。这篇指南把 Bookshelf 的 Token 语法从入门到进阶一次讲透，新手也能照着写出自己的模板。

一、先认识 Token：它在哪里生效

Bookshelf 里所有可编辑的文字行——封面顶部的预览卡（标题、作者、简介、系列）、屏幕最上方的状态行（默认显示剩余空间、电量、灯光、Wi-Fi、时间）、列表视图的行、封面下的自定义说明——都可以插入 Token。

最简单的例子：

• %title → 当前书名
• %author → 第一作者
• %book_pct → 已读百分比

在设置里点 menu > Settings > Edit top panel content 打开行编辑器，就会看到 Tokens… 按钮：点开后是一个带搜索、分类和实时预览的占位符目录，挑一个插入即可，不需要死记语法。

💡 小技巧：目录里的每个 Token 都附有说明文字，例如 %rating 显示为星级（★★★☆☆），未评分时为空——空值正好能配合条件判断实现"没评分就不显示"。

二、分类占位符终极清单

下面是完整的 Token 速查表（与 lib/bookshelf_tokens.lua 中的目录一一对应）。

📚 书籍元数据

Token	含义	示例
%title	书名	The Great Gatsby
%author	第一作者	F. Scott Fitzgerald
%author_2 / %author_3	第二 / 第三作者	无则留空
%authors	全部作者，逗号分隔	Neil Gaiman, Terry Pratchett
%authors_short	短作者列表：1 人直接显示，2 人"A and B"，3 人以上"A, B, et al."	适合合集封面
%author_count	作者人数（数字）	2
%genres / %genre	全部 / 第一个标签（即 calibre 的 tags）	Science Fiction
%series_name / %series_num	系列名 / 系列编号	Dune / 1
%rating	星级（未评分为空）	★★★☆☆
%rating_number	评分数字 1–5	3
%hardcover_rating / %hardcover_stars	缓存的 Hardcover 评分（数字 / 星级，可带半星）	4.5
%status	阅读状态原始值：unread / reading / on_hold / finished	reading
%status_label	状态的可读标签（Unread / Reading / On hold / Finished）	Reading
%favourite	收藏图标（非收藏为空）	♥
%size	文件大小	2.2 MB
%added / %opened	文件加入日 / 最近打开日	2026-05-03
%calibre{name}	任意 Calibre 列（含自定义列）	%calibre{pubdate}
%filename / %format / %lang	文件名 / 格式 / 语言	EPUB / en
%description	内容简介（自动去 HTML）	书籍简介文本
%quote / %quote_source / %quote_page / %quote_chapter	本书的一条随机高亮及出处、页码、章节	"……"
%highlights / %notes / %bookmarks / %annotations	高亮、笔记、书签数及总和	12 / 3 / 2 / 17

📖 位置与进度

Token	含义	示例
%page_num / %page_count	当前页 / 总页数（EPUB 未打开前可能为空）	42 / 218
%pages_left	剩余页数	176
%book_pct / %book_pct_left	已读 / 剩余百分比	19% / 81%
%book_pct_read	实际读过的比例（区别于"当前所在位置"）	44%
%bar	进度条控件（仅 Progress 区域）	▰▰▱▱
%bar{rel}	长度反映书籍厚度的进度条	长书长条
%spacer	弹性空隙：把内容推向左右边缘	见下方示例

%spacer 是最有魔力的一对字符：Reading%spacer47% 会把 Reading 钉在左边、47% 钉在右边，中间自动留白撑满整行。

⏱️ 时间与日期

Token	示例
%time / %time_24h	14:35
%time_12h	2:35 pm
%date / %date_long / %date_numeric	3 May / 3 May 2026 / 03/05/2026
%weekday / %weekday_short	Monday / Mon
%datetime{格式}	任意 os.date 格式，如 %datetime{%H:%M}

📊 统计（需启用 statistics 插件）

%book_time_left（剩余时间）、%book_read_time（已读总时长）、%book_pages_read（已读页数）、%days_reading_book（第几天在读）、%pages_per_day（日均页数）、%speed（页/小时）、%avg_page_time（单页均时）。插件没开或本书没有记录时，这些 Token 自动隐藏，不会打出空壳文字。

🔌 设备状态

Token	说明
%batt / %batt_icon	电量百分比 / 带充电状态的电池图标
%wifi_icon	Wi-Fi 图标（连接中 / 未连接两种形态）
%light / %light_pct / %light_icon	灯光强度：原始值（关灯时显示 OFF）/ 百分比 / 灯泡图标
%warmth / %warmth_pct / %warmth_icon	色温：设备原生刻度（Kindle 为 0–24）/ 百分比 / 三档温度计图标（仅自然光机型）
%nightmode	夜间模式月亮图标 / 白天太阳图标
%mem / %ram / %sysused / %disk	系统内存占用 / KOReader 内存 / 已用 MiB / 剩余存储 GB
%ssh_icon	SSH 服务运行中才显示的终端图标

📚 全图书馆级别

%books_read（标记 Finished 的总本数，%books_finished 是它的别名）、%books_started（有阅读时长记录的本数）、%total_read_time（累计阅读时长）、%pages_today / %time_today（今日阅读页数 / 时长）。它们与具体哪本书无关，最适合放在状态行和微型模块里——Bookshelf 首页状态行默认的"Books read: 16 · 11:50 PM"就是一行模板渲染出来的。

三、条件判断语法：[if:...] 一次讲清

条件判断是 Token 进阶的核心。基本形态：

[if:条件]满足时显示的内容[/if]
[if:条件]满足时显示[else]不满足时显示[/if]

条件支持三种写法，可用 and / or / not 自由组合：

写法	含义
[if:rating]	只要 Token 有值（非空、非 0）就成立
[if:foo>50]	数值比较，运算符支持 = != < > <= >=
[if:lang="ja"]	字符串相等比较（用双引号包住值）

几个拿来即用的实战模板：

[if:batt<20]LOW BATTERY %batt[/if]
[if:book_time_left]%book_time_left LEFT[else]Open to start reading[/if]
[if:not series]Standalone[/if]
[if:connected]%wifi_icon[/if]
%time_12h[if:full_width]   ·   %date[/if]

要点说明：

• connected 与 full_width 是"隐形 Token"：前者仅当 Wi-Fi 真正联网时成立，后者仅当状态行处于宽屏环境（微型模块/全屏视图）成立，让你在空间够用时才多塞一个日期进去。
• 可嵌套：[if:] 块可以任意层套娃，引擎会从最内层逐层求值。
• 数字按数字比，字符串按字符串比：[if:book_pct>50] 比较的是百分比数值，[if:status=finished] 比较的是状态字符串——所以 %status 返回的四个规范值（unread / reading / on_hold / finished）是"承重墙"，不要期待它变成别的写法。

四、三个容易踩的坑（及解法）

坑 1：Token 紧贴字母会被"吃字"

Token 名会一直读到下一个非字母字符，所以 %author 后面直接跟 s 会被当成 %authors，打出全部作者。解法是用尖括号把名字"封口"：

%<author>s book      ->  Frank Herberts book
%<page_num>/%<page_count>  ->  42/500

坑 2：%warmth 的刻度变了

%warmth 现在输出设备原生刻度（Kindle 上最大 24），不再输出 0–100 百分比。如果你从旧模板里抄来 [if:warmth>50] 会发现永远不成立——改用 %warmth_pct 或按 24 为上限写条件即可。

坑 3：状态值用对了才是"翻译"而不是"破坏"

%status 是给条件判断用的原始值（英文、不翻译、不大写），%status_label 才是给人看的标签。想显示"Reading"直接用 %status_label，而不是去翻译 %status——后者一改，所有基于它的条件就静默失效了。同理，%books_read 与 %books_finished、%favourite 与 %favorite 都是等价的别名写法，抄别人的模板时不用纠结拼写。

五、把清单用起来：三步上手

1. 打开 menu > Settings > Edit top panel content，找到想改的文字区块，点进行编辑器。
2. 点 Tokens… 从分类目录挑选占位符，或对照本文速查表手动敲入模板。
3. 保存后回到书架看效果；不满意随时点编辑器里的 Default 一键还原默认模板。

更多模板思路（封面说明自定义、列表行排版、状态行默认值）见 README.md 的 "Token cheatsheet" 一节，Token 目录与展开引擎的完整实现都在 lib/bookshelf_tokens.lua，与 Bookends 插件共享的格式化规则在 lib/token_semantics.lua。从 %title 到 [if:and/or]，这份清单基本覆盖了 Bookshelf 模板系统的全部能力——剩下的，就动手写你自己的那一行吧。