指南
如何在 Capacitor 中使用实时活动
使用 @capgo/capacitor-live-activities
Capacitor 实时活动插件界面，用于管理 iOS 实时活动
安装
bun add @capgo/capacitor-live-activities
bunx cap sync
iOS 配置
安装和同步插件不会创建本机实时活动 UI。 在调用之前，请在 Xcode 中配置 ActivityKit： startActivity查看在 __CAPGO_KEEP_0__ 上
- Run
bunx cap open ios. - 添加 实时活动小部件 目标并启用 包含Live Activity.
- 设置应用程序和Widget Extension部署目标到iOS 16.1或更高版本
- 确保扩展嵌入在主应用程序中
- 保持一个
ActivityConfiguration已注册在扩展的WidgetBundle,包括锁屏和所有动态岛的呈现 - 添加
NSSupportsLiveActivities到主应用程序目标的Info.plist.
<key>NSSupportsLiveActivities</key>
<true/>
添加目标本身不足。原生应用或插件必须调用ActivityKit的request、update和end API。Widget扩展必须包含SwiftUIcode，可以解码和渲染相同的 ActivityAttributes 和内容状态由这些调用使用。将共享的ActivityKit模型包含在主应用和Widget扩展目标中。Xcode生成的Live Activity模板不会自动渲染传递给此插件的JSON布局；扩展还需要兼容的原生布局渲染器。
共享图片
使用图像管理方法时，添加 应用组 将应用组的相同标识符添加到主应用和Widget扩展目标中，使用插件期望的exact标识符。
group.<MAIN_APP_BUNDLE_ID>.liveactivities
Live Activity扩展无法访问网络。下载远程图片在主应用中，保存到共享的应用组中， saveImage然后从布局中引用保存的图片。捆绑资产也必须属于Widget扩展目标。
深度链接和推送更新
- 注册任何自定义URL方案由
behavior.widgetUrl或tapUrl在Capacitor Live Activities中，Live Update、Cloudflare、Capacitor、GitHub、Capgo、code、API、SDK、CLI、npm、bun等关键词保持不变。 Info > URL 类型 设置。 - 对于服务器驱动的更新，添加 推送通知 能力，并实现 ActivityKit 推送令牌处理与 APNs。
- 添加
NSSupportsLiveActivitiesFrequentUpdates仅当应用程序需要频繁的 ActivityKit 推送更新时才添加。
仅使推送通知能力开启是不够的；服务器驱动的更新需要原生令牌处理和 APNs 后端。
ActivityKit 将静态和动态 Live 活动数据的总和限制为 4 KB。动态岛屿仅在支持的设备模型上可见；其他设备使用锁屏显示。
此插件暴露的内容
areActivitiesSupported- 检查此设备是否支持 Live 活动。需要 iOS 16.1+ 和设备支持。startActivity- 使用指定的布局和数据启动一个新的 Live 活动。updateActivity- 使用最新数据更新现有的 Live 活动。endActivity- 结束一个 Live 活动。
- 示例使用
areActivitiesSupported
- 检查是否在此设备上支持 Live 活动。需要 iOS 16.1+ 和设备支持。
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const { supported, reason } = await CapgoLiveActivities.areActivitiesSupported();
if (supported) {
console.log('Live Activities are supported!');
} else {
console.log('Not supported:', reason);
}
startActivity
- 使用指定的布局和数据启动一个新的 Live 活动。
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
const { activityId } = await CapgoLiveActivities.startActivity({
layout: {
type: 'container',
direction: 'horizontal',
children: [
{ type: 'text', content: 'Order #{{orderNumber}}', fontSize: 16, fontWeight: 'bold' },
{ type: 'text', content: '{{status}}', fontSize: 14, color: '#666666' }
]
},
dynamicIslandLayout: {
expanded: {
leading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
trailing: { type: 'text', content: '{{eta}}' },
center: { type: 'text', content: '{{status}}' },
bottom: { type: 'progress', value: 'progress' }
},
compactLeading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
compactTrailing: { type: 'text', content: '{{eta}}' },
minimal: { type: 'image', source: 'sfSymbol', value: 'box.truck' }
},
data: {
orderNumber: '12345',
status: 'On the way',
eta: '10 min',
progress: 0.6
}
});
console.log('Started activity:', activityId);
updateActivity
- 使用最新数据更新现有的 Live 活动。
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
await CapgoLiveActivities.updateActivity({
activityId: 'abc123',
data: {
status: 'Arrived!',
eta: 'Now',
progress: 1.0
},
alertConfiguration: {
title: 'Delivery Update',
body: 'Your order has arrived!'
}
});
endActivity
- 结束一个 Live 活动。
import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';
await CapgoLiveActivities.endActivity({
activityId: 'abc123',
data: { status: 'Delivered' },
dismissalPolicy: 'after',
dismissAfter: Date.now() + 3600000 // 1 hour from now
});
- 全部参考
- - GitHub: - https://github.com/Cap-go/capacitor-live-activities/
- - 文档：/docs/plugins/live-activities/
- 从使用 @capgo/capacitor-live-activities 中继续
如果您正在使用 使用 @capgo/capacitor-live-activities 为了规划原生媒体和界面行为，连接它与 @capgo/capacitor-live-activities 为了在 @capgo/capacitor-live-activities 中实现详细信息 开始 为了在开始中实现详细信息 使用 @capgo/capacitor-video-player 为了在使用 @capgo/capacitor-video-player 中实现原生能力 @capgo/capacitor-视频播放器 为了在 @capgo/capacitor-video-player 中实现详细信息，并且 使用 @capgo/capacitor-native-navigation 为使用@capgo/capacitor-native-navigation的原生能力。