开始获取

安装

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

iOS 设置

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

在应用目标和 Widget 扩展目标上使用 iOS 16.1 或更高版本。

• 保持组合静态和动态 ActivityKit 数据在 Apple 的 4 KB 限制之下。
• 1. 创建一个 Widget 扩展
• __CAPGO_KEEP_0__

__CAPGO_KEEP_1__

打开本机 iOS 项目：

bunx cap open ios

然后：

1. 选择 文件 > 新建 > 目标.
2. 添加一个 小部件扩展.
3. 启用 包含 Live 活动.
4. 禁用 包含配置意图 除非应用程序还需要一个可配置的小部件。
5. 确保生成的扩展程序嵌入到主应用程序目标中。

小部件扩展程序必须包含一个 ActivityConfiguration 并在其 WidgetBundle。它必须提供所有所需的实时活动呈现形式：

• 锁屏
• 动态岛扩展
• 动态岛紧凑的前导和尾随
• 动态岛最小

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

2. 开启实时活动

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

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

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

3. 配置共享图片的 App 组

仅当使用 saveImage, removeImage, listImages，或者 cleanupImages复制到剪贴板

group.<MAIN_APP_BUNDLE_ID>.liveactivities

必须使用： com.example.delivery 复制到剪贴板

group.com.example.delivery.liveactivities

App Groups 功能到主应用程序目标和 Widget Extension 目标，然后在两个目标上启用相同的标识符。 Live Activity 扩展无法访问网络。从主应用程序下载远程图片并将它们保存到共享的 App Group 中，然后从 Live Activity 中引用它们。对于捆绑的图片，还需要启用 Widget Extension 在资产的目标成员资格中。

4. 配置深度链接

标题：4. 配置深度链接

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

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

本地更新不需要推送通知。要从服务器开始、更新或结束 Live 活动：

• 将 推送通知 能力添加到主应用目标。
• 获取 ActivityKit 推送令牌并将它们发送到服务器。
• 使用 " liveactivity "类型的 APNs 发送 ActivityKit 通知。
• 仅在使用案例需要频繁推送更新时，才将其添加到主应用程序中。 NSSupportsLiveActivitiesFrequentUpdates ActivityKit 推送令牌与标准用户通知设备令牌是不同的。 仅开启推送通知能力是不够的；服务器驱动的更新需要原生令牌处理和 APNs 后端。 原生设置清单 Info.plist 原生设置清单

在调用

之前，请确保：

__CAPGO_KEEP_0__ startActivity__CAPGO_KEEP_0__

• NSSupportsLiveActivities __CAPGO_KEEP_0__
• The Widget Extension is embedded and registers an __CAPGO_KEEP_0__. ActivityConfiguration.
• 使用相同的 ActivityAttributes 类型。
• 该应用和小部件扩展的部署目标是 iOS 16.1 或更高版本。
• 在iOS设置中，应用程序启用了实时活动。
• 在使用共享图像时，两个目标都启用了匹配的 App 组。
• 任何由 Capgo 使用的自定义 URL 方案 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

List all saved images in the shared container.

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

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

cleanupImages

Remove all saved images from the shared container.

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

await CapgoLiveActivities.cleanupImages();

startTimerSequence

Start a timer sequence for workouts/sports. On iOS: Shows in Live Activity and Dynamic Island On Android: Shows as a foreground notification with timer

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

获取所有活动的结果。

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上游更改时，请重新运行同步。

继续从开始

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