README-zhCN.md

Zotero Plugin Template So 插件模板

这是 Zotero 的插件模板.

开发指南
- 📖 插件开发文档 (中文版，尚不完善)
- 📖 Zotero 7 插件开发文档
开发工具参考
- 🛠️ Zotero 插件工具包 | API 文档
- 🛠️ Zotero 插件开发脚手架
- 📜 Zotero 源代码
- ℹ️ Zotero 类型定义
- 📌 Zotero 插件模板 (即本仓库)

Tip 提示

👁 Watch 本仓库，以及时收到修复或更新的通知.

使用此模板构建的插件

如果你正在使用此库，我建议你将这个标志 () 放在 README 文件中:

[![Using Zotero Plugin Template](https://img.shields.io/badge/Using-Zotero%20Plugin%20Template-blue?style=flat-square&logo=github)](https://github.com/windingwind/zotero-plugin-template)

Features 特性特点特性

事件驱动、函数式编程的可扩展框架；
简单易用，开箱即用；
⭐[新特性!]自动热重载！每当修改源码时，都会自动编译并重新加载插件；详情请跳转→
src/modules/examples.ts 中有丰富的示例，涵盖了插件中常用的大部分API (使用 zotero-plugin-toolkit；
TypeScript 支持:
- 为使用 JavaScript 编写的 Zotero 源码提供全面的类型定义支持 (使用 zotero-types)；
- 全局变量和环境设置；
插件开发/构建/发布工作流:
- 自动生成/更新插件版本、更新配置和设置环境变量 (development/production)；
- 自动在 Zotero 中构建和重新加载代码；
- 自动发布到 GitHub ;
集成 Prettier 和 ES Lint;

Examples 示例示例示例

此库提供了 zotero-plugin-toolkit 中API的示例.

在 src/examples.ts 中搜索@example 查看示例. 这些示例在 src/hooks.ts 中调用演示.

基本示例(Basic Examples)

registerNotifier 注册通知程序
registerPrefs, unregisterPrefs
注册偏好、取消注册偏好

快捷键示例(Shortcut Keys Examples)

registerShortcuts 注册快捷方式
exampleShortcutLargerCallback
exampleShortcutSmallerCallback
exampleShortcutConflictionCallback
示例快捷方式冲突回调

UI示例(UI Examples)

registerStyleSheet(the official make-it-red example)
registerStyleSheet（官方的make-it-red示例）
registerRightClickMenuItem
注册右键菜单项
registerRightClickMenuPopup
注册右键菜单弹出
registerWindowMenuWithSeprator
注册窗口菜单带分隔符
registerExtraColumn 注册额外列
registerExtraColumnWithCustomCell
注册ExtraColumnWithCustomCell
registerCustomItemBoxRow 注册自定义项目框行
registerLibraryTabPanel 注册LibraryTabPanel
registerReaderTabPanel 注册ReaderTabPanel

首选项面板示例(Preference Pane Examples)

Preferences bindings 首选项绑定
UI Events 用户界面事件
Table 桌子
Locale 当地的

详情参见 src/modules/preferenceScript.ts

帮助示例(HelperExamples)

dialogExample 对话框示例
clipboardExample 剪贴板示例
filePickerExample filePicker示例
progressWindowExample 进度窗口示例
vtableExample(See Preference Pane Examples)
vtableExample（请参阅首选项窗格示例）

指令行示例(PromptExamples)

Obsidian风格的指令输入模块，它通过接受文本来运行插件，并在弹出窗口中显示可选项.

使用 Shift+P 激活.

registerAlertPromptExample
注册AlertPrompt示例

快速上手

0 环境要求

安装 beta 版 Zotero
安装 Node.js 和 Git

Note 笔记

本指南假定你已经对 Zotero 插件的基本结构和工作原理有初步的了解. 如果你还不了解，请先参考官方文档和官方插件样例 Make It Red。

1 创建你的仓库(Create Your Repo)

点击 Use this template；
使用 git clone 克隆上一步生成的仓库；
💡 从 GitHub Codespace 开始

GitHub CodeSpace 使你可以直接开始开发而无需在本地下载代码/IDE/依赖.

重复下列步骤，仅需三十秒即可开始构建你的第一个插件！
- 点击首页 Use this template 按钮，随后点击 Open in codespace，你需要登录你的 GitHub 账号.
- 等待 codespace 加载.
进入项目文件夹；

2 配置模板和开发环境(Config Template Settings and Enviroment)

修改 ./package.json 中的设置，包括：

{
  version: "", // 修改为 0.0.0
  author: "",
  description: "",
  homepage: "",
  config: {
    addonName: "", // 插件名称
    addonID: "", // 插件 ID 【重要：防止冲突】
    addonRef: "", // 插件命名空间：元素前缀等
    addonInstance: "", // 注册在 Zotero 根下的实例名
    prefsPrefix: "extensions.zotero.${addonRef}", // 首选项的前缀
  },
}

[!warning] 注意设置 addonID 和 addonRef 以避免冲突.

如果你需要在 GitHub 以外的地方托管你的 XPI 包，请修改 zotero-plugin.config.ts 中的 updateURL 和 xpiDownloadLink。

复制 Zotero 启动配置，填入 Zotero 可执行文件路径和 profile 路径.

(可选项) 创建开发用 profile 目录：

此操作仅需执行一次: 使用 /path/to/zotero -p 启动 Zotero，创建一个新的配置文件并用作开发配置文件。
```
cp .env.example .env
vim .env
```
如果你维护了多个插件，可以将这些内容存入系统环境变量，以避免在每个插件中都需要重复设置。
运行 npm install 以安装相关依赖

如果你使用 pnpm 作为包管理器，你需要添加 public-hoist-pattern[]=*@types/bluebird* 到.npmrc, 详情请查看 zotero-types 的文档.

如果你使用 npm install 的过程中遇到了 npm ERR! ERESOLVE unable to resolve dependency tree ，这是由于上游依赖 typescript-eslint 导致的错误，请使用 npm i -f 命令进行安装。

3 开发插件

使用 npm start 启动开发服务器，它将：

在开发模式下预构建插件
启动 Zotero ，并让其从 build/ 中加载插件
打开开发者工具（devtool）
监听 src/** 和 addon/**.
- 如果 src/** 修改了，运行 esbuild 并且重新加载
- 如果 addon/** 修改了，(在开发模式下)重新构建插件并且重新加载

自动热重载

厌倦了无休止的重启吗？忘掉它，拥抱热加载！

运行 npm start.
编码. (是的，就这么简单)

当检测到 src 或 addon 中的文件修改时，插件将自动编译并重新加载.

💡 将此功能添加到现有插件的步骤

请参阅：zotero-plugin-scaffold。

调试代码

你还可以:

在 Tools->Developer->Run Javascript 中测试代码片段;
使用 Zotero.debug() 调试输出. 在 Help->Debug Output Logging->View Output 查看输出;
调试 UI. Zotero 建立在 Firefox XUL 框架之上. 使用 XUL Explorer 等软件调试 XUL UI.

XUL 文档: http://www.devdoc.net/web/developer.mozilla.org/en-US/docs/XUL.html

4 构建插件

运行 npm run build 在生产模式下构建插件，构建的结果位于 build/ 目录中.

构建步骤:

创建/清空 build/
复制 addon/** 到 build/addon/**
替换占位符：使用 replace-in-file 去替换在 package.json 中定义的关键字和配置 (xhtml、.flt 等)
准备本地化文件以避免冲突，查看官方文档了解更多（https://www.zotero.org/support/dev/zotero_7_for_developers#avoiding_localization_conflicts）
- 重命名**/*.flt 为 **/${addonRef}-*.flt
- 在每个消息前加上 addonRef-
使用 Esbuild 来将 .ts 源码构建为 .js，从 src/index.ts 构建到./build/addon/content/scripts
(仅在生产模式下工作) 压缩 ./build/addon 目录为 ./build/*.xpi
(仅在生产模式下工作) 准备 update.json 或 update-beta.json

Note 笔记

Dev & prod 两者有什么区别?

此环境变量存储在 Zotero.${addonInstance}.data.env 中，控制台输出在生产模式下被禁用.
你可以根据此变量决定用户无法查看/使用的内容.
在生产模式下，构建脚本将自动打包插件并更新 update.json.

5 发布

如果要构建和发布插件，运行如下指令：

# version increase, git add, commit and push
# then on ci, npm run build, and release to GitHub
npm run release

Note 笔记

在此模板中，release-it 被配置为在本地更新版本号、提交并推送标签，随后 GitHub Action 将重新构建插件并将 XPI 发布到 GitHub Release.

关于预发布

该模板将 prerelease 定义为插件的测试版，当你在 release-it 中选择 prerelease 版本 (版本号中带有 - )，构建脚本将创建一个 update-beta.json 给预发布版本使用，这将确保常规版本的用户不会自动更新到测试版，只有手动下载并安装了测试版的用户才能自动更新到下一个测试版. 当下一个正式版本更新时，脚本将同步更新 update.json 和 update-beta.json，这将使正式版和测试版用户都可以更新到最新的正式版.

Warning 警告

严格来说，区分 Zotero 6 和 Zotero 7 兼容的插件版本应该通过 update.json 的 addons.__addonID__.updates[] 中分别配置 applications.zotero.strict_min_version，这样 Zotero 才能正确识别，详情在 Zotero 7 开发文档（https://www.zotero.org/support/dev/zotero_7_for_developers#updaterdf_updatesjson）获取.

Details 更多细节

关于Hooks(About Hooks)

可以在 src/hooks.ts 中查看更多

当在 Zotero 中触发安装/启用/启动时，bootstrap.js > startup 被调用
- 等待 Zotero 就绪
- 加载 index.js (插件代码的主入口，从 index.ts 中构建)
- 如果是 Zotero 7 以上的版本则注册资源
主入口 index.js 中，插件对象被注入到 Zotero ，并且 hooks.ts > onStartup 被调用.
- 初始化插件需要的资源，包括通知监听器、首选项面板和UI元素.
当在 Zotero 中触发卸载/禁用时，bootstrap.js > shutdown 被调用.
- events.ts > onShutdown 被调用. 移除 UI 元素、首选项面板或插件创建的任何内容.
- 移除脚本并释放资源.

关于全局变量(About Global Variables)

可以在 src/index.ts中查看更多

bootstrap插件在沙盒中运行，但沙盒中没有默认的全局变量，例如 Zotero 或 window 等我们曾在overlay插件环境中使用的变量.

此模板将以下变量注册到全局范围:

Zotero, ZoteroPane, Zotero_Tabs, window, document, rootURI, ztoolkit, addon;

创建元素 API(Create Elements API)

插件模板为 bootstrap 插件提供了一些新的API. 我们有两个原因使用这些 API，而不是使用 createElement/createElementNS：

在 bootstrap 模式下，插件必须在推出（禁用或卸载）时清理所有 UI 元素，这非常麻烦. 使用 createElement，插件模板将维护这些元素. 仅仅在退出时 unregisterAll .
Zotero 7 需要 createElement()/createElementNS() → createXULElement() 来表示其他的 XUL 元素，而 Zotero 6 并不支持 createXULElement. 类似于 React.createElement 的API createElement 检测 namespace(xul/html/svg) 并且自动创建元素，返回元素为对应的 TypeScript 元素类型.

createElement(document, "div"); // returns HTMLDivElement
createElement(document, "hbox"); // returns XUL.Box
createElement(document, "button", { namespace: "xul" }); // manually set namespace. returns XUL.Button

关于 Zotero API(About Zotero API)

Zotero 文档已过时且不完整，克隆 https://github.com/zotero/zotero 并全局搜索关键字.

⭐zotero-types 提供了最常用的 Zotero API，在默认情况下它被包含在此模板中. 你的 IDE 将为大多数的 API 提供提醒.

猜你需要：查找所需 API的技巧

在 .xhtml/.flt 文件中搜索 UI 标签，然后在 locale 文件中找到对应的键. ，然后在 .js/.jsx 文件中搜索此键.

目录结构(Directory Structure)

本部分展示了模板的目录结构.

所有的 .js/.ts 代码都在 ./src;
插件配置文件：./addon/manifest.json;
UI 文件: ./addon/content/*.xhtml.
区域设置文件: ./addon/locale/**/*.flt;
首选项文件: ./addon/prefs.js;

.
|-- .github/                  # github conf
|-- .vscode/                  # vscode conf
|-- addon                     # static files
|   |-- bootstrap.js
|   |-- content
|   |   |-- icons
|   |   |   |-- favicon.png
|   |   |   `-- favicon@0.5x.png
|   |   |-- preferences.xhtml
|   |   `-- zoteroPane.css
|   |-- locale
|   |   |-- en-US
|   |   |   |-- addon.ftl
|   |   |   |-- mainWindow.ftl
|   |   |   `-- preferences.ftl
|   |   `-- zh-CN
|   |       |-- addon.ftl
|   |       |-- mainWindow.ftl
|   |       `-- preferences.ftl
|   |-- manifest.json
|   `-- prefs.js
|-- build                         # build dir
|-- node_modules
|-- src                           # source code of scripts
|   |-- addon.ts                  # base class
|   |-- hooks.ts                  # lifecycle hooks
|   |-- index.ts                  # main entry
|   |-- modules                   # sub modules
|   |   |-- examples.ts
|   |   `-- preferenceScript.ts
|   `-- utils                 # utilities
|       |-- locale.ts
|       |-- prefs.ts
|       |-- wait.ts
|       |-- window.ts
|       `-- ztoolkit.ts
|-- typings                   # ts typings
|   `-- global.d.ts

|-- .env                      # enviroment config (do not check into repo)
|-- .env.example              # template of enviroment config, https://github.com/northword/zotero-plugin-scaffold
|-- .gitignore                # git conf
|-- .gitattributes            # git conf
|-- .prettierrc               # prettier conf, https://prettier.io/
|-- eslint.config.mjs         # eslint conf, https://eslint.org/
|-- LICENSE
|-- package-lock.json
|-- package.json
|-- tsconfig.json             # typescript conf, https://code.visualstudio.com/docs/languages/jsconfig
|-- README.md
`-- zotero-plugin.config.ts   # scaffold conf, https://github.com/northword/zotero-plugin-scaffold

Disclaimer 免责声明

在 AGPL 下使用此代码. 不提供任何保证. 遵守你所在地区的法律！

如果你想更改许可，请通过 wyzlshx@foxmail.com 与我联系.

Provide feedback 提供反馈

Saved searches 已保存的搜索

Use saved searches to filter your results more quickly

README-zhCN.md

README-zhCN.md

Zotero Plugin Template So 插件模板

使用此模板构建的插件

Features 特性特点特性

Examples 示例示例示例

基本示例(Basic Examples)

快捷键示例(Shortcut Keys Examples)

UI示例(UI Examples)

首选项面板示例(Preference Pane Examples)

帮助示例(HelperExamples)

指令行示例(PromptExamples)

快速上手

0 环境要求

1 创建你的仓库(Create Your Repo)

2 配置模板和开发环境(Config Template Settings and Enviroment)

3 开发插件

自动热重载

调试代码

4 构建插件

5 发布

关于预发布

Details 更多细节

关于Hooks(About Hooks)

关于全局变量(About Global Variables)

创建元素 API(Create Elements API)

关于 Zotero API(About Zotero API)

目录结构(Directory Structure)

Disclaimer 免责声明

Files

README-zhCN.md

Latest commit

History

README-zhCN.md

File metadata and controls

Zotero Plugin Template So 插件模板

使用此模板构建的插件

Features 特性 特点 特性

Examples 示例 示例 示例

基本示例(Basic Examples)

快捷键示例(Shortcut Keys Examples)

UI示例(UI Examples)

首选项面板示例(Preference Pane Examples)

帮助示例(HelperExamples)

指令行示例(PromptExamples)

快速上手

0 环境要求

1 创建你的仓库(Create Your Repo)

2 配置模板和开发环境(Config Template Settings and Enviroment)

3 开发插件

自动热重载

调试代码

4 构建插件

5 发布

关于预发布

Details 更多细节

关于Hooks(About Hooks)

关于全局变量(About Global Variables)

创建元素 API(Create Elements API)

关于 Zotero API(About Zotero API)

目录结构(Directory Structure)

Disclaimer 免责声明

Features 特性特点特性

Examples 示例示例示例