为模板和JS API 现代化内联脚本标签

[david (David Taylor)]

在主题中使用 ＜script type='text/discourse-plugin'＞ 或 ＜script type='text/x-handlebars'＞ 现已弃用。主题中所有使用这些标签的地方应根据以下说明进行更新。

常规的 ＜script＞ 和 ＜script type='text/javascript'＞ 不受此更改影响。

时间表

这些是粗略估计，可能会有变动

• 2025 年 5 月 - 启用控制台弃用警告消息

• 2025 年 7 月 - 启用管理员警告横幅

• 2025 年 9 月下旬 2026 年 3 月 - 功能移除

转换 ＜script type='text/x-handlebars'＞

使用此方法引入的模板应移至专用的 .hbs 文件，或重构为 .gjs 文件。

如需保留为 HBS，连接器模板可以放置在：

{theme}/javascripts/discourse/connectors/{outlet-name}/{connector-name}.hbs

组件模板可以放置在：

{theme}/javascripts/discourse/components/{component-name}.hbs

自 2026 年 3 月起，.hbs 文件也已弃用。完成此转换后，请参阅 Deprecating .hbs file extension in themes and plugins 中的说明。

要以现代的 .gjs 格式构建连接器和组件，请查看主题开发者教程的此章节：

Theme Developer Tutorial: 4. Using Outlets to insert and replace content

Discourse uses the Ember JS Framework for its user interface. On top of Ember, Discourse provides a number of APIs to allow themes to customize the user interface. The most commonly-used API is Plugin Outlets. These outlets are positioned throughout Discourse core, and allow themes to render Ember Components inside them. Those components are given access to some contextual information called “outlet args”. Some outlets also “wrap” part of the core user interface, which allows themes to add the…

转换 ＜script type='text/discourse-plugin'＞

这些标签中的代码可以迁移到专用的 JavaScript 文件中。

如果您通过管理面板界面开发主题，请将代码从 ＜script＞ 中复制出来，并移至 JS 选项卡（显示 // your code here 的位置）。

如果您在本地开发主题，请在以下位置创建一个新文件：

{theme}/javascripts/discourse/api-initializers/init-theme.js

然后添加此包装器，并将您的代码放在指定位置：

import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  // 您的代码
});

在 script 标签中，导入其他 JS 模块的唯一方法是使用 require() 语法。虽然这在 .js 文件中仍然有效，但它很快就会被弃用，所以现在是将其转换为现代 ES6 导入的好时机。例如：

- const I18n = require("discourse-i18n").default;
+ import I18n from "discourse-i18n";

- const { h } = require("virtual-dom");
+ import { h } from "virtual-dom";

有关 JS 初始化程序的更多信息：

Theme Developer Tutorial: 6. Using the JS API

In the last couple of chapters, we’ve explored how to use the JavaScript API to render content into outlets. renderInOutlet is the most commonly-used API, but there are a ton more! In this chapter we’ll try out a few of them, and show you how to discover more. Common API methods getCurrentUser() api.getCurrentUser() will return information about the current user, or null if nobody is logged in. This can be used for all sorts of things, including per-group logic, or rendering a user’s username i…

[jimkleiber]

也许是个非常愚蠢的问题，但我有一个非常非常简单的自定义组件，我直接将其放入管理控制台的 \u003chead\u003e 下：

<script type="text/x-handlebars" data-template-name="/connectors/top-notices/whos-online-below-site-header">
{{whos-online}}
</script>

如果我正确理解了这篇文章，是否意味着我现在必须创建一个单独的自定义组件文件夹，将其托管在 GitHub 上，然后仅仅为了将内容添加到插件出口而添加该组件？

我当然希望不是这样，因为这会破坏我大部分简单的自定义组件

[NateDhaliwal]

现在有了 JS 标签，所以你现在大概可以使用 api.renderInOutlet 了。

[jimkleiber]

@NateDhaliwal

现在有了 JS 选项卡，因此您现在可以使用 api.renderInOutlet 了。

@david

如果通过管理面板界面开发主题，请将 \u003cscript\u003e 中的代码复制出来，并移至 JS 选项卡（在显示 // your code here 的地方）。

啊，我没看到连接器/组件也可以这样做，但在链接的文章中我发现了这个：

@system

最简单的组件是“仅模板组件”，可以这样编写：

const MyComponent = \u003ctemplate\u003eHello World\u003c/template\u003e;
api.renderInOutlet("some-outlet", MyComponent);

// 或者写在一行
api.renderInOutlet("some-outlet", \u003ctemplate\u003eHello World\u003c/template\u003e);

