cross-platform

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cross-platform

跨平台开发

Purpose

用途

This skill guides the selection and implementation of cross-platform mobile frameworks like React Native with Expo, Flutter with Dart (using Bloc or Riverpod), Capacitor, and Kotlin Multiplatform Mobile (KMM). It focuses on choosing the right framework based on project needs and provides step-by-step integration for efficient mobile app development.

本技能指导如何选择和实现跨平台移动框架，包括搭配Expo的React Native、搭配Dart的Flutter（使用Bloc或Riverpod）、Capacitor以及Kotlin Multiplatform Mobile（KMM）。它聚焦于根据项目需求选择合适的框架，并提供分步集成方案，以实现高效的移动应用开发。

When to Use

适用场景

Use this skill for projects requiring multi-platform deployment (iOS/Android) to reduce code duplication. Apply it when building apps with shared business logic, such as e-commerce apps, social networks, or productivity tools. Ideal for teams with limited resources or when rapid prototyping is needed, like integrating native modules or handling state management across platforms.

当项目需要跨iOS/Android多平台部署以减少代码重复时，可使用本技能。适用于构建具备共享业务逻辑的应用，如电商应用、社交网络或生产力工具。尤其适合资源有限的团队，或需要快速原型开发的场景，比如集成原生模块或跨平台处理状态管理。

Key Capabilities

核心能力

Framework selection: Choose React Native for JavaScript-heavy apps, Flutter for custom UI with Dart, Capacitor for web-to-mobile conversion, or KMM for shared Kotlin codebases.
Expo integration: Use EAS (Expo Application Services) for streamlined builds, including OTA updates and cloud services.
State management: Implement Bloc for event-driven state in Flutter or Riverpod for reactive state in Flutter/Dart apps.
Cross-platform features: Handle platform-specific code, like accessing device APIs (e.g., camera, GPS) via Capacitor's bridge or KMM's expect/actual declarations.
Configuration: Manage app configs in JSON/YAML formats, such as Expo's app.json for routing and permissions.

框架选型：JavaScript技术栈为主的项目选React Native；需要自定义UI的选Flutter；Web转移动应用选Capacitor；共享Kotlin代码库的选KMM。
Expo集成：使用EAS（Expo Application Services）实现简化构建，包括OTA更新和云服务。
状态管理：在Flutter中实现基于事件驱动状态的Bloc，或基于响应式状态的Riverpod。
跨平台特性：处理平台专属代码，比如通过Capacitor的桥接层或KMM的expect/actual声明访问设备API（如相机、GPS）。
配置管理：使用JSON/YAML格式管理应用配置，例如Expo的app.json用于路由和权限设置。

Usage Patterns

使用模式

To select a framework, evaluate based on tech stack: use React Native if the team knows JS; Flutter for high-performance UIs. Start by initializing a project:

For React Native with Expo: Run

expo init MyApp --template blank

then add dependencies with

npm install @react-navigation/native

For Flutter with Riverpod: Create a project with
```
flutter create MyApp
```
and set up state:
```
final counterProvider = StateProvider((ref) => 0);
```
in a Dart file. Always wrap platform-specific code: In KMM, use
```
expect fun platformFunction() {}
```
in common code and implement in iOS/Android modules. For Capacitor, convert a web app by running
```
npx cap add android
```
after setting up a web project.

选择框架时，根据技术栈评估：若团队熟悉JS则选React Native；需要高性能UI则选Flutter。从初始化项目开始：

React Native搭配Expo：运行

expo init MyApp --template blank

，然后通过

npm install @react-navigation/native

添加依赖。

Flutter搭配Riverpod：通过
```
flutter create MyApp
```
创建项目，在Dart文件中设置状态：
```
final counterProvider = StateProvider((ref) => 0);
```
。始终封装平台专属代码：在KMM中，在通用代码中使用
```
expect fun platformFunction() {}
```
，并在iOS/Android模块中实现。对于Capacitor，在搭建Web项目后运行
```
npx cap add android
```
即可将其转换为移动应用。

Common Commands/API

常用命令/API

Expo (React Native): Use
```
expo login
```
(requires $EXPO_API_KEY env var),
```
eas build --platform all
```
for multi-platform builds, and API endpoint
```
POST https://api.expo.dev/v2/projects
```
for project management.

Flutter: Run

flutter pub add flutter_bloc

for Bloc, or

flutter run --device-id emulator-5554

to target a specific emulator; access APIs like

BlocProvider.of(context).add(Event())

for state changes.

Capacitor: Execute
```
npx cap sync
```
to update native projects, or
```
npx cap open android
```
to launch Android Studio; use Capacitor's Plugins API, e.g.,
```
Capacitor.Plugins.Camera.getPhoto()
```
in JavaScript.

KMM: Build with

./gradlew build

in the shared module, and use KMM Bridge for iOS:

