本指南将介绍如何使用 JavaScript 在外部网站上嵌入和显示 Discourse 主题列表，从而在博客、网站或外部内容平台上展示论坛内容，例如讨论或公告。
所需用户级别：管理员
摘要
在外部网站上嵌入 Discourse 主题，可以让你直接在其他网站上显示 Discourse 论坛的主题列表。这种集成有助于为你的论坛带来流量，并让你的受众与你的社区内容保持互动。嵌入的主题将显示为 JavaScript 小部件，可与你网站的 DOM 结构集成，从而更易于通过 CSS 进行自定义。
启用主题嵌入
要在外部网站上设置主题嵌入：
-
导航到你的 Discourse 管理仪表板，然后点击
site_settings。搜索并启用embed_topics_list站点设置。 -
将嵌入脚本添加到外部网站的 HTML
<head>部分：<script src="https://discourse.example.com/javascripts/embed-topics.js"></script>将
discourse.example.com替换为你实际的 Discourse 论坛 URL。 -
将主题列表元素放置在你想要显示主题的位置（例如，在博客文章或单个网站页面中）：
<d-topics-list discourse-url="https://discourse.example.com" category="1234" per-page="5"></d-topics-list> -
如果你要在与 Discourse 站点不同的域上嵌入主题，请将外部网站的域添加到 Admin > Advanced > Embedding > Hosts。
例如，如果你的 Discourse 站点位于
yourdiscourseforum.com，而你想在yourexternalsite.com上嵌入主题，则需要将yourexternalsite.com添加到你的允许主机列表中。
你无法嵌入来自私有、需要登录的 Discourse 站点的帖子。
配置参数
d-topics-list 元素支持以下属性来自定义你的主题显示：
discourse-url- 你的 Discourse 站点的 URL（必需）template- 显示样式选项：basic（默认）- 显示最少的主题信息complete- 显示标题、用户名、头像、创建日期和缩略图
per-page- 要显示的主题数量category- 要从特定类别过滤主题的类别 IDtags- 按特定标签过滤主题allow-create- 设置为true时，显示“新主题”按钮top_period- 显示特定时间段内的热门主题：allyearlyquarterlymonthlyweeklydaily
你可以组合多个参数来优化你的主题列表显示。例如：
<d-topics-list
discourse-url="https://discourse.example.com"
category="5"
tags="announcements"
per-page="10"
template="complete">
</d-topics-list>
自定义外观
你可以使用 Admin > Customize > Themes 面板中的自定义 SCSS 来设置嵌入式主题的样式。点击你当前或默认的主题，然后点击 Edit Code。然后，你可以选择 Show_advanced 并选择 Embedded CSS 来添加你的自定义代码：
以下是用于创建网格布局的 SCSS 示例：
.topics-list {
display: grid;
grid-template-columns: repeat(2, 1fr);
.topic-list-item {
.main-link {
border: 1px dotted gray;
padding: 0;
}
.topic-column-wrapper {
flex-direction: column-reverse;
.topic-column.details-column {
width: 100%;
}
.topic-column.featured-image-column .topic-featured-image img {
max-width: initial;
max-height: initial;
width: 100%;
}
}
}
}
最佳实践
- 使用有意义的类别和标签过滤器来显示与你的受众相关的内容
- 设置适当的
per-page值，避免让访问者不知所措 - 在不同的屏幕尺寸上测试你嵌入的主题，以确保响应式设计
- 当空间允许时，考虑使用
complete模板以获得更好的视觉效果 - 定期查看你的允许主机列表，以确保只有授权的域可以嵌入你的主题
常见问题及解决方案
主题未在外部域上显示
问题：嵌入式主题在外部域上查看时显示为空白或灰色框。
解决方案：将外部域添加到 Discourse 站点的 Admin > Customize > Embedding > Allowed Hosts。确保包含正确的子域（例如，如果你的站点使用 www.example.com，请添加 www.example.com 而不是仅 example.com）。
脚本加载错误
问题：嵌入脚本未能加载或返回连接错误。
解决方案：
- 验证脚本源中的 Discourse URL 是否正确且可访问
- 检查
embed_topics_list站点设置是否已启用 - 确保你的 Discourse 站点不要求登录才能访问公开主题
SameSite 上下文行为
在嵌入站点和论坛共享父域的 SameSite 上下文中，Discourse 会尊重登录状态并相应地显示结果。已登录用户可能会看到来自安全类别的、匿名用户无法访问的内容。
常见问题解答
问：我可以在私有 Discourse 站点上嵌入主题吗？
答：不可以，主题嵌入仅适用于公开的 Discourse 站点。无法嵌入私有、需要登录的站点。
问：我可以在同一页面上嵌入多个主题列表吗？
答：是的，你可以在同一页面上包含多个 <d-topics-list> 元素，并使用不同的参数来显示不同的主题集合。
问：如何嵌入带有特色图片的主题？
答：在 <d-topics-list> 元素中使用 template="complete" 参数来显示带有缩略图和特色图片的主题。
问：我可以更改主题链接的打开方式吗？
答：默认情况下，主题链接会在父窗口中打开。你可以通过 CSS 或 JavaScript 自定义来修改此行为。
