Chartero插件版本迁移指南：从Zotero 7到8的平滑过渡方案

【免费下载链接】CharteroChart in Zotero项目地址: https://gitcode.com/gh_mirrors/ch/Chartero

您是否遇到过这样的场景：升级Zotero到最新版本后，Chartero插件的侧边栏突然消失，阅读统计数据无法加载，或者图表显示异常？这些问题往往源于Zotero 7到8的架构性变更，主要表现为三个方面：

文献管理工作流中断：当您在Zotero 8中打开PDF文献时，阅读进度无法记录，历史统计数据为空。这是因为Zotero 8重构了阅读器模块，原有的Zotero.Reader.getByTabID()接口已被移除。

设置面板无法访问：尝试调整Chartero偏好设置时，界面无响应或显示空白。这是由于Zotero 8将偏好系统从Zotero.Prefs迁移到了Zotero.PreferencePanes。

数据可视化异常：仪表盘图表加载失败，提示"数据格式错误"。这是因为Zotero 8采用了基于会话的阅读数据存储格式，与Zotero 7的页面粒度格式不兼容。

变更类型	Zotero 7特性	Zotero 8特性	影响范围	解决优先级
API接口	`Zotero.Reader.getByTabID()`	`Zotero.Reader.getReaderByTabID()`	阅读记录、进度跟踪	高
偏好系统	`Zotero.Prefs.get()`	`Zotero.PreferencePanes.get()`	设置面板、用户配置	中
事件机制	`onSelect.addListener()`	`onItemsSelect.addListener()`	侧边栏交互、数据更新	高
数据存储	页面粒度记录	会话粒度记录	统计分析、历史数据	中
UI架构	XUL界面组件	`Zotero_Tabs`新组件	侧边栏、仪表盘渲染	中

在开始迁移前，请先通过以下决策路径确定适合您的方案：

当前版本检测：
若您使用Zotero 7 Beta55及以上版本，且无紧急功能需求，建议采用增量适配策略
若已升级到Zotero 8或需要使用新功能，需执行全量迁移
数据重要性评估：
阅读历史数据量 < 100条：直接采用新版格式
阅读历史数据量 ≥ 100条：先执行数据备份再迁移

📌操作要点：

该架构通过三层设计实现版本兼容：

当从Zotero 7迁移到8时，系统会自动执行以下转换流程：

📌操作要点：

适用于Zotero 7用户希望提前兼容Zotero 8的场景：

环境准备

git clone https://gitcode.com/gh_mirrors/ch/Chartero cd Chartero npm install

构建兼容版本
```
npm run build:compat
```
安装测试版本
- 打开Zotero → 工具 → 插件 → 安装附加组件
- 选择dist/chartero.xpi文件
- 重启Zotero完成安装

适用于已升级到Zotero 8的用户：

数据备份
- 打开Chartero设置面板 → 数据管理 → 导出数据
- 保存备份文件（建议命名格式：chartero_backup_YYYYMMDD.json）
卸载旧版插件
- Zotero菜单 → 工具 → 插件 → 找到Chartero → 移除
- 重启Zotero确保完全卸载
安装新版插件
- 从项目 Releases 页面下载最新版chartero-x.y.z.xpi
- 安装并重启Zotero
数据恢复
- 打开Chartero设置面板 → 数据管理 → 导入数据
- 选择之前备份的JSON文件
- 等待数据转换完成（大文件可能需要3-5分钟）