---
title: Widget 组件
description: "使用 Widget MDX 组件在文档中嵌入实时 What's New 小组件演示：触发按钮可在模态框中打开更新日志，无需 script 标签。"
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

`<Widget>` 可将实时的 What's New 触发器直接放入文档页面。点击后，Jamdesk 更新日志会在客户通过[在应用中嵌入小组件](/cn/development/embed-page)时看到的同一个模态框中打开。区别在于：此处只需编写一个 MDX 标签，而不是 `<script>`，页面还会自动解析你的网站。

## 快速开始

```mdx
<Widget />
```

这会渲染一个按钮，在模态框中打开 `/changelog`（默认路径）。如果更新日志位于其他位置，请将 `page` 设置为其实际路由，否则模态框会打开 404 页面。（例如，Jamdesk 自己的更新日志位于 `/reference/changelog`。）

```mdx
<Widget page="/reference/changelog" label="What's new" />
```

<Note>
`<Widget>` 会自动解析你的规范 `*.jamdesk.app` 来源，因此无论文档位于 `jamdesk.app` 子域名还是自定义域名上，运行方式都相同。模态框始终从该子域名加载，因为只有此来源能够渲染嵌入视图。
</Note>

## 属性

| 属性 | 类型 | 默认值 | 用途 |
|------|------|---------|---------|
| `page` | string | `/changelog` | 模态框打开的文档路径。 |
| `label` | string | `What's new` | 触发按钮文本。 |
| `theme` | `auto` \| `light` \| `dark` | `auto` | 模态框配色方案。 |
| `trigger` | CSS selector | _(none)_ | 绑定到你自己的元素，而不是渲染按钮。 |
| `width` / `height` | CSS length | `560px` / `680px` | 模态框大小。 |
| `radius` | CSS length | `12px` | 模态框圆角半径。 |
| `unread` | boolean | `true` | 显示未读圆点。设置为 `false` 可将其隐藏。 |
| `unreadColor` | hex / CSS color | `#e5484d` | 未读圆点颜色。 |
| `project` | string | derived | 覆盖存储的“seen”键。 |

<Note>
设置 `trigger` 时，请确保选择器与页面上已有的元素匹配。如果没有匹配到任何元素，小组件会在角落显示自己的浮动启动器，而不是不执行任何操作。
</Note>

未读圆点的“seen”状态会按浏览器**以及每个来源**（小组件运行所在的页面）分别存储，因此访客在文档和应用中的已查看状态会分开跟踪，二者不会同步。对于演示按钮，请设置 `unread={false}` 以完全跳过圆点。

## 实时示例

<Widget page="/reference/changelog" label="See what's new in Jamdesk" unread={false} />

<Note>
此按钮会在部署后的文档网站上打开模态框，此时 `<Widget>` 会绑定到你的规范 `*.jamdesk.app` 来源。在本地 `jamdesk dev` 预览中，没有可用于加载模态框的已发布来源，因此触发器无法打开模态框，而会在按钮旁显示“Live preview”说明。请部署页面（或在实时网站上打开页面）以体验实际效果。
</Note>

## 接下来做什么？

<Columns cols={2}>
  <Card title="在应用中嵌入" icon="code" href="/cn/development/embed-page">
    用于将小组件放入你自己产品中的 `<script>` 代码片段
  </Card>
  <Card title="Update Component" icon="timeline" href="/cn/components/update">
    编写小组件读取的更新日志条目
  </Card>
  <Card title="Widget Source" icon="github" href="https://github.com/jamdesk/jamdesk-widget">
    固定版本、自行托管，或在 GitHub 上阅读源代码
  </Card>
</Columns>