widgets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write and review SwiftUI WidgetKit code, choosing the right configuration, timeline policy, and surface so the widget renders correctly in every mode, updates within its budget, and behaves correctly across the extension/app process boundary.

Review process:

Establish the widget execution model (the extension process, app groups, the timeline lifecycle, the reload budget) using
```
references/fundamentals.md
```
.
Validate the timeline provider (
```
placeholder
```
/
```
snapshot
```
/
```
timeline
```
, reload policy,
```
WidgetCenter
```
reloads, entry relevance) using
```
references/timeline-provider.md
```
.

Validate the configuration and any user-configurable parameters (

StaticConfiguration

AppIntentConfiguration

WidgetConfigurationIntent

) using

references/configuration-and-intents.md

Check whether any legacy API is in use and route it to the modern equivalent (SiriKit
```
.intentdefinition
```
→ App Intents, ClockKit → WidgetKit,
```
PreviewProvider
```
→
```
#Preview
```
) using
```
references/migration-and-deprecations.md
```
.
Validate data loading - networking, persistence, images, location - in the provider and intents using
```
references/data-and-networking.md
```
.
Validate family support and per-family layout (
```
WidgetFamily
```
, sizing, content margins,
```
ViewThatFits
```
) using
```
references/families-and-layout.md
```
.
Validate Lock Screen / accessory widgets and watch complications (
```
widgetLabel
```
,
```
AccessoryWidgetBackground
```
, the transparent-container trick, ClockKit migration) using
```
references/lock-screen-and-watch.md
```
.
Validate rendering across full-color, accented, tinted, and vibrant modes (
```
widgetRenderingMode
```
,
```
widgetAccentable
```
,
```
widgetAccentedRenderingMode
```
, the luminance-to-alpha trick) using
```
references/rendering-modes-and-tinting.md
```
.

Validate interactivity (

Button(intent:)

Toggle(intent:)

, the app-process boundary,

reloadTimelines

invalidatableContent

) using

references/interactive-widgets.md

Validate deep links and navigation into the app (

widgetURL

Link

onOpenURL

OpenIntent

) using

references/deep-linking-and-navigation.md

