Skip to content

6. Capítulo 5 - Portabilidade do aplicativo Flutter para mobile, desktop e web

6.1. Um único código-fonte, vários alvos de compilação

Este é o núcleo deste capítulo e a razão de ser desta variante do curso: NENHUMA linha do Capítulo 4 ([lib/], [pubspec.yaml], [assets/]) muda, qualquer que seja o alvo escolhido. “Portar” o aplicativo aqui consiste simplesmente em escolher um COMANDO DE COMPILAÇÃO diferente ([flutter run -d <target>] ou [flutter build <target>])—nunca em escrever, duplicar ou adaptar widgets. Isso é muito diferente do que um port exigiria com as ferramentas abordadas no restante deste curso: um cliente [Vue.js]/[React]/[Angular] só roda NATIVAMENTE em um navegador—portá-lo para mobile exige uma ferramenta de TERCEIROS ([Cordova]/[Capacitor], não usada neste curso) que o empacota em um invólucro nativo contendo, na realidade, um navegador embutido (uma [WebView]): o código permanece inalterado, mas AINDA ASSIM não é um executável nativo, ao contrário do que [Flutter] produz aqui para mobile e desktop (veja o Capítulo 3, “O que o Flutter não é”).

Os seis alvos ([Android], [iOS], [macOS], [Windows], [Linux], [web]) estão habilitados POR PADRÃO em qualquer projeto criado com [flutter create] desde o [Flutter 3] (veja o Capítulo 1) - Nenhuma configuração é necessária no projeto para adicionar um deles. As únicas diferenças de um alvo para outro são: as ferramentas de compilação nativas instaladas na máquina de desenvolvimento ([Xcode], [Visual Studio], [GTK]...), o comando exato executado e—apenas para mobile—um detalhe de configuração de rede descrito mais adiante neste capítulo.

6.2. Alvo web

O alvo já usado no Capítulo 2 ([flutter run -d chrome]). Dois comandos bastam:

flutter run -d chrome              # desenvolvimento, com hot reload
flutter build web                  # build de produção, em build/web/

[flutter build web] gera uma pasta [build/web/] autônoma ([index.html], [JavaScript], ou [WebAssembly] compilado, recursos) - para ser implantada em QUALQUER servidor web estático ([Nginx], [Apache], um simples [npx serve]....), exatamente como a pasta [dist/] gerada por [npm run build] no lado [Vue.js]/[Vite]. Este build continua sendo um arquivo [JavaScript] servido a um navegador: portanto, continua dependendo de um servidor [NestJS] ALCANÇÁVEL a partir desse navegador, e, assim, de [app.enableCors()] (veja [src/main.ts] no servidor)—que já está ativo, sem nenhuma alteração necessária no servidor para este alvo.

