跳到内容

全部开发者文档

可嵌入的 changelog widget

两行 HTML 就能把你的 changelog、路线图和反馈框放进产品里。本页介绍属性、主题、只显示部分仓库、版本控制,以及 widget 的备用托管页面。

可嵌入的 widget

如果你不想自己构建任何东西,插入这两行代码即可。widget 是一个渲染在 shadow root 中的自定义元素,因此它既不会继承你的样式,也不会泄漏到你的样式中。

<script src="https://api.changeloop.dev/widget.js" defer></script>
<changelogapp-widget
  data-public-id="YOUR_PUBLIC_ID"
  data-api="https://api.changeloop.dev"></changelogapp-widget>

两个属性都是必需的。data-public-id 是你的 feed ID,data-api 是 widget 获取数据的来源。如果缺少任意一个,该元素会在控制台写入错误并且不渲染任何内容——如果你看到本应显示 widget 的地方是一片空白,这是首先要检查的事项。

给元素加上 data-theme="dark" 即可使用深色渲染;你的页面可以在运行时切换。若要更深入地定制样式,widget 提供了 CSS 自定义属性(--changelogapp-text、--changelogapp-bg、--changelogapp-accent 等)和 ::part() 名称,在你自己的样式表中设置即可。应用会在设置的“公开 Feed”中实时预览两种主题。

添加 data-repos 可以只展示部分仓库,例如多个产品共用一个账户时,在某个产品的网站上只展示该产品的 changelog。值是用逗号分隔的完整名称列表,格式为 owner/repo;不带所有者的名称不会匹配任何内容,并且会无提示地显示为空的动态。最多支持十个仓库。限定范围后的小组件只显示 Updates 和 Feedback 两个标签页,因为路线图没有按仓库划分的视图;反馈仍会提交到团队反馈目标所指向的位置。在“设置,公开动态”中有一个选择器,可以替你写好这个属性。

它按以下顺序渲染三个标签页:Updates、Roadmap 和 Feedback。前两个读取上面的 feed。第三个会提交到下方的端点,并将每次提交的 ID 保存到 localStorage 中,这样访问者可以回来查看他们提交内容的处理情况。

该脚本按版本提供。/widget.js 始终提供最新构建,并缓存一小时,因此新版本无需你做任何操作即可到达访问者。/widget-vN.js 固定某一个构建:一旦某个版本号被提供过,其字节内容将永不改变,并缓存一年。如果你希望有意地采用变更,请使用固定版本。

每个页面只加载一个 widget 脚本

这两个 URL 是替代方案,不是叠加层。两者都注册相同的自定义元素名称,而浏览器只允许每个文档注册一次某个名称:先执行的脚本会在该页面的整个生命周期内胜出,第二个则会失效。因此同时包含 /widget.js 和 /widget-v5.js 的页面会渲染浏览器先执行的那一个,这不是你能控制的,在已有 /widget.js 旁边添加 /widget-v5.js 来固定版本不会产生任何效果。

发生这种情况时,widget 会在控制台写入一条同时指出两个构建的警告,因此你不必猜测。它只能给出警告:等到第二份副本执行时,第一份已经占用了该名称。解决方法始终是替换脚本标签,而不是再添加一个,如果是标签管理器或某个片段代替你插入的脚本也同样适用。要从持续更新的构建切换到固定构建,请更改 src。

发布弹窗

添加 data-mode="popup",元素就不会渲染标签页。当访问者有新内容可看时,它会显示一张小卡片,展示你的最新发布,其余时候什么都不显示。data-mode 不区分大小写。

<script src="https://api.changeloop.dev/widget.js" defer></script>
<changelogapp-widget
  data-public-id="YOUR_PUBLIC_ID"
  data-api="https://api.changeloop.dev"
  data-mode="popup"
  data-changelog-url="https://feed.changeloop.dev/feed/YOUR_PUBLIC_ID"></changelogapp-widget>

在宽屏上,卡片位于左下角,因为右下角通常留给在线聊天按钮。在宽度小于 480px 的屏幕上,它会占满整个宽度,并在关闭之前盖住聊天按钮。它在浏览器的顶层中打开,因此父元素的 overflow、transform 或 z-index 都无法裁剪或遮住它。如需调整位置,请为 ::part(popup) 设置样式。

