本指南介绍如何使用 JavaScript 在外部网站上嵌入并显示 Discourse 主题列表，从而在博客、网站或外部内容平台上展示论坛内容（如讨论或公告）。
所需用户等级：管理员
摘要
在外部网站上嵌入 Discourse 主题，使您能够直接将 Discourse 论坛的主题列表显示在其他站点上。这种集成有助于为论坛引流，并保持受众与社区内容的互动。嵌入的主题以 JavaScript 小部件的形式呈现，可与您站点的 DOM 结构集成，从而更便于通过 CSS 进行自定义。
启用主题嵌入
要在外部站点上设置主题嵌入，请执行以下步骤：
- 导航至 管理 > 高级 > 嵌入，切换到 设置 选项卡。启用
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 站点不同的域上嵌入主题，请将您的外部站点域名添加到 管理 > 高级 > 嵌入 > 主机。
例如，如果您的 Discourse 站点位于 yourdiscourseforum.com，而您希望在 yourexternalsite.com 上嵌入主题，则需要将 yourexternalsite.com 添加到您的允许主机列表中。
您无法嵌入来自需要登录的私有 Discourse 站点的主题。
配置参数
d-topics-list 元素支持以下属性以自定义主题显示：
discourse-url- 您的 Discourse 站点 URL（必需）template- 显示样式选项：basic（默认）- 仅显示作为链接的主题标题complete- 显示标题、用户名、头像、创建时间、最后回复时间、点赞数、回复数以及特色图片/缩略图
per-page- 显示的主题数量（受隐藏的embed_topic_limit_per_page站点设置限制，默认为 200）category- 类别 ID，用于从特定类别筛选主题tags- 按特定标签筛选主题allow-create- 设置为true时，显示“新建主题”按钮embed-class- 为嵌入的主题列表容器添加自定义 CSS 类（仅限字母数字、连字符和下划线）top-period- 显示特定时间段内的热门主题：allyearlyquarterlymonthlyweeklydaily
您可以组合多个参数以优化主题列表的显示。例如：
<d-topics-list
discourse-url="https://discourse.example.com"
category="5"
tags="announcements"
per-page="10"
template="complete">
</d-topics-list>
自定义外观
您可以在 管理 > 外观 > 主题和组件 面板中使用自定义 SCSS 来设置嵌入主题的样式。点击当前或默认主题，然后点击 编辑代码。接着选择 Show_advanced 并选择 嵌入式 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 站点的 管理 > 高级 > 嵌入 > 主机。请确保包含正确的子域名（例如，如果您的站点使用 www.example.com，请添加 www.example.com 而不是仅添加 example.com）。
脚本加载错误
问题：嵌入脚本加载失败或返回连接错误。
解决方案：
- 验证脚本源中的 Discourse URL 是否正确且可访问
- 检查
embed_topics_list站点设置是否已启用 - 确保您的 Discourse 站点对公开主题不要求登录
SameSite 上下文行为
在嵌入站点和论坛共享父域名的 SameSite 上下文中，Discourse 会尊重登录状态并相应地显示结果。已登录用户可能看到匿名用户无法访问的安全类别中的内容。
常见问题解答（FAQs）
问：我可以嵌入来自私有 Discourse 站点的主题吗？
答：不可以。主题嵌入仅适用于公共 Discourse 站点。需要登录的私有站点无法被嵌入。
问：我可以在同一页面上嵌入多个主题列表吗？
答：可以。您可以在同一页面上包含多个 <d-topics-list> 元素，并使用不同的参数来显示各种主题集合。
问：如何嵌入带有特色图片的主题？
答：在您的 <d-topics-list> 元素中使用 template="complete" 参数，即可显示带有缩略图和特色图片的主题。
问：我可以更改主题链接的打开位置吗？
答：默认情况下，主题链接会在父窗口中打开。您可以通过 CSS 或 JavaScript 自定义来修改此行为。