Validate animations and entry transitions (

contentTransition

.transition

+ identity,

invalidatableContent

, what doesn't animate) using

references/animations-and-transitions.md

Validate Control Center controls (
```
ControlWidget
```
, toggle vs button,
```
SetValueIntent
```
, value providers,
```
ControlCenter
```
reloads) using
```
references/controls.md
```
.

Validate Live Activities and the Dynamic Island (

ActivityAttributes

ActivityConfiguration

DynamicIsland

, request/update/end, push,

supplementalActivityFamilies

) using

references/live-activities.md

Validate Smart Stack relevance (

TimelineEntryRelevance

relevance()

WidgetRelevance

RelevanceConfiguration

, push-based relevance) using

references/relevance-and-smart-stacks.md

Check the design and gallery presentation (glanceability, sizes, the don'ts,
```
configurationDisplayName
```
/
```
description
```
, the placeholder) using
```
references/design-and-gallery.md
```
.
Validate previews and the testing/debugging workflow (
```
#Preview(as:)
```
, WidgetKit developer mode, the reload budget) using
```
references/previews-and-testing.md
```
.
Validate platform-specific surfaces (visionOS spatial widgets, CarPlay, macOS menu bar, the availability map) using
```
references/platforms.md
```
.
Catch common mistakes using
```
references/anti-patterns.md
```
.

If doing partial work, load only the relevant reference files.

编写和审查SwiftUI WidgetKit代码，选择合适的配置、时间线策略和界面场景，确保组件在所有模式下渲染正常、在预算内更新，并在扩展/应用进程边界间表现合规。

审查流程：

借助
```
references/fundamentals.md
```
确立组件执行模型（扩展进程、应用组、时间线生命周期、重载预算）。
借助
```
references/timeline-provider.md
```
验证时间线提供者（
```
placeholder
```
/
```
snapshot
```
/
```
timeline
```
、重载策略、
```
WidgetCenter
```
重载、条目相关性）。

借助

references/configuration-and-intents.md

验证配置及任何用户可配置参数（

StaticConfiguration

、

AppIntentConfiguration

、

WidgetConfigurationIntent

）。

检查是否使用了旧版API，并将其替换为现代等效方案（SiriKit
```
.intentdefinition
```
→ App Intents、ClockKit → WidgetKit、
```
PreviewProvider
```
→
```
#Preview
```
），参考
```
references/migration-and-deprecations.md
```
。
借助
```
references/data-and-networking.md
```
验证提供者和意图中的数据加载——网络请求、持久化、图片、位置信息。
借助
```
references/families-and-layout.md
```
验证组件家族支持及按家族布局（
```
WidgetFamily
```
、尺寸、内容边距、
```
ViewThatFits
```
）。
借助
```
references/lock-screen-and-watch.md
```
验证锁屏/附属组件和手表复杂功能（
```
widgetLabel
```
、
```
AccessoryWidgetBackground
```
、透明容器技巧、ClockKit迁移）。
借助
```
references/rendering-modes-and-tinting.md
```
验证全彩、强调、着色、活力模式下的渲染（
```
widgetRenderingMode
```
、
```
widgetAccentable
```
、
```
widgetAccentedRenderingMode
```
、亮度转透明度技巧）。

借助

references/interactive-widgets.md

验证交互性（

Button(intent:)

、

Toggle(intent:)

、应用进程边界、

reloadTimelines

、

invalidatableContent

）。

借助

references/deep-linking-and-navigation.md

验证深度链接和应用内导航（

widgetURL

、

Link

、

onOpenURL

、

OpenIntent

）。

借助

references/animations-and-transitions.md

验证动画和条目过渡（

contentTransition

、

.transition

+ identity、

invalidatableContent

、不支持动画的内容）。

借助
```
references/controls.md
```
验证控制中心控件（
```
ControlWidget
```
、切换器与按钮、
```
SetValueIntent
```
、值提供者、
```
ControlCenter
```
重载）。

借助

references/live-activities.md

验证Live Activities与灵动岛（

ActivityAttributes

、

ActivityConfiguration

、

DynamicIsland

、请求/更新/结束、推送、

supplementalActivityFamilies

）。

借助

references/relevance-and-smart-stacks.md

验证智能堆栈相关性（

TimelineEntryRelevance

、

relevance()

WidgetRelevance

、

RelevanceConfiguration

、基于推送的相关性）。

借助
```
references/design-and-gallery.md
```
检查设计和组件库展示（易读性、尺寸、禁忌、
```
configurationDisplayName
```
/
```
description
```
、占位符）。
借助
```
references/previews-and-testing.md
```
验证预览和测试/调试工作流（
```
#Preview(as:)
```
、WidgetKit开发者模式、重载预算）。
借助
```
references/platforms.md
```
验证平台特定界面（visionOS空间组件、CarPlay、macOS菜单栏、可用性映射）。
借助
```
references/anti-patterns.md
```
排查常见错误。

如果只做部分工作，仅加载相关参考文件。

Task-based routing

基于任务的路由

Match the user's goal to the read order. Load only what you need.

将用户目标与阅读顺序匹配，仅加载所需内容。

"Create my first widget" / "show me a complete widget"

"创建我的第一个组件" / "展示完整的组件示例"

```
references/fundamentals.md
```
- the extension, the widget bundle, the timeline lifecycle
```
references/worked-example.md
```
- one widget built end to end (entry → provider → layout → links → tinting → animation → preview)

references/timeline-provider.md

TimelineProvider

, entries, reload policy

```
references/families-and-layout.md
```
- pick families, per-family layout

references/previews-and-testing.md

#Preview(as:)

to iterate

```
references/fundamentals.md
```
- 扩展、组件包、时间线生命周期
```
references/worked-example.md
```
- 端到端构建一个组件（条目 → 提供者 → 布局 → 链接 → 着色 → 动画 → 预览）

references/timeline-provider.md

TimelineProvider

、条目、重载策略

```
references/families-and-layout.md
```
- 选择组件家族、按家族布局

references/previews-and-testing.md

- 使用

#Preview(as:)

迭代开发

"Let the user configure my widget"

"允许用户配置我的组件"

references/configuration-and-intents.md

AppIntentConfiguration

WidgetConfigurationIntent

, dynamic options, defaults

references/timeline-provider.md

AppIntentTimelineProvider

(the intent is the first argument)

references/configuration-and-intents.md

AppIntentConfiguration

WidgetConfigurationIntent

、动态选项、默认值

references/timeline-provider.md

AppIntentTimelineProvider

（意图作为第一个参数）

"Add a Lock Screen widget / watch complication"

"添加锁屏组件 / 手表复杂功能"

references/lock-screen-and-watch.md

- accessory families,

widgetLabel

AccessoryWidgetBackground

, gauges, ClockKit migration

```
references/rendering-modes-and-tinting.md
```
- accessory widgets are always rendered in a tint mode

references/lock-screen-and-watch.md

- 附属组件家族、

widgetLabel

、

AccessoryWidgetBackground

、仪表盘、ClockKit迁移

references/rendering-modes-and-tinting.md

- 附属组件始终以着色模式渲染

"My widget looks wrong in tinted / dark / accented mode"

"我的组件在着色/深色/强调模式下显示异常"

references/rendering-modes-and-tinting.md

widgetRenderingMode

widgetAccentable

widgetAccentedRenderingMode

, the luminance-to-alpha trick, designing for the accent group

references/lock-screen-and-watch.md

- the transparent

containerBackground

for accessory widgets

references/rendering-modes-and-tinting.md

widgetRenderingMode

、

widgetAccentable

、

widgetAccentedRenderingMode

、亮度转透明度技巧、为强调组设计

references/lock-screen-and-watch.md

- 附属组件的透明

containerBackground

"Add a button / toggle inside my widget"

"在组件内添加按钮 / 切换器"

references/interactive-widgets.md

Button(intent:)

Toggle(intent:)

, the app-process boundary, App Group store,

reloadTimelines

invalidatableContent

references/configuration-and-intents.md

isDiscoverable = false

on helper intents

references/interactive-widgets.md

Button(intent:)

Toggle(intent:)

, 应用进程边界、App Group存储、

reloadTimelines

、

invalidatableContent

references/configuration-and-intents.md

- 辅助意图设置

isDiscoverable = false

"Add a Control Center control / Action button / Lock Screen control"

"添加控制中心控件 / 操作按钮 / 锁屏控件"

references/controls.md

ControlWidget

ControlWidgetToggle

(

SetValueIntent

) vs

ControlWidgetButton

(

AppIntent

), value providers,

ControlCenter.shared.reloadControls

```
references/interactive-widgets.md
```
- the same app-process / shared-store rules apply

references/controls.md

ControlWidget

、

ControlWidgetToggle

（

SetValueIntent

）与

ControlWidgetButton

（

AppIntent

）、值提供者、

ControlCenter.shared.reloadControls

```
references/interactive-widgets.md
```
- 同样适用应用进程/共享存储规则

"Build a Live Activity / Dynamic Island"

"构建Live Activity / 灵动岛"

references/live-activities.md

ActivityAttributes

ContentState

ActivityConfiguration

DynamicIsland

regions, request/update/end, staleness, push,

supplementalActivityFamilies

, the iOS-27 landscape Dynamic Island

references/interactive-widgets.md

LiveActivityIntent

buttons

references/live-activities.md

ActivityAttributes

ContentState

、

ActivityConfiguration

、

DynamicIsland

区域、请求/更新/结束、过期、推送、

supplementalActivityFamilies

、iOS 27横屏灵动岛

references/interactive-widgets.md

LiveActivityIntent

按钮

"Keep my widget fresh from the server"

"通过服务器保持组件内容新鲜"

```
references/timeline-provider.md
```
- reload policy, the reload budget, reload on app background
```
references/relevance-and-smart-stacks.md
```
- push-updated widgets (
```
WidgetPushHandler
```
, iOS 26), and when a Live Activity is the right tool instead

```
references/timeline-provider.md
```
- 重载策略、重载预算、应用后台时重载
```
references/relevance-and-smart-stacks.md
```
- 推送更新组件（
```
WidgetPushHandler
```
, iOS 26），以及何时适合使用Live Activity替代

"Make my widget show up in the Smart Stack at the right time"

"让我的组件在合适的时间出现在智能堆栈中"

references/relevance-and-smart-stacks.md

TimelineEntryRelevance

relevance()

WidgetRelevance

RelevanceConfiguration

(watchOS 26),

RelevantContext

references/relevance-and-smart-stacks.md

TimelineEntryRelevance

、

relevance()

WidgetRelevance

、

RelevanceConfiguration

（watchOS 26）、

RelevantContext

"Fetch data / load images / use a database or location in my widget"

"在组件中获取数据 / 加载图片 / 使用数据库或位置信息"

```
references/data-and-networking.md
```
- App Group snapshot,
```
async
```
fetch in the provider, image downsampling, SwiftData/Core Data,
```
NSWidgetUsesLocation
```
```
references/timeline-provider.md
```
- where fetching fits in the lifecycle and the budget

```
references/data-and-networking.md
```
- App Group快照、提供者中的
```
async
```
获取、图片降采样、SwiftData/Core Data、
```
NSWidgetUsesLocation
```
```
references/timeline-provider.md
```
- 数据获取在生命周期和预算中的位置

"Deep link / open my app from the widget"

"从组件深度链接 / 打开我的应用"

references/deep-linking-and-navigation.md

widgetURL

Link

, per-family rules,

onOpenURL

OpenIntent

references/deep-linking-and-navigation.md

widgetURL

与

Link

对比、按家族规则、

onOpenURL

、

OpenIntent

"Animate my widget / make values roll or transition"

"为组件添加动画 / 实现数值滚动或过渡"

references/animations-and-transitions.md

- entry diffing,

contentTransition(.numericText)

.transition

.id

invalidatableContent

, what doesn't animate

references/animations-and-transitions.md

- 条目差异、

contentTransition(.numericText)

、

.transition

.id

、

invalidatableContent

、不支持动画的内容

"Modernize an old widget / I'm seeing IntentConfiguration / ClockKit / PreviewProvider"

"现代化旧组件 / 我看到了IntentConfiguration / ClockKit / PreviewProvider"

references/migration-and-deprecations.md

- the old → new map,

CustomIntentMigratedAppIntent

, the ClockKit migrator, dual-path

#available

references/migration-and-deprecations.md

- 新旧映射、

CustomIntentMigratedAppIntent

、ClockKit迁移器、双路径

#available

"Design my widget well / make it gallery-ready"

"优化组件设计 / 使其符合组件库要求"

```
references/design-and-gallery.md
```
- glanceable/personal/relevant, sizes & tap styles, the don'ts, the snapshot, the placeholder

```
references/design-and-gallery.md
```
- 易读/个性化/相关性、尺寸与点击样式、禁忌、快照、占位符

"Support visionOS / CarPlay / macOS / Apple Watch"

"支持visionOS / CarPlay / macOS / Apple Watch"

references/platforms.md

- spatial widgets (

supportedMountingStyles

widgetTexture

levelOfDetail

), CarPlay, macOS menu bar, the availability map

references/platforms.md

- 空间组件（

supportedMountingStyles

、

widgetTexture

、

levelOfDetail

）、CarPlay、macOS菜单栏、可用性映射

"My widget won't update / shows stale data / never appears"

"我的组件无法更新 / 显示过期数据 / 始终不出现"

```
references/previews-and-testing.md
```
- the reload budget, WidgetKit developer mode, debugging
```
references/anti-patterns.md
```
- the usual causes

```
references/previews-and-testing.md
```
- 重载预算、WidgetKit开发者模式、调试
```
references/anti-patterns.md
```
- 常见原因

"I'm hitting build errors or rendering bugs"

"我遇到了构建错误或渲染bug"

```
references/anti-patterns.md
```
- catches with before/after fixes

```
references/anti-patterns.md
```
- 提供前后修复对比

Decision trees

决策树

Quick orientation when you know the task but not the right API.

当你知道任务但不确定正确API时的快速指南。

Which configuration should the widget use?

组件应使用哪种配置？

No user configuration, fixed behavior?
  -> StaticConfiguration(kind:provider:)

User picks parameters (account, city, repo)?
  -> AppIntentConfiguration(kind:intent:provider:) + WidgetConfigurationIntent   (iOS 17+)

Migrating an existing iOS 14-16 configurable widget?
  -> WidgetConfigurationIntent + CustomIntentMigratedAppIntent (keep intentClassName)
  -> or keep IntentConfiguration(kind:intent:provider:) with the legacy INIntent

Appears in the Smart Stack only when relevant (watchOS)?
  -> RelevanceConfiguration(kind:provider:)   (watchOS 26+)

无需用户配置，行为固定？
  -> StaticConfiguration(kind:provider:)

用户选择参数（账户、城市、仓库）？
  -> AppIntentConfiguration(kind:intent:provider:) + WidgetConfigurationIntent   (iOS 17+)

迁移现有iOS 14-16可配置组件？
  -> WidgetConfigurationIntent + CustomIntentMigratedAppIntent（保留intentClassName）
  -> 或继续使用IntentConfiguration(kind:intent:provider:)搭配旧版INIntent

仅在相关时出现在智能堆栈中（watchOS）？
  -> RelevanceConfiguration(kind:provider:)   (watchOS 26+)

Which timeline provider?

使用哪种时间线提供者？

StaticConfiguration?
  -> TimelineProvider           (placeholder / getSnapshot / getTimeline, completion-based)

AppIntentConfiguration?
  -> AppIntentTimelineProvider  (placeholder / snapshot(for:in:) / timeline(for:in:), async, intent FIRST)

RelevanceConfiguration (watchOS)?
  -> RelevanceEntriesProvider   (placeholder / relevance() / entry(configuration:context:), one entry per config)

StaticConfiguration？
  -> TimelineProvider           (placeholder / getSnapshot / getTimeline，基于完成回调)

AppIntentConfiguration？
  -> AppIntentTimelineProvider  (placeholder / snapshot(for:in:) / timeline(for:in:)，异步，意图为第一个参数)

RelevanceConfiguration（watchOS）？
  -> RelevanceEntriesProvider   (placeholder / relevance() / entry(configuration:context:)，每个配置对应一个条目)

Which reload policy?

使用哪种重载策略？

Next update time is known (countdown ends, event starts)?
  -> .after(date)

Entries cover a window and the next batch can be computed at the end?
  -> .atEnd

Content only changes from interaction / push, never on a schedule?
  -> .never   (then reload via WidgetCenter from an intent, app, or push)

已知下次更新时间（倒计时结束、活动开始）？
  -> .after(date)

条目覆盖一个时间段，且可在末尾计算下一批条目？
  -> .atEnd

内容仅因交互/推送变化，无需定时更新？
  -> .never   (随后通过WidgetCenter从意图、应用或推送触发重载)

Which interactive element?

使用哪种交互元素？

Inside a widget or Live Activity, runs an action?
  -> Button(intent:) with an AppIntent          (iOS 17+)

Inside a widget, binary on/off?
  -> Toggle(isOn:intent:) with an AppIntent      (iOS 17+)

Inside a Control Center control, binary on/off?
  -> ControlWidgetToggle(action:) with a SetValueIntent

Inside a Control Center control, runs an action / opens the app?
  -> ControlWidgetButton(action:) with an AppIntent (or OpenIntent to launch)

在组件或Live Activity内，执行操作？
  -> 搭配AppIntent的Button(intent:)          (iOS 17+)

在组件内，二进制开关？
  -> 搭配AppIntent的Toggle(isOn:intent:)      (iOS 17+)

在控制中心控件内，二进制开关？
  -> 搭配SetValueIntent的ControlWidgetToggle(action:)

在控制中心控件内，执行操作 / 打开应用？
  -> 搭配AppIntent（或OpenIntent启动应用）的ControlWidgetButton(action:)

Widget vs Live Activity vs Control?

组件 vs Live Activity vs 控件？

Glanceable data on a schedule, lives on Home/Lock Screen?
  -> Widget (timeline)

Ongoing, time-bound event the user wants to watch live (delivery, game, workout)?
  -> Live Activity (ActivityKit) - NOT a fast-reloading widget

A quick action or state toggle from Control Center / Lock Screen / Action button?
  -> Control (ControlWidget)

主屏幕/锁屏上的定时易读数据？
  -> 组件（时间线）

用户需要实时关注的正在进行的限时事件（配送、游戏、锻炼）？
  -> Live Activity（ActivityKit）- 不是高频重载的组件

从控制中心/锁屏/操作按钮快速执行操作或切换状态？
  -> 控件（ControlWidget）

Core Instructions

核心说明

A widget runs in a separate extension process, not your app. It is always SwiftUI, even in a UIKit app. The system archives your view and renders it later - your code is not running while the widget is on screen. Share data with the app only through an App Group container (shared
```
UserDefaults(suiteName:)
```
, a shared file, or a shared
```
ModelContainer
```
/Core Data store) - never
```
UserDefaults.standard
```
, never in-memory singletons.
Never make a widget interactive with a closure or
```
onTapGesture
```
. The only interactivity is
```
Button(intent:)
```
/
```
Toggle(intent:)
```
backed by an
```
AppIntent
```
(iOS 17+), plus
```
Link
```
/
```
widgetURL
```
for deep links. Anything else silently does nothing.
Always mark the widget's background with
```
.containerBackground(for: .widget) { ... }
```
(iOS 17+). Without it the widget is blank in the gallery, can't be removed/relocated cleanly, and the system can't substitute the material background in Lock Screen / StandBy / tinted contexts. The container type is
```
ContainerBackgroundPlacement
```
(value
```
.widget
```
) - there is no
```
WidgetBackgroundPlacement
```
.
Never do blocking or asynchronous work in
```
placeholder(in:)
```
- it must return synchronously with stand-in data. Do real fetching in
```
getSnapshot
```
/
```
getTimeline
```
(or the async
```
snapshot
```
/
```
timeline
```
). Use
```
.redacted(reason: .placeholder)
```
for the first-render stand-in.
```
getSnapshot
```
(and
```
snapshot(for:in:)
```
) is what the widget gallery shows - return realistic, populated sample data even when the user has none yet, never an empty/loading state.
Treat timeline reloads as a budgeted, opportunistic resource, not a timer. The system gives roughly 40-70 reloads/day per widget and learns from viewing habits. Never assume
```
.after(date)
```
fires exactly on time. Provide multiple entries to cover a window, pick the policy that matches your data (
```
.atEnd
```
/
```
.after
```
/
```
.never
```
), and trigger a final
```
WidgetCenter.shared.reloadAllTimelines()
```
when the app enters the background if data changed.
```
TimelineReloadPolicy
```
is a struct;
```
.after(_:)
```
takes a Date
, not a
```
TimeInterval
```
.
```
WidgetCenter.shared.reloadTimelines(ofKind:)
```
takes the widget's
```
kind
```
string - keep
```
kind
```
values as shared constants so the app and extension can't drift.
For a configurable widget, use
```
AppIntentConfiguration
```
+ a
```
WidgetConfigurationIntent
```
(iOS 17+) and an
```
AppIntentTimelineProvider
```
whose
```
snapshot
```
/
```
timeline
```
take the intent as the first argument.
```
WidgetConfigurationIntent
```
lives in the AppIntents module and needs no
```
perform()
```
. Provide sensible
```
@Parameter
```
defaults; never force the user to configure before the widget shows anything.
Never write a new configurable widget with the legacy SiriKit path -
```
IntentConfiguration
```
, an
```
INIntent
```
from a
```
.intentdefinition
```
file, or
```
IntentTimelineProvider
```
. Since iOS 17 the modern path is App Intents (
```
AppIntentConfiguration
```
+
```
WidgetConfigurationIntent
```
+
```
AppIntentTimelineProvider
```
). Only keep the legacy types behind
```
#available
```
when deploying below iOS 17, and when migrating an existing one conform the new intent to
```
CustomIntentMigratedAppIntent
```
with the original
```
intentClassName
```
so saved configurations survive. Likewise build watch complications with WidgetKit (+ a
```
CLKComplicationWidgetMigrator
```
), not ClockKit, and previews with
```
#Preview(as:)
```
, not
```
PreviewProvider
```
. See
```
references/migration-and-deprecations.md
```
.
Don't fetch data inside the widget view (no
```
AsyncImage
```
, no network at render time) - the view is an archived snapshot rendered later. Resolve data and downsample images during timeline generation and put them in the entry, prefer reading an App-Group snapshot the app wrote, and always complete the provider (fall back to last-good data on error). See
```
references/data-and-networking.md
```
.
Switch on
```
@Environment(\.widgetFamily)
```
and design each supported family deliberately. List only the families you actually lay out in
```
supportedFamilies
```
- shipping a family you didn't design looks broken. Accessory families (
```
accessoryCircular
```
/
```
accessoryRectangular
```
/
```
accessoryInline
```
) are iOS 16+;
```
accessoryCorner
```
is watchOS only.
Design for every rendering mode, not just full color. Read
```
@Environment(\.widgetRenderingMode)
```
(
```
.fullColor
```
/
```
.accented
```
/
```
.vibrant
```
); both
```
WidgetRenderingMode
```
and
```
WidgetAccentedRenderingMode
```
are structs with type properties, not enums. In
```
.accented
```
mode the system flattens your view into two tint groups by alpha - put foreground content in the accent group with
```
.widgetAccentable()
```
, and control how images flatten with
```
.widgetAccentedRenderingMode(.desaturated / .accented / .accentedDesaturated / .fullColor)
```
(the image modifier is iOS 18+).
For a multicolor image or icon that the accent group would crush into a flat silhouette: on iOS 18+ use
```
.widgetAccentedRenderingMode(.desaturated)
```
(the system maps luminance to alpha and recolors for you); on iOS 17 and below that modifier doesn't exist, so apply the manual
```
.luminanceToAlpha()
```
filter (bright pixels opaque, dark transparent) to preserve the shape's internal detail as a clean monochrome glyph - it also stays useful on iOS 18+ for hands-on control. Pair it with a soft gradient background and
```
.widgetAccentable()
```
. (See
```
references/rendering-modes-and-tinting.md
```
.)
For an accessory/Lock Screen widget or watch complication that should let the watch face or wallpaper show through, give it an empty
```
.containerBackground(for: .widget) { }
```
. Omitting
```
containerBackground
```
entirely makes the system add an opaque default material instead of a transparent one.
An interactive
```
AppIntent
```
runs in the app's process (the app is launched in the background if needed), not the widget extension - so it can write to the real data store. After it mutates data a widget displays, call
```
WidgetCenter.shared.reloadTimelines(ofKind:)
```
(or
```
reloadAllTimelines()
```
); for a control, call
```
ControlCenter.shared.reloadControls(ofKind:)
```
. Mark helper intents that only back a widget/control button with
```
static let isDiscoverable = false
```
so they don't pollute Shortcuts.
In the 27 releases (iOS 27): a widget button's write intent must run on
```
.main
```
(the widget extension has a read-only view of the shared store). Pin it with
```
static var allowedExecutionTargets: ExecutionTargets { .main }
```
, and pin display-only intents with
```
.widgetKitExtension
```
.
A Control (
```
ControlWidget
```
, iOS 18; macOS/watchOS 26) uses
```
ControlWidgetToggle
```
with a SetValueIntent
(its
```
value: Bool
```
is set by the system) or
```
ControlWidgetButton
```
with a plain
```
AppIntent
```
/
```
OpenIntent
```
. The status modifier is
```
controlWidgetStatus(_:)
```
- there is no
```
controlWidgetStatusText
```
. Provide a
```
previewValue
```
and an async
```
currentValue
```
in the value provider.
A Live Activity is the right tool for an ongoing, time-bound event - not a widget that reloads every few seconds. Split immutable data into
```
ActivityAttributes
```
and the only-updatable half into the nested
```
ContentState: Codable, Hashable
```
(keep it under 4 KB).
```
ActivityConfiguration
```
and
```
DynamicIsland
```
live in WidgetKit;
```
Activity.request/update/end
```
and tokens live in ActivityKit.
```
staleDate
```
/
```
relevanceScore
```
are set on
```
ActivityContent.init
```
, not the configuration.
Live Activities require
```
NSSupportsLiveActivities
```
=
```
YES
```
in the app's Info.plist; high-frequency push updates also need
```
NSSupportsLiveActivitiesFrequentUpdates
```
. Push-to-start uses
```
Activity.pushToStartToken
```
(iOS 17.2+) - it is not a
```
PushType
```
case. For mass-audience pushes use a broadcast
```
channel
```
; otherwise per-activity push tokens.
Never put a
```
symbolEffect
```
animation in a Live Activity or widget - they aren't supported and silently no-op. Widget/Live Activity views are static snapshots; only
```
Text(_:style:)
```
timers/dates and the system's transition between timeline entries animate.
```
widgetAccentedRenderingMode
```
is iOS 18+; Controls are iOS 18+ (macOS/watchOS 26+); push-updated widgets (
```
WidgetPushHandler
```
) and
```
RelevanceConfiguration
```
are iOS 26 / watchOS 26; spatial-widget modifiers (
```
supportedMountingStyles
```
,
```
widgetTexture
```
,
```
levelOfDetail
```
) are iOS/visionOS 26;
```
systemExtraLargePortrait
```
, the landscape Dynamic Island (
```
isDynamicIslandLimitedInWidth
```
), and
```
allowedExecutionTargets
```
are part of the 27 releases. Gate each behind the correct availability and call the WWDC 2026 cohort "the 27 releases", not "iOS 19".
Use the
```
#Preview(as:)
```
macro (iOS 17+) to iterate on widgets across families, color schemes, and rendering modes without running the host app; enable WidgetKit developer mode (Settings ▸ Developer) to lift the reload budget while iterating. The reload budget being exhausted - not a code bug - is the most common reason a widget "stops updating".

