visionos-widgetkit-developer

visionOS WidgetKit 开发者

快速入门

首先将 visionOS 小组件视为空间对象，而不是小型 2D 表面。

1. 先确定平台和尺寸系列范围。
2. 在润色视觉效果之前，先定义近距离和远距离布局。
3. 将时间线条目、共享存储和 App Intents 视为集成边界；不要依赖宿主应用的实时状态。
4. 仅加载与当前问题匹配的参考文件。

在以下情况下加载参考资料

参考资料	使用时机
widget-overview.md	查看 Vision Pro 小组件的概览、决策要点和快速检查清单时。
families-and-platforms.md	选择原生 visionOS 尺寸系列、兼容的 iOS 尺寸系列或特大号小组件支持时。
mounting-styles.md	决定采用凸起式还是凹入式支撑，以及避免布局错乱时。
visionos-rendering-styles.md	查看官方 visionOS 小组件渲染模式、背景、尺寸系列、纹理，以及如何转到共享按钮形状规范时。
textures-and-rendering.md	选择玻璃或纸张效果，并确保在不同渲染模式下内容清晰易读时。
proximity-levelofdetail.md	使用 LevelOfDetail 实现近距离和远距离布局时。
interactive-widgets.md	为小组件添加由 Button、Toggle 或 AppIntent 驱动的交互时。
debugging-and-updates.md	小组件未刷新、未显示，或显示陈旧或异常时。
widget-animation.md	使用时间线条目和 Canvas 淡入淡出为小组件内容添加动画、调整帧率，或遇到套件或计算预算限制时。

工作流

1. 确认小组件的平台和尺寸系列组合。
2. 选择安装样式、纹理和近距离／远距离布局策略。
3. 决定数据路径：仅使用时间线、App Group／共享存储、后台 URL 会话或 WidgetKit 推送通知。
4. 仅在小组件仍能一目了然时添加交互。
5. 确定结构后，验证时间线、重新加载、渲染模式和扩展日志。

注意事项

• 始终考虑使用 .simplified 提升远距离可读性。
• 有针对性地使用原生 visionOS 尺寸系列；原生 visionOS 特大号小组件使用 .systemExtraLargePortrait，而兼容的 iOS／iPadOS 小组件继续使用 .systemExtraLarge。
• 不要假设凹入模式无需明确检查布局即可正常工作。
• 避免使用信息密集、对比度低的布局。
• 使用 Link 或 widgetURL(_:) 实现打开应用的导航；仅将 Button 和 Toggle 用于真正的 AppIntent 操作。
• 将每个 WidgetBundle 中的小组件配置数量控制在实用上限内。

输出要求

请提供：

• 小组件的平台和尺寸系列范围
• 使用了哪些参考资料
• 选择的呈现策略
• 主要的渲染、交互或时间线限制
• 下一步验证工作