Um ponto a observar, específico deste alvo: o campo “URL do servidor” na tela de login (veja [_ServerUrlField] em [lib/app.dart], Capítulo 4) deve então apontar para um endereço ALCANÇÁVEL a partir do navegador que executa o aplicativo—[http://localhost:8080] é aceitável desde que o servidor [NestJS] esteja rodando na MESMA máquina que o navegador.

6.3. Alvo desktop

Três sistemas operacionais, três conjuntos de ferramentas nativas pré-requisitos (veja o Capítulo 1), mas comandos [flutter] idênticos na forma:

1
2
3
4
5
6
7
flutter run -d macos               # macOS - requer o Xcode
flutter run -d windows              # Windows - requer o Visual Studio (C++ Desktop)
flutter run -d linux                # Linux - requer os pacotes de desenvolvimento do GTK

flutter build macos                 # build de produção
flutter build windows
flutter build linux

Cada comando [flutter build <target>] produz um executável nativo AUTÔNOMO ([.app] no macOS, [.exe] + suas bibliotecas no Windows, um binário [ELF] no Linux), em [build/<target>/]—um executável que, ao contrário do build web, não roda em NENHUM navegador nem em NENHUMA [WebView]: trata-se de código nativo executado diretamente no sistema operacional, com sua própria janela e barra de título, gerenciadas pelo próprio [Flutter] .

Este alvo não exige NENHUMA configuração de rede especial: um aplicativo desktop roda na mesma máquina do usuário e acessa [http://localhost:8080] exatamente como qualquer outro programa instalado nessa máquina faria (o campo “URL do servidor” da tela de login permite, como nos outros alvos, apontar para um servidor remoto, se necessário).

PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter devices    
Found 4 connected devices:
  sdk gphone16k x86 64 (mobile) • emulator-5554 • android-x64    • Android 17 (API 37) (emulator)
  Windows (desktop)             • windows       • windows-x64    • Microsoft Windows [version
  10.0.26200.9457]
  Chrome (web)                  • chrome        • web-javascript • Google Chrome 153.0.8010.48
  Edge (web)                    • edge          • web-javascript • Microsoft Edge 153.0.4234.48

Run "flutter emulators" to list and start any available device emulators.

If you expected another device to be detected, please run "flutter doctor" to diagnose potential issues. You
may also try increasing the time to wait for connected devices with the "--device-timeout" flag. Visit
https://flutter.dev/setup/ for troubleshooting tips.
PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter run -d windows

Isso produz o seguinte resultado:

Image

A tela acima não é de um navegador, mas de um aplicativo Windows. Para que isso funcione, certas ferramentas precisam estar disponíveis:

1
2
3
4
[√] Visual Studio - develop Windows apps (Visual Studio Build Tools 2026 18.9.0) [221ms]
    • Visual Studio at C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools
    • Visual Studio Build Tools 2026 version 18.9.12105.275
    • Windows 10 SDK version 10.0.26100.0

Para ter uma ideia clara do que está faltando no seu projeto Flutter, digite o seguinte comando:

flutter doctor -v

6.4. Emuladores como alvo

O aplicativo Flutter foi testado em um emulador Android:

PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter devices       
Found 4 connected devices:
  sdk gphone16k x86 64 (mobile) • emulator-5554 • android-x64    • Android 17 (API 37) (emulator)
  Windows (desktop)             • windows       • windows-x64    • Microsoft Windows [version
  10.0.26200.9457]
  Chrome (web)                  • chrome        • web-javascript • Google Chrome 153.0.8010.48
  Edge (web)                    • edge          • web-javascript • Microsoft Edge 153.0.4234.48

...
PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter run -d emulator-554

O resultado no emulador:

Image

  • Observe a URL em [1];

Fazer login com admin / admin produz o seguinte resultado:

Image

Preencha o formulário e envie:

Image

Acima está o horário que reservamos usando o aplicativo web.

6.5. Alvo mobile

Nota: o revisor não testou esta seção.

Esta é a área que exige mais atenção, devido a um detalhe específico da rede do emulador/simulador.

1
2
3
4
5
6
7
8
9
flutter emulators                   # lista os emuladores Android configurados
flutter emulators --launch <id>     # inicia um emulador Android
open -a Simulator                   # inicia um simulador iOS (somente macOS)

flutter run -d <emulator-or-device-id>

flutter build apk                   # build Android (.apk), ou:
flutter build appbundle             # build Android para a Play Store (.aab)
flutter build ios                   # build iOS - requer macOS + Xcode + uma conta de desenvolvedor Apple para um dispositivo físico

6.5.1. A armadilha de rede específica do mobile: localhost deixa de se referir ao PC de desenvolvimento

Este é O detalhe a conhecer para este alvo, sem relação com o próprio [Flutter] : [localhost] (ou [127.0.0.1]), no campo “URL do servidor” da tela de login, SEMPRE se refere à máquina que executa o código - e um emulador/simulador mobile é uma máquina VIRTUAL DISTINTA da máquina de desenvolvimento onde o servidor ([NestJS]) está rodando, mesmo que as duas pareçam “estar no mesmo computador”.

  • Emulador [Android] (criado pelo [Android Studio]): use [http://10.0.2.2:8080]—um endereço especial, específico do emulador oficial [Android], que redireciona automaticamente para [localhost] na máquina hospedeira (o PC de desenvolvimento).
  • Simulador [iOS] (somente macOS): [http://localhost:8080] funciona diretamente, pois o simulador [iOS] compartilha a rede da máquina hospedeira (ao contrário do emulador [Android]).
  • Dispositivo físico ([Android] ou [iOS], conectado à mesma rede Wi-Fi do PC de desenvolvimento): use o endereço [IP] LOCAL deste PC nesta rede (por exemplo, [http://192.168.1.42:8080]), nunca [localhost] nem [10.0.2.2], pois ambos se referem ao próprio dispositivo móvel nesse caso.

6.5.2. Duas restrições adicionais específicas do dispositivo móvel

  • O [Android] (desde a API 28) bloqueia por padrão todo o tráfego [HTTP] em TEXTO CLARO (não criptografado com [https://])—como o servidor deste curso escuta em [HTTP] em modo simples, um aplicativo [Android] PRONTO PARA PRODUÇÃO deveria declarar uma exceção explícita ([android:usesCleartextTraffic="true"] no manifesto [Android] gerado, ou uma configuração de segurança de rede mais granular)—uma configuração nativa, em [android/], fora do código [Dart] apresentado neste documento.
  • O [iOS] impõe uma política comparável, o [App Transport Security] ([ATS]), que também bloqueia por padrão o [HTTP] em texto simples—uma exceção equivalente é declarada em [ios/Runner/Info.plist] ([NSAppTransportSecurity], [NSAllowsArbitraryLoads]ou, de forma mais específica, uma exceção direcionada apenas ao domínio do servidor de desenvolvimento).

Essas duas configurações se aplicam SOMENTE ao desenvolvimento/demonstração com um servidor [HTTP] não criptografado, como o usado neste curso—uma implantação real em produção exporia, em vez disso, o próprio servidor [NestJS] em [https://] (por exemplo, atrás de um [reverse proxy] como o [Nginx]), o que tornaria essas duas exceções desnecessárias.

6.5.3. Uma tela mais estreita: a armadilha do layout

Uma última diferença específica dos dispositivos móveis nada tem a ver com a rede: um celular em orientação retrato tem apenas cerca de 360 pixels de largura (em pixels lógicos do [Flutter]), contra várias centenas a mais em um navegador ou em uma janela desktop. Uma tela projetada para um monitor grande pode, portanto, se tornar inutilizável em um celular: foi isso que aconteceu com a primeira versão do cliente deste documento, testada em um emulador [Android]. O seletor de médico/dia/botão ([doctor_day_picker.dart]) alinhava três campos em uma única [Row], e a barra de título ([app.dart]) exibia tudo de uma vez: foi preciso colocar o emulador em modo paisagem para ver tudo. O Capítulo 4 mostra a correção. Duas regras decorrem disso:

  • Nunca presuma uma largura. Para escolher um layout, verifique a largura realmente disponível—seja em um ponto específico da árvore usando [LayoutBuilder] ([constraints.maxWidth]), seja para a tela inteira com [MediaQuery.sizeOf(context).width]—e então escolha [Row] (tela larga) ou [Column] (tela estreita).
  • Teste cedo em uma tela estreita: use o emulador em modo retrato ou uma janela do [Chrome] que você redimensiona para ficar mais estreita. No modo de depuração, o [Flutter] indica que o conteúdo está largo demais com uma faixa amarela e preta com o texto “RIGHT OVERFLOWED BY … PIXELS” no aplicativo, além de uma mensagem no console.

Isso não contradiz a observação a seguir: o layout se adapta com base no TAMANHO da tela, nunca na plataforma—nenhum [if (kIsWeb)] aparece. Estreitar uma janela de navegador ou de desktop aciona exatamente o mesmo layout “estreito” que um celular.

6.6. Tabela-resumo

  • [web] — [flutter run -d chrome] / [flutter build web] — compilado para [JavaScript]/[WebAssembly], executado por um navegador — URL do servidor: [localhost] (mesma máquina).
  • [desktop] (macOS/Windows/Linux) — [flutter run -d <os>] / [flutter build <os>] — compilação nativa [AOT], executável autônomo — URL do servidor: [localhost] (mesma máquina).
  • [mobile] (emulador Android) — [flutter run] — compilação nativa [AOT] — URL do servidor: [10.0.2.2] (endereço especial para o emulador).
  • [mobile] (simulador iOS) — [flutter run] — compilação nativa [AOT] — URL do servidor: [localhost] (rede compartilhada com o hospedeiro).
  • [mobile] (dispositivo físico) — [flutter run] — compilação nativa [AOT] — URL do servidor: endereço [IP] local do PC de desenvolvimento, + exceção [cleartext]/[ATS].

6.7. O que NÃO muda no código Dart

Para concluir este capítulo, vale enfatizar o que NÃO precisou ser escrito nem adaptado para cobrir essas três famílias de alvos: nenhuma condição [if (kIsWeb) { ... } else { ... }] aparece no Capítulo 4, nenhum arquivo [_mobile.dart]/[_web.dart] separado e nenhuma biblioteca de abstração adicional. As poucas escolhas já feitas no Capítulo 4 bastam, por si sós, para tornar este código portável entre as três famílias de alvos: [shared_preferences] (em vez de [localStorage], que é específico do navegador) para a persistência, [rootBundle.loadString(...)] (em vez de um [fetch] a um servidor web) para os dicionários de tradução embutidos, e o pacote [http] (em vez de uma API específica do navegador) para a rede. É exatamente o que a introdução deste documento prometia: [a single Flutter codebase is enough to build a mobile app, a desktop app and a web app].