如何编写Expo原生模块：Expo Skills的expo-module Swift、Kotlin与配置插件完整参考

如何编写Expo原生模块Expo Skills的expo-module Swift、Kotlin与配置插件完整参考【免费下载链接】skillsA collection of AI agent skills for working with Expo projects and Expo Application Services项目地址: https://gitcode.com/gh_mirrors/skills9/skillsExpo Skills是 Expo 官方出品的 AI 技能集其中expo-module技能专门指导开发者编写Expo 原生模块用SwiftiOS、KotlinAndroid和TypeScript打通 JS 与原生代码并支持配置插件Config Plugins自动修改原生工程文件。无论你想接入相机、传感器还是封装第三方 SDK这份参考都能帮你少走弯路 为什么需要 Expo 原生模块纯 JavaScript 无法直接调用系统 API。当你需要访问设备硬件、封装平台 SDK、或修改 Info.plist / AndroidManifest.xml 时就需要写一个 Expo 原生模块。expo-module技能的完整资料位于 plugins/expo/skills/expo-module/核心文档包括模块定义 DSL函数、常量、事件、类型系统native-module.md原生视图把 iOS UIView / Android View 变成 React 组件native-view.md生命周期钩子lifecycle.md配置插件config-plugin.md模块注册与自动链接module-config.md快速开始用 create-expo-module 一键脚手架⚠️最佳实践不要手动创建模块文件优先使用create-expo-module生成脚手架它会自动配置好目录结构、expo-module.config.json、Podspec/Gradle 文件和 TypeScript 绑定。先选脚手架类型再执行命令类型适用场景本地模块Local原生代码只服务于当前一个 App放在modules/目录独立模块Standalone需要跨应用复用、放在 monorepo 或发布到 npm本地模块示例npx create-expo-modulelatest key-value-store --local --platform apple android --features Function AsyncFunction常用选项速查详见 create-expo-module.md选项说明--platform目标平台apple、android、web--features生成示例代码Constant、Function、AsyncFunction、Event、View、ViewEvent、SharedObject--name原生模块类名不是目录名--full-example等价于--features all已有模块想新增平台时使用add-platform-support子命令而不是手动复制原生目录。Swift 与 Kotlin 模块结构一套 DSL两种写法Expo Modules API 的核心思想是用definition()方法声明式地描述模块Swift 与 Kotlin 共享同一套 DSL 结构。SwiftiOS——一个最小模块长这样public class MyModule: Module { public func definition() - ModuleDefinition { Name(MyModule) Function(hello) { (name: String) - String in return Hello \(name)! } } }KotlinAndroid——同样结构class MyModule : Module() { override fun definition() ModuleDefinition { Name(MyModule) Function(hello) { name: String - Hello $name! } } }TypeScript 侧通过requireNativeModule即可调用const MyModule requireNativeModule(MyModule);常用 DSL 能力一览DSL作用注意点Function同步函数会阻塞 JS 线程最多 8 个参数AsyncFunction异步函数返回 Promise默认后台线程执行Kotlin 版支持协程Constant只读常量首次访问时计算并缓存Property可读写的 JS 属性支持.get/.setEvents声明可发送给 JS 的事件必须先声明才能sendEventSharedObject把原生对象桥接到 JS自动生命周期管理两端都无引用时自动释放类型系统方面Swift/Kotlin 的原生类型会自动映射到 JSBool→boolean、String→string、UIColor/Color→颜色字符串、Data→Uint8Array还支持Record结构化对象、Enumerable枚举和Either联合类型。完整映射表见 native-module.md。原生视图把平台 UI 变成 React 组件如果模块需要渲染界面用ViewDSL 把ExpoView子类注册为 React 组件iOS继承ExpoViewUIViewAndroid继承ExpoViewAndroid View通过Prop同步属性、EventDispatcher派发事件、AsyncFunction提供可通过 React ref 调用的方法OnViewDidUpdateProps钩子在所有 props 设置完成后触发Android 还提供PropGroup批量注册属性和GroupView管理子视图。完整示例见 native-view.md。 小建议只有模块真的需要渲染 UI 时才选View特性纯功能模块不要生成多余的视图文件。生命周期钩子在正确的时机做正确的事模块内可直接声明生命周期回调无需侵入 AppDelegate 或 Activity 代码模块级OnCreate、OnDestroy、OnAppContextDestroysiOS前后台切换OnAppEntersForeground/OnAppEntersBackground深度集成可用ExpoAppDelegateSubscriberAndroidActivity 生命周期OnActivityEntersForeground/OnActivityDestroys、深链接OnNewIntent、startActivityForResult回调等详见 lifecycle.md。expo-module.config.json自动链接的关键expo-module.config.json是模块注册与自动链接Autolinking的核心{ platforms: [android, apple], apple: { modules: [MyModule] }, android: { modules: [expo.modules.mymodule.MyModule] } }⚠️易错点iOS 只写类名Android 必须写完全限定类名包名 类名。有了这个文件Expo 会自动发现并链接模块——安装依赖后执行pod install即可无需手动修改任何原生工程配置。字段说明与解析顺序见 module-config.md。配置插件让 npx expo prebuild 自动改原生工程配置插件是同步函数接收ExpoConfig并返回修改后的配置典型用途是在npx expo prebuild时自动写入 API Key 等配置iOS用withInfoPlist修改 Info.plistAndroid用withAndroidManifest修改 AndroidManifest.xml然后在app.json的expo.plugins中注册插件并传参原生代码再通过Bundle.mainSwift或metaDataKotlin读取这些值规则要点插件必须同步执行Mods才是 prebuild 同步阶段的异步函数修改后用npx expo prebuild --clean验证。完整写法见 config-plugin.md。推荐工作流五步写出规范的 Expo 原生模块选类型单一应用选 Local复用/发布选 Standalone定特性确定需要哪些--featuresFunction、AsyncFunction、Event、View…跑脚手架显式传入 slug/路径主动指定--platform不要依赖默认值替换示例代码把生成的样板代码换成真实实现扩平台后续加平台一律用add-platform-support不手动拷贝 补充如果要把旧的 Swift 定义 DSL 迁移到 Expo Modules API 2.0 宏ExpoModule、JS、Event请改用实验插件中的expo-migrate-module技能见 plugins/expo-experiments/。常见问题排查问题排查方向JS 侧拿到undefined检查expo-module.config.json中 Android 是否用了完全限定类名事件收不到确认先Events(...)声明、再sendEvent发送模块没有被链接独立模块放包根目录本地模块放modules/或nativeModulesDir同步函数卡住 UI改用AsyncFunction它默认在后台线程执行总结Expo Skills 的expo-module技能覆盖了编写 Expo 原生模块的完整链路脚手架生成 → Swift/Kotlin DSL 定义 → 原生视图 → 生命周期 → 自动链接 → 配置插件。掌握create-expo-module脚手架和definition()DSL 这两件武器你就能快速为 App 接入任何原生能力。更多官方技能EAS 构建、上架、OTA 更新等可在 plugins/expo/README.md 中一览。【免费下载链接】skillsA collection of AI agent skills for working with Expo projects and Expo Application Services项目地址: https://gitcode.com/gh_mirrors/skills9/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考