组件运行在独立的扩展进程中，而非你的应用进程。它始终基于SwiftUI，即使在UIKit应用中也是如此。系统会归档你的视图并在稍后渲染——组件显示时你的代码并未运行。仅通过App Group容器与应用共享数据（共享
```
UserDefaults(suiteName:)
```
、共享文件或共享
```
ModelContainer
```
/Core Data存储）——绝不能使用
```
UserDefaults.standard
```
或内存单例。
绝不能使用闭包或
```
onTapGesture
```
实现组件交互。唯一支持的交互方式是基于
```
AppIntent
```
的
```
Button(intent:)
```
/
```
Toggle(intent:)
```
（iOS 17+），以及用于深度链接的
```
Link
```
/
```
widgetURL
```
。其他方式会静默失效。
必须使用
```
.containerBackground(for: .widget) { ... }
```
（iOS 17+）标记组件背景。如果不设置，组件在组件库中会显示空白，无法正常删除/移动，且系统无法在锁屏/StandBy/着色场景下替换为材质背景。容器类型为
```
ContainerBackgroundPlacement
```
（值为
```
.widget
```
）——不存在
```
WidgetBackgroundPlacement
```
。
绝不能在
```
placeholder(in:)
```
中执行阻塞或异步操作——必须同步返回占位数据。在
```
getSnapshot
```
/
```
getTimeline
```
（或异步的
```
snapshot
```
/
```
timeline
```
）中执行真实的数据获取。使用
```
.redacted(reason: .placeholder)
```
作为首次渲染的占位符。
```
getSnapshot
```
（以及
```
snapshot(for:in:)
```
）是组件库展示的内容——即使用户尚未有数据，也需返回真实的填充样本数据，绝不能返回空/加载状态。
将时间线重载视为有预算、机会性的资源，而非定时器。系统每天为每个组件提供约40-70次重载机会，并会根据用户查看习惯学习调整。绝不能假设
```
.after(date)
```
会准时触发。提供多个条目覆盖一个时间段，选择与数据匹配的策略（
```
.atEnd
```
/
```
.after
```
/
```
.never
```
），如果数据发生变化，在应用进入后台时调用
```
WidgetCenter.shared.reloadAllTimelines()
```
。
```
TimelineReloadPolicy
```
是一个结构体；
```
.after(_:)
```
接收**
```
Date
```
**类型参数，而非
```
TimeInterval
```
。
```
WidgetCenter.shared.reloadTimelines(ofKind:)
```
接收组件的
```
kind
```
字符串——将
```
kind
```
值设为共享常量，避免应用和扩展出现不一致。
对于可配置组件，使用
```
AppIntentConfiguration
```
+
```
WidgetConfigurationIntent
```
（iOS 17+），以及
```
snapshot
```
/
```
timeline
```
将意图作为第一个参数的
```
AppIntentTimelineProvider
```
。
```
WidgetConfigurationIntent
```
属于AppIntents模块，无需实现
```
perform()
```
。为
```
@Parameter
```
提供合理的默认值；绝不能强制用户先配置再显示组件。
绝不能使用旧版SiriKit路径编写新的可配置组件——包括
```
IntentConfiguration
```
、来自
```
.intentdefinition
```
文件的
```
INIntent
```
或
```
IntentTimelineProvider
```
。自iOS 17起，现代方案是App Intents（
```
AppIntentConfiguration
```
+
```
WidgetConfigurationIntent
```
+
```
AppIntentTimelineProvider
```
）。仅在部署到iOS 17以下版本时，在
```
#available
```
保留旧版类型；迁移现有组件时，让新意图遵循
```
CustomIntentMigratedAppIntent
```
并保留原始
```
intentClassName
```
，确保已保存的配置不会丢失。同样，使用WidgetKit（搭配
```
CLKComplicationWidgetMigrator
```
）构建手表复杂功能，而非ClockKit；使用
```
#Preview(as:)
```
构建预览，而非
```
PreviewProvider
```
。详见
```
references/migration-and-deprecations.md
```
。
不要在组件视图内获取数据（不使用
```
AsyncImage
```
，渲染时不发起网络请求）——视图是归档的快照，会在稍后渲染。在时间线生成期间解析数据并对图片进行降采样，将其放入条目中；优先读取应用写入的App Group快照；提供者始终要完成执行（出错时回退到上次的有效数据）。详见
```
references/data-and-networking.md
```
。
根据
```
@Environment(\.widgetFamily)
```
进行分支，为每个支持的家族设计专属布局。在
```
supportedFamilies
```
中仅列出实际设计过的家族——发布未设计的家族会显示异常。附属组件家族（
```
accessoryCircular
```
/
```
accessoryRectangular
```
/
```
accessoryInline
```
）为iOS 16+；
```
accessoryCorner
```
仅适用于watchOS。
为所有渲染模式设计，而非仅全彩模式。读取
```
@Environment(\.widgetRenderingMode)
```
（
```
.fullColor
```
/
```
.accented
```
/
```
.vibrant
```
）；
```
WidgetRenderingMode
```
和
```
WidgetAccentedRenderingMode
```
都是带类型属性的结构体，而非枚举。在
```
.accented
```
模式下，系统会通过透明度将视图扁平化为两个着色组——使用
```
.widgetAccentable()
```
将前景内容放入着色组，并使用
```
.widgetAccentedRenderingMode(.desaturated / .accented / .accentedDesaturated / .fullColor)
```
控制图片的扁平化方式（该图片修饰符为iOS 18+）。
对于会被着色组压平为扁平轮廓的多色图片或图标：在iOS 18+上使用
.widgetAccentedRenderingMode(.desaturated)
（系统会将亮度映射为透明度并重新着色）；在iOS 17及以下版本中该修饰符不存在，因此手动应用
```
.luminanceToAlpha()
```
滤镜（亮像素不透明，暗像素透明），以保留形状的内部细节，使其成为清晰的单色符号——该方式在iOS 18+上也可用于手动控制。搭配柔和渐变背景和
```
.widgetAccentable()
```
使用。（详见
```
references/rendering-modes-and-tinting.md
```
。）
对于需要让表盘或壁纸透出来的附属/锁屏组件或手表复杂功能，设置空的
```
.containerBackground(for: .widget) { }
```
。完全省略
```
containerBackground
```
会让系统添加不透明的默认材质，而非透明背景。
交互式
```
AppIntent
```
运行在应用进程中（必要时应用会在后台启动），而非组件扩展进程——因此它可以写入真实的数据存储。在修改组件显示的数据后，调用
```
WidgetCenter.shared.reloadTimelines(ofKind:)
```
（或
```
reloadAllTimelines()
```
）；对于控件，调用
```
ControlCenter.shared.reloadControls(ofKind:)
```
。将仅支持组件/控件按钮的辅助意图标记为
```
static let isDiscoverable = false
```
，避免污染快捷指令。
在27版本（iOS 27）中：组件按钮的写入意图必须在
```
.main
```
运行（组件扩展对共享存储只有只读权限）。使用
```
static var allowedExecutionTargets: ExecutionTargets { .main }
```
指定，将仅用于显示的意图指定为
```
.widgetKitExtension
```
。
控件（
```
ControlWidget
```
，iOS 18；macOS/watchOS 26）使用搭配**
```
SetValueIntent
```
**的
```
ControlWidgetToggle
```
（其
```
value: Bool
```
由系统设置），或搭配普通
```
AppIntent
```
/
```
OpenIntent
```
的
```
ControlWidgetButton
```
。状态修饰符为
```
controlWidgetStatus(_:)
```
——不存在
```
controlWidgetStatusText
```
。在值提供者中提供
```
previewValue
```
和异步
```
currentValue
```
。
Live Activity适用于正在进行的限时事件——而非每隔几秒重载一次的组件。将不可变数据拆分为
```
ActivityAttributes
```
，将仅可更新的部分放入嵌套的
```
ContentState: Codable, Hashable
```
（保持大小在4KB以下）。
```
ActivityConfiguration
```
和
```
DynamicIsland
```
属于WidgetKit；
```
Activity.request/update/end
```
和令牌属于ActivityKit。
```
staleDate
```
/
```
relevanceScore
```
设置在
```
ActivityContent.init
```
中，而非配置中。
Live Activities需要在应用的Info.plist中设置
```
NSSupportsLiveActivities
```
=
```
YES
```
；高频推送更新还需要
```
NSSupportsLiveActivitiesFrequentUpdates
```
。推送启动使用
```
Activity.pushToStartToken
```
（iOS 17.2+）——它不是
```
PushType
```
的枚举值。面向大量受众的推送使用广播
```
channel
```
；否则使用每个活动的推送令牌。
绝不能在Live Activity或组件中添加
```
symbolEffect
```
动画——它们不受支持，会静默失效。组件/Live Activity视图是静态快照；只有
```
Text(_:style:)
```
计时器/日期和系统在时间线条目间的过渡会动画。
```
widgetAccentedRenderingMode
```
为iOS 18+；控件为iOS 18+（macOS/watchOS 26+）；推送更新组件（
```
WidgetPushHandler
```
）和
```
RelevanceConfiguration
```
为iOS 26 / watchOS 26；空间组件修饰符（
```
supportedMountingStyles
```
、
```
widgetTexture
```
、
```
levelOfDetail
```
）为iOS/visionOS 26；
```
systemExtraLargePortrait
```
、横屏灵动岛（
```
isDynamicIslandLimitedInWidth
```
）和
```
allowedExecutionTargets
```
属于27版本。为每个功能添加正确的可用性判断，并将WWDC 2026系列版本称为**"27版本"**，而非"iOS 19"。
使用
```
#Preview(as:)
```
宏（iOS 17+）在不运行宿主应用的情况下，跨组件家族、配色方案和渲染模式迭代开发；启用WidgetKit开发者模式（设置 ▸ 开发者）以在迭代时解除重载预算限制。重载预算耗尽——而非代码bug——是组件"停止更新"的最常见原因。

