数字标牌应用库：200+ 内置卡片

卡片是播放列表画布上的内置组件。它用时钟、菜单、队列或其他实时细节填充其矩形，可覆盖图像或视频。

布局和锚点

在播放列表项中，在 card 旁设置 layout 和 anchor。layout 是必需的。

`layout`	以 1080p 设计单位为盒	`anchor`
`full`	整个画布，横屏或竖屏	无
`free`	你自己的`rect`和`layer`	无
`center`	900 × 420，居中	无
`wide`	画布从顶部和底部内嵌 80，侧边内嵌 30	无
`header`	整个顶边为 80	无
`footer`	整个底边为 80	无
`corner`	270 × 270，紧贴角落	`top-left`, `top-right`, `bottom-left`, `bottom-right`
`chip`	240 × 70，距最近两边各内缩 30	`top-left`, `top-right`, `bottom-left`, `bottom-right`
`strip`	整个边缘为 120	`top`, `bottom`, `left`, `right`

尺寸按min(canvas width, canvas height) / 1080缩放。4K 画布（3840 × 2160）显示的视觉大小与 1080p 相同，纵向画布与横向画布相同。卡片的设计遵循其盒子的形状：条形、横向、正方形、纵向或塔形。

anchor 是 corner、chip 和 strip 的必需项，不允许用于 full、free、center、wide、header 和 footer。除 free 外，所有布局均省略 rect 和 layer：screenRIG 在保存播放列表时从页面画布中推导它们。free 项目需要自己的 rect 和 layer。

用一个full、center或wide卡片加上需要的corner、chip和strip卡片组成页面。页面最多包含一个full、center或wide卡片，每个角落最多一个corner或chip卡片，每条边最多一个strip，加上一个共享该边的存在卡片。header和footer是全宽条，80高，分别沿顶部和底部边缘，页面每边持有一个条：header占用顶部边的strip槽，footer占用底部边的槽，因此该边无普通strip，但存在卡片仍可共享。页面可同时持有header和footer。图像、视频和网页项目不受此规则限制，任意数量的free卡片可共享页面。边缘上的corner或chip在有strip时向内移动120，有header或footer时移动80（边缘同时有两者时取较大值），因此永不重叠。center、wide、header或footer卡片忽略条带。

左或右 strip 是该边缘的带状区域，宽 120，高与画布相同。卡片绘制为水平条带，播放器围绕带中心将其旋转 90 度：左条带逆时针旋转，文字从下到上；右条带顺时针旋转，文字从上到下。

卡片层级决定其布局。核心卡片取全部九个，缩小为其绘制的布局：仅 header 和 footer 卡片取这两个。全屏卡片为全景或纵向屏幕设计，仅取 full。过渡卡片为页面切换缓冲，不取布局。GET /api/card-types 和 screenrig cards show ID 列出每个卡片的层级和布局。

在线状态

某些卡片仅在其条件成立时显示，如底部边缘的提醒条或“附近有闪电”芯片。缺失时卡片不绘制。与普通条形同边的存在条形在存在时替代它，存在条形消失后普通条形恢复。带存在的卡片出现和消失的动画匹配其布局：条形从边缘滑入，角落和芯片上升并淡出，center、wide、header、footer、full 和 free 卡片淡出。

布局错误

保存播放列表时，如果缺少或未知布局、缺少、未知或不需要的锚点、卡片的层级或视图不支持的布局，或 rect 或 layer 不是派生的，将拒绝并返回 card_layout_invalid（400）。当两个卡片声明页面上的同一位置时，将拒绝并返回 card_layout_conflict（400）。errors[0].field 指定成员。

主题

将 params.theme 设置为 neomustard（NeoMustard）、cyanotype（Cyanotype）、propaganda（Propaganda）、signal（Signal）、avant-garde（Avant Garde）、bloom（Bloom）、clear-dark（Clear Dark）、clear-light（Clear Light）或 primetime（Primetime）。screenrig.ai 上的卡片默认打开 Bloom，主题控制可切换它们。Primetime 是动画主题，background none 提供透明背景，角落和芯片布局使用主题的紧凑面板。

核心、全屏和插播卡片

每张卡片分为核心、全屏或转场三类。核心卡片适配所有布局，并显示在应用页面。全屏卡片填满横屏或竖屏，并在下方卡片参考中有各自页面。转场卡片在两个页面间切换时播放。

常用属性

这些属性控制每张卡片的主题和位置。在 params 中设置它们。

