expo-module

编写 Expo Modules

使用 Expo Modules API 构建原生模块和视图的完整参考。涵盖 Swift（iOS）、Kotlin（Android）和 TypeScript。

适用场景

• 创建新的 Expo 原生模块或原生视图
• 为 Expo 应用添加原生功能（相机、传感器、系统 API）
• 封装平台 SDK，供 React Native 使用
• 构建用于修改原生项目文件的配置插件
• 为现有 Expo 模块添加 Android、Apple 或 Web 支持
• 编辑 expo-module.config.json、配置插件或生命周期钩子

若要将现有 Swift 模块从定义 DSL 迁移到 Expo Modules API 2.0 宏（@ExpoModule、@JS、@Event），请改用 expo-migrate-module 技能（来自 expo-experiments 插件）。

参考资料

按需查阅以下资源：

references/
  create-expo-module.md      Scaffolding and add-platform-support workflow, defaults, and quirks
  native-module.md           Module definition DSL: Name, Function, AsyncFunction, Property, Constant, Events, type system, shared objects
  native-view.md             Native view components: View, Prop, EventDispatcher, view lifecycle, ref-based functions
  lifecycle.md               Lifecycle hooks: module, iOS app/AppDelegate, Android activity/application listeners
  config-plugin.md           Config plugins: modifying Info.plist, AndroidManifest.xml, reading values in native code
  module-config.md           expo-module.config.json fields, file placement, and autolinking behavior

快速开始

相比手动创建原生模块文件和目录，优先使用 create-expo-module。实际上，最佳做法通常是先创建脚手架，再在此基础上构建。脚手架会设置预期的目录结构、expo-module.config.json、podspec 或 Gradle 文件、TypeScript 绑定，以及独立示例应用的流程。

如果现有 Expo 模块只需添加另一个平台，请使用 create-expo-module add-platform-support，不要手动复制原生目录。

在创建或扩展模块之前，请参阅 references/create-expo-module.md。其中介绍了：

• 本地模块与独立模块
• --platform、--features、--barrel、--package-manager 和非交互模式
• expo.autolinking.nativeModulesDir
• add-platform-support 的行为和注意事项

推荐工作流

1. 首先选择脚手架类型：
   • 本地模块，用于单个应用
   • 独立模块，用于复用、monorepo 或发布
2. 确定需要的原生 expo-module 功能。
   • 根据用户的说明，确定哪些功能脚手架会有帮助。
   • 可用功能：Constant、Function、AsyncFunction、Event、View、ViewEvent、SharedObject
3. 有意选择脚手架选项：
   • 明确传入 slug 或路径
   • 有意选择 --platform，不要依赖默认值
   • 使用 --features 选择代码示例，并在下一步修改这些示例以匹配实际实现。
4. 将生成的示例代码替换为实际实现。
5. 如果之后添加新平台，优先使用 add-platform-support，不要手动复制文件。

实用脚手架规则

• 功能示例为可选项。如果未选择任何功能，新建的模块可能只有最基本的内容。
• ViewEvent 隐含 View。
• 本地模块默认不会生成 index.ts 聚合文件。只有需要时才使用 --barrel。
• 在非交互式本地脚手架中，请明确传入位置参数 slug 或路径。--name 会更改原生类名，而不是文件夹名称。
• 如果已配置 expo.autolinking.nativeModulesDir，本地模块会放在该目录中；否则会放在 modules/ 中。
• 独立模块拥有自己的包元数据、脚本，通常还包含一个示例应用。本地模块则使用宿主应用的工具。

核心文件结构

Swift 和 Kotlin DSL 采用相同的结构。Swift 通常是最清晰的主要示例；有关特定功能的详细信息，请参阅参考资料。

模块结构参考

Swift 和 Kotlin DSL 采用相同的结构。此处展示了这两个平台以供参考；在其他参考文件中，除非 Kotlin 模式有显著差异，否则主要使用 Swift 进行说明。

Swift（iOS）：

import ExpoModulesCore

public class MyModule: Module {
  public func definition() -> ModuleDefinition {
    Name("MyModule")

    Function("hello") { (name: String) -> String in
      return "Hello \(name)!"
    }
  }
}

Kotlin（Android）：

package expo.modules.mymodule

import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition

class MyModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("MyModule")

    Function("hello") { name: String ->
      "Hello $name!"
    }
  }
}

TypeScript：

import { requireNativeModule } from "expo";

const MyModule = requireNativeModule("MyModule");

export function hello(name: string): string {
  return MyModule.hello(name);
}

expo-module.config.json

{
  "platforms": ["android", "apple"],
  "apple": {
    "modules": ["MyModule"]
  },
  "android": {
    "modules": ["expo.modules.mymodule.MyModule"]
  }
}

注意：iOS 只使用类名；Android 使用完全限定类名（包名 + 类名）。有关所有字段，请参阅 references/module-config.md。

提交反馈

如果你在此技能中发现错误、误导性信息或过时信息，请进行报告，以便 Expo 改进：

npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-module" "<actionable feedback>"

仅在有具体且可执行的内容需要报告时提交。请尽可能提供相关背景信息。 如果 Agent 在 Expo 任务中反复失败，或用户不得不介入，请使用 --category evals，并将相关的 Expo 包或命令作为 --subject，简要报告任务、预期结果以及出现的问题。