每次发布只展示一次。当访问者有尚未看过的条目时,卡片才会出现。它展示其中最新的一条,条目有多个时会附上数量,并在出现的那一刻就将它们记为已读。下次加载页面时不会再显示,直到你再发布新内容。

首次访问时什么都不会显示:widget 只会记录你的 changelog 目前到哪里,这样在你添加它的当天,老用户不会看到一堆旧消息。卡片从你的下一次发布开始出现。已经在内嵌 widget 中读过某次发布的访问者,也不会再次看到它。

访问者看过什么保存在 localStorage 中,而不是 cookie 中,因此它只属于一个浏览器和一个站点来源。同一个人访问你的另一个域名时,会重新从首次访问开始。如果浏览器阻止了存储,每次访问都会被视为首次访问,卡片也就永远不会显示。

data-changelog-url 是可选的。如果它是 http 或 https 地址,卡片上会出现一个指向该地址的“See all updates”链接,通常是你的托管页面或你自己的 changelog 页面。如果是其他内容,则不会显示链接。data-theme 和 data-repos 的用法与内嵌 widget 完全相同。

卡片从不抢占焦点,也不会阻塞页面:它是一个带标签的区域,而不是对话框。可以通过关闭按钮关闭,或在焦点位于卡片内时按 Escape 关闭。在页面其他位置按 Escape,则交由你自己的代码处理。

每个页面只加载一个 widget 脚本的规则依然适用。弹窗和内嵌 widget 可以放在同一个页面:只加载一次脚本,再添加两个元素,它们对访问者已经看过什么会保持一致。

固定到 /widget-v18.js 及更早的构建比弹窗更旧。它们会忽略 data-mode,转而渲染内嵌的标签页,因此请使用 /widget.js 或更新的固定构建。

在应用的设置的“公开 Feed”中,有一段可直接复制的代码,其中已填好你的 feed ID、主题和仓库范围。卡片的展示次数及其“Learn more”链接的点击次数,会作为单独的数据显示在 Analytics 中。

表情回应

读者无需写任何文字,就能对一个条目作出回应。开启回应后,每个条目末尾都会有一行五个表情,👍 🎉 ❤️ 🚀 👀,每个都带有计数。这一行会显示在内嵌 widget、发布弹窗卡片和托管的 feed 页面上。

回应默认关闭,需要你在应用的“设置”的“公开 Feed”中开启。你的嵌入代码不用改:widget 会从你的 feed 读取这个开关,所以这一行会随开关出现或消失。关闭回应只是隐藏这一行,计数会保留,再次开启时就会恢复。在回应功能出现之前固定下来的构建永远不会显示这一行。

每位读者对一个条目的每种回应只能给一次,再按一下就会撤回。widget 靠首次点击时在浏览器中生成的随机 ID 来区分读者,而不是账号或邮箱地址。我们只保存这个 ID 与你的团队组合后的哈希值,所以同一个浏览器在两个不同的 changelog 上留下的哈希值互不相关。

计数是尽力而为的:它是一个友好的信号,不是投票。清除浏览器存储或打开无痕窗口后,同一个人可以再次回应,所以请不要用它来做重要决定。你的 feed 中的计数也可能滞后几分钟,因为 feed 有缓存,不过点击的人会立刻看到自己的回应被计入。在应用中,收件箱的“已发布”标签页会显示每个条目的总数。

回应会在访问者的 localStorage 中保存两项内容,绝不会写入 cookie。changelogapp-widget:reader-id 保存随机 ID,每个浏览器和站点来源各一个。changelogapp-widget:reactions: 后面跟着你的 feed ID,保存这个浏览器选过的回应,最多记录 200 个条目,也就是最近回应过的那些。托管页面会在它自己的地址下保存同样的两项。如果浏览器阻止了存储,回应在当前这次页面访问中仍然有效,但之后不会被记住。

要为这一行设置样式,请使用 ::part(reactions),用 ::part(reaction) 设置每个按钮,用 ::part(reaction-count) 设置其数字,这些都列在下面的“样式定制”中。计数为零时不显示数字。已按下的按钮带有 aria-pressed="true",并以你的 --changelogapp-accent 颜色的圆环和粗体文字绘制。::part() 无法按该属性选择,所以若要改变已按下按钮的外观,请设置 --changelogapp-accent。

