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

第55章 NodeBB Widgets 开发指南:嵌入、注册与自定义

第55章:为 NodeBB 编写 Widgets 嵌入 HTML 和 JavaScript 你无需具备开发者背景也能搞定。进入主题控制面板,点击 Widgets 标签页。通过拖拽,在任意模板上创建一个 HTML widget。将 HTML 或 JavaScript 代码复制粘贴到 widget 中并点击保存——完成! 可选地,你可以从“containers”区域拖拽出一个容器,赋予你的 widget 一个容器。 如果你想要参考一些示例脚本,请前往我们的插件部分,查找任何标记为 nodebb-script-xyz 的主题。也别忘了提交你的脚本和创意! 创建 Widgets 你可以在插件和主题中定义 widgets。如果你正在开发一个专门提供 widget(或 widget 集合)的插件,我们强烈建议你在发布时采用 nodebb-widget-xyz 的命名规范。 注册你的 widget 监听此钩子以注册你的 widget: "hook": "filter:widgets.getWidgets", "method": "defineWidgets" 在数组中返回以下对象: { widget: "widget_namespace", name: "My Widget", description: "Short description of what it does.", content: "" } Content 定义了显示在管理面板中用于自定义 widget 的表单。 监听你的 widget NodeBB 核心会通过钩子系统,在适当的页面加载时调用你的 widget。钩子的名称将基于你 widget 的命名空间(见上文示例)——例如: filter:widget.render:widget_namespace 这会传入一个包含以下有用属性的 widget 对象: widget.area - 由钩子 filter:widgets.getAreas 定义(见下文相关章节)——将包含 location, template, url widget.data - 将包含你在管理端定义的数据;以上文示例为例,你将暴露 obj.data.myKey widget.req - req 对象,表示当前 HTTP 请求。 你通过向 widget.html 赋值 HTML 来渲染 widget。例如: Plugin.renderWidget = function (widget, callback) { widget.html = ''; callback(null, widget); }; 或者,你可以通过 widget.req.app.render 渲染模板文件(也请参阅模板系统)。例如: Plugin.renderWidget = async function (widget) { widget.html = await widget.req.app.renderAsync('widgets/my-widget'); return widget }; 由于 widget.html 作为原始 HTML 插入,请记得转义你插值进去的任何动态值。 在主题中定义 Widget Areas Widget Area 由模板和位置特征化。如果主题定义了相同的 Widget Areas,它们可以共享 widgets。如果管理员切换主题,之前定义在与新主题不兼容的 Widget Area 中的 widgets 将被保存。 监听此钩子以注册你的 Widget Area: "hook": "filter:widgets.getAreas", "method": "defineWidgetAreas" 在数组中返回以下对象: { widget: "categorysidebar", name: "Category Sidebar", template: "category.tpl", location: "sidebar" } 就是这样了。你可以在你的主题中定义任意数量的 Widget Areas。如果你仍然卡住,请查看这个 commit,它升级了 Cerulean 主题以使用 widget 系统。

评论 (0)