feat: add chinese readme document (#75 )

* feat: add chinese readme document

* docs: fixed some translation errors

* move: readme-zhCN

---------

Co-authored-by: windingwind <33902321+windingwind@users.noreply.github.com>

2023-11-13 02:37:28 -06:00

18 KiB

Raw Blame History

Zotero Plugin Template

这是 Zotero 的插件模板.

English | 简体中文

使用此模板创建的一些插件:

📖 插件开发文档 (中文版)

🛠️ Zotero 插件工具包 | API 文档

ℹ️ Zotero 类型定义

📜 Zotero 源代码

📌 Zotero 插件模板 (即当前库)

👁 关注此库，以便在有修复或更新时及时收到通知.

如果你正在使用此库，我建议你将这个标志 () 放在 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 特性

❗Zotero系统已升级(dtd 已弃用，我们将不在使用 .properties). 主分支将只支持 Zotero 7.0.0-beta.12 或更高版本. 如果需要支持 Zotero 6，可能需要同时使用dtd、properties 和ftl. 请参考此库的 zotero6-bootstrap 分支.

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

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)
registerRightClickMenuItem
registerRightClickMenuPopup
registerWindowMenuWithSeprator
registerExtraColumn
registerExtraColumnWithCustomCell
registerCustomItemBoxRow
registerLibraryTabPanel
registerReaderTabPanel

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

Preferences bindings
UI Events
Tabel
Locale

详情参见 src/modules/preferenceScript.ts

帮助示例(HelperExamples)

dialogExample
clipboardExample
filePickerExample
progressWindowExample
vtableExample(See Preference Pane Examples)

指令行示例(PromptExamples)

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

使用 Shift+P 激活.

registerAlertPromptExample

Quick Start Guide 快速入门指南

安装预构建 `xpi`

通过直接在GitHub中下载构建好的 xpi 文件并将其安装到Zotero中来了解示例的工作原理.

这也是你发布插件的格式，同时这也将是其他人可以直接使用的版本.

该库构建好的xpi文件不具有任何实际功能，它可能不随Zotero更新而随时更新.

xpi 文件实际上是一个zip压缩包，然而，请不要直接修改它，而是修改源代码并重新构建它.

从源码构建(Build from Source)

Fork 此库或者使用 Use this template；
使用 git clone 克隆此库；
进入项目文件夹；

💡 从 GitHub Codespace 开始

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

重复下列步骤，仅需三十秒即可开始构建你的第一个插件！

去 homepage顶部，点击绿色按钮Use this template，点击 Open in codespace，你需要登录你的GitHub账号.
等待 codespace 加载.
修改 ./package.json 中的设置，包括：

{
  version,
  author,
  description,
  homepage,
  config {
    releasepage, // URL to releases(`.xpi`)
    updaterdf, // URL to update.json
    addonName, // name to be displayed in the plugin manager
    addonID, // ID to avoid conflict. IMPORTANT!
    addonRef, // e.g. Element ID prefix
    addonInstance // the plugin's root instance: Zotero.${addonInstance}
  }
}

注意设置 addonID 和 addonRef 以避免冲突.

运行 npm install 以设置插件并安装相关依赖. 如果你没有安装 Node.js，请在此处下载;

运行 npm run build 以在生产模式下构建插件，运行 npm run build-dev 以在开发模式下构建插件. 用于安装的 xpi 文件和用于构建的代码在 build 文件夹下.

Dev & prod 两者有什么区别?

此环境变量存储在 Zotero.${addonInstance}.data.env 中，控制台输出在生产模式下被禁用.

你可以根据此变量决定用户无法查看/使用的内容.

发布(Release)

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

# A release-it command: version increase, npm run build, git push, and GitHub release
# You need to set the environment variable GITHUB_TOKEN https://github.com/settings/tokens
# release-it: https://github.com/release-it/release-it
npm run release

设置开发环境(Setup Development Environment)

安装 Zotero: https://www.zotero.org/support/beta_builds (Zotero 7 beta: https://www.zotero.org/support/dev/zotero_7_for_developers)
安装 Firefox 102 (适用于 Zotero 7)
复制 zotero 命令行配置文件，修改开始安装 beta Zotero 的命令.