名称	类型	默认	数值和限制	描述
`theme`	string	`"neomustard"`	`"neomustard"`, `"cyanotype"`, `"propaganda"`, `"signal"`, `"avant-garde"`, `"bloom"`, `"clear-dark"`, `"clear-light"`, `"primetime"`
`background`	string	`"theme"`	`"theme"`, `"none"`	无背景色，用于覆盖视频的分层。
`accent`	字符串，空值	`null`	模式：`"^#[0-9A-Fa-f]{6}$"`	覆盖主题强调色。
`layout`	string		`"full"`, `"free"`, `"center"`, `"wide"`, `"corner"`, `"chip"`, `"strip"`	卡片放置位置（CONTRACT.md “布局”）：full 为全屏，free 为主机提供的任意矩形，center 为 900x420，wide 为屏幕上下各内缩 80，左右各内缩 30，corner 为 270x270 紧贴角落，chip 为 240x70 内缩 30，strip 为沿边缘高 120（尺寸为 1080p 设计像素）。无指定时，卡片矩形填满屏幕则为 full，否则为 free。
`anchor`	string		`"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"`, `"top"`, `"bottom"`, `"left"`, `"right"`	布局所在角落（角落和芯片）或边缘（条带）。角落默认为右上，条带默认为底部；其他布局无此属性。

静态和动态属性

卡片是项目中的一个实例：一个 crd_ ID，保存卡片的静态属性和实时数据文档。创建一次，把它的 ID 放入页面项目，之后可随时更改其值。

静态属性是实例的 params：主题、位置、标题等。使用 card params 更改它们，然后再次发送播放列表以使其生效。动态属性是卡片契约中标记为 dynamic: true 的值，如菜单部分、队列条目或仪表读数。它们保存在卡片的数据文档中，用 card data put 替换该文档无需重新发布播放列表。

播放器应用默认值，然后是静态参数，最后是文档的动态属性。实时文档不能更改样式，params也从不包含动态属性。必需的动态属性尚无文档的卡片保持隐藏，直到写入文档。

一张卡片，一个文档

每张卡片都有自己的数据文档，每个持有其 crd_ ID 的页面项目都显示该文档。显示不同帖子的两张 Workplace Posts 卡片是各有自己 ID 的两张卡片：写入其中一张只会更新持有其 ID 的项目。当多个项目应显示同一文档时，把同一个 ID 放入这些项目，它们可以在同一页，也可以分布在多页。

Feeds

Feeds 是由后端获取并缓存的第三方数据，通过 Player 传递给卡片。对于天气，设置 location，包含名称、纬度和经度。后端根据这些静态属性推导 Feed 键；请勿在画布项中发送 feed 字段。Feed 文档包含来源归属和获取时间戳。每个卡片引用其 Feed 架构和来源归属。

在 feed 的数据显示的任何位置都要显示其署名：卡片会自动完成。智能体用 GET /api/feeds/FAMILY 读取卡片读取的文档，其中系列是下面各节系列和卡片之后的第一个名称。对新地点的首次读取会在 screenRIG 获取期间返回带 Retry-After: 60 的 202，同一地点的所有卡片共享同一份文档。

潮汐

来自 NOAA CO-OPS 的单个潮位站潮汐预测：美国及其属地的公共领域数据。

系列和卡片： tides 和 tides
设置： station（NOAA 的七位潮位站 ID），或 location（选取 100 公里内最近的预测站）。附近没有这么近的潮位站的地点不会生成 feed 键：卡片会等待，API 返回 400 invalid_request。
数据： 从两天前到三天后的高潮和低潮，另外还有 NOAA 按调和分析预测的潮位站的 15 分钟序列。高度以 MLLW 以上的米为单位，时间为 UTC。每 6 小时刷新一次。
署名： Tide predictions from NOAA CO-OPS, reformatted by screenRIG; not an official NOAA product.

火箭发射

来自 The Space Devs 的 Launch Library 2 的全球后续火箭发射。

系列和卡片： launches 和 launch-tracker
设置： 无。所有卡片显示同一份列表。
数据： 最近的 20 次发射，含发射服务商、运载火箭、发射台和轨道，每 15 分钟刷新一次。发射在升空后 24 小时内仍会列出，卡片就是这样显示其结果的，位于发射台的那次发射还会得到最多 20 个事件的任务时间线。
署名： Data: The Space Devs / Launch Library 2.

药品和食品召回

来自某国卫生或食品机构的召回信息。

系列和卡片： drugalerts 和 drug-alerts
设置： country（us、ca 或 gb）和 category（默认为 drug，或 food）。
数据： 最近 90 天，先列 I 类，同一类别内按最新优先，最多 100 条。美国：通过 openFDA 提供的 FDA 执法报告，按报告日期排序，已完成和已终止的召回不包含在内。加拿大：Health Canada 和 CFIA 的召回与安全警示。英国：MHRA 的药品召回（1 至 3 类）和 Food Standards Agency 的食品警示。每 3 到 6 小时刷新一次。
署名： 各机构自己的署名，遵循其开放许可：openFDA（CC0）、Open Government Licence – Canada 和 Open Government Licence v3.0。

呼吸道疾病