Output Format

输出格式

If the user asks for a review, organize findings by file. For each issue:

State the file and relevant line(s).
Name the anti-pattern being replaced.
Show a brief before/after code fix.

Skip files with no issues. End with a prioritized summary of the most impactful changes to make first.

If the user asks you to write or fix widget code, make the changes directly instead of returning a findings report.

Example output:

如果用户要求审查，按文件整理发现的问题。每个问题包含：

说明文件及相关行号。
指出要替换的反模式。
展示简短的修复前后代码对比。

跳过无问题的文件。最后给出优先级排序的摘要，列出最需优先修改的关键变更。

如果用户要求编写或修复组件代码，直接修改代码，而非返回问题报告。

示例输出：

CaffeineWidget.swift

Line 14:
placeholder(in:)
does a synchronous disk fetch - placeholders must return instantly.

swift

// Before
func placeholder(in context: Context) -> Entry {
    Entry(date: .now, drinks: Store.shared.loadAllDrinks())   // blocks the render
}

// After
func placeholder(in context: Context) -> Entry {
    Entry(date: .now, drinks: .sample)   // synchronous stand-in; real data in getTimeline
}

Line 41: interactive
onTapGesture
in a widget does nothing - use an App Intent.

swift

// Before
Image(systemName: "plus.circle").onTapGesture { addDrink() }

