Getting Started

复制安装提示并包含该插件的完整Markdown指南。

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-live-activities`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/live-activities/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

安装

您可以使用我们的AI辅助设置来安装插件。将Capgo技能添加到您的AI工具中，使用以下命令:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下提示:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-live-activities` plugin in my project.

如果您更喜欢手动设置，请运行以下命令安装插件，并按照以下平台特定的说明进行操作:

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

iOS设置

安装和同步插件不会创建原生Live活动UI。ActivityKit需要一个Widget扩展来注册一个Live活动配置，然后才能显示任何内容。 startActivity 需求

标题为“需求”的部分

使用 iOS 16.1 或更高版本作为应用目标和 Widget Extension 目标。
在 iOS 设备或兼容的模拟器上进行测试。动态岛仅在支持的设备模型上可见；其他设备使用锁屏演示。
确保组合静态和动态 ActivityKit 数据不超过 Apple 的 4 KB限制。

打开原生 iOS 项目：

bunx cap open ios

然后：

选择 文件 > 新建 > 目标.
添加一个 扩展组件.
启用 包含实时活动.
禁用 包含配置意图 除非应用程序还需要一个可配置的widget.
确保生成的扩展嵌入到主应用程序目标中。

扩展组件必须包含一个 ActivityConfiguration 并在其 WidgetBundle中注册它。它必须提供每个所需的实时活动呈现:

锁屏
动态岛屿扩展
动态岛屿紧凑型前后导航
动态岛屿最小化

仅添加目标是不够的。原生应用或插件必须调用ActivityKit的request、update和end API。扩展必须包含SwiftUIcode，可以解码和渲染这些调用使用的相同 ActivityAttributes 和内容状态。将共享的ActivityKit模型添加到主应用和小部件扩展目标中。Xcode生成的Live Activity模板不会自动渲染传递给此插件的JSON布局；扩展还需要兼容的原生布局渲染器。

2. 启用实时活动

将以下键添加到主应用目标的 Info.plist:

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

如果项目生成其 Info.plist, 添加 支持实时活动 值为布尔值 YES 在主应用目标的自定义 iOS 目标属性下。

3. 配置共享图片的 App 组

仅当使用时，才需要 App 组 saveImage, removeImage, listImages或 cleanupImages。该插件从主应用包标识符中派生 App 组标识符，使用以下精确格式：

group.<MAIN_APP_BUNDLE_ID>.liveactivities

例如，具有包标识符的应用必须使用： com.example.delivery 在 Xcode 中，添加

group.com.example.delivery.liveactivities

App 组 App 组 让主应用和小部件扩展都能访问此功能,然后在两个目标上启用相同的标识符。

Live Activity 扩展无法访问网络。请在主应用中下载远程图片并将它们保存到共享 App Group 中，然后从 Live Activity 中引用它们。对于捆绑的图片，还需要在资产的目标成员中启用小部件扩展。

4. 配置深度链接

使用 behavior.widgetUrl 或一个计时器序列 tapUrl，注册匹配的 URL 方案或 Universal Link 在主应用中。对于一个自定义方案，如 myapp://order/12345，在主应用目标的 信息> URL 类型 设置中添加该方案。

5. 可选：启用服务器驱动更新

推送通知并非本地更新所必需。若要从服务器开始、更新或结束 Live 活动，请：

添加 推送通知 capability 到主应用目标。
获取 ActivityKit 推送令牌并将其发送到服务器。
通过 APNs 使用 liveactivity 推送类型。
添加 NSSupportsLiveActivitiesFrequentUpdates 仅在需要频繁推送更新的场景下才添加到主应用中。 Info.plist ActivityKit 推送令牌与标准用户通知设备令牌是不同的。仅启用推送通知能力不足；服务器驱动的更新需要本机令牌处理和 APNs 后端。

原生设置清单

context

在调用之前 startActivity请确认