流感、COVID-19 和 RSV 的每周活动情况。

系列和卡片： respiratory 和 respiratory-activity
设置： country（us 或 gb）和 region：美国的州、属地或 DC（按名称或邮政编码），或英格兰或 UKHSA 的某个地区。地区为空表示全国。
数据： 每种病毒有一个从很低到很高的级别、一个趋势（上升、平稳或下降，由 screenRIG 用最近两周与之前两周比较得出）、最新的值和 26 周的历史。美国：CDC 的每周住院级别和比率，每 6 小时刷新一次。英格兰：UKHSA 的实验室检测阳性比例，每 12 小时刷新一次。UKHSA 不发布级别，因此由 screenRIG 通过比较最新一周与过去 52 周的最高值来确定：低于 5% 为很低，低于 20% 为低，低于 40% 为中等，低于 70% 为高，更高则为很高。
署名： CDC，不代表 CDC、HHS 或美国政府认可 screenRIG，且内容未作更改；UKHSA，遵循 Open Government Licence v3.0。

年鉴

today 卡片为日期增加的内容：纪念日、当天的历史事件，以及太阳和月亮。

系列和卡片： almanac 和 today
设置： language（ar、bs、cs、de、en、es、fr、it、pt、ru、sv、tr、uk 或 zh；默认为 en）、country（ISO 3166-1 代码）、location（由 {screen.location} 填入）和 date。这些都不设置的卡片显示英文历史和国际节日。
数据： 该国的法定假日、纪念日和国际节日（无论什么语言，假日名称都是英文）、来自维基百科 On This Day 的当天最多十个事件，以及在有地点时的日出、日落、太阳正午、民用晨光和暮光、白昼时长和月相。太阳和月亮是计算得出的，而不是获取的。文档涵盖前一天到两天后，因此页面会在当地午夜翻页。
署名： 维基百科贡献者，遵循 CC BY-SA 4.0。

户外安全

outdoor-safety 卡片显示的高温读数。

系列和卡片： outdoorsafety 和 outdoor-safety
设置： location。
数据： 针对烈日下开阔地面的湿球黑球温度估算值，根据该地点的天气计算：温度、湿度、风、云量和太阳高度。阴凉处读数更低。这是估算值，绝不是传感器读数，文档中也会这样说明。观测数据每小时一次，因此请把卡片的 staleMinutes 设为 120 或更大。
闪电： 该 feed 只提供高温数据。请把卡片的 show 设为 heat，或把闪电记录写入卡片的数据。

公共交通发车

一个交通服务商的一到四个站点的后续发车信息，按发车顺序排列。

系列和卡片： departures 和 departures
设置： provider（tfl、entur 或 digitransit）和 stops（服务商的站点 ID，在 API 中以逗号分隔）。请使用服务商自己的站点搜索查找 ID。
数据： 屏幕显示看板期间每分钟刷新一次。已取消的发车仍列为已取消，没有发车的站点是空看板。服务商不认识的站点会让整个看板失败，并保留上一个看板。TfL 只提供实时预测，因此其行没有延误信息。

服务商	站点 ID 示例	署名
`tfl`	`940GZZLUOXC`（Oxford Circus）、`490008660N`（一个公交站）	Powered by TfL Open Data
`entur`	`NSR:StopPlace:337`, `NSR:Quay:568`	Contains data under the Norwegian licence for Open Government data (NLOD) distributed by Entur
`digitransit`	`HSL:1040129`	© Digitransit, CC BY 4.0

离某个地点最近的共享单车站点，来自发布 GBFS 的系统。

系列和卡片： bikeshare 和 bike-share
设置： location（可使用 {screen.location}），以及可选的 system，即 MobilityData 的系统 ID，如 Mobibikes_CA_Vancouver、dublin 或 nextbike_bn。不设置 system 时，由区域包含该地点的最近的已列出系统提供服务；没有任何已列出系统覆盖的地点不会生成键：卡片会等待，API 在 system 处返回 invalid_request。
数据： 先列最近的站点，最多 40 个（20 公里内），每个都有自行车、电助力车、车桩和状态，每分钟刷新一次。
系统： 28 个，其自身的 feed 带有允许再分发和商业展示的许可：ODbL 许可的 Mobi（温哥华）和 City Bikes Helsinki，CC BY 4.0 许可的 docomo（东京），Licence Ouverte 许可的 JCDecaux 系统（都柏林、里昂、图卢兹、南特、布鲁塞尔、卢森堡、瓦伦西亚、卢布尔雅那），以及 CC0 许可的 nextbike（柏林、科隆、杜塞尔多夫、汉诺威、纽伦堡、波恩、维也纳、林茨、因斯布鲁克、布拉格、布尔诺、华沙、弗罗茨瓦夫、萨格勒布、巴塞罗那、哥德堡和斯特拉斯堡）。
署名： 运营方，遵循其许可。