// After
Button(intent: AddDrinkIntent()) { Image(systemName: "plus.circle") }
// AddDrinkIntent.perform() writes to the App Group store, then:
// WidgetCenter.shared.reloadTimelines(ofKind: "CaffeineWidget")

第14行：
placeholder(in:)
执行同步磁盘读取——占位符必须立即返回。

swift

// 修复前
func placeholder(in context: Context) -> Entry {
    Entry(date: .now, drinks: Store.shared.loadAllDrinks())   // 阻塞渲染
}

// 修复后
func placeholder(in context: Context) -> Entry {
    Entry(date: .now, drinks: .sample)   // 同步占位数据；真实数据在getTimeline中获取
}

第41行：组件中的交互式
onTapGesture
无效——使用App Intent。

swift

// 修复前
Image(systemName: "plus.circle").onTapGesture { addDrink() }

// 修复后
Button(intent: AddDrinkIntent()) { Image(systemName: "plus.circle") }
// AddDrinkIntent.perform()写入App Group存储，然后调用：
// WidgetCenter.shared.reloadTimelines(ofKind: "CaffeineWidget")

Summary

摘要

Placeholder (high): must be synchronous; move fetching to the timeline.
Interactivity (high): gestures don't work in widgets; back the tap with an
```
AppIntent
```
.

