开发话语主题及其组成部分

Discourse · 2018 年8 月 1 日 12:00

Discourse Themes and Theme Components can be used to customize the look, feel and functionality of Discourse’s frontend. This section of the developer guides aims to provide all the reference materials you need to develop simple themes for a single site, right up to complex open-source theme components.

This introduction aims to provide a map of all the tools and APIs for theme development. If you prefer a step-by-step tutorial for theme development, jump straight to:

Themes vs. Theme Components

Discourse Themes can be used to customize the frontend user experience using CSS and JavaScript. Each theme has its own git repository, and community admins can generally install and manage them via the Discourse admin panel, even on shared hosting platforms.

Theme Components are themes which are intended for use alongside other Theme Components, as part of an overall Theme. From a development point of view, Theme Components and Themes are almost identical. In these guides, the phrase “Theme” and “Theme Component” are used interchangeably.

Prerequisites

Firstly, make sure you understand how to use existing themes and theme components in Discourse. Using ready-made themes is the quickest and safest way to customize your community. If you need more, then it’s time to consider writing your own theme.

As part of Discourse’s overall architecture, Discourse Themes are built using standard HTML, CSS, JavaScript technologies, and make use of Ember concepts for more advanced UIs. These reference guides assume a base-level understanding of these technologies, and link out to external references where possible.

Discourse is a fast-moving project, and as such any custom theme will require maintenance over time. Make sure you consider this as part of your planning & development processes.

Getting Started

Frontend Customization

More!

Check out the rest of the Developer Guides !

This document is version controlled - suggest changes on github.

rsigg · 2024 年6 月 21 日 21:02

The PluginApi - modifyClass() section 部分有很多旧的或已失效的链接和引用……

这个文件已经改变了很多，checkReplyLength 甚至已经不存在了……

在同一部分的后面：

这个链接只会导致“404 - 页面未找到”错误……

之后我就放弃使用这些文档了……

JammyDodger · 2024 年7 月 26 日 18:13

帖子已拆分为新主题：用户卡片模板或小部件？

Overgrow · 2024 年8 月 12 日 10:48

这部分的文档似乎有点过时了……（而且 api.modifyClass 抱怨缺少 pluginId）。我该如何在 about-page 加载时运行脚本？这个似乎不起作用（但也没有错误）。我在其他一些组件上尝试过，结果好坏参半。谢谢。

<script type="text/discourse-plugin" version="0.11.1">

api.modifyClass("component:about-page", {
  pluginId: 'discourse-about-theme',

  didInsertElement() {
    this._super(...arguments);
    console.log("Welcome to the about page!");
  }

});

</script>

Don · 2024 年8 月 12 日 11:17

您好 about-page 现在是 .gjs 格式，这也意味着它无法再以这种方式修改。如果您想进行更改，必须使用该页面上提供的连接器之一。

您可以使用 Plugin outlet locations theme component 轻松检查这些，或者在 \u003cPluginOutlet\u003e 文件中进行检查。

Overgrow · 2024 年8 月 12 日 14:22

非常感谢。有道理。我改用了连接器，现在工作正常。

ddsgad · 2025 年2 月 5 日 11:03

这份指南还准确吗？我通读了整份指南来尝试创建一个主题组件，然后查看了示例主题组件，发现它们都没有使用指南中的说明。例如，在查看 discourse-brand-header 主题组件时，它似乎已经从在 header.html 中使用 api.createwidget 重构为使用完全不同的代码，其中包含 initializers、Components 等。代码极其复杂。指南中提到了使用带有 widget 的 API 方法，但任何组件都根本不使用这些。是否有更新的指南或可以使用 Components 的东西？

编辑：据称 widget API 正在消失，但是否有关于改用什么的指南？这里的整个指南似乎都基于已弃用的代码？

NateDhaliwal · 2025 年2 月 5 日 11:08

确实如此。指南应该更新了。不过，有些部分仍然非常相关，比如文件的结构等等。

ddsgad · 2025 年2 月 5 日 11:12

是的，SCSS 似乎是相关的，但除此之外，似乎所有示例主题组件都使用组件，并且已经重构为与此处教授的完全不同的代码库。我浏览了他们在插件 API 部分链接的所有组件，每一个都以一种与此处指南中所教的完全不同的方式进行了重构。小部件已不再使用。全部都是组件。是否有关于如何正确使用新的组件（因为小部件正在消失）的指南？

ddsgad · 2025 年2 月 5 日 11:17

我刚刚看到了这个帖子，例如：Upcoming Header Changes - Preparing Themes and Plugins - 所以他们将所有内容从旧版小部件重构为 Glimmer 组件了吗？但是，本教程全是旧版小部件。Glimmer 组件到底是什么？有相关指南吗？在开始使用旧版小部件进行开发之前，我很高兴能及早发现这一点。也许在此指南中添加一个注释，说明小部件是旧版的，不应再使用？

ddsgad · 2025 年2 月 5 日 11:35

好的，我看到 Glimmer 是新的 Ember 组件。但是，我看了一下 Discourse TOC 的代码，我的天……以前只需要大约 10 行代码的地方，现在却分散在许多文件中，有数百行代码，包含复杂的类、装饰器等。我猜 Ember 经历了一次 React 时刻，决定再次让事情变得非常复杂。看来主题组件不再像以前那样简单，拥有简单的 widget API，而是需要大量的编码……

david · 2025 年2 月 5 日 12:29

@ddsgad 是的，你说得对，本指南大部分内容已严重过时。我最近一直在进行通用文档改进，希望在未来几周内更新/替换此指南。

正如你所提到的，像 DiscoTOC 这样的真实示例可以作为很好的参考。另外，这里有一些更新的特定指南：

关于 Ember 及其组件的通用信息，我建议查看 Ember 指南。

ddsgad · 2025 年2 月 5 日 14:45

感谢您提供的链接。非常有帮助。目前，我们基本上只在 discourse 主题（第一篇帖子）中自定义内容以实现更好的设计，因此我们基本上能够使用纯粹的 JavaScript（querySelectorAll 等）和 SCSS 来完成所有工作，所以我想我们目前将继续这样做。

david · 2025 年3 月 18 日 16:11

OP 中冗长且过时的教程现已替换为更通用的介绍/指引信息，包括一个指向全新7步教程的链接，该教程遵循更现代的主题开发模式。

Arkshine · 2025 年3 月 18 日 16:32

我已经全部读完了，我很喜欢！解释得很清楚，是非常好的介绍！

NateDhaliwal · 2025 年3 月 18 日 23:33

我喜欢这些指南！终于弄懂了 api.decorateCookedElement，再次感谢这些有用的文档！

话题		回复	浏览量
Beginner's guide to using Discourse Themes Site Management reference , customization	11	81557	2025 年3 月 26 日
Theme Developer Tutorial: 1. Introduction Developer Guides	0	876	2025 年3 月 18 日
Introduction to Discourse Development Developer Guides	1	1613	2025 年2 月 1 日
Develop a theme Dev	2	1241	2023 年5 月 8 日
How do I go about making a very customized theme? Dev	3	1552	2023 年11 月 8 日