进阶 docs.nodebb.org 2026-10-13 15:07:09 · 32 阅读
第47章 NodeBB 插件设置
插件设置
适用版本:>=4.0.0
大多数插件都需要一些可由管理员配置的选项。NodeBB 内置了一套设置系统,用于持久化存储插件的选项,并提供一个客户端设置模块,将 ACP 表单与该存储绑定。因此,你通常无需自行编写保存或加载逻辑。本页将完整走通一个往返流程:ACP 中的表单、负责读写该表单的客户端模块,以及服务端读取已保存值的方法。
1. ACP 页面与表单
首先,注册一个 ACP 页面路由并创建其模板。每个表单控件的 name 属性会成为保存的设置对象中的一个键。
templates/admin/plugins/myplugin.tpl
2. 客户端设置模块
ACP 模块通过 plugin.json 的 modules 属性进行配置,将虚拟管理路径映射到你的脚本文件:
{
"acpScripts": ["public/lib/acp.js"],
"modules": {
"../admin/plugins/myplugin.js": "./public/lib/admin.js"
}
}
ACP 模块采用 ES 模块(import/export)规范编写。从内置设置模块导入 save 和 load,以便将表单与数据存储绑定:
public/lib/admin.js
'use strict';
import { save, load } from 'settings';
export function init() {
// 使用 "myplugin" 插件 ID 对应的已存设置填充表单
load('myplugin', $('.myplugin-settings'));
$('#save').on('click', () => {
// 将表单值持久化存储至相同的 ID 下
save('myplugin', $('.myplugin-settings'));
});
}
load(id, formEl) 读取已存对象并填充匹配的表单字段;save(id, formEl[, callback]) 将表单序列化回存储库。id 是你插件的设置命名空间——请确保在客户端和服务器端保持一致。
3. 在服务器端读取设置
在库的任何位置通过 meta.settings 读取已存值:
const meta = require.main.require('./src/meta');
const settings = await meta.settings.get('myplugin');
你也可以通过 meta.settings.set('myplugin', obj) 以编程方式写入。
复选框值存储为字符串 'on' / 'off'
这是最常见的混淆点。通过设置模块保存的复选框值,在勾选时存储为字符串 'on',未勾选时为 'off'(或不存在)——它不是布尔值。请显式比较:
if (settings.allowGuests === 'on') {
// 已启用
}
使用真值检查(if (settings.allowGuests))是错误的,因为字符串 'off' 本身也是真值。
文本和文本区域字段返回原始字符串值,因此需按需解析:
const lines = (settings.greeting || '').split(/\r?\n/).map(s => s.trim()).filter(Boolean);