公开反馈看板

看板让读者看到其他人提出了哪些需求,并为它们投票。开启看板后,“反馈”标签页会先显示票数最多的需求及其状态,常规的反馈表单则排在它们下面。

看板默认关闭,需要你在应用的“设置”的“公开 Feed”中开启。你的嵌入代码不用改:widget 会从你的 feed 读取这个开关。关闭看板只是把它隐藏,你的需求和票数都会保留。看板位于“反馈”标签页中,所以不显示“反馈”标签页的 widget 也就没有看板。

看板只显示你亲自写下的内容。访客的反馈不会自动出现在上面:哪些需求上看板由你决定,每条需求的标题和描述也由你在应用的“反馈看板”页面自己填写。你可以根据访客发来的消息创建需求,也可以发布自己的想法,看板绝不会显示访客的消息或邮箱地址。看板显示票数最高的 100 条需求,一个团队最多可以保留 500 条。

每条需求有五种状态之一:考虑中、已计划、进行中、已发布或已拒绝。把需求关联到某条更新后,该更新发布时需求会自动变为“已发布”,如果更新已经发布,则会立即变为“已发布”。由访客消息创建的需求,在发布了处理该消息的更新时,同样会变为“已发布”。

在每个站点上,每个浏览器对每条需求只有一票,再点一次就会撤回。需求一旦变为“已发布”或“已拒绝”,投票就会关闭,不过已经投过票的人仍然可以撤回自己的票。票数是一种信号,而不是真实人数:清除浏览器存储或打开无痕窗口后,同一个人可以再次投票,所以请用它来了解大家关心什么,不要用它来决定重要的事。其他访客看到的计数可能略有滞后,而投票的访客本人会立刻看到准确的新计数。

投票会在访客的 localStorage 中保存两项内容,绝不会写入 cookie。changelogapp-widget:votes: 后面跟着你的 feed ID,列出这个浏览器投过票的需求,最多记录最近的 200 条。changelogapp-widget:reader-id 是回应功能使用的随机 ID,每个浏览器和站点来源各一个,所以如果访客已经回应过,投票不会再新建任何内容。我们只保存这个 ID 与你的团队组合后的哈希值,绝不保存 ID 本身,所以同一个浏览器在两个不同的 changelog 上留下的哈希值互不相关。我们不会把访客的 IP 地址与投票一起保存。如果浏览器阻止了存储,投票在当前这次页面访问中仍然有效,但之后不会被记住。

看板从不显示在发布弹窗中,用 data-repos 限定范围的 widget 上也不显示,因为看板涵盖你的整个团队。你托管的 changelog 页面有一个“Requests”标签页,其中是同样的看板,还可以按状态筛选,投票的计算方式也相同。看板同时也是公开的 JSON,位于同一个 API 的 GET /v1/public/YOUR_PUBLIC_ID/board.json,看板关闭时它会返回 404。

要为看板设置样式,请用 ::part(board) 设置整个区块,用 ::part(board-heading) 设置其标题,再设置每条需求的各个部分,这些都列在下面的“样式定制”中。投票按钮 ::part(board-vote) 在这个浏览器投过票后会带有 aria-pressed="true",并以你的 --changelogapp-accent 颜色的圆环绘制。::part() 无法按该属性选择,所以若要改变已计票按钮的外观,请设置 --changelogapp-accent。

样式定制

widget 渲染在 shadow root 中,因此你的大部分样式表无法作用到其内部。在 widget 没有自行设置的地方,可继承的属性仍会传入,下面的自定义属性也一样,可以设置在元素本身或其任一祖先元素上。其他情况请使用下面的 ::part() 名称。这两份列表都是稳定的接口:名称一旦发布,就不会再改名。

自定义属性

  • --changelogapp-font-family
  • --changelogapp-text
  • --changelogapp-text-muted
  • --changelogapp-bg
  • --changelogapp-border
  • --changelogapp-accent
  • --changelogapp-radius
  • --changelogapp-space
  • --changelogapp-timeline-line
  • --changelogapp-pill-bg
  • --changelogapp-pill-text

