widgets

编写和审查 SwiftUI WidgetKit 代码，选择合适的配置、时间线策略和显示界面，确保小组件在各种模式下都能正确渲染、在预算范围内更新，并能正确处理扩展与应用进程之间的边界。

审查流程：

1. 使用 references/fundamentals.md 了解小组件的执行模型（扩展进程、应用组、时间线生命周期、重新加载预算）。
2. 根据 references/timeline-provider.md 检查时间线提供程序（placeholder/snapshot/timeline、重新加载策略、WidgetCenter 重新加载、条目相关性）。
3. 根据 references/configuration-and-intents.md 检查配置及所有用户可配置参数（StaticConfiguration、AppIntentConfiguration、WidgetConfigurationIntent）。
4. 根据 references/migration-and-deprecations.md 检查是否使用了旧版 API，并将其迁移到现代等效方案（SiriKit .intentdefinition → App Intents、ClockKit → WidgetKit、PreviewProvider → #Preview）。
5. 根据 references/data-and-networking.md 检查提供程序和意图中的数据加载——网络、持久化、图像、位置。
6. 根据 references/families-and-layout.md 检查对各个尺寸的支持和布局（WidgetFamily、尺寸、内容边距、ViewThatFits）。
7. 根据 references/lock-screen-and-watch.md 检查锁定屏幕／配件小组件和 Apple Watch 表盘复杂功能（widgetLabel、AccessoryWidgetBackground、透明容器技巧、ClockKit 迁移）。
8. 根据 references/rendering-modes-and-tinting.md 检查全彩、强调色、着色和鲜艳模式下的渲染（widgetRenderingMode、widgetAccentable、widgetAccentedRenderingMode、亮度转 Alpha 技巧）。
9. 根据 references/interactive-widgets.md 检查交互功能（Button(intent:)、Toggle(intent:)、应用进程边界、reloadTimelines、invalidatableContent）。
10. 根据 references/deep-linking-and-navigation.md 检查深度链接和应用内导航（widgetURL、Link、onOpenURL、OpenIntent）。
11. 根据 references/animations-and-transitions.md 检查动画和条目过渡（contentTransition、.transition + 标识、invalidatableContent、无法执行动画的内容）。
12. 根据 references/controls.md 检查控制中心控件（ControlWidget、切换控件与按钮、SetValueIntent、值提供程序、ControlCenter 重新加载）。
13. 根据 references/live-activities.md 检查实时活动和灵动岛（ActivityAttributes、ActivityConfiguration、DynamicIsland、请求／更新／结束、推送、supplementalActivityFamilies）。
14. 根据 references/relevance-and-smart-stacks.md 检查智能叠放相关性（TimelineEntryRelevance、relevance() / WidgetRelevance、RelevanceConfiguration、基于推送的相关性）。
15. 根据 references/design-and-gallery.md 检查设计和图库展示（一目了然、尺寸、注意事项、configurationDisplayName/description、占位内容）。
16. 根据 references/previews-and-testing.md 检查预览和测试／调试工作流（#Preview(as:)、WidgetKit 开发者模式、重新加载预算）。
17. 根据 references/platforms.md 检查特定平台的显示界面（visionOS 空间小组件、CarPlay、macOS 菜单栏、可用性对照表）。
18. 使用 references/anti-patterns.md 排查常见错误。

如果只处理部分内容，仅加载相关参考文件。

按任务路由

根据用户目标匹配阅读顺序。只加载所需内容。

“创建我的第一个小组件” / “向我展示一个完整的小组件”

1. references/fundamentals.md - 扩展、小组件包、时间线生命周期
2. references/worked-example.md - 从头到尾构建一个小组件（入口 → 提供器 → 布局 → 链接 → 着色 → 动画 → 预览）
3. references/timeline-provider.md - TimelineProvider、条目、重新加载策略
4. references/families-and-layout.md - 选择类型、按类型设置布局
5. references/previews-and-testing.md - 使用 #Preview(as:) 进行迭代

“让用户配置我的小组件”

1. references/configuration-and-intents.md - AppIntentConfiguration + WidgetConfigurationIntent、动态选项、默认值
2. references/timeline-provider.md - AppIntentTimelineProvider（intent 是第一个参数）