End of example.

占位符（高优先级）： 必须同步；将数据获取移至时间线。
交互性（高优先级）： 手势在组件中无效；使用
```
AppIntent
```
支持点击操作。

示例结束。

References

参考文件

```
references/fundamentals.md
```
- the widget execution model: the extension process, app groups,
```
WidgetBundle
```
, the
```
Widget
```
protocol, the timeline lifecycle,
```
containerBackground
```
, content margins, deep linking,
```
kind
```
, and the "which surface" map.

references/timeline-provider.md

TimelineProvider

AppIntentTimelineProvider

TimelineEntry

Timeline

, reload policies, the reload budget,

WidgetCenter

reloads, reload-on-background,

TimelineEntryRelevance

references/configuration-and-intents.md

StaticConfiguration

AppIntentConfiguration

WidgetConfigurationIntent

, dynamic options / entity parameters,

recommendations()

, defaults.

references/migration-and-deprecations.md

- the old → new map: SiriKit

.intentdefinition

IntentConfiguration

→ App Intents,

IntentTimelineProvider

→

AppIntentTimelineProvider

, ClockKit → WidgetKit,

PreviewProvider

→

#Preview

, what's deprecated vs legacy-but-supported,

CustomIntentMigratedAppIntent

```
references/data-and-networking.md
```
- loading data for timelines: App Group snapshots,
```
async
```
/background
```
URLSession
```
fetches, image downsampling, SwiftData/Core Data in widgets, location, Lock Screen privacy.