tag 徽章。带颜色的 tag 会将该颜色用作背景,在两种主题下,文字颜色都会选择在该背景上清晰可读的颜色,对比度为 4.5:1 或更高。只要白色能达到这个对比度,就优先使用白色。如果 widget 无法将某个颜色解析为纯色 RGB 值,就不会为它挑选文字颜色,而是沿用主题的默认值。若想自己指定文字颜色,无论哪种主题,都请设置 --changelogapp-pill-text。::part(entry-tag) 规则的优先级高于一切,因此如果你在那里设置了背景,也请同时设置 color。--changelogapp-pill-bg 是没有颜色的 tag 的背景。固定到 /widget-v18.js 及更早的构建,在浅色主题下仍使用白色的徽章文字。

Parts

  • changelog 条目: month-heading, entry, entry-date, entry-tag, entry-title, entry-body, entry-link, timeline-dot, entry-image, entry-header-image
  • 条目正文内部: entry-body-heading, entry-body-paragraph, entry-body-list, entry-body-list-item, entry-body-link, entry-body-code
  • Updates 标签页上的未读数量: unread-badge
  • 发布弹窗: popup, popup-heading, popup-close, popup-link
  • “Get updates by email”表单,在启用邮件订阅者时位于 Updates 顶部(Team 套餐): subscribe, subscribe-heading, subscribe-input, subscribe-button, subscribe-status
  • 表情回应,开启时: reactions, reaction, reaction-count
  • 公开反馈看板,开启时: board, board-heading, board-request, board-request-title, board-request-description, board-request-status, board-request-link, board-vote, board-vote-count

Content-Security-Policy

如果你的站点发送 Content-Security-Policy 头,widget 需要在两个指令中加入 API 来源。script-src 让脚本得以加载。connect-src 让它能够读取你的 changelog、发送反馈并记录浏览。如果只设置了第一个,元素会出现但始终为空,看起来像是 feed 坏了,而不是请求被拦截。弹窗同样需要这两个指令。

script-src https://api.changeloop.dev; connect-src https://api.changeloop.dev;

从 widget 0.16.0 起(/widget.js 提供的就是该版本),当前的浏览器无需修改 style-src:widget 以构造样式表的方式提供样式,而 style-src 并不管辖它。更旧的构建(包括固定到 /widget-v18.js 及更早的构建)以及不支持构造样式表的浏览器,则改用 style 元素,这需要 style-src 'unsafe-inline'。

img-src 只有在你已于应用中开启图片(“设置”的“公开 Feed”中的“图片”)时才需要。此时 widget 会直接从你的图片主机加载图片,而没有列出这些主机的策略会拦截每一张图片。“设置”会打印出确切的那一行,其中的 img-src 已按你的列表填好,因此每次修改列表后都请重新复制。GitHub 的截图主机还需要在 img-src 中加入 https://github-production-user-asset-6210df.s3.amazonaws.com,因为 GitHub 的截图链接会重定向到那里,浏览器也会检查这个地址。

如果你的策略只设置了 default-src,请添加这两个指令,并在每个指令中重复你的 default-src 来源。script-src 或 connect-src 会取代 default-src 对脚本或连接的设置,因此漏掉你自己的来源就会将它们拦截。

请将该来源添加到你现有的指令中,而不是替换它们。应用的设置的“公开 Feed”中会显示这一行,并带有适用于你账户的正确来源。如果你不发送该头,则无需做任何事。

托管的 feed 页面

我们也在该地址托管了一个简单的页面:你的 changelog 和 roadmap 看板,均从上面相同的两个 feed 渲染而来。它不需要登录,也不需要你做任何配置。当一个反馈闭环完成时,这里也是我们将人们导回的地方:我们在 GitHub issue 上留下的 Shipped 评论会链接到这里,上面提交查询中的 shippedEntry.link 也是如此,两者都会指向已交付条目自身的 #entry-ID 锚点,即使该条目后来移到了后面的页面,这个锚点仍然能找到它。

请将其视为备用方案,而非集成方式。将其放在你自己的网站上、让它看起来像你的产品而不是我们的产品,方法仍然是 changelog feed 和 widget;这个页面是为了你尚未这样做的情况,也是为了无论你还构建了什么,都会指向这里的反馈闭环链接。

把 changelog 放进你的产品

Changeloop 根据每个已合并的 pull request 起草条目,等你审核后再提供给这个 widget 和 JSON feed。一个仓库免费,无需信用卡。

免费开始

阅读开发者文档