Discourse 分类自定义展示（网格平铺）调研报告
日期：2026-10-03 范围：能不能让某个分类（category）下的话题用网格、瀑布流等非列表方式展示，以及 Discourse 前端定制大致分几个层次 结论来源：组件设置项来自 GitHub 仓库
discourse/discourse-topic-thumbnails的settings.yml（2026-10-03 查阅）；其余内容根据已有了解整理，没有在本地discourse/实例上安装验证
一、结论摘要
- 能做，而且不用写代码。 官方主题组件 Topic Thumbnails（
discourse-topic-thumbnails）可以按分类或按标签单独设置话题列表的展示方式。 - 可选的展示方式有五种：网格（grid）、瀑布流（masonry）、极简网格（minimal grid）、博客风格（blog style）、带缩略图的列表（list）。
- 安装不需要重建容器，在管理后台粘贴 Git 地址就能装。
- 有一个坑：组件默认把全站都切成网格，装完必须先改默认值，见第三节。
- 对本项目的建议：先装组件试用，只给少数分类开网格。不够用再考虑自己写主题组件。
二、Topic Thumbnails 组件
名称：discourse-topic-thumbnails，由 Discourse 官方维护（Civilized Discourse Construction Kit, Inc.），MIT 协议，仍在活跃开发。
仓库：GitHub - discourse/discourse-topic-thumbnails: Display thumbnails in topic lists · GitHub
缩略图从哪来：Discourse 核心会自动取话题首楼的第一张图片生成缩略图。没有图片的话题显示一个占位图标，图标可以设置（placeholder_icon，默认是 comments）。
安装步骤：
- 管理后台 → 自定义 → 主题 → 安装 → 从 Git 仓库安装
- 粘贴仓库地址
- 把组件添加到当前使用的主题上（组件不能单独生效，要挂在某个主题下）
2.1 展示方式
| 模式 | 设置项（分类 / 标签） | 适合放什么 |
|---|---|---|
| 网格 grid | grid_categories / grid_tags |
图片为主的内容，比如作品、商品、相册 |
| 瀑布流 masonry | masonry_categories / masonry_tags |
图片高矮不一的内容，比如摄影、设计稿 |
| 极简网格 minimal grid | minimal_grid_categories / minimal_grid_tags |
卡片里只放图和标题，信息更少 |
| 博客风格 blog style | blog_style_categories / blog_style_tags |
公告、长文，大图配摘要 |
| 列表 list | list_categories / list_tags |
普通列表，左边加一张缩略图 |
2.2 其他设置
| 设置项 | 默认值 | 说明 |
|---|---|---|
default_thumbnail_mode |
grid | 没有在上面任何列表里出现的分类用哪种展示方式 |
docs_thumbnail_mode |
none | 文档分类（Docs）的展示方式 |
suggested_topics_mode |
空 | 话题底部的“推荐话题”区域用哪种展示方式 |
enable_outside_topic_lists |
false | 是否在主话题列表以外的地方也显示缩略图 |
mobile_thumbnails |
true | 移动端是否显示缩略图 |
list_thumbnail_size |
200 | list 模式下缩略图的像素尺寸 |
三、注意：默认值会改动全站
default_thumbnail_mode 的默认值是 grid。也就是说，装上组件而不改设置的话，所有分类和首页都会变成网格。
正确的做法：
- 先把
default_thumbnail_mode改成 none，全站保持原来的列表 - 再把需要网格的分类加进
grid_categories（或其他模式对应的列表）
最好先在本地实例上走一遍，再装到正式站。
四、数据模型：网格里放的仍然是“话题”
组件只改变展示方式，网格里的每一张卡片仍然是一个话题。如果要展示“商品”“作品”“会员名片”之类的东西，做法是：
- 一个东西 = 一个话题，首楼第一张图就是卡片的封面
- 属性用标签表示，比如价格区间、类型，用户可以按标签筛选
- 详情写在首楼正文里，回复区就是这件东西的讨论区
这样不需要新增任何数据结构。只有当“东西”需要话题装不下的结构化字段（比如库存、状态流转）时，才需要写插件，见第五节第 3 层。
五、不够用时的定制层次
按成本从低到高排列，能停在哪一层就停在哪一层：
| 层次 | 方式 | 能做什么 | 是否需要重建 | 升级风险 |
|---|---|---|---|---|
| 0 | 现成主题组件（本报告第二节） | 按分类或标签切换展示方式 | 否 | 低，官方维护 |
| 1 | 主题里只写 CSS | 每个分类页面的 <body> 上有 category-<slug> 这个 class，可以只改某一个分类的间距、配色、卡片样式 |
否 | 低 |
| 2 | 主题组件里写 JS | 用官方 plugin API（api.renderInOutlet、value transformers、plugin outlets）往页面插 Glimmer 组件或替换某些区域。话题列表已经是 Glimmer 组件，加列、加 class 都有正式接口 |
否 | 中，只用官方 API 就比较稳 |
| 3 | Ruby 插件 | 新增后端数据、API、自定义字段 | 是，要执行 ./launcher rebuild app |
较高 |
要避开的做法：直接用 JS 改 DOM 结构，或者靠 CSS 选择器去抓 Discourse 内部的元素层级。Discourse 前端更新很快，这类改法升级后经常失效。
六、对本项目的建议
本项目是北美、仅限邀请、以人工运营为主的论坛：
- 只用第 0 层，装 Topic Thumbnails 组件，不写自定义代码。
- 装完先把
default_thumbnail_mode改成 none，主讨论区保持列表。 - 只给确实以图片为主的分类开网格或瀑布流，比如作品展示、会员活动相册。
- 卡片的内容和筛选靠“首楼图片 + 标签”，不新增数据结构。
暂不考虑：自己写主题组件或插件。等现成组件确实满足不了某个具体需求时，再从第 1 层（CSS）开始往上加。
七、待验证
- [ ] 在本地
discourse/实例上安装组件，确认default_thumbnail_mode可以选 none，并且改成 none 后全站恢复原样 - [ ] 给一个测试分类开 grid，确认首楼图片能正常生成缩略图（如果没有缩略图，检查站点设置里的缩略图生成选项）
- [ ] 检查移动端的网格效果，决定
mobile_thumbnails是否保持开启 - [ ] 确认组件
.discourse-compatibility文件支持当前 Discourse 版本