references/families-and-layout.md

WidgetFamily

cases, sizing,

supportedFamilies

, content margins, the per-family switch,

ViewThatFits

ContainerRelativeShape

```
references/lock-screen-and-watch.md
```
- accessory families, watch complications,
```
widgetLabel
```
,
```
AccessoryWidgetBackground
```
, gauges, the transparent
```
containerBackground
```
trick, ClockKit → WidgetKit migration.

references/rendering-modes-and-tinting.md

widgetRenderingMode

(

.fullColor

.accented

.vibrant

widgetAccentable

widgetAccentedRenderingMode

, the luminance-to-alpha trick, designing for the tinted/clear Home Screen and accent groups.

references/interactive-widgets.md

Button(intent:)

Toggle(intent:)

, the app-process boundary,

@Parameter

persistence, the App Group store,

reloadTimelines

, the optimistic

ToggleStyle

invalidatableContent

isDiscoverable

allowedExecutionTargets

(the 27 releases).

```
references/deep-linking-and-navigation.md
```
-
```
widgetURL
```
vs
```
Link
```
, per-family tap rules, URL-scheme design, handling on the app side (
```
onOpenURL
```
/ scene delegate), Live Activity
```
widgetURL
```
/
```
keylineTint
```
, control
```
OpenIntent
```
.
```
references/animations-and-transitions.md
```
- the entry-diffing animation model,
```
contentTransition(.numericText)
```
,
```
.transition
```
+
```
.id
```
identity, the optimistic
```
Toggle
```
,
```
invalidatableContent
```
, Live Activity transitions, what does not animate (
```
symbolEffect
```
, loops, video).

references/controls.md

ControlWidget

StaticControlConfiguration

AppIntentControlConfiguration

ControlWidgetToggle

(

SetValueIntent

) vs

ControlWidgetButton

(

AppIntent

OpenIntent

), value providers,

ControlCenter

reloads, status/action-hint modifiers, platforms.

references/live-activities.md

ActivityAttributes

ContentState

ActivityConfiguration

DynamicIsland

Activity.request/update/end

ActivityContent

staleness, push (token / channel / push-to-start),

supplementalActivityFamilies

activityFamily

, the landscape Dynamic Island, StandBy,

LiveActivityIntent

, entitlements.

references/relevance-and-smart-stacks.md

TimelineEntryRelevance

relevance()

WidgetRelevance

WidgetRelevanceAttribute

RelevantContext

RelevanceConfiguration

RelevanceEntriesProvider

(watchOS 26), push-updated widgets (

WidgetPushHandler

, iOS 26), Smart Stack behavior.

```
references/design-and-gallery.md
```
- the design rules (glanceable/relevant/personal, not a mini-app), sizes & tap styles, layout margins & type, the explicit don'ts, the gallery (
```
configurationDisplayName
```
/
```
description
```
/snapshot), the placeholder, personalization, Smart Stack etiquette.
```
references/previews-and-testing.md
```
- the
```
#Preview(as:)
```
macro variants,
```
WidgetPreviewContext
```
, testing rendering modes/families, WidgetKit developer mode, the reload budget, debugging "won't update".
```
references/platforms.md
```
- visionOS spatial widgets (
```
supportedMountingStyles
```
,
```
widgetTexture
```
,
```
levelOfDetail
```
,
```
systemExtraLargePortrait
```
), CarPlay widgets and Live Activities, macOS menu bar, watchOS, the cross-platform availability map.
```
references/worked-example.md
```
- one widget built end to end (a
```
systemMedium
```
Quick Actions widget): entry + provider, multi-
```
Link
```
layout, full-color-vs-tinted handling, an entry-driven
```
MeshGradient
```
animation,
```
contentMarginsDisabled
```
, and the preview - with pointers to the deeper reference for each step.
```
references/anti-patterns.md
```
- the consolidated smell → fix checklist, including the API-name confusions LLMs make (struct vs enum rendering modes,
```
ContainerBackgroundPlacement
```
,
```
pushToStartToken
```
,
```
controlWidgetStatus
```
).

