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

第53章 创建新的 NodeBB 主题

创建一个新的 NodeBB 主题

NodeBB 基于 Twitter Bootstrap 构建,因此主题定制非常简单。

快速开始

开始定制 NodeBB 主题最简单的方法,是 fork Quickstart Theme,然后在此基础上做你的自定义修改。

Quickstart 主题是 NodeBB 默认主题(Harmony)的子主题(见下文),因此会继承父主题的全部样式和模板。

如果你想覆盖某个已有模板,只需从 Harmony 仓库把它复制到你主题的 /templates 目录下,并保持相同的目录结构。这个目录可能需要你手动创建。

然后重新构建 NodeBB 的静态资源,你的模板就会覆盖 Harmony 中同路径的模板。

例如,如果你想修改 topic.tpl,操作如下:

  1. 复制 nodebb-theme-harmony/templates/topic.tpl 的内容
  2. 创建 nodebb-theme-mytheme/templates 目录
  3. 新建文件 nodebb-theme-mytheme/templates/topic.tpl,把原 topic.tpl 的内容粘贴进去
  4. 按需修改
  5. 执行 ./nodebb build tpl && ./nodebb dev 重新构建并启动 NodeBB

为 NodeBB 打包主题

NodeBB 要求所有已安装的主题都通过 npm 安装。每个主题都是一个独立的 npm 包,用户可以通过命令行安装,例如:

npm install nodebb-theme-modern-ui

一个有效的主题文件夹至少要包含两个文件:

  • theme.json
  • theme.scss

theme.scss 是存放主题样式的地方。NodeBB 要求这个文件使用 SCSS 编写,并会按需将其预编译为 CSS。关于 SCSS 的更多信息,请查看其项目主页。

注意
建议不要把所有样式都写在主 theme.scss 文件里,而是通过 @import 引入多个较小的文件。

配置

主题配置文件是一个简单的 JSON 字符串,包含主题的所有相关元数据。请注意以下属性:

  • id:主题的唯一标识(如 "my-theme")
  • name:用户可见的主题名称(如 "My Theme")
  • description:一两句话的主题描述(如 "这是我为个人 NodeBB 制作的 主题")
  • screenshot:预览图的文件名(与 theme.json 同目录),建议尺寸 370x250,即宽高比约 1.48:1
  • url:指向主题主页/项目页的完整 URL
  • templates:(可选)模板文件所在文件夹的路径(相对于插件根目录)。如果未指定,NodeBB 会先查找 "templates" 目录,找不到则回退到 vanilla 的模板文件。
  • baseTheme:(可选)如果未定义,缺失的模板文件将默认使用 nodebb-theme-persona(当前的基础主题)。详见「子主题」部分。

子主题

CSS / LESS

如果你的主题基于另一个主题,只需修改 LESS 文件,将其指向基础主题即可,例如 topics.less:

由于 nodebb-theme-vanilla 的 topic.less 已被引入,其样式会自动并入你的主题。

模板

你不需要在主题中重新定义所有模板。如果当前主题缺少某个模板文件,NodeBB 会从 theme.json 中定义的 baseTheme 继承(未定义则继承 nodebb-theme-persona 的模板)。

如果你的主题依赖于 nodebb-theme-vanilla 以外的主题,应在 theme.json 中把 baseTheme 配置为对应的主题。

更多信息请参阅关于模板系统的详细文章。

评论 (0)