Expo 棕地

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

Android

iOS

GitHub

npm

更新日志

Recommended version:

~56.0.29

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

// 稍后，移除监听器：
BrownfieldMessaging.removeListener(listenerId)

import ExpoBrownfield

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

// 稍后，移除监听器：
BrownfieldMessaging.removeListener(id: listenerId)

app 配置中的配置

expo-brownfield 包提供了一个配置插件，可在使用 Continuous Native Generation (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 目标名称。这会在你的 Xcode 项目中创建一个单独的目标来承载 React Native 代码。
`ios.bundleIdentifier`	`"<ios.bundleIdentifier base>.<targetName>" or "com.example.<targetName>"`	Only for: iOS brownfield 目标的 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 库包含一个 CLI，用于构建并发布到 Maven 仓库（Android）和 XCFrameworks（iOS）。

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 复制到产物目录。

Terminal

- npx expo-brownfield build:ios [options]

选项	描述
`-d, --debug`	以调试模式构建
`-r, --release`	以发布模式构建（默认）
`-a, --artifacts`	产物目录的路径（默认：`./artifacts`）
`-s, --scheme`	要构建的 Xcode scheme
`-x, --xcworkspace`	Xcode workspace 路径
`-p, --package`	将产物作为 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	`(value: 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>