```
references/fundamentals.md
```
- 组件执行模型：扩展进程、应用组、
```
WidgetBundle
```
、
```
Widget
```
协议、时间线生命周期、
```
containerBackground
```
、内容边距、深度链接、
```
kind
```
、界面场景映射。

references/timeline-provider.md

TimelineProvider

AppIntentTimelineProvider

、

TimelineEntry

、

Timeline

、重载策略、重载预算、

WidgetCenter

重载、后台重载、

TimelineEntryRelevance

。

references/configuration-and-intents.md

StaticConfiguration

、

AppIntentConfiguration

、

WidgetConfigurationIntent

、动态选项 / 实体参数、

recommendations()

、默认值。

references/migration-and-deprecations.md

- 新旧映射：SiriKit

.intentdefinition

IntentConfiguration

→ App Intents、

IntentTimelineProvider

→

AppIntentTimelineProvider

、ClockKit → WidgetKit、

PreviewProvider

→

#Preview

、已废弃与仍支持的旧版API、

CustomIntentMigratedAppIntent

。

```
references/data-and-networking.md
```
- 时间线数据加载：App Group快照、
```
async
```
/后台
```
URLSession
```
请求、图片降采样、组件中的SwiftData/Core Data、位置信息、锁屏隐私。

references/families-and-layout.md

WidgetFamily

枚举值、尺寸、

supportedFamilies

、内容边距、按家族分支、

ViewThatFits

、

ContainerRelativeShape

。

```
references/lock-screen-and-watch.md
```
- 附属组件家族、手表复杂功能、
```
widgetLabel
```
、
```
AccessoryWidgetBackground
```
、仪表盘、透明容器技巧、ClockKit → WidgetKit迁移。

references/rendering-modes-and-tinting.md

widgetRenderingMode

（

.fullColor

.accented

.vibrant

）、

widgetAccentable

、

widgetAccentedRenderingMode

、亮度转透明度技巧、为着色/透明主屏幕和着色组设计。

references/interactive-widgets.md

Button(intent:)

Toggle(intent:)

、应用进程边界、

@Parameter

持久化、App Group存储、

reloadTimelines

、乐观

ToggleStyle

、

invalidatableContent

、

isDiscoverable

、

allowedExecutionTargets

（27版本）。

```
references/deep-linking-and-navigation.md
```
-
```
widgetURL
```
vs
```
Link
```
、按家族点击规则、URL scheme设计、应用端处理（
```
onOpenURL
```
/ 场景代理）、Live Activity
```
widgetURL
```
/
```
keylineTint
```
、控件
```
OpenIntent
```
。
```
references/animations-and-transitions.md
```
- 条目差异动画模型、
```
contentTransition(.numericText)
```
、
```
.transition
```
+
```
.id
```
标识、乐观
```
Toggle
```
、
```
invalidatableContent
```
、Live Activity过渡、不支持动画的内容（
```
symbolEffect
```
、循环、视频）。

references/controls.md

ControlWidget

、

StaticControlConfiguration

AppIntentControlConfiguration

、

ControlWidgetToggle

（

SetValueIntent

） vs

ControlWidgetButton

（

AppIntent

OpenIntent

）、值提供者、

ControlCenter

重载、状态/操作提示修饰符、平台支持。

references/live-activities.md

ActivityAttributes

ContentState

、

ActivityConfiguration

、

DynamicIsland

、

Activity.request/update/end

、

ActivityContent

过期、推送（令牌 / 频道 / 推送启动）、

supplementalActivityFamilies

activityFamily

、横屏灵动岛、StandBy、

LiveActivityIntent

、权限。

references/relevance-and-smart-stacks.md

TimelineEntryRelevance

、

relevance()

WidgetRelevance

WidgetRelevanceAttribute

RelevantContext

、

RelevanceConfiguration

RelevanceEntriesProvider

（watchOS 26）、推送更新组件（

WidgetPushHandler

, iOS 26）、智能堆栈行为。

```
references/design-and-gallery.md
```
- 设计规则（易读/相关/个性化，不是迷你应用）、尺寸与点击样式、布局边距与字体、明确的禁忌、组件库（
```
configurationDisplayName
```
/
```
description
```
/快照）、占位符、个性化、智能堆栈规范。
```
references/previews-and-testing.md
```
-
```
#Preview(as:)
```
宏变体、
```
WidgetPreviewContext
```
、测试渲染模式/家族、WidgetKit开发者模式、重载预算、调试"无法更新"问题。
```
references/platforms.md
```
- visionOS空间组件（
```
supportedMountingStyles
```
、
```
widgetTexture
```
、
```
levelOfDetail
```
、
```
systemExtraLargePortrait
```
）、CarPlay组件和Live Activities、macOS菜单栏、watchOS、跨平台可用性映射。
```
references/worked-example.md
```
- 端到端构建一个组件（
```
systemMedium
```
快速操作组件）：条目 + 提供者、多
```
Link
```
布局、全彩与着色模式处理、条目驱动的
```
MeshGradient
```
动画、
```
contentMarginsDisabled
```
、预览——每个步骤都指向更深入的参考文件。
```
references/anti-patterns.md
```
- 整合的问题→修复清单，包括LLMs常犯的API名称混淆（结构体vs枚举渲染模式、
```
ContainerBackgroundPlacement
```
、
```
pushToStartToken
```
、
```
controlWidgetStatus
```
）。",