嵌入页面 — Jamdesk Documentation

在自己的产品中放置一个“What's new?”触发器。按钮或悬浮启动器会在模态框中打开文档更新日志条目。提示点会标记每位访客尚未读过的更新。粘贴一个 <script> 标签即可。Jamdesk 会托管并为此小组件提供版本管理。

屏幕截图显示的是英文界面。

未读提示点围绕更新日志设计。不过，小组件也可以在模态框中打开任意文档页面。请参阅将模态框指向任意页面。

The What's new modal open over a dimmed app, showing the Jamdesk changelog page with a Copy page button and dated update entries, and a close button in the top corner

立即在线试用

此页面运行的是真实小组件。点击按钮即可打开访客看到的模态框，其中加载了本网站的更新日志：

这个按钮就是 <Widget> MDX 组件。使用它可以在 Jamdesk 文档页面中嵌入小组件。只需一个标签，无需脚本，它会自动找到你的网站。若要在自己的产品或应用中嵌入小组件（MDX 组件无法在其中运行），请使用下方的 <script> 代码片段。小组件和模态框都相同。本页其余部分介绍此脚本。

前置条件

已发布的 Jamdesk 网站，位于 *.jamdesk.app 子域名下。小组件始终从该域名加载，即使你也通过自定义域名提供文档。
更新日志页面，由 <Update> 条目构建，并在其 frontmatter 中设置 rss: true（请参阅通过 rss: true 启用）。

快速开始

打开仪表板，然后前往 Integrations → What's New widget。设置页面和启动器选项，然后复制生成的代码片段。它看起来如下：

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-theme="auto"
  async
></script>

将其粘贴到应用的 HTML 中，放在结束的 </body> 标签之前。它会在角落添加一个悬浮的 What's new 启动器。启动器会在模态框中打开更新日志。当有访客尚未看过的条目时，会显示未读提示点。

将 acme 替换为你自己的子域名。仪表板卡片会自动填入该值。它会将 data-base 指向正确的源站；如果你在子路径下托管文档，也会包含 /docs 路径。

固定版本或自行托管

此小组件是开源的。上方的托管代码片段始终提供最新版本。jamdesk-widget 仓库还提供另外两种加载方式，可固定已知版本或自行提供文件。

**通过 jsDelivr 固定版本。**从 CDN 加载带标签的发布版本，文件内容不会发生变化：

<script
  src="https://cdn.jsdelivr.net/gh/jamdesk/jamdesk-widget@v1.0.0/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  async
></script>

**自行托管。**从最新发布版本下载 widget.js，并从自己的源站提供文件。当严格的 script-src 策略不允许第三方脚本时，可使用此方式。

对于固定版本或自行托管的文件，请将 data-base 设置为你的 *.jamdesk.app 源站。托管代码片段会从脚本自身的 URL 读取该值；CDN 或你自己的服务器则不会。每个发布版本都会提供 Subresource Integrity 哈希，以便固定确切的文件内容。仓库 README介绍了三种安装方式。

使用 `rss: true` 启用

小组件会读取 RSS feed 中最新的条目。只有当页面的 frontmatter 设置了 rss: true 时，页面才会向小组件提供内容：

---
title: Changelog
rss: true
---

<Update label="June 2026" date="2026-06-01">

**Spec validation at build time.** Every deploy validates the OpenAPI specs your `docs.json` references.

</Update>

如果没有设置 rss: true，小组件仍会加载，但不会显示任何条目。启动器会保持隐藏。仅演示 <Update> 组件（未设置 rss: true）的文档页面不会显示在其中。演示日期不会点亮提示点。

每个向小组件提供内容的 <Update> 都必须有一个 date（任何 Date.parse 可以读取的值都可以，例如 2026-06-01）。仅在页面上设置 rss: true 并不够。日期用于排列 feed 并识别最新条目。小组件会跳过没有日期的条目。如果没有带日期的条目，悬浮启动器会保持隐藏，未读提示点也不会出现，即使已设置 rss: true。

配置代码片段

每个选项都是脚本标签上的一个 data- 属性。仪表板卡片会生成这些属性，你也可以手动编辑代码片段。

Attribute	Values	Default	Purpose
`data-base`	Your site URL	script origin	The `*.jamdesk.app` origin (plus `/docs` if you host under a subpath).
`data-page`	Path	`/changelog`	Any docs path to open in the modal, not just the changelog. See Point the modal at any page.
`data-theme`	`auto`, `light`, `dark`	`auto`	Force the modal's color scheme, or follow the visitor's system setting.
`data-position`	`bottom-right`, `bottom-left`, `top-right`, `top-left`	`bottom-right`	Which corner the floating launcher sits in. Ignored when `data-trigger` is set.
`data-label`	Text	`What's new`	The floating launcher's button text.
`data-width`	CSS length	`560px`	Modal width. See Size the modal.
`data-height`	CSS length	`680px`	Modal height.
`data-radius`	CSS length	`12px`	The modal's corner radius. Lower it for squarer corners.
`data-unread`	`off` to disable	on	Whether to show the unread dot.
`data-unread-color`	Hex or CSS color name	`#e5484d`	The unread dot's color.
`data-button-color`	Hex or CSS color name	`#111`	Floating launcher background. Ignored when `data-trigger` is set.
`data-button-text-color`	Hex or CSS color name	`#fff`	Floating launcher text color.
`data-trigger`	CSS selector	(none)	Bind to your own element instead of the floating launcher.
`data-project`	Slug	derived from `data-base`	The key the per-visitor "seen" state is stored under. Override only if one origin serves more than one changelog.