也许比我想象的要容易，谢谢！

[Sujeeva_Tissaarachchi]

感谢您的帖子！
这可能是一个非常基本的问题，我认为：
由于我们没有沙盒，在继续之前我需要确认一下。
我需要更新一个受影响的主题，那么我说所有与“head”选项卡中的“Script”相关的代码都需要移动到JS选项卡中，如下图所示，我是正确的吗？

[NateDhaliwal]

差不多，但还不够。您需要删除脚本标签，并将导入更改为类似以下内容：

import { ajax } from "discourse/lib/ajax";

然后，将所有这些粘贴到 JS 选项卡中，位于：

@david

export default apiInitializer((api) => {
  // Your code here
});

[BradCray (Brad Chamberlain)]

我们由 Discourse 托管的 Discourse 站点目前正在生成以下错误栏（这也是我找到此帖子的原因）：

我不确定我们是否对“Light”主题进行了任何自定义，并且查看其管理员页面，并没有发现任何表明这不仅仅是系统提供的默认设置的迹象（但我可能忽略了什么）。

对于像我们这样的托管站点，这种情况会随着时间自行解决，还是需要我们采取行动？

谢谢，
-Brad

[david (David Taylor)]

您需要采取行动来解决这个问题——它不会自行消失。

我在 Chrome 开发者工具中快速查看了您的网站，看起来相关的代码与将“chapel”语言添加到 highlightjs 有关。

如果您访问您的“Light”主题，然后点击“编辑代码”，您应该可以在其中一个 HTML 选项卡下找到它。然后，您可以按照此主题 OP 中的说明将其移至“JS”选项卡。

[BradCray (Brad Chamberlain)]

谢谢 @david！ 我忘了我们做了一些自定义设置来获得 Chapel 高亮显示，而且我不确定我是否能仅凭错误提示就自己解决，所以很感谢你的帮助和指导。

-Brad

[marco084]

我有一个简单的 .html 文件：

<script type='text/x-handlebars' data-template-name='/connectors/below-site-header/oprs-top-container'>
    <div id='WW_T_D_1' class='oprs-top-leaderboard'></div>
</script>

我对执行此迁移的不同方法感到有些困惑。如果有人能解释该怎么做，我将不胜感激。谢谢

[Lhc_fl (Linca)]

只需将 renderInOutlet 添加到连接器

import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  api.renderInOutlet("below-site-header", <template>
    <div id='WW_T_D_1' class='oprs-top-leaderboard'></div>
  </template>);
});

[marco084]

谢谢。我试过了，但没用

这是我的结构，以及

below-site-header.js

export function test() {
    let test2 = document.querySelector('.test');
    console.log('test ', test2);
}

以及 below-siteheader-connectors.hbs

<div class="test"></div>

我是新手，所以任何帮助都将不胜感激。我从之前的开发者那里接管了这个仓库。

[NateDhaliwal]

你好，可以分享一下你的 Github 仓库链接吗？谢谢！

[Yuun (Sam)]

所以我把我的小“放大头像”脚本放到了 JS 选项卡中（在 Desktop - head 中），这很简单，但有没有至少一种快速简单的方法让它只在 Desktop 中生效？我的移动端头像也变大了，看起来有点傻。\n\n代码参考如下：\n\njavascript\nimport { apiInitializer } from \"discourse/lib/api\";\n\nexport default apiInitializer((api) =\u003e {\n api.changeWidgetSetting('post-avatar', 'size', '70');\n});\n

[NateDhaliwal]

嗯……也许用 CSS 调整一下？

[Yuun (Sam)]

这完美地解决了问题，谢谢！

[Lhc_fl (Linca)]

友好的提醒一下：post-avatar 上的 changeWidgetSetting 是一个已弃用的 API，即将被移除。

也许你应该将你的代码更改为：

import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  const site = api.container.lookup("service:site");
  if (!site.mobileView) {
    api.modifyClass("component:post/avatar", (SuperClass) => class extends SuperClass {
      get size() { return "70"; }
    });
  }
});

[JammyDodger]

我认为还有一个#official主题组件？Avatar Size and Shape

不确定它是否符合特定用例，但似乎应该符合（还有一个额外的好处是有人会在需要更新时修复它 ）

[Yuun (Sam)]

我已经从“quick 'n dirty”升级到了官方支持，感谢大家！

[ES-Alexander]

请注意，对于使用单独的桌面/移动端处理的旧组件用户，JS 选项卡仅在“通用”部分可用 - 希望能为其他人节省一些搜索时间