import shared.Platform().hello()

in Swift. Config formats: Edit Expo's app.json like

{ "expo": { "name": "MyApp", "slug": "myapp", "platforms": ["ios", "android"] } }

; for Flutter, modify pubspec.yaml with

dependencies: flutter_riverpod: ^2.0.0

Expo（React Native）：使用
```
expo login
```
（需$EXPO_API_KEY环境变量），
```
eas build --platform all
```
用于多平台构建，项目管理API端点为
```
POST https://api.expo.dev/v2/projects
```
。

Flutter：运行

flutter pub add flutter_bloc

引入Bloc，或使用

flutter run --device-id emulator-5554

指定模拟器；通过

BlocProvider.of(context).add(Event())

等API处理状态变更。

Capacitor：执行
```
npx cap sync
```
更新原生项目，或
```
npx cap open android
```
启动Android Studio；使用Capacitor的Plugins API，例如在JavaScript中调用
```
Capacitor.Plugins.Camera.getPhoto()
```
。
KMM：在共享模块中运行
```
./gradlew build
```
进行构建，在iOS中使用KMM Bridge：
```
import shared.Platform().hello()
```
（Swift代码）。配置格式：编辑Expo的app.json，示例：
```
{ "expo": { "name": "MyApp", "slug": "myapp", "platforms": ["ios", "android"] } }
```
；对于Flutter，修改pubspec.yaml添加依赖：
```
dependencies: flutter_riverpod: ^2.0.0
```
。

Integration Notes

集成说明

Integrate these frameworks with backends by setting environment variables for auth, e.g., export $BACKEND_API_KEY for API calls. For React Native, use Expo's Fetch API:

fetch('https://api.example.com/data', { headers: { Authorization:

Bearer ${process.env.BACKEND_API_KEY}

 } })

. In Flutter, add HTTP packages:

http.get(Uri.parse('https://api.example.com/data'), headers: {'Authorization': 'Bearer $envVar'}).then((response) => ...);

. For Capacitor, bridge web requests: Install

@capacitor/core

and use

CapacitorHttp.get({url: 'https://api.example.com/data', headers: {Authorization: $BACKEND_API_KEY}});

. KMM integration: Share networking code via common module and call from native apps, ensuring Gradle sync for dependencies.

将这些框架与后端集成时，设置身份验证相关的环境变量，例如导出$BACKEND_API_KEY用于API调用。在React Native中，使用Expo的Fetch API：

fetch('https://api.example.com/data', { headers: { Authorization:

Bearer ${process.env.BACKEND_API_KEY}

 } })

。在Flutter中，添加HTTP包：

http.get(Uri.parse('https://api.example.com/data'), headers: {'Authorization': 'Bearer $envVar'}).then((response) => ...);

。在Capacitor中，桥接Web请求：安装

@capacitor/core

并使用

CapacitorHttp.get({url: 'https://api.example.com/data', headers: {Authorization: $BACKEND_API_KEY}});

。KMM集成：通过共享模块共享网络代码，并在原生应用中调用，确保Gradle同步依赖。

Error Handling

错误处理

Handle common errors by checking for platform mismatches: In React Native, if

expo build

fails with "Invalid platform", verify app.json platforms array. For Flutter, if

flutter run

errors on "No devices", use

flutter emulators --launch Pixel_API_33

then retry. Capacitor errors like "Plugin not found" require

npx cap sync

and verifying package.json. In KMM, resolve build failures with

./gradlew clean

for corrupted caches. Always log errors: In Expo, use

console.error(e)

and check EAS build logs; in Flutter, wrap with try-catch:

try { await http.get(...); } catch (e) { print(e.toString()); }

. Use env vars for secure keys to avoid exposure.

通过检查平台匹配情况处理常见错误：在React Native中，若

expo build

提示“Invalid platform”错误，需验证app.json中的platforms数组。在Flutter中，若

flutter run

提示“No devices”错误，使用

flutter emulators --launch Pixel_API_33

启动模拟器后重试。Capacitor出现“Plugin not found”错误时，需执行

npx cap sync

并检查package.json。在KMM中，通过

./gradlew clean

清理损坏的缓存以解决构建失败问题。始终记录错误：在Expo中，使用

console.error(e)

并查看EAS构建日志；在Flutter中，用try-catch包裹：

try { await http.get(...); } catch (e) { print(e.toString()); }

。使用环境变量存储密钥以避免泄露。

Graph Relationships

关联关系

Connected to: mobile cluster
Relates to: react-native skill, flutter skill, expo skill, capacitor skill
Depends on: cross-platform tags for embedding
Interacts with: kmm framework in mobile ecosystem

关联集群：移动开发集群
相关技能：React Native技能、Flutter技能、Expo技能、Capacitor技能
依赖项：跨平台标签用于嵌入
交互对象：移动生态中的KMM框架