(可选项) 此操作仅需执行一次: 使用 /path/to/zotero -p 启动 Zotero，创建一个新的配置文件并用作开发配置文件. 将配置文件的路径 profilePath 放入 zotero-cmd.json 中，以指定要使用的配置文件.
```
cp ./scripts/zotero-cmd-default.json ./scripts/zotero-cmd.json
vim ./scripts/zotero-cmd.json
```
构建插件并使用 npm run restart 重启 Zotero.
启动 Firefox 102 (Zotero 7)
在 Firefox 中，转到devtools，转到设置，单击 "enable remote debugging" ，同时，旁边的按钮也是关于调试的。

在 FirFox 102 中输入 about:debugging#/setup .
在 Zotero 中，进入设置-高级-编辑器，搜索 "debugging" 然后单击 "allow remote debugging".
在 Firefox 中连接 Zotero. 在 FireFox 102中，在远程调试页面底部输入 localhost:6100 然后单击 add.
在远程调试页面左侧栏点击 connect.
点击 "Inspect Main Process"

自动热重载(Auto Hot Reload)

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

运行 npm run start-watch. (如果Zotero已经在运行，请使用 npm run watch)
编码. (是的，就这么简单)

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

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

复制 scripts/reload.mjs
复制 reload 、watch 和 start-watch 命令 package.json
运行 npm install --save-dev chokidar-cli
结束.

在 Zotero 中调试

你还可以:

在 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

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 中查看更多

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

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

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

关于构建(About Build)

使用 Esbuild 将 .ts 源代码构建为 .js.

使用 replace-in-file 去替换在 package.json 中定义的关键字和配置 (xhtml、.flt 等).

步骤 scripts/build.mjs:

清理 ./build
复制 ./addon 到 ./build
Esbuild 到 ./build/addon/chrome/content/scripts
替换__buildVersion__ 和 __buildTime__ 在 ./build/addon
压缩 ./build/addon 到 ./build/*.xpi

关于 Zotero API(About Zotero API)

Zotero 文档已过时且不完整，git clone 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/chrome/content/*.xhtml.
区域设置文件: ./addon/locale/**/*.flt;
首选项文件: ./addon/prefs.js;

不要在 prefs.js 中换行

.
|-- .eslintrc.json            # eslint conf
|-- .gitattributes            # git conf
|-- .github/                  # github conf
|-- .gitignore                # git conf
|-- .prettierrc               # prettier conf
|-- .release-it.json          # release-it conf
|-- .vscode                   # vs code conf
|   |-- extensions.json
|   |-- launch.json
|   |-- setting.json
|   `-- toolkit.code-snippets
|-- package-lock.json         # npm conf
|-- package.json              # npm conf
|-- LICENSE
|-- README.md
|-- addon
|   |-- bootstrap.js               # addon load/unload script, like a main.c
|   |-- chrome
|   |   `-- content
|   |       |-- icons/
|   |       |-- preferences.xhtml  # preference panel
|   |       `-- zoteroPane.css
|   |-- locale                     # locale
|   |   |-- en-US
|   |   |   |-- addon.ftl
|   |   |   `-- preferences.ftl
|   |   `-- zh-CN
|   |       |-- addon.ftl
|   |       `-- preferences.ftl
|   |-- manifest.json              # addon config
|   `-- prefs.js
|-- build/                         # build dir
|-- scripts                        # scripts for dev
|   |-- build.mjs                  # esbuild and replace
|   |-- reload.mjs
|   |-- start.mjs
|   |-- stop.mjs
|   `-- zotero-cmd-default.json
|-- src                           # source code
|   |-- 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
|-- tsconfig.json                 # https://code.visualstudio.com/docs/languages/jsconfig
|-- typings                       # ts typings
|   `-- global.d.ts
|-- update-template.json          # template of `update.json`
`-- update.json

Disclaimer 免责声明

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

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

18 KiB Raw Blame History Unescape Escape