zotero-style API参考：完整接口文档和使用示例

zotero-style是一个功能强大的Zotero插件，提供了丰富的API接口来增强文献管理体验。本文档详细介绍了所有可用的API接口和使用方法。

核心API接口

1. 主模块接口

Addon类 (src/addon.ts) 是整个插件的核心入口点：

// 获取插件实例
const addon = Zotero.ZoteroStyle;

// 访问工具包
const toolkit = addon.data.ztoolkit;

// 检查运行环境
const isDevelopment = addon.data.env === "development";

2. 生命周期钩子

Hooks模块 (src/hooks.ts) 提供了完整的生命周期管理：

// 启动时初始化
addon.hooks.onStartup();

// 界面加载完成
addon.hooks.onMainWindowLoad(window);

// 偏好设置窗口加载
addon.hooks.onPrefsWindowLoad(window);

3. 项目处理接口

Item模块 (src/modules/item.ts) 提供了文献项目处理功能：

// 获取文献阅读进度
const progress = addon.item.getReadingProgress(itemID);

// 更新文献状态
addon.item.markAsRead(itemID, true);

// 获取文献标签信息
const tags = addon.item.getFormattedTags(itemID);

功能模块API

4. 进度管理

Progress模块 (src/modules/progress.ts) 提供阅读进度可视化：

// 获取文献阅读统计
const stats = addon.progress.getReadingStats(itemID);

// 更新页面阅读时间
addon.progress.updatePageTime(itemID, pageNumber, duration);

// 重置阅读进度
addon.progress.resetProgress(itemID);

5. 标签管理

Tags模块 (src/modules/tags.ts) 提供高级标签功能：

// 获取嵌套标签结构
const nestedTags = addon.tags.getNestedTags();

// 创建新标签分类
addon.tags.createTagCategory(name, color);

// 过滤特定前缀标签
const filteredTags = addon.tags.filterTagsByPrefix('#');

6. 视图管理

Views模块 (src/modules/views.ts) 管理界面视图：

// 切换视图组
addon.views.switchViewGroup('research');

// 保存当前视图配置
addon.views.saveCurrentView('my-view');

// 获取所有可用视图
const availableViews = addon.views.getAllViews();

数据处理API

7. 本地存储

LocalStorage模块 (src/modules/localStorage.ts) 提供数据持久化：

// 存储用户配置
addon.storage.set('user.preferences', preferences);

// 读取存储数据
const config = addon.storage.get('app.config');

// 清除特定数据
addon.storage.remove('temp.data');

8. 工具函数

Utils模块 (src/modules/utils.ts) 提供通用工具：

// 格式化日期时间
const formatted = addon.utils.formatDate(new Date());

// 生成唯一ID
const uniqueId = addon.utils.generateId();

// 深拷贝对象
const cloned = addon.utils.deepClone(object);

事件系统API

9. 事件管理

Events模块 (src/modules/events.ts) 提供事件处理：

// 注册事件监听器
addon.events.on('itemUpdated', callback);

// 触发自定义事件
addon.events.emit('customEvent', data);

// 移除事件监听
addon.events.off('itemUpdated', callback);

配置和偏好设置

10. 偏好设置管理

Prefs模块 (src/modules/prefs.ts) 处理用户配置：

// 获取偏好设置值
const value = addon.prefs.get('key');

// 设置偏好设置
addon.prefs.set('key', value);

// 监听设置变化
addon.prefs.onChange('key', callback);

使用示例

基本初始化

// 等待Zotero加载完成
if (typeof Zotero !== 'undefined' && Zotero.ZoteroStyle) {
    const style = Zotero.ZoteroStyle;
    // 使用插件功能
    const progress = style.item.getReadingProgress(12345);
}

自定义扩展开发

开发者可以利用这些API创建自定义功能扩展，提升文献管理体验。