Expo Brownfield

用于将 Expo 集成到现有原生应用中的工具包和 API。

Android

iOS

GitHub

npm

更新日志

Recommended version:

~57.0.21

expo-brownfield 是一个用于向现有原生 Android 和 iOS 应用中添加 React Native 视图的工具包。它提供：

内置 API，用于原生应用和 React Native 应用之间的双向通信与导航
配置插件，用于在你的 Expo 项目中自动设置 brownfield 目标
CLI，用于构建并将产物发布到 Maven 仓库（Android）和 XCFrameworks（iOS）

安装

Terminal

- npx expo install expo-brownfield

- yarn expo install expo-brownfield

- pnpm expo install expo-brownfield

- bun expo install expo-brownfield

If you are installing this in an existing React Native app, make sure to install expo in your project.

用法

通信 API

通信 API 支持原生（宿主）应用与 React Native 之间基于消息的双向通信。

从 React Native 向原生发送消息

import * as Brownfield from 'expo-brownfield';

Brownfield.sendMessage({
  type: 'MyMessage',
  data: {
    language: 'TypeScript',
    expo: true,
    platforms: ['android', 'ios'],
  },
});

在 React Native 中接收来自原生的消息

import * as Brownfield, { type MessageEvent } from 'expo-brownfield';
import { useEffect } from 'react';

function MyComponent() {
  useEffect(() => {
    const handleMessage = (event: MessageEvent) => {
      console.log('收到消息：', event);
    };

    Brownfield.addMessageListener(handleMessage);

    return () => {
      Brownfield.removeMessageListener(handleMessage);
    };
  }, []);

  // ...
}

从原生向 React Native 发送消息

import expo.modules.brownfield.BrownfieldMessaging

BrownfieldMessaging.sendMessage(mapOf(
    "type" to "MyAndroidMessage",
    "timestamp" to System.currentTimeMillis(),
    "data" to mapOf(
        "platform" to "android"
    )
))

import ExpoBrownfield

BrownfieldMessaging.sendMessage([
    "type": "MyIOSMessage",
    "timestamp": Date().timeIntervalSince1970,
    "data": [
        "platform": "ios"
    ]
])

在原生中接收来自 React Native 的消息

import expo.modules.brownfield.BrownfieldMessaging

val listenerId = BrownfieldMessaging.addListener { event ->
    println("来自 React Native 的消息：$event")
}

// Later, to remove the listener:
BrownfieldMessaging.removeListener(listenerId)

import ExpoBrownfield

let listenerId = BrownfieldMessaging.addListener { message in
    print("来自 React Native 的消息：\(message)")
}

// Later, to remove the listener:
BrownfieldMessaging.removeListener(id: listenerId)

app 配置中的配置

expo-brownfield 包提供了一个配置插件，可在使用连续原生生成（CNG）时用于配置 brownfield 集成。此插件允许你自定义 Expo 项目的打包方式，以及它如何集成到现有的原生应用中。

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-brownfield",
        {
          "ios": {
            "targetName": "MyBrownfieldTarget",
            "bundleIdentifier": "com.example.brownfield"
          },
          "android": {
            "group": "com.example",
            "libraryName": "brownfield",
            "package": "com.example.brownfield",
            "version": "1.0.0"
          }
        }
      ]
    ]
  }
}

Configurable properties

Name	Default	Description
`ios.targetName`	`"<scheme>brownfield" or "<slug>brownfield"`	Only for: iOS brownfield 集成的 Xcode target 名称。这用于在你的 Xcode 项目中为 React Native 代码创建一个单独的 target。
`ios.bundleIdentifier`	`"<ios.bundleIdentifier base>.<targetName>" or "com.example.<targetName>"`	Only for: iOS brownfield target 的 bundle 标识符。它应当是唯一的，并且不同于你的主应用 bundle 标识符。
`ios.buildReactNativeFromSource`	`false`	Only for: iOS 从源码构建 React Native，而不是使用预构建框架。开启此项会显著增加构建时间。
`android.group`	`"<package without last segment>"`	Only for: Android 生成的 Android 库的 Maven group ID。将该库发布到 Maven 仓库时会使用此项。
`android.libraryName`	`"brownfield"`	Only for: Android 生成的 Android 库模块名称。
`android.package`	`"<android.package>.brownfield" or "com.example.brownfield"`	Only for: Android 生成的 Android 库代码的 Java/Kotlin 包名。
`android.version`	`"1.0.0"`	Only for: Android 生成的 Android 库的版本字符串。将其发布到 Maven 仓库时会使用此项。
`android.publishing`	`[{ type: "localMaven" }]`	Only for: Android 生成的 Android 库的发布配置。支持 `localMaven`、`localDirectory`、`remotePublic` 和 `remotePrivate` 发布类型。每种类型都有不同的配置选项，用于指定库发布的位置和方式。

CLI

expo-brownfield 库包含一个用于构建并发布到 Maven 仓库（Android）和 XCFrameworks（iOS）的 CLI。

