进阶 docs.nodebb.org 2026-10-13 15:07:09 · 34 阅读

第46章 NodeBB 核心库使用指南

核心库使用指南

如《编写插件》中所述,插件通过 `require.main.require('./src/...')` 访问 NodeBB 的内部核心。本页梳理了插件中最常用的库,并附有几个将它们组合使用的常见代码示例。

提示 `require.main.require('./src/...')` 在所有当前版本中均可用,但从 NodeBB v4.12.0 开始将逐步弃用。面向未来的标准写法是 `nodebb.require('./src/user')`。下文示例为保持兼容性仍使用 `require.main.require`;如果你的目标环境是 v4.12.0 或更高版本,请替换为 `nodebb.require`。

提示 这是一份精选入门指南,而非详尽的 API 参考。NodeBB 模块暴露的方法远多于此处所列,且不同大版本间的函数签名可能会发生变化。若需使用此处未涵盖的方法,请查阅 NodeBB 源码中 `src/` 目录下对应的文件,那是最权威的参考。此外,这些方法大多为异步操作,并返回 Promise。

常用模块 `const db = require.main.require('./src/database');` `const user = require.main.require('./src/user');` `const groups = require.main.require('./src/groups');` `const topics = require.main.require('./src/topics');` `const privileges = require.main.require('./src/privileges');` `const notifications = require.main.require('./src/notifications');` `const meta = require.main.require('./src/meta');` `const translator = require.main.require('./src/translator');` `const pagination = require.main.require('./src/pagination');` `const helpers = require.main.require('./src/controllers/helpers');` `const routeHelpers = require.main.require('./src/routes/helpers');`

database `database` 模块是对底层存储后端(Redis、MongoDB 或 Postgres)的抽象层,提供统一 API,使插件可在任意后端上运行。它主要处理对象(哈希)和有序集合等数据结构。

请注意区分《数据库结构》页面,该页记录的是 NodeBB 核心本身存储的键值。以下列出的方法是供你读写自定义键值时调用的 API: `getObject(key) / getObjects([keys]) // 读取哈希对象` `getObjectFields(key, [fields]) // 读取哈希对象的指定字段` `setObject(key, obj) // 写入哈希对象` `deleteObjectFields(key, [fields]) // 删除哈希对象的指定字段` `delete(key) / deleteAll([keys]) // 删除键` `incrObjectField(key, field) // 原子自增(例如 ID 计数器)` `sortedSetAdd(key, score, member) // 添加至有序集合` `sortedSetRemove(key, member) // 从有序集合中移除` `sortedSetCard(key) // 统计成员数量` `getSortedSetRange(key, start, stop) // 按分数升序获取成员` `getSortedSetRevRange(key, start, stop) // 按分数降序获取成员` `getSortedSetRevRangeWithScores(key, start, stop) // 获取 [{ value, score }]`

常见的模式是为每个实体创建一个哈希对象,再配一个有序集合作为排序索引: `const id = await db.incrObjectField('global', 'nextThingId');` `await db.setObject(`thing:${id}`, { id, uid, content, timestamp: Date.now() });` `await db.sortedSetAdd(`thing:byTopic:${tid}`, Date.now(), id);`

user `getUserFields(uid, [fields]) // 获取单个用户` `getUsersFields([uids], [fields]) // 获取多个用户` `getSettings(uid) // 用户个人设置(如 topicsPerPage)` `exists(uid) // 布尔值,判断是否存在` `isAdministrator(uid) // 布尔值,判断是否为管理员` `isGlobalModerator(uid) // 布尔值,判断是否为全局版主` `isModeratorOfAnyCategory(uid) // 布尔值,判断是否为任何版块的版主`

常需获取的字段:`['uid', 'username', 'userslug', 'picture']`。

groups `search(query, { sort, filterHidden }) // 按名称搜索群组` `getMembers(name, start, stop) // 获取成员 uids` `getUserGroups([uids]) // 获取用户所属群组` `getGroupFields(name, [fields]) // 获取群组元数据` `exists(name) // 布尔值,判断是否存在` `isPrivilegeGroup(name) // 布尔值,若是权限群组则在 UI 列表中过滤`

topics `getTopicFields(tid, [fields]) // 获取单个主题的指定字段` `getTopicsByTids([tids], uid) // 获取完整、可直接渲染的主题对象` `getFollowers(tid) // 关注该主题的用户 uids` `follow(tid, uid) // 让用户关注某主题`

privileges 在返回或渲染内容前,务必根据查看者的权限过滤内容: `const visibleTids = await privileges.topics.filterTids('read', tids, uid);`

示例:发送通知 `const notifications = require.main.require('./src/notifications');`

`const notifObj = await notifications.create({` ` type: 'myplugin-event', // 事件标识符` ` bodyShort: '[[myplugin:notif-text, ' + title + ']]', // 翻译键(见 i18n)` ` nid: 'myplugin:thing:' + tid + ':' + id, // 必须唯一,作为去重键` ` from: fromUid, // 触发者` ` path: '/topic/' + slug, // 通知链接跳转地址` `});`

`// 若 notifObj 为 null(如无可发送内容),push() 会直接返回,因此无需手动检查` `await notifications.push(notifObj, recipientUids);`

`bodyShort` 是多语言字符串,支持位置参数。请在你的语言文件中定义对应的键,例如 `"notif-text": "New activity in %1"`。

示例:自定义列表页 页面路由可渲染自定义模板,或通过提供模板所需数据来复用核心模板。对于主题列表,`recent` 模板比较方便。以下是组装该数据的辅助函数: `const user = require.main.require('./src/user');` `const topics = require.main.require('./src/topics');` `const privileges = require.main.require('./src/privileges');` `const pagination = require.main.require('./src/pagination');` `const helpers = require.main.require('./src/controllers/helpers');`

`async function renderMyList(req, res) {` ` const uid = req.uid;` ` const page = Math.max(1, parseInt(req.query.page, 10) || 1);`

` const settings = await user.getSettings(uid); // settings.topicsPerPage` ` let tids = await getMyTids(uid); // 你的数据源` ` tids = await privileges.topics.filterTids('read', tids, uid); // 遵循读权限`

` const start = (page - 1) * settings.topicsPerPage;` ` const stop = start + settings.topicsPerPage - 1;` ` const topicsData = await topics.getTopicsByTids(tids.slice(start, stop + 1), uid);`

` const pageCount = Math.max(1, Math.ceil(tids.length / settings.topicsPerPage));` ` res.render('recent', {` ` topics: topicsData,` ` title: '[[myplugin:list.title]]',` ` breadcrumbs: helpers.buildBreadcrumbs([{ text: '[[myplugin:list.title]]' }]),` ` pagination: pagination.create(page, pageCount),` ` });` `}`

评论 (0)