NSSupportsLiveActivities 是否已在主应用目标中启用
小部件扩展已嵌入并注册了 ActivityConfiguration.
原生 ActivityKit 实现和小部件扩展使用相同的 ActivityAttributes 类型
应用和小部件扩展的部署目标均为 iOS 16.1 或更高版本
在 iOS 设置中已启用应用的 Live Activities
在使用共享图像时，匹配的 App Group 已在两个目标上启用
或 widgetUrl 或 tapUrl 已注册。

导入

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

API概述

`areActivitiesSupported`

需要 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`

开始一个新的实时活动，指定布局和数据

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`

更新现有实时活动的数据。

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`

结束实时活动。

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
});

`getAllActivities`

获取当前所有活跃的实时活动。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { activities } = await CapgoLiveActivities.getAllActivities();
activities.forEach(activity => {
  console.log(`Activity ${activity.activityId}: ${activity.state}`);
});

`saveImage`

将图片保存到共享App Group容器中，以便在实时活动中使用。图片必须保存到共享容器中才能从小部件扩展中访问。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { success, imageName } = await CapgoLiveActivities.saveImage({
  imageData: 'base64EncodedImageData...',
  name: 'product-image',
  compressionQuality: 0.8
});
// Use in layout with: { type: 'image', source: 'saved', value: imageName }

`removeImage`

从共享容器中删除保存的图片。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { success } = await CapgoLiveActivities.removeImage({ name: 'product-image' });

`listImages`

共享容器中所有保存的图片列表。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { images } = await CapgoLiveActivities.listImages();
console.log('Saved images:', images);

`cleanupImages`

从共享容器中删除所有保存的图片。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.cleanupImages();

`startTimerSequence`

开始计时器序列，用于运动/运动。在 iOS 中：在 Live Activity 和动态岛屿中显示。在 Android 中：以计时器形式显示为前台通知

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { sequenceId } = await CapgoLiveActivities.startTimerSequence({
  title: 'HIIT Workout',
  steps: [
    { duration: 30, title: 'Jumping Jacks', subtitle: 'Warm up', color: '#FF6B00', icon: 'figure.jumprope' },
    { duration: 10, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
    { duration: 45, title: 'Burpees', subtitle: 'High intensity', color: '#FF0000', icon: 'flame.fill' },
    { duration: 15, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
    { duration: 45, title: 'Mountain Climbers', color: '#FF0000', icon: 'figure.run' },
    { duration: 15, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
  ],
  loop: true,
  loopCount: 3,
  soundEnabled: true,
  vibrateEnabled: true,
  countdownBeeps: true,
  tapUrl: 'myapp://workout/hiit'
});

`pauseTimerSequence`

暂停计时器序列。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.pauseTimerSequence({ sequenceId: 'abc123' });

`resumeTimerSequence`

恢复暂停的计时器序列。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.resumeTimerSequence({ sequenceId: 'abc123' });

`stopTimerSequence`

停止并关闭计时器序列。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.stopTimerSequence({ sequenceId: 'abc123' });

`skipTimerStep`

跳过序列中的下一步。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.skipTimerStep({ sequenceId: 'abc123' });

`previousTimerStep`

返回到序列中的前一个步骤。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.previousTimerStep({ sequenceId: 'abc123' });

`getTimerState`

获取计时器序列的当前状态。

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const state = await CapgoLiveActivities.getTimerState({ sequenceId: 'abc123' });
console.log(`Step ${state.currentStepIndex + 1}/${state.totalSteps}: ${state.currentStep.title}`);
console.log(`Time remaining: ${state.remainingSeconds}s`);

类型参考

`AreActivitiesSupportedResult`

检查活动是否支持的结果。

export interface AreActivitiesSupportedResult {
  /** Whether Live Activities are supported on this device */
  supported: boolean;
  /** Reason if not supported */
  reason?: string;
}

`StartActivityOptions`

开始实时活动的选项。

export interface StartActivityOptions {
  /** Main activity layout (lock screen widget) */
  layout: ActivityLayout;
  /** Dynamic Island layout configuration */
  dynamicIslandLayout: DynamicIslandLayout;
  /** Activity behavior settings */
  behavior?: LiveActivitiesBehavior;
  /** Dynamic data for the activity */
  data: Record<string, unknown>;
  /** Stale date timestamp (activity becomes stale after this) */
  staleDate?: number;
  /** Relevance score for activity ordering (0-100) */
  relevanceScore?: number;
}

`StartActivityResult`

启动活动的结果。

export interface StartActivityResult {
  /** Unique activity identifier */
  activityId: string;
}

`UpdateActivityOptions`

更新实时活动的选项。

export interface UpdateActivityOptions {
  /** Activity ID to update */
  activityId: string;
  /** Updated data */
  data: Record<string, unknown>;
  /** Optional alert to show with update */
  alertConfiguration?: ActivityAlertConfiguration;
  /** Updated stale date */
  staleDate?: number;
  /** Updated relevance score */
  relevanceScore?: number;
}

`EndActivityOptions`

结束实时活动的选项。

export interface EndActivityOptions {
  /** Activity ID to end */
  activityId: string;
  /** Final data to display */
  data?: Record<string, unknown>;
  /** Dismissal policy */
  dismissalPolicy?: 'immediate' | 'default' | 'after';
  /** Dismiss after timestamp (when dismissalPolicy is 'after') */
  dismissAfter?: number;
}

`GetAllActivitiesResult`

getAllActivities的结果。

export interface GetAllActivitiesResult {
  /** List of activities */
  activities: ActivityInfo[];
}

`SaveImageOptions`

保存图片的选项。

export interface SaveImageOptions {
  /** Base64 encoded image data */
  imageData: string;
  /** Name to save the image as */
  name: string;
  /** JPEG compression quality (0-1, default 0.8) */
  compressionQuality?: number;
}

`SaveImageResult`

保存图片的结果。

export interface SaveImageResult {
  /** Whether the save was successful */
  success: boolean;
  /** Saved image name */
  imageName: string;
}

`RemoveImageOptions`

删除图片的选项。

export interface RemoveImageOptions {
  /** Name of the image to remove */
  name: string;
}

`RemoveImageResult`

移除图片的结果。

export interface RemoveImageResult {
  /** Whether the removal was successful */
  success: boolean;
}

`ListImagesResult`

列出图片的结果。

export interface ListImagesResult {
  /** List of saved image names */
  images: string[];
}

`TimerSequenceOptions`

启动计时器序列的选项。

export interface TimerSequenceOptions {
  /** Array of steps in the sequence */
  steps: TimerStep[];
  /** Overall title for the sequence (e.g., "HIIT Workout", "Tabata") */
  title?: string;
  /** Whether to loop the sequence when complete */
  loop?: boolean;
  /** Number of times to loop (if loop is true, 0 means infinite) */
  loopCount?: number;
  /** Play sound on step change (default: true) */
  soundEnabled?: boolean;
  /** Vibrate on step change (default: true) */
  vibrateEnabled?: boolean;
  /** Play countdown beeps in last 3 seconds (default: true) */
  countdownBeeps?: boolean;
  /** Deep link URL when tapping the notification/activity */
  tapUrl?: string;
  /** Keep screen on during timer (Android only, default: false) */
  keepScreenOn?: boolean;
}

真实来源

本页是由插件的 src/definitions.ts当公共API在上游发生变化时，请重新同步。

继续从 Getting Started

如果您正在使用 开始使用 规划仪表板和 API 操作，连接它与使用 @capgo/capacitor-live-activities 为使用 @capgo/capacitor-live-activities 的原生能力 API 概述为 API 概述的实现细节介绍为介绍的实现细节 API 密钥在 API Keys 中的实现细节设备在设备中实现细节

Getting Started

安装

iOS设置

标题为“需求”的部分

1. 创建一个 Widget Extension

2. 启用实时活动

3. 配置共享图片的 App 组

4. 配置深度链接

5. 可选：启用服务器驱动更新

context

导入

API概述

areActivitiesSupported

startActivity

updateActivity

endActivity

getAllActivities

saveImage

removeImage

listImages

cleanupImages

startTimerSequence

pauseTimerSequence

resumeTimerSequence

stopTimerSequence

skipTimerStep

previousTimerStep

getTimerState