“添加锁屏小组件 / 手表复杂功能”

1. references/lock-screen-and-watch.md - 配件类型、widgetLabel、AccessoryWidgetBackground、仪表、ClockKit 迁移
2. references/rendering-modes-and-tinting.md - 配件小组件始终以着色模式渲染

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

1. references/rendering-modes-and-tinting.md - widgetRenderingMode、widgetAccentable、widgetAccentedRenderingMode、亮度转 Alpha 技巧、针对强调组进行设计
2. references/lock-screen-and-watch.md - 配件小组件使用透明的 containerBackground

“在我的小组件中添加按钮 / 开关”

1. references/interactive-widgets.md - Button(intent:) / Toggle(intent:)、应用进程边界、App Group 存储、reloadTimelines、invalidatableContent
2. references/configuration-and-intents.md - 在辅助 intent 上设置 isDiscoverable = false

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

1. references/controls.md - ControlWidget、ControlWidgetToggle（SetValueIntent）与 ControlWidgetButton（AppIntent）、值提供器、ControlCenter.shared.reloadControls
2. references/interactive-widgets.md - 同样适用应用进程 / 共享存储规则

“构建实时活动 / 灵动岛”

1. references/live-activities.md - ActivityAttributes / ContentState、ActivityConfiguration、DynamicIsland 区域、请求 / 更新 / 结束、过期状态、推送、supplementalActivityFamilies、iOS 27 横向灵动岛
2. references/interactive-widgets.md - LiveActivityIntent 按钮

“让我的小组件通过服务器保持最新”

1. references/timeline-provider.md - 重新加载策略、重新加载预算、应用进入后台时重新加载
2. references/relevance-and-smart-stacks.md - 推送更新的小组件（WidgetPushHandler、iOS 26），以及何时应改用实时活动

“让我的小组件在合适的时间显示在智能叠放中”

1. references/relevance-and-smart-stacks.md - TimelineEntryRelevance、relevance() + WidgetRelevance、RelevanceConfiguration（watchOS 26）、RelevantContext

“在小组件中获取数据 / 加载图像 / 使用数据库或位置信息”

1. references/data-and-networking.md - App Group 快照、在提供器中执行 async 获取、图像降采样、SwiftData/Core Data、NSWidgetUsesLocation
2. references/timeline-provider.md - 获取数据在生命周期中的位置以及预算

“从小组件深度链接 / 打开我的应用”

1. references/deep-linking-and-navigation.md - widgetURL 与 Link、按类型设置规则、onOpenURL、OpenIntent

“为我的小组件添加动画 / 让数值滚动或过渡”

1. references/animations-and-transitions.md - 条目差异比较、contentTransition(.numericText)、.transition + .id、invalidatableContent、无法添加动画的内容

“让旧小组件现代化 / 我看到了 IntentConfiguration / ClockKit / PreviewProvider”

1. references/migration-and-deprecations.md - 旧版 → 新版对照、CustomIntentMigratedAppIntent、ClockKit 迁移器、双路径 #available

“设计好我的小组件 / 让它达到画廊展示标准”

1. references/design-and-gallery.md - 一目了然、个性化且相关；尺寸和点按样式、注意事项、快照、占位符

“支持 visionOS / CarPlay / macOS / Apple Watch”

1. references/platforms.md - 空间小组件（supportedMountingStyles、widgetTexture、levelOfDetail）、CarPlay、macOS 菜单栏、可用性对照表

“我的小组件无法更新 / 显示过期数据 / 从不出现”

1. references/previews-and-testing.md - 刷新预算、WidgetKit 开发者模式、调试
2. references/anti-patterns.md - 常见原因

“我遇到了构建错误或渲染问题”

1. references/anti-patterns.md - 提供修复前后的示例

决策树

当你知道要完成什么任务，但不确定该使用哪个 API 时，可快速查看。

小组件应使用哪种配置？

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?
  -> 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)

应使用哪种刷新策略？

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)

应使用哪种交互元素？

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)

小组件、实时活动还是控制项？

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)

核心说明

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

