创建和使用配置插件

了解如何在 Expo 项目中创建和使用配置插件。

本指南涵盖了如何创建配置插件、如何向配置插件传递参数以及如何将多个配置插件串联在一起的章节。它还介绍了如何使用来自 Expo 库的配置插件。

🌐 This guide covers sections on how to create a config plugin, how to pass parameters to a config plugin, and how to chain multiple config plugins together. It also covers how to use a config plugin from an Expo library.

在本指南中，通过下图，你将了解配置插件层次结构的前两部分：

🌐 Using the diagram below, in this guide, you will learn the first two parts of the config plugin hierarchy:

信息 注意： 以下部分使用动态 应用配置（app.config.js/app.config.ts 而不是 app.json），对于使用简单配置插件来说并非必需。然而，当你想创建/使用接受参数的基于函数的配置插件时，则需要使用动态应用配置。

创建配置插件

🌐 Creating a config plugin

在以下部分中，让我们创建一个本地配置插件，为Android的 AndroidManifest.xml 和iOS的 Info.plist 添加一个任意属性 HelloWorldMessage。

🌐 In the following section, let's create a local config plugin that adds an arbitrary property HelloWorldMessage to the AndroidManifest.xml for Android and Info.plist for iOS.

此示例将创建并修改以下文件。要跟随操作，请在项目根目录下创建一个 plugins 文件夹，并在其中创建 withAndroidPlugin.ts、withIosPlugins.ts 和 withPlugin.ts 文件。

🌐 This example will create and modify the following files. To follow along, create a plugins directory in the root of your project, and inside it, create withAndroidPlugin.ts, withIosPlugins.ts, and withPlugin.ts files.

import { ConfigPlugin, withAndroidManifest } from 'expo/config-plugins';

const withAndroidPlugin: ConfigPlugin = config => {
  // Define a custom message
  const message = 'Hello world, from Expo plugin!';

  return withAndroidManifest(config, config => {
    const mainApplication = config?.modResults?.manifest?.application?.[0];

    if (mainApplication) {
      // Ensure meta-data array exists
      if (!mainApplication['meta-data']) {
        mainApplication['meta-data'] = [];
      }

      // Add the custom message as a meta-data entry
      mainApplication['meta-data'].push({
        $: {
          'android:name': 'HelloWorldMessage',
          'android:value': message,
        },
      });
    }

    return config;
  });
};

export default withAndroidPlugin;

import { ConfigPlugin, withInfoPlist } from 'expo/config-plugins';

const withIosPlugin: ConfigPlugin = config => {
  // Define the custom message
  const message = 'Hello world, from Expo plugin!';

  return withInfoPlist(config, config => {
    // Add the custom message to the Info.plist file
    config.modResults.HelloWorldMessage = message;
    return config;
  });
};

export default withIosPlugin;

import { ConfigPlugin } from 'expo/config-plugins';
import withAndroidPlugin from './withAndroidPlugin';
import withIosPlugin from './withIosPlugin';

const withPlugin: ConfigPlugin = config => {
  // Apply Android modifications first
  config = withAndroidPlugin(config);
  // Then apply iOS modifications and return
  return withIosPlugin(config);
};

export default withPlugin;

import 'tsx/cjs';

module.exports = () => {
  %%placeholder-start%%... rest of your app config %%placeholder-end%%
};

import "tsx/cjs";
import { ExpoConfig } from "expo/config";

module.exports = ({ config }: { config: ExpoConfig }) => {
  %%placeholder-start%%... rest of your app config %%placeholder-end%%
  plugins: [
      ["./plugins/withPlugin.ts"],
    ],
};

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<!-- ... rest of the configuration-->
	<application ...>
		<meta-data android:name="HelloWorldMessage" android:value="Hello world, from Expo plugin!"/>
		<!-- ... -->
	</application>
</manifest>

<plist version="1.0">
  <dict>
  <!-- ... -->
    <key>HelloWorldMessage</key>
    <string>Hello world, from Expo plugin!</string>
	<!-- ... -->
	</dict>
</plist>

向配置插件传递参数

🌐 Passing a parameter to a config plugin

你的配置插件可以接受从应用配置传入的参数。要实现这一点，你需要在配置插件函数中读取该参数，然后在应用配置中将包含该参数的对象与配置插件函数一起传入。

🌐 Your config plugin can accept parameters passed from your app config. To do so, you will need to read the parameter in your config plugin function, and then pass an object containing the parameter along with the config plugin function in your app config.

%%placeholder-start%%...%%placeholder-end%%
type AndroidProps = {
  message?: string;
};

const withAndroidPlugin: ConfigPlugin<AndroidProps> = (
  config,
  options = {}
) => {
  const message = options.message || 'Hello world, from Expo plugin!';
  return withAndroidManifest(config, config => {
   %%placeholder-start%%... rest of the example remains unchanged %%placeholder-end%%
  });
};

export default withAndroidPlugin;

%%placeholder-start%%...%%placeholder-end%%
type IosProps = {
  message?: string;
};

