跳至主要內容

Zotero 首选项

windingwindShareStuffnorthword大约 3 分钟

Zotero 首选项

Preference 是 Zotero 插件的一种持久化设置能力。与其他代码运行环境相同,变量在 Zotero 重启后会被重置,因此对于用户的设置等需要持久存储的变量,通过 Preference 来存取。

Preference 存储于 Zotero 配置文件目录open in new window 下的 prefs.js。除特殊情况,请勿引导用户修改该文件。

💡 注意:Preference 的值有长度限制,请勿设置太长的字符串。

默认设置

在插件根目录新建 prefs.js,并填入如下示例的内容,可以初始化的 Preference 的键和值。键为字符串,值为布尔、数字或字符串其一。

pref("extensions.zotero.Knowledge4Zotero.syncNoteIds", "");
pref("extensions.zotero.Knowledge4Zotero.syncPeriod", 10000);
pref("extensions.zotero.Knowledge4Zotero.autoAnnotation", false);

注意

请注意,该文件中每一行的 pref 请勿换行。换行可能导致失效,并不会有明显的错误提示,可能导致新用户的默认配置为空。

首选项窗格

注册首选项窗格

Zotero 现在包含一个用于注册首选项窗格的内置接口。在插件的 startup 中:

Zotero.PreferencePanes.register({
  pluginID: "[email protected]",
  src: "prefs.xhtml",
  scripts: ["prefs.js"],
  stylesheets: ["prefs.css"],
});

更多设置项请参考源码:preferencePanes.jsopen in new window

窗格的 src 应指向包含 XUL/XHTML 片段的文件。片段不能有 <!DOCTYPE 。默认命名空间是 XUL,HTML 标签可在 html: 下访问。一个简单的窗格可能如下所示:

<vbox onload="MakeItRed_Preferences.init()">
	<groupbox>
		<label><html:h2>Colors</html:h2></label>
		<!-- [...] -->
	</groupbox>
</vbox>

要使用 Fluent 进行本地化,请在 XUL <linkset> 中包含一个或多个 HTML <link> 元素:

<linkset>
	<html:link rel="localization" href="make-it-red.ftl"/>
</linkset>

首选项窗格文本的本地化详情请参考:本地化

设置命名空间以避免冲突

请注意,首选项窗格中的所有 classiddata-l10n-id 都应命名空间以避免插件之间发生冲突。

绑定首选项

通过将标签的 preference 属性设置为首选项的键,即可绑定首选项,例如:

<html:input type="text" preference="extensions.zotero.makeItRed.color"/>

增删改查设置项

源码位置:chrome\content\Zotero\xpcom\prefs.jsopen in new window

declare namespace Zotero {
  interface Prefs {
    /**
     * Retrieve a preference
     */
    get(pref: string, global?: boolean): boolean | string | number | undefined;

    /**
     * Set a preference
     */
    set(pref: string, value: boolean | string | number, global?: boolean): any;

    clear(pref: string, global?: boolean): void;
  }
}

Zotero.Prefs.get

读取名称为 pref 的 Preference。

pref 为 Preference 的键,global 为是否是全局命名域,默认否。

注意,对于 extensions.zotero.addonRef.key,在页面绑定以及设置编辑器中,Preference 的键名为 extensions.zotero.addonRef.key,而在 API 中调用时只需要 addonRef.key,否则则需要启用全局命名域。

例:首选项键 extensions.zotero.formatmetadata.abbr 的值为 true

Zotero.Prefs.get("pdfpreview.enable"); // true
Zotero.Prefs.get("extensions.zotero.formatmetadata.abbr"); // undefined
Zotero.Prefs.get("extensions.zotero.formatmetadata.abbr", true); // true
Zotero.Prefs.get("formatmetadata.abbr", true); // undefined

Zotero.Prefs.set

设置名称为 pref 的 Preference 为 value

pref 为 Preference 的键,value 为 Preference 的值,global 为是否是全局命名域,默认否。

例:首选项键 extensions.zotero.pdfpreview.enable 的当前值为 true,需要将其修改为 false

Zotero.Prefs.set("pdfpreview.enable", false);
Zotero.Prefs.get("pdfpreview.enable"); // false

Zotero.Prefs.clear

Todo

辅助函数

在插件模板中,提供了一个简便的工具函数,来见避免我们每次都要输入 Zotero.Prefs.:

// src/utils/prefs.ts
import { config } from "../../package.json";

/**
 * Get preference value.
 * Wrapper of `Zotero.Prefs.get`.
 * @param key
 */
export function getPref(key: string) {
  return Zotero.Prefs.get(`${config.prefsPrefix}.${key}`, true);
}

/**
 * Set preference value.
 * Wrapper of `Zotero.Prefs.set`.
 * @param key
 * @param value
 */
export function setPref(key: string, value: string | number | boolean) {
  return Zotero.Prefs.set(`${config.prefsPrefix}.${key}`, value, true);
}

/**
 * Clear preference value.
 * Wrapper of `Zotero.Prefs.clear`.
 * @param key
 */
export function clearPref(key: string) {
  return Zotero.Prefs.clear(`${config.prefsPrefix}.${key}`, true);
}

有了工具函数,我们就可以通过 getPref("enable") 来简写 Zotero.Prefs.get("pdfpreview.enable");

参考资料