发布卡片画布

按照开始指引安装官方插件，选择项目并配对播放器。创建卡片，把它的 ID 放入播放列表并发布。本页使用 center 布局中的仪表卡片。

将卡片的静态属性保存为 gauge-params.json：

{"theme":"neomustard"}

使用插件自带的 CLI 创建卡片。结果中包含它的 crd_ ID。

screenrig card create --type gauge --file gauge-params.json

或者使用类型及其参数调用 API。201 响应中包含卡片的 id。

curl --request POST "https://api.screenrig.ai/api/cards" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"type":"gauge","params":{"theme":"neomustard"}}'

将以下内容保存为 playlist.json，并用你的卡片 ID 替换 crd_01EXAMPLEGAUGE000000000。页面项目只发送 ID 及其布局：卡片的 params 和数据保留在卡片中。

{
  "name": "Live gauge",
  "pages": [
    {
      "id": "main",
      "canvas": {
        "width": 1920,
        "height": 1080,
        "background": "#000000FF",
        "viewport_fit": "contain"
      },
      "transition": {
        "type": "crossfade",
        "duration_ms": 500
      },
      "advance": {
        "mode": "duration",
        "after_ms": 15000
      },
      "primitives": [
        {
          "id": "gauge",
          "primitive": "card",
          "card": "crd_01EXAMPLEGAUGE000000000",
          "layout": "center",
          "content_fit": "fill"
        }
      ]
    }
  ]
}

使用 API 认证进行授权。智能体令牌已指定项目，因此示例未发送 ScreenRig-Project 头；若发送，必须与令牌项目匹配。令牌值请勿放入播放列表文件。

curl --request POST "https://api.screenrig.ai/api/playlists" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: application/json" \
  --data @playlist.json

响应以 pl_ ID 标识播放列表。pending_review 响应等待项目审核后上线。要更改静态属性，请用 screenrig card params crd_ID --file gauge-params.json（PATCH /api/cards/{id} 和 {"params": {...}}）更新卡片，然后再次用 PUT /api/playlists/{id} 发送 {name, pages} 文档：播放列表在保存时会采用卡片当前的参数。卡片的 major 在创建时是可选的，用于固定其契约；省略则选择当前主版本。

以内联 params 和 data 指定目录类型的旧页面项目，以及它们背后的 /api/card-data/{key} 路由，仍会被接受。每个响应都带有一条弃用警告，指明其替代方式：来自 /api/cards 的卡片实例 ID，以及 /api/cards/{id}/data。

写入实时数值

建议使用CLI，内含命令。将文档保存为gauge-data.json。该文件仅包含文档本身，无包装：

{"metrics":[{"label":"Capacity","value":72,"unit":"%"}]}

screenrig card data put crd_01EXAMPLEGAUGE000000000 --file gauge-data.json

写入会替换整个文档，并按卡片的动态属性检查：卡片拒绝的文档会被 card_data_invalid（409）拒绝，且不会有任何改变。如需在没有任何更新时清空所有屏幕（包括离线屏幕）上的数据，请添加 --ttl 30m 或 --expires-at INSTANT。针对 card_data_stale 条件的通知会在卡片数据因无人续期而过期时告知项目。

或者直接调用 API。API 将相同文档包装在 document 字段中。文档为最大 1 MiB 的 JSON 对象。

curl --request PUT "https://api.screenrig.ai/api/cards/crd_01EXAMPLEGAUGE000000000/data" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"document":{"metrics":[{"label":"Capacity","value":72,"unit":"%"}]}}'

显示卡片的屏幕会重新获取文档并就地更新。使用 GET /api/cards/{id}/data 读取文档；其修订 ETag 可作为 If-Match 发送以进行下一次写入。添加 Idempotency-Key 以实现安全可重复写入，在 document 旁添加 ttl_seconds 或 expires_at 以设置过期。使用 GET /api/cards 列出项目的卡片；在没有播放列表使用某张卡片后，用 DELETE /api/cards/{id} 删除它。

卡片属性中的图像使用 media:<mediaId>，引用同一项目中准备好的图像。实时数据写入需要这些图像被批准。切勿在卡片属性中放置图像 URL。

使用 CLI 分配并验证

使用官方插件捆绑的 CLI 和相同项目。API 响应中获取播放列表 ID，screen list 中获取屏幕 ID，然后分配并检查结果：

screenrig screen list
screenrig screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE
screenrig screen screenshot scr_EXAMPLE

分配记录所需播放列表。报告播放前检查播放器证据。CLI 参考 · API 参考。

卡片引用

卡片参考涵盖三组：核心卡片、全屏卡片和插播。核心卡片适配所有布局，全屏卡片填满整个屏幕，插播在页面间播放。

核心卡片

全屏卡片

短促插入

刺针