const withIosPlugin: ConfigPlugin<IosProps> = (config, options = {}) => {
   const message = options.message || 'Hello world, from Expo plugin!';
  %%placeholder-start%%... rest of the example remains unchanged%%placeholder-end%%
};

export default withIosPlugin;

%%placeholder-start%%...%%placeholder-end%%
const withPlugin: ConfigPlugin<{ message?: string }> = (config, options = {}) => {
  config = withAndroidPlugin(config, options);
  return withIosPlugin(config, options);
};

{
  %%placeholder-start%%...%%placeholder-end%%
  plugins: [
    [
      "./plugins/withPlugin.ts",
      { message: "Custom message from app.config.ts" },
    ],
  ],
}

链式配置插件

🌐 Chaining config plugins

配置插件可以串联使用以应用多个修改。链中的每个插件按照它出现的顺序运行，一个插件的输出会成为下一个插件的输入。这种顺序执行确保插件之间的依赖得到尊重，并允许你控制对原生代码修改的确切顺序。

🌐 Config plugins can be chained together to apply multiple modifications. Each plugin in the chain runs in the order it appears, with the output of one plugin becoming the input for the next. This sequential execution ensures that dependencies between plugins are respected and allows you to control the precise order of modifications to your native code.

要链接配置插件，你可以将插件数组传递给应用配置中的 plugins 数组属性。在 JSON 应用配置文件格式（app.json）中也支持这种用法。

🌐 To chain config plugins, you can pass an array of plugins to the plugins array property in your app config. This is also supported in JSON app config file format (app.json).

module.exports = ({ config }: { config: ExpoConfig }) => {
  name: 'my app',
  plugins: [
    [withFoo, 'input 1'],
    [withBar, 'input 2'],
    [withDelta, 'input 3'],
  ],
};

plugins 数组在底层使用 withPlugins 方法来连接插件。如果你的插件数组变得很长或配置复杂，你可以直接使用 withPlugins 方法来让配置更易读。withPlugins 会将插件串联在一起并按顺序执行。

🌐 The plugins array uses withPlugins method under the hood to chain the plugins. If your plugins array is getting long or has complex configuration, you can use the withPlugins method directly to make your configuration easier to read. withPlugins will chain the plugins together and execute them in order.

import { withPlugins } from 'expo/config-plugins';

// Create a base config object
const baseConfig = {
  name: 'my app',
  %%placeholder-start%%... rest of the config %%placeholder-end%%
};

// ❌ Hard to read
withDelta(withFoo(withBar(config, 'input 1'), 'input 2'), 'input 3');

// ✅ Easy to read
withPlugins(config, [
  [withFoo, 'input 1'],
  [withBar, 'input 2'],
  // When no input is required, you can just pass the method
  withDelta,
]);

// Export the base config with plugins applied
module.exports = ({ config }: { config: ExpoConfig }) => {
  return withPlugins(baseConfig, plugins);
};

使用配置插件

🌐 Using a config plugin

Expo 配置插件通常包含在 Node.js 模块中。你可以像安装项目中的其他库一样安装它们。

🌐 Expo config plugins are usually included in Node.js modules. You can install them just like other libraries in your project.

例如，expo-camera 有一个插件，可以向 AndroidManifest.xml 和 Info.plist 添加相机权限。要将其安装到你的项目中，请运行以下命令：

🌐 For example, expo-camera has a plugin that adds camera permissions to the AndroidManifest.xml and Info.plist. To install it in your project, run the following command:

在你的应用配置中，你可以将 expo-camera 添加到插件列表中：

🌐 In your app config, you can add expo-camera to the list of plugins:

{
  "expo": {
    "plugins": ["expo-camera"]
  }
}

一些配置插件通过允许你传递选项来自定义其配置，从而提供灵活性。为此，你可以传递一个数组，将 Expo 库名称作为第一个参数，将包含选项的对象作为第二个参数。例如，expo-camera 插件允许你自定义相机权限提示信息：

🌐 Some config plugins offer flexibility by allowing you to pass options to customize their configuration. To do this, you can pass an array with the Expo library name as the first argument, and an object containing the options as the second argument. For example, the expo-camera plugin allows you to customize the camera permission message:

{
  "expo": {
    "plugins": [
      [
        "expo-camera",
        {
          "cameraPermission": "Allow $(PRODUCT_NAME) to access your camera."
        }
      ]
    ]
  }
}

信息 提示：对于每个拥有配置插件的 Expo 库，你可以在该库的 API 参考中找到更多相关信息。例如，expo-camera 库有一个配置插件部分。

运行 npx expo prebuild 时，mods 会被编译，本地文件会发生变化。

🌐 On running the npx expo prebuild, the mods are compiled, and the native files change.

这些更改在你重建本地项目之前不会生效，例如使用 Xcode。如果你在没有本地目录的项目（CNG 项目）中使用配置插件，它们将在 EAS 构建的预构建步骤中应用，或者在本地运行 npx expo prebuild|android|ios 时应用。

🌐 The changes don't take effect until you rebuild the native project, for example, with Xcode. If you're using config plugins in a project without native directories (CNG projects), they will be applied during the prebuild step in EAS Build or when running npx expo prebuild|android|ios locally.