Skip to content

Releases: zhongrubo/zotero-annotation-filter

Release list

v0.2

v0.2 Latest
Latest

Choose a tag to compare

View all tags
@zhongrubo zhongrubo released this 03 Sep 04:37
v0.2
da8de2d

批注筛选 Annotation Filter v0.2 更新：类型按钮改为图标显示、修复选区按钮空白、Draw 命名、新增插件图标。

Assets 3
Loading

批注筛选 Annotation Filter v0.1

批注筛选 Annotation Filter v0.1

Choose a tag to compare

View all tags
@zhongrubo zhongrubo released this 18 Aug 11:08
v0.1
075dc1b
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

批注筛选 Annotation Filter

Zotero version version platform license

在 Zotero 阅读器左侧侧栏的「注释」列表底部添加一个筛选工具栏，可按 批注类型 进行多选筛选，帮助研究者快速定位特定批注。

A Zotero plugin that adds a filter toolbar at the bottom of the reader's annotation list, allowing you to filter annotations by type.

目录

简介

在文献阅读中，我们经常会在 PDF / EPUB 上做大量批注。当批注数量变多（几十甚至数百条）时，要从中找到某一类批注会变得困难。本插件在 Zotero 阅读器左侧侧栏的注释列表底部加入一个轻量工具栏，让你可以：

  • 按 批注类型 筛选（高亮 / 下划线 / 笔记 / 文本 / 选区 / 手写）；
  • 多选组合（可同时选中多个类型，只显示匹配类型的批注）。

说明：Zotero 阅读器已原生支持按颜色筛选，因此本插件专注于按类型筛选，避免功能重复。

工具栏的 UI 复用 Zotero 阅读器侧栏原生的 CSS 变量与字体，自动适配浅色 / 深色主题，与 Zotero 界面融为一体。

功能特性

  • ✅ 六种批注类型筛选（多选）

    图标含义 类型 英文 说明
    🖍️ 高亮 Highlight 划重点的高亮标记
    ▔ 下划线 Underline 下划线标记
    🗒️ 笔记 Note 用户笔记注释
    ➕ 文本 / 新增文字 Inserted Text 在原文中插入的文字
    ⬚ 选区 / 图片 Area Selection 框选区域截图
    ✍️ 手写标记 Ink / Handwriting 手写 / 笔迹批注

  • ✅ 多选组合：可同时选中多个类型，只显示匹配所选类型的批注。

  • ✅ 隐藏而非删除：未匹配的批注仅被隐藏（display: none），不会修改或删除任何数据；点击「重置」即可完整恢复。

  • ✅ 一键重置：工具栏内置「重置」按钮，清空所有筛选条件。

  • ✅ 原生风格 UI：字体、字号、配色与 Zotero 阅读器侧栏一致，支持浅色 / 深色模式；类型按钮带等大线框，排列为 2×3 网格，标题为「按类型筛选批注」。

  • ✅ 高性能：筛选仅做 DOM 显示 / 隐藏，不改变批注数据，数百条批注下依然流畅。

  • ✅ 零配置：安装后工具栏自动出现在注释列表底部，无需任何设置。

安装

方法一：安装 Release 中的 .xpi（推荐）

  1. 到本仓库 Releases 页面下载最新版 zotero-annotation-filter-0.1.xpi；
  2. 打开 Zotero → 菜单「工具」→「插件」；
  3. 点击右上角齿轮 →「Install Plugin From File…（从文件安装附加组件）」；
  4. 选择下载的 .xpi 文件，确认安装；
  5. 重启 Zotero。

方法二：从源码构建

见 从源码构建。

使用

  1. 在 Zotero 中打开任意 PDF / EPUB 附件（进入阅读器）；
  2. 打开左侧侧栏的「注释」标签页（工具栏自动出现在注释列表底部）；
  3. 点击类型按钮进行多选筛选，再次点击取消；
  4. 点击「重置」清空全部筛选条件。

提示：类型按钮为多选，可自由组合。筛选结果会实时更新。

兼容性

项目 说明
Zotero 版本 7.0 及以上（strict_min_version: 7.0，strict_max_version: 10.9.9），已在 Zotero 9.0.x 实测通过
操作系统 Windows / macOS / Linux
文档类型 PDF、EPUB、Snapshot（快照）等 Zotero 阅读器支持的所有附件

更新源：manifest.json 的 update_url 指向本仓库的 update.json（GitHub Raw），用于 Zotero 自动更新检查。发布新版本时请同步更新该文件，详见 发布新版本。

目录结构

zotero-annotation-filter/
├── manifest.json       # 插件清单（Zotero 7 WebExtension 风格）
├── bootstrap.js        # 插件主逻辑（注入工具栏 + 筛选）
├── update.json         # Zotero 自动更新清单
├── README.md           # 本说明文档
├── LICENSE             # AGPL-3.0 许可证
├── CHANGELOG.md        # 更新日志
├── .gitignore          # Git 忽略规则
└── screenshots/        # 截图（可选）