将模态框指向任意页面

data-page 可以打开文档网站上的任意路径，而不仅限于 /changelog。模态框会渲染你指定的页面，但不包含网站外框。可用于公告或迁移说明：

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/announcements/2026-migration"
  data-unread="off"
  async
></script>

以下两种行为仍与更新日志 feed 相关：

未读提示点跟踪更新日志中的最新条目，而不是模态框中的页面。当模态框打开其他页面时，请设置 data-unread="off"。否则，访客看不到的更新日志更新也会点亮提示点。
悬浮启动器仅在更新日志中有条目时显示（请参阅通过 rss: true 启用）。如果网站没有更新日志，请使用 data-trigger 绑定到自己的元素。你的元素始终会显示。

启动器模式

悬浮启动器

保持 data-trigger 关闭。小组件会在 data-position 指定的角落渲染自己的按钮，并显示 data-label 文本。

绑定到自己的元素

设置 data-trigger="#whats-new"（任意 CSS 选择器均可）。小组件会从现有的导航链接或按钮打开。

绑定的元素会显示未读提示点。小组件不会渲染悬浮按钮，data-position 和 data-label 也不再生效：

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-trigger="#whats-new"
  async
></script>

调整模态框大小

模态框默认以 560 × 680 px 的尺寸打开。使用 data-width 和 data-height 更改尺寸。纯数字会被视为像素值。也可以使用任何 px、vw、vh、rem、em 或 % 值：

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-width="720px"
  data-height="600px"
  async
></script>

模态框最大宽度为 92vw，最大高度为 86vh。即使尺寸较大，在手机上也能完整显示。无法识别的值会回退到默认值。默认圆角半径为 12px。使用 data-radius（任意 CSS 长度值）可以将圆角改为直角或进一步增大圆角。

设置启动器按钮样式

悬浮启动器默认为深色胶囊形按钮。使用 data-button-color（背景）和 data-button-text-color（文本）更改颜色。可以使用十六进制值或 CSS 颜色名称：

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-button-color="#4f46e5"
  data-button-text-color="#ffffff"
  async
></script>

这两个属性只会设置小组件自身的悬浮按钮样式。它们不会影响通过 data-trigger 绑定的元素，该元素会保留自己的样式。

自定义未读圆点

未读提示点默认为红色（#e5484d），且默认启用。使用 data-unread-color（十六进制值或 CSS 颜色名称）更改颜色。设置 data-unread="off" 可将其关闭：

<!-- Recolor the dot -->
<script src="https://acme.jamdesk.app/_jd/widget.js" data-base="https://acme.jamdesk.app" data-unread-color="#7c3aed" async></script>

<!-- Turn the dot off -->
<script src="https://acme.jamdesk.app/_jd/widget.js" data-base="https://acme.jamdesk.app" data-unread="off" async></script>

关闭提示点不会影响启动器和模态框，只会移除提示标记。

未读圆点

小组件会将最新条目的 id 与浏览器 localStorage 中的值进行比较（每个项目使用一个键）。两者不同时，启动器上会显示提示点。打开模态框后，该条目会被标记为已读。提示点会保持熄灭，直到发布下一次更新。

此状态保存在 localStorage 中，按浏览器和访客分别记录。它不涉及账户或跟踪。清除网站数据会重置状态。首次使用新浏览器的访客会看到一次提示点。发布新内容后，提示点会再次出现。

示例

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-position="bottom-left"
  data-unread-color="#22c55e"
  async
></script>

内容安全策略

如果网站发送了严格的 Content-Security-Policy，请在三个指令中允许 *.jamdesk.app 源站。否则小组件不会有任何提示地停止工作：

Content-Security-Policy:
  script-src  https://acme.jamdesk.app;
  frame-src   https://acme.jamdesk.app;
  connect-src https://acme.jamdesk.app;

script-src 用于加载 widget.js。
frame-src 用于渲染模态框的 iframe。
connect-src 用于获取未读提示点所需的更新日志元数据。

缺少指令时不会显示错误横幅。启动器不会出现，或者模态框会保持空白。如果小组件没有显示，请检查浏览器控制台中的 CSP 违规信息。

受密码保护的网站

如果文档网站受密码保护，请勿嵌入小组件。解锁页面应显示在你的 *.jamdesk.app 网站上，而不是第三方 iframe 中。嵌入后，访客需要在另一个源站的框架中输入网站密码，看起来像钓鱼提示。请仅在公开的更新日志中使用小组件。

下一步

Update 组件

编写小组件读取的更新日志条目

自定义域名

使用自己的域名提供文档（小组件仍从 jamdesk.app 加载）

小组件源代码

固定版本、自行托管，或在 GitHub 上查看源代码