Expo Modules: Criando Módulos Nativos

Referência completa para construir módulos e views nativas usando a API de Módulos do Expo. Abrange Swift (iOS), Kotlin (Android) e TypeScript.

Quando Usar

• Criar um novo módulo ou view nativa do Expo
• Adicionar funcionalidades nativas (câmera, sensores, APIs do sistema) a um app Expo
• Empacotar SDKs de plataforma para uso no React Native
• Construir plugins de configuração que modificam arquivos de projeto nativos
• Adicionar suporte Android, Apple ou web a um módulo Expo existente
• Editar expo-module.config.json, plugins de configuração ou hooks de ciclo de vida

Referências

Consulte estes recursos conforme necessário:

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

Início Rápido

Prefira create-expo-module em vez de criar manualmente arquivos e diretórios de módulos nativos. Na prática, o melhor caminho geralmente é criar o "esqueleto" primeiro e depois construir sobre ele. O esqueleto configura o layout esperado, expo-module.config.json, arquivos podspec ou Gradle, bindings TypeScript e o fluxo do app de exemplo independente.

Se um módulo Expo existente só precisa de outra plataforma, use create-expo-module add-platform-support em vez de copiar manualmente diretórios nativos.

Veja references/create-expo-module.md antes de criar o esqueleto ou estender um módulo. Ele cobre:

• módulos locais vs. independentes
• --platform, --features, --barrel, --package-manager e modo não interativo
• expo.autolinking.nativeModulesDir
• comportamento e peculiaridades do add-platform-support

Fluxo de Trabalho Recomendado

1. Escolha o tipo de esqueleto primeiro:
   • Módulo Local para um único app
   • Módulo Independente para reutilização, monorepos ou publicação
2. Determine as funcionalidades nativas do expo-module que você precisará.
   • Com base nas instruções do usuário, determine qual funcionalidade do esqueleto será útil.
   • Funcionalidades disponíveis: Constant, Function, AsyncFunction, Event, View, ViewEvent, SharedObject
3. Crie o esqueleto deliberadamente:
   • passe um slug ou caminho explícito
   • escolha --platform intencionalmente em vez de depender dos padrões
   • use --features para escolher exemplos de código que você modificará na próxima etapa para corresponder à implementação real.
4. Substitua o código de exemplo gerado pela implementação real.
5. Se você adicionar uma nova plataforma posteriormente, prefira add-platform-support em vez de copiar arquivos manualmente.

Regras Práticas de Criação de Esqueletos

• Exemplos de funcionalidades são opt-in. Um módulo recém-criado pode ser mínimo se nenhuma funcionalidade foi selecionada.
• ViewEvent implica View.
• Módulos locais não geram um barril index.ts por padrão. Use --barrel apenas se desejar um.
• Na criação de esqueletos locais não interativos, passe o slug ou caminho posicional explicitamente. --name altera o nome da classe nativa, não o nome da pasta.
• Módulos locais residem em expo.autolinking.nativeModulesDir quando configurados, caso contrário, em modules/.
• Módulos independentes têm seus próprios metadados de pacote, scripts e geralmente um app de exemplo. Módulos locais usam as ferramentas do app host em vez disso.

Estrutura de Arquivos Principais

O DSL Swift e Kotlin compartilham a mesma estrutura. Swift geralmente é o exemplo primário mais claro; consulte as referências para detalhes específicos de funcionalidades.

Referência de Estrutura de Módulos

O DSL Swift e Kotlin compartilham a mesma estrutura. Ambas as plataformas são mostradas aqui para referência — em outros arquivos de referência, Swift é mostrado como a linguagem primária, a menos que o padrão Kotlin difira significativamente.

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() {

…