输出格式

如果用户要求进行审查，请按文件整理问题。对于每个问题：

1. 指明文件和相关行号。
2. 指出要替换的反模式。
3. 展示简短的修复前后代码。

跳过没有问题的文件。最后按优先级总结最值得优先处理的改动。

如果用户要求编写或修复 widget 代码，请直接修改，而不是返回问题报告。

输出示例：

CaffeineWidget.swift

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

// 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
}

第 41 行：widget 中的交互式 onTapGesture 不起作用——请改用 App Intent。

// 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")

总结

1. 占位内容（高优先级）： 必须同步生成；请将数据获取移至时间线中。
2. 交互（高优先级）： 手势在 widget 中不起作用；请使用 AppIntent 处理点击。

示例结束。

参考资料

• references/fundamentals.md - Widget 的执行模型：扩展进程、应用组、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 请求、图像降采样、Widget 中的 SwiftData／Core Data、位置、锁定屏幕隐私。
• references/families-and-layout.md - WidgetFamily 的各个枚举值、尺寸、supportedFamilies、内容边距、按类型切换、ViewThatFits、ContainerRelativeShape。
• references/lock-screen-and-watch.md - 配件类型、手表复杂功能、widgetLabel、AccessoryWidgetBackground、仪表、透明 containerBackground 技巧、从 ClockKit 迁移到 WidgetKit。
• references/rendering-modes-and-tinting.md - widgetRenderingMode（.fullColor／.accented／.vibrant）、widgetAccentable、widgetAccentedRenderingMode、亮度转 Alpha 技巧，为着色／透明主屏幕和强调色组进行设计。
• references/interactive-widgets.md - Button(intent:)／Toggle(intent:)、应用进程边界、@Parameter 持久化、App Group 存储、reloadTimelines、乐观式 ToggleStyle、invalidatableContent、isDiscoverable、allowedExecutionTargets（27 个版本）。
• references/deep-linking-and-navigation.md - widgetURL 与 Link、各类型的点按规则、URL 方案设计、应用端处理方式（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）与 ControlWidgetButton（AppIntent／OpenIntent）、值提供器、ControlCenter 重新加载、状态／操作提示修饰符、平台。
• references/live-activities.md - ActivityAttributes／ContentState、ActivityConfiguration、DynamicIsland、Activity.request/update/end、ActivityContent 过期状态、推送（令牌／通道／推送启动）、supplementalActivityFamilies／activityFamily、横向 Dynamic Island、待机模式、LiveActivityIntent、授权。
• references/relevance-and-smart-stacks.md - TimelineEntryRelevance、relevance() + WidgetRelevance／WidgetRelevanceAttribute／RelevantContext、RelevanceConfiguration + RelevanceEntriesProvider（watchOS 26）、推送更新的 Widget（WidgetPushHandler，iOS 26）、Smart Stack 行为。
• references/design-and-gallery.md - 设计规则（便于一览、相关、个性化，而非迷你应用）、尺寸与点按样式、布局边距与字体、明确的禁忌、图库（configurationDisplayName／description／快照）、占位内容、个性化、Smart Stack 使用规范。
• references/previews-and-testing.md - #Preview(as:) 宏的各种形式、WidgetPreviewContext、测试渲染模式／类型、WidgetKit 开发者模式、重新加载预算、调试“无法更新”问题。
• references/platforms.md - visionOS 空间 Widget（supportedMountingStyles、widgetTexture、levelOfDetail、systemExtraLargePortrait）、CarPlay Widget 和 Live Activity、macOS 菜单栏、watchOS、跨平台可用性映射。
• references/worked-example.md - 从头到尾构建一个 Widget（systemMedium 快捷操作 Widget）：条目与提供器、多 Link 布局、全彩与着色模式处理、由条目驱动的 MeshGradient 动画、contentMarginsDisabled，以及预览；每个步骤均附有更深入的参考文档链接。
• references/anti-patterns.md - 汇总的常见问题 → 修复检查清单，包括 LLM 常混淆的 API 名称（渲染模式的结构体与枚举、ContainerBackgroundPlacement、pushToStartToken、controlWidgetStatus）。