readme.Md

Chartero

English | 简体中文

简介

Chartero 这个名字是连接了 Chart 与 Zotero，作为一个Zotero插件，它可以帮助你更直观地了解你的文献库。

使用指南

• ⚠️ 从 Zotero6旧版更新后请先前往首选项页面导入旧版历史数据后再使用！！！

旧版数据迁移

新版本记录格式采用 note 与附件一、一对应的形式。若当前电脑使用过旧版 chartero，则可在_首选项->存储_中点击“自动搜索并导入旧版数据”按钮，否则需要手动复制旧版 json 数据到文本框中再点击“导入粘贴的历史记录”按钮。导入时会覆盖已有的新版记录。

此外，旧版扫描周期以毫秒为单位，新版以秒为单位，自动导入时会自动将周期除以 1000，否则需手动修改！。

👉 主要功能 👈

截图	功能
	Chartero的核心功能，当你阅读文献时，记录当前页面与时间。
	在主菜单文件中，可以打开最近读过的文档。
	在文库视图中新增一列信息显示当前条目的阅读时长。
	可视化与当前条目相关的所有信息，在阅读器的侧边栏可实时刷新。
	总结多个条目之间的关系，若选中条目数超过首选项中设置的值，则不会加载。
	在阅读器滚动条旁边，灰色块表示对应页面的阅读时长，彩色条表示注释。
	点击主菜单 → 查看 → 文库总览后弹出标签页
	在阅读器左侧边栏显示当前文档中的所有图片。单击可跳转，双击可复制。若 PDF 图片过多，则每次只加载 10 页，点击最下方按钮可手动加载更多。

FAQ

开发指南

• 

• 图表采用 生成

• Minimap与图片提取采用内置 渲染

• 图片提取功能在ChromeWorker中调用内置PDF.js实现。

• UI 组件库使用

• 欲参考纯 JavaScript 版本（适用于 Zotero 6）请切换分支

目录结构

• addon：存放插件所需的资源文件，详见模板
• tools：存放开发环境所需的脚本文件等
• src

  • src/bootstrap：主窗口环境中运行的代码

    • src/bootstrap/modules：各个功能模块的实现细节

  • src/vue：使用 Vue 的 iframe 页面

    • src/vue/summary：分类统计（在文件夹的侧边栏）
    • src/vue/dashboard：仪表盘（在普通条目的侧边栏）
    • src/vue/overview：文库概览（单独标签页）
    • src/vue/utility：一些辅助代码
    • src/vue/test：测试模块

  • src/modules：Git子仓库，用于在VS Code中调试TS源码

    • 初始化：

      git submodule init
      git submodule update

  • src/worker：数据处理的后台线程

URL

这些链接在bootstrap.js中注册，可以在Zotero中通过fetch函数访问：

• chrome://chartero/：访问addon文件夹
• resource://chartero/：访问addon/content文件夹

全局变量

与其他插件不同，Chartero 没有在全局 Zotero 变量下定义任何对象，仅可通过侧边栏 iframe 窗口访问window.addon。

在_src/bootstrap_与_src/vue_中各有一个 global.d.ts 文件，定义了该目录下可访问的全局变量。 由zotero-types定义的Zotero等变量在 Vue 中未定义。 addon是整个插件内部的“全局”变量，定义在 SandBox 中，插件外不可访问。新建 iframe 时通过contentWindow将其传入 Vue。

默认设置

package.json的config.defaultSettings字段定义了插件使用的所有首选项及其默认值，编译时将自动替换addon中相应内容，同时在 TS 中提供类型检查。

多语言

locale文件夹下定义了不同语言在 UI 上显示的字符串，插件启动时动态加载，同时在 TS 中提供类型检查。

开发环境

package.json中定义了构建项目所需的 npm 脚本，修改tools/zotero-cmd.json后，在 vscode 的主菜单Run Task…中选择指令npm: build即可以开发模式全部编译并重载 Zotero。使用带有NODE_ENV=development的指令时，全局变量__dev__为true，插件进入调试模式，此时debug.ts会注册一些调试用的选项。

• 以下列出了一些常用的指令：
  • reload-all：以生产环境全部编译并重载 Zotero
  • reload-dev：以开发环境跳过vue部分的编译并重载 Zotero
  • build：以开发环境全部编译并重载 Zotero
  • watch：实时监听Vue更改并编译后重载 Zotero
  • dev：开启vue测试模块热重载

⚡热重载与源码断点

开启Zotero的状态下，在VS Code的侧边栏调试面板中运行Vue配置可以开启Vue测试模块的热重载并呼出Firefox，此时可以在Firefox中使用Vue调试插件，也可以在VS Code中设置断点进行单步调试。

插件在开发环境下会在本地服务器注册一个/test/chartero的路由，该节点会eval任何POST请求来的指令并以JSON格式返回结果。Vue测试模块提供了一系列“dummy”类，通过访问/test/chartero路由来仿真Zotero环境，此方法对其他 Zotero 客户端应用具有借鉴价值。

阅读记录结构

history/data.ts定义了阅读记录的数据结构。转换成 JSON 字符串后的形式如下：

{
    "pages": {
        "0": {
            "p": {
                "1693200000": 6
            }
        }
    },
    "numPages": 27
}

其中pages为页码与记录的映射，numPages为总页数。p意为 “period”，其键为时间戳，值为记录周期（单位：秒）。

插件间兼容性

一些不太优雅的实现，可能导致潜在的兼容性问题，供其他插件开发者查错时参考。

• 篡改了Zotero.Search对象的search方法，使其无法搜索到存储历史记录的笔记条目。

• 显示“所有图片”的侧边栏添加时给其他选项卡按钮添加了点击事件，可能导致冲突。

• 打开“文库总览”时contextPane.js会抛出异常extraData[ids[0]] is undefined，忽略即可。

友情链接

• 🤩 Awesome Zotero Plugins

---