rndynamic-island

React Native 灵动岛（Live Activity）封装，iOS 16.2+。在 RN 中通过 JS 启动、更新、结束 Live Activity，支持订单、音乐、计时器、配送等多种类型。

作者：Jason

特性

• 支持多种业务类型（order / music / timer / delivery / ride / fitness / call / recording / custom）
• 统一入口：startActivity(params)，params 中传 type（order / music / timer / delivery 等）
• 通用 API：update、stop、forceStopAll
• 主 App 通过 CocoaPods 自动链接；Widget Extension 通过 Pod 子模块依赖 DynamicIslandKit

要求

• iOS 16.2+
• Xcode 15+（Swift 5.9）
• React Native 项目（已有 ios 工程）

安装

npm install rndynamic-island
# 或 yarn add rndynamic-island
# 或 pnpm add rndynamic-island

iOS 集成（完整步骤）

Live Activity 的 UI 由 Widget Extension 渲染，需在工程里单独建一个 Extension target 并接入示例 UI。按下面顺序做即可。

第一步：安装依赖

npm install rndynamic-island
# 或 yarn add rndynamic-island / pnpm add rndynamic-island

第二步：主 App 安装 Pod

cd ios && pod install && cd ..

主 App 通过 use_native_modules! 自动引入 RNDynamicIsland，无需改 Podfile。

第三步：添加 Widget Extension

任选其一：

• 方式 A（推荐）：复制本仓库示例 Extension 到你的工程
  • 将 example/ios/DynamicIslandWidget/ 整个目录复制到你的 ios/ 下（与 YourApp 同级）。
  • 在 Xcode 中打开 ios/YourApp.xcworkspace，把 DynamicIslandWidget 文件夹拖进工程，勾选你的主 App target 的 Embed Foundation Extensions（或 Build Phases 里加入该 .appex）。
• 方式 B：在 Xcode 里新建
  • File → New → Target → Widget Extension，命名为如 DynamicIslandWidget，勾选 Include Live Activity。
  • 再将 example/ios/DynamicIslandWidget/ 下的 Swift 与 Views 复制到该 Extension 目录并加入 target（见第五步文件列表）。

第四步：配置 Info.plist

• 主 App 的 Info.plist（如 YourApp/Info.plist）添加：

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

• Widget Extension 的 Info.plist（如 DynamicIslandWidget/Info.plist）需包含：

<key>NSExtension</key>
<dict>
  <key>NSExtensionPointIdentifier</key>
  <string>com.apple.widgetkit-extension</string>
</dict>
<key>NSSupportsLiveActivities</key>
<true/>

若用 Xcode 创建 Extension 时勾选了 Include Live Activity，通常已自动生成，可对照检查。

第五步：Extension 内使用示例 UI

若第三步用的是方式 B（自己新建的 Extension），需把示例文件复制进去并加入 target：

• DynamicIslandWidgetLiveActivity.swift（GenericLiveActivity）
• Views/DynamicIslandView.swift
• Views/LockScreenView.swift
• DynamicIslandWidgetBundle.swift（在其中注册 GenericLiveActivity）

Extension 的 Bundle ID 一般为「主 App Bundle ID + 扩展名」，例如 com.yourapp.hello.DynamicIslandWidget。

第六步：为 Extension 添加 DynamicIslandKit 依赖

在 ios/Podfile 里为 Widget target 增加（target 名改成你的 Extension 名）：

target 'DynamicIslandWidget' do
  pod 'RNDynamicIsland', :path => '../node_modules/rndynamic-island', :subspecs => ['DynamicIslandKit']
end

然后执行：

cd ios && pod install && cd ..

Widget 内通过 import RNDynamicIsland 使用数据模型与 Manager。

完成以上六步后，在 JS 中即可使用 start、update、stop 等 API 控制 Live Activity。

JS API

通用方法

| 方法 | 说明 | |------|------| | startActivity(params) | 启动 Live Activity（params 需含 type：order / music / timer / delivery 等） | | update(params) | 更新当前 Activity 状态 | | stop() | 结束当前 Activity | | forceStopAll() | 强制结束所有 Live Activity |

启动参数 StartParams

| 字段 | 类型 | 说明 | |------|------|------| | type | string | 类型：order / music / timer / delivery / ride / fitness / call / recording / custom | | id | string | 唯一标识（如订单号、歌曲 ID） | | title | string | 主标题 | | subtitle | string | 副标题 / 状态描述 | | progress | number | 进度 0~1；-1 表示不显示进度条 | | leftLabel | string | 紧凑形态左侧文案 | | rightLabel | string | 紧凑形态右侧文案 | | iconName | string | SF Symbol 名，见下方「图标」 |

图标 iconName（SF Symbol）

不传 iconName 时按 type 使用默认图标；传了则优先使用你指定的图标。

各 type 默认图标：

| type | 默认图标 | |------|----------| | order | shippingbox.fill | | music | music.note | | timer | timer | | delivery / ride | car.fill | | fitness | figure.walk | | call | phone.fill | | recording | record.circle | | custom / 其他 | circle.fill |

自定义时可用的 SF Symbol 示例：
star.fill、heart.fill、bell.fill、flag.fill、bookmark.fill、tag.fill、gift、cup.and.saucer.fill、fork.knife、airplane、train.side.front.car、bicycle、figure.run、headphones、gamecontroller.fill、creditcard.fill、ticket.fill 等。名称参考 SF Symbols。

更新参数 UpdateParams

可传：title、subtitle、progress、leftLabel、rightLabel、iconName（同上）。

使用示例

import { startActivity, update, stop } from 'rndynamic-island';

// 订单
startActivity({
  type: 'order',
  id: 'ORD-001',
  progress: 0.1,
  rightLabel: '10%',
});

// 音乐（无进度条）
startActivity({
  type: 'music',
  id: 'track-1',
  progress: -1,
  leftLabel: 'Now Playing',
  rightLabel: '3:20',
});

// 配送
startActivity({
  type: 'delivery',
  id: 'DEL-001',
  progress: 0.3,
  iconName: 'xiazai-2',
});

// 更新与结束
update({ progress: 0.6, rightLabel: '60%' });
stop();

注意事项

• 实时活动开关：用户需在 设置 → 面容 ID 与密码 中开启「实时活动」，否则 start 不会发起请求。
• 设备与形态：iPhone 14 Pro 及以上支持灵动岛；更早机型仅锁屏 Live Activity。
• 数量限制：系统对同时存在的 Live Activity 数量有限制（通常 2 个），超出会报错，需先 stop() 再启动新的。
• 审核：Live Activity 仅用于真实实时场景（如订单、配送、计时），结束后应调用 stop()；勿用于广告或营销推送。

工程结构

rndynamic-island/
├── ios/
│   ├── DynamicIslandKit/        # 数据模型与 Manager（主 App + Widget 共用）
│   └── RNDynamicIslandModule/   # RN 桥接（Pod 自动链接）
├── js/
│   ├── index.js
│   ├── index.d.ts
│   └── DynamicIsland.example.js
├── package.json
├── rndynamic-island.podspec
├── RNDynamicIsland.podspec
└── react-native.config.js

本地开发

从本地路径引用时：

yarn add file:../path/to/DynamicIslandRN

Podfile 中 Widget 的 :path 会解析为 ../node_modules/rndynamic-island，无需改 path。

License

MIT