Terminal

- npx expo-brownfield [command] [options]

命令

`build:android`

构建并发布 brownfield 库及其依赖到 Maven 仓库。

Terminal

- npx expo-brownfield build:android [options]

选项	描述
`-d, --debug`	以调试模式构建
`-r, --release`	以发布模式构建
`-a, --all`	同时以调试和发布模式构建（默认）
`-l, --library`	指定 brownfield 库名称
`--repo, --repository`	指定要发布到的 Maven 仓库
`-t, --task`	指定要运行的 Gradle 发布任务
`--verbose`	包含子进程的所有日志

`build:ios`

构建 brownfield XCFramework，并将 Hermes XCFramework 复制到 artifacts 目录。

Terminal

- npx expo-brownfield build:ios [options]

选项	描述
`-d, --debug`	以调试模式构建
`-r, --release`	以发布模式构建（默认）
`-a, --artifacts`	artifacts 目录的路径（默认：`./artifacts`）
`-s, --scheme`	要构建的 Xcode scheme
`-x, --xcworkspace`	Xcode workspace 路径
`-p, --package`	将 artifacts 作为 Swift Package 交付（可选指定名称）
`--verbose`	包含子进程的所有日志

`tasks:android`

列出所有可用的发布任务和 Maven 仓库。

Terminal

- npx expo-brownfield tasks:android

API

import * as Brownfield from 'expo-brownfield';

Hooks

`useSharedState(key, initialValue)`

Android

iOS

Parameter	Type	Description
key	`string`	The key to get the value for.
initialValue(optional)	`T`	The initial value to be used if the shared state is not set.

Hook to observe and set the value of shared state for a given key. Provides a synchronous API similar to useState.

Returns:

[T | undefined, (value: T | (prev: T | undefined) => T) => void]

A tuple containing the value and a function to set the value.

Methods

`Brownfield.deleteSharedState(key)`

Android

iOS

Parameter	Type	Description
key	`string`	The key to delete the shared state for.

Deletes the shared state for a given key.

Returns:

void

`Brownfield.getMessageListenerCount()`

Android

iOS

Gets the number of registered message listeners.

Returns:

number

The number of active message listeners.

`Brownfield.getSharedStateValue(key)`

Android

iOS

Parameter	Type	Description
key	`string`	The key to get the value for.

Gets the value of shared state for a given key.

Returns:

T | undefined

`Brownfield.popToNative(animated)`

Android

iOS

Parameter	Type	Description
animated(optional)	`boolean`	Whether to animate the transition (iOS only). Defaults to `false`. Default:`false`

Navigates back to the native part of the app, dismissing the React Native view.

Returns:

void

`Brownfield.sendMessage(message)`

Android

iOS

Parameter	Type	Description
message	`Record<string, any>`	A dictionary containing the message payload to send to native.

Sends a message to the native side of the app. The message can be received by setting up a listener in the native code.

Returns:

void

`Brownfield.setNativeBackEnabled(enabled)`

Android

iOS

Parameter	Type	Description
enabled	`boolean`	Whether to enable native back button handling.

Enables or disables the native back button behavior. When enabled, pressing the back button will navigate back to the native part of the app instead of performing the default React Navigation back action.

Returns:

void

`Brownfield.setSharedStateValue(key, value)`

Android

iOS

Parameter	Type	Description
key	`string`	The key to set the value for.
value	`T`	The value to be set.

Sets the value of shared state for a given key.

Returns:

void

Event subscriptions

`Brownfield.addMessageListener(listener)`

Android

iOS

Parameter	Type	Description
listener	`Listener<MessageEvent>`	A callback function that receives message events from native.

Adds a listener for messages sent from the native side of the app.

Returns:

EventSubscription

A subscription object that can be used to remove the listener.

Example

const subscription = addMessageListener((event) => {
  console.log('Received message from native:', event);
});

// Later, to remove the listener:
subscription.remove();

`Brownfield.addSharedStateListener(key, callback)`

Android

iOS

Parameter	Type	Description
key	`string`	The key to add the listener for.
callback	`(event: SharedStateChangeEvent<T> \| undefined) => void`	The callback to be called when the shared state changes.

Adds a listener for changes to the shared state for a given key.

Returns:

EventSubscription

A subscription object that can be used to remove the listener.

`Brownfield.removeAllMessageListeners()`

Android

iOS

Removes all message listeners.

Returns:

void

`Brownfield.removeMessageListener(listener)`

Android

iOS

Parameter	Type	Description
listener	`Listener<MessageEvent>`	The listener function to remove.

Removes a specific message listener.

Returns:

void

Interfaces

`EventSubscription`

Android

iOS

A subscription object that allows to conveniently remove an event listener from the emitter.

EventSubscription Methods

`remove()`

Android

iOS

Removes an event listener for which the subscription has been created. After calling this function, the listener will no longer receive any events from the emitter.

Returns:

void

Types

`MessageEvent`

Android

iOS

Type: Record<string, any>