.xpi 本质是 ZIP 压缩包，其中 manifest.json 与 bootstrap.js 必须位于压缩包根目录（不能多套一层文件夹）。

从源码构建

# 1. 克隆仓库
git clone https://github.com/zhongrubo/zotero-annotation-filter.git
cd zotero-annotation-filter

# 2. 打包为 .xpi（仅需这两个文件，且位于压缩包根目录）
zip -X -r zotero-annotation-filter-0.1.xpi manifest.json bootstrap.js

然后按 安装 的步骤安装生成的 .xpi 即可。

本插件为零依赖的纯 JavaScript 插件，无需 Node.js / npm 构建流程即可直接打包运行。

发布新版本

  1. 按需修改 manifest.json 的 version 与 bootstrap.js；

  2. 打包新的 .xpi：

    zip -X -r zotero-annotation-filter-<version>.xpi manifest.json bootstrap.js

  3. 在 GitHub 创建 Release（tag 用 v<version>），并把 .xpi 作为附件上传；

  4. 在 update.json 的 updates 数组中新增一条，填写 version 与对应的 Release 下载地址 update_link。

update.json 示例：

{
  "addons": {
    "annotation-filter@zhongrubo.github.io": {
      "updates": [
        {
          "version": "0.1",
          "update_link": "https://github.com/zhongrubo/zotero-annotation-filter/releases/download/v0.1/zotero-annotation-filter-0.1.xpi"
        }
      ]
    }
  }
}

注意：update.json 中的插件 ID 必须与 manifest.json 的 applications.zotero.id 完全一致。

收录到 Zotero 插件市场

本插件可被收录进 Zotero 插件市场（Add-on Market for Zotero，即 Zotero 内置的「插件市场」），供用户在 Zotero 内直接检索、安装。

收录条件：

  1. 插件托管在公开的 GitHub 仓库，并通过 Release 发布 .xpi（见 发布新版本）；
  2. 向市场数据源 syt2/zotero-addons-scraper 提交 PR，新增一个条目文件。

提交步骤：

  1. Fork syt2/zotero-addons-scraper；
  2. 在 addons/ 目录下新增一个文件：
    • 文件名：zhongrubo@zotero-annotation-filter
    • 内容（标签最多两个，本插件归属「阅读器 / 批注」）： 
      {"tags": ["reader"]}
  3. 提交并创建 Pull Request；
  4. 待 CI 抓取信息、维护者合并后，即可在 Zotero 插件市场中检索到本插件。

可用标签：ai / metadata / reader / notes / attachment / interface / integration / utility。本插件推荐 reader（阅读与批注），也可追加 utility。

技术实现

  • 注入时机：通过 Zotero.Reader.registerEventListener("renderToolbar", …) 在阅读器每次渲染后注入工具栏；
  • 数据监听：通过 Zotero.Notifier（item 类型）监听批注的新增 / 修改 / 删除；
  • 兜底刷新：低频轮询（700ms）处理插件启用前已打开的阅读器与侧栏重挂载等情况，这是最可靠的注入手段；
  • 筛选映射：从 reader._item.getAnnotations() 读取每个批注的 annotationType，与侧栏 DOM 中的 data-sidebar-annotation-id（即批注 item key）一一对应，据此显示 / 隐藏 .annotation 元素；
  • 样式：复用 Zotero 阅读器侧栏的 CSS 变量（--material-sidepane、--material-panedivider、--fill-secondary、--color-border 等），自动适配主题。

常见问题

Q：安装后工具栏没有出现？
A：请确认已重启 Zotero，并在阅读器中打开「注释」侧栏标签页。工具栏位于注释列表最底部。

Q：筛选后批注“消失”了，是数据被删除了吗？
A：没有。筛选只是隐藏（display: none），不会修改或删除任何批注。点击「重置」即可恢复全部批注。

Q：如何更新插件？
A：Zotero 会通过 update_url 指向的 update.json 自动检查更新；也可以手动下载最新 .xpi 覆盖安装。

参与贡献

欢迎提交 Issue 与 Pull Request！

  1. Fork 本仓库；
  2. 创建特性分支（git checkout -b feature/xxx）；
  3. 提交修改（git commit -m 'feat: xxx'）；
  4. 推送到分支（git push origin feature/xxx）；
  5. 发起 Pull Request。

提交前请确保 bootstrap.js 语法正确（node --check bootstrap.js）并重新打包验证。

许可证

本项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 开源许可。详见 LICENSE。

选择 AGPL-3.0 与 Zotero 本体保持一致。使用、修改与分发时请遵守许可证条款。

致谢

Loading