实时活动 Capacitor 插件

使用 @capgo/capacitor-live-activities

用于管理 iOS Live Activities 的 Capacitor Live Activities 插件接口。

安装

bun add @capgo/capacitor-live-activities
bunx cap sync

iOS 配置

安装并同步插件不会自动创建原生 Live Activity UI。在调用 startActivity之前，请在 Xcode 中配置 ActivityKit：

1. 运行 bunx cap open ios.
2. 添加一个 小组件扩展 目标并启用 包含 Live Activity.
3. 将 App 和 Widget Extension 的部署目标设置为 iOS 16.1 或更高版本。
4. 确保该 Extension 已嵌入主 App 中。
5. 保持 ActivityConfiguration 已注册在 Extension 的 WidgetBundle中，并支持锁定屏幕及所有 Dynamic Island 展示。
6. 添加 NSSupportsLiveActivities 至主 App target Info.plist.

<key>NSSupportsLiveActivities</key>
<true/>

仅添加 target 是不够的。原生 App 或 plugin 必须调用 ActivityKit 的 request、update 和 end API。Widget Extension 必须包含能够解码并渲染与这些调用相同的 SwiftUI code ActivityAttributes 及内容状态的视图。请在主 App 和 Widget Extension target 中都包含共享的 ActivityKit 模型。Xcode 生成的 Live Activity 模板不会自动渲染传递给此 plugin 的 JSON 布局；extension 也需要一个兼容的原生布局渲染器。

共享图片

使用图片管理方法时，请为 App Groups capability 添加到主 App 和 Widget Extension target。在两个 target 上使用 plugin 所需的完全一致的 identifier 来启用同一个 group：

group.<MAIN_APP_BUNDLE_ID>.liveactivities

Live Activity extension 无法访问网络。请在主 App 中下载远程图片，并使用 saveImage将其保存到共享的 App Group 中，然后在布局中引用该保存的图片。Bundled assets 也必须属于 Widget Extension target。

Deep Links 与 Push Updates

• 注册由以下项使用的任何自定义 URL scheme behavior.widgetUrl 或 tapUrl 在主 App Target 的 Info > URL Types 中 设置中添加该 Scheme。
• 若要实现服务端驱动的更新，请添加 推送通知 capability，并使用 APNs 实现 ActivityKit push-token 处理。
• 添加 NSSupportsLiveActivitiesFrequentUpdates 仅当 App 需要频繁的 ActivityKit 推送更新时才需要。

仅启用 Push Notifications capability 是不够的；服务端驱动的更新需要原生 token 处理和 APNs 后端支持。

ActivityKit 限制静态与动态 Live Activity 数据总量为 4 KB。Dynamic Island 仅在支持的机型上可见；其他设备将通过锁屏界面展示。

插件暴露的内容

• areActivitiesSupported - 检查此设备是否支持 Live Activities。需要 iOS 16.1+ 及设备支持。
• startActivity - 使用指定的布局和数据启动新的 Live Activity。
• updateActivity - 使用新数据更新现有的 Live Activity。
• endActivity - 结束 Live Activity。

用法示例

areActivitiesSupported

检查此设备是否支持 Live Activities。需要 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 Activity。

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 Activity。

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 Activity。

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-video-player 在 @capgo/capacitor-video-player 中的实现细节，以及 使用 @capgo/capacitor-native-navigation 用于使用 @capgo/capacitor-native-navigation. 时的原生能力