Visualização de Página WebView
Na aula anterior, aprendemos onde fica a interface da nossa página. Vamos continuar os estudos nesta aula.
Entender a única visualização web nativa (WebView)
Todos os aplicativos móveis desenvolvidos com o NativePHP têm como núcleo uma única visualização web nativa (WebView). A WebView permite criar a interface do app com qualquer tecnologia frontend web que você domine. Como ela é basicamente uma página web, o navegador embutido é responsável por renderizar todo o conteúdo.
Por padrão, a WebView ocupa toda a área visível da tela. Ao abrir funcionalidades como câmera, a tela da câmera cobrirá temporariamente a WebView.
Fundamento do NativePHP: Backend PHP + desenvolvimento híbrido com qualquer stack frontend (Vue, jQuery, Tailwind e outros)
A WebView sempre é exibida em primeiro plano; apenas telas em tela cheia, como câmera ou navegador interno, a ocultam. Toda a interface visível ao usuário é renderizada pela WebView.
Arquitetura base do NativePHP Mobile: contêiner único de WebView, sem camadas nativas de múltiplas páginas. Ou seja, o NativePHP só tem uma página; todas as navegações e retornos são executados dentro da mesma WebView.
Um app móvel NativePHP contém sempre apenas um único controle nativo de WebView. Toda renderização de páginas do aplicativo fica dentro desse contêiner web:
- Troca de páginas, roteamento, voltar à página anterior, popups, subpáginas e alternância de SPA nunca criam uma segunda WebView. Essa estrutura reduz o consumo de memória.
- Não existe pilha de páginas nativas do Android/iOS nem hierarquia de Activity/ViewController;
- As “várias páginas” que vemos são apenas trocas de DOM dentro da mesma WebView via roteamento frontend (Laravel / Livewire / Vue Router etc.), com lógica idêntica aos SPA web tradicionais.
1 Configuração Viewport (tag meta para adaptação de tela)
Quem já desenvolveu sites móveis certamente conhece essa configuração.
Assim como um navegador comum, a WebView possui o conceito de Viewport (área de visualização), controlado por uma tag meta com sintaxe igual às páginas web tradicionais.
<meta name="viewport" content="width=device-width, initial-scale=1">Code language: HTML, XML (xml)Adicione essa tag meta no seu arquivo HTML ou Blade PHP. Atualmente quase todos os sites usam essa configuração para se adaptar a navegadores móveis. Sem ela, a renderização segue o padrão de computador: as fontes ficam finas e o layout fica distorcido, pois celulares possuem resolução DPI alta.
Você pode testar em qualquer site, por exemplo a documentação oficial do NativePHP: Web View – NativePHP mobile v3 – NativePHP. Clique com o botão direito na página e visualize o código fonte para ver a tag.
Essa configuração tem dois atributos principais:
width=device-width: A largura da página corresponde à largura física da tela do dispositivo
initial-scale=1: Escala inicial de renderização 1:1, sem zoom automático
2 Desabilitar zoom com dois dedos (simular experiência de app nativo)
Aplicativos nativos Android ou iOS não permitem ampliar/reduzir com dois dedos, diferente de navegadores móveis. Para deixar a interface do NativePHP similar a um app nativo, é preciso desativar esse gesto de zoom.
No desenvolvimento mobile, precisamos de controle total sobre a exibição; bloquear o zoom manual garante o mesmo comportamento de um aplicativo totalmente nativo.
Adicione o atributo abaixo na tag viewport:
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">Code language: HTML, XML (xml)user-scalable=no: Desativa gestos de zoom manual
3 Renderização até as bordas Edge-to-Edge (pré-requisito para notch e telas curvas)
Para maximizar a liberdade de design da interface, a WebView ocupa toda a tela por padrão. Com apenas HTML/CSS/JS você consegue posicionar conteúdos em qualquer local da tela principal.
Mas nem toda a superfície da tela é utilizável. A maioria dos dispositivos tem notch para câmera frontal, cantos arredondados, bordas curvas ou Dynamic Island no iPhone. Essas áreas fazem parte do viewport, mas ocultam conteúdo e não são clicáveis.
Para adaptar telas com formatos especiais, adicione viewport-fit=cover na tag meta viewport e combine com as margens de segurança (Safe Area Insets).
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no, viewport-fit=cover">Code language: HTML, XML (xml)viewport-fit=cover: Permite renderizar a página até as extremidades da tela (incluindo notch e cantos arredondados). Esse parâmetro sozinho não basta, pois o conteúdo ficará coberto pela notch; é obrigatório usá-lo junto aos estilos CSS de área segura, leia abaixo.
Áreas Seguras Safe Areas
As áreas seguras são as regiões visíveis não obstruídas da tela: não são cobertas por estruturas de hardware (cantos arredondados, notch da câmera, Dynamic Island) nem por interfaces permanentes do sistema (barra de gestos inferior, barra de status).
O dispositivo calcula automaticamente os limites das áreas seguras e ajusta dinamicamente ao alternar entre modo retrato e paisagem. O NativePHP disponibiliza variáveis CSS nativas para criar layouts adaptáveis para todos os aparelhos.
<!-- Aplicar restrição global de área segura no body -->
<body class="nativephp-safe-area">
<!-- Barra de navegação superior com margens laterais para cantos arredondados -->
<div class="fixed top-0 left-0 w-full bg-red-500 pl-[var(--inset-left)] pr-[var(--inset-right)]">
Barra de Navegação Superior
</div>
</body>Code language: HTML, XML (xml)--inset-top: Margem de segurança superior (altura da barra de status / notch)--inset-bottom: Margem de segurança inferior (altura da barra de gestos)--inset-left: Margem de segurança esquerda para telas curvas / cantos arredondados--inset-right: Margem de segurança direita para telas curvas / cantos arredondados
Essas variáveis CSS são integradas nativamente ao NativePHP Mobile e injetadas automaticamente pelo framework; não é necessário importar bibliotecas CSS externas.
Classe CSS global rápida: nativephp-safe-area
Basta adicionar essa classe no contêiner principal HTML: ela restringe todo o conteúdo automaticamente dentro das áreas seguras e simplifica o desenvolvimento, veja o exemplo acima.
Vamos comparar um exemplo sem adaptação de área segura com o modelo oficial para entender o princípio, depois testaremos em aparelho real. Segue o código sem configuração de área segura:
<div class="fixed top-0 left-0 w-full bg-red-500>
...
</div>
Na imagem, vemos que a barra de título superior é totalmente coberta pela notch da câmera frontal.
No modo paisagem o resultado é ainda pior, veja a imagem abaixo:
No modo paisagem, grandes espaços vazios aparecem nas laterais, a barra superior não ocupa toda a tela e o visual fica ruim.
Com a configuração de área segura, adicione a classe padrão na tag body:
<body class="nativephp-safe-area">
<div class="fixed top-0 left-0 w-full bg-red-500 pl-[var(--inset-left)] pr-[var(--inset-right)]">
...
</div>Code language: HTML, XML (xml)
A interface ocupa perfeitamente toda a tela e o visual melhora muito.
Editar Código
Vamos modificar o arquivo de exemplo da aula anterior: welcome.blade.php
Substitua todo o conteúdo dentro da tag body pelo código abaixo. Usamos o Tailwind, uma biblioteca de interface frontend similar ao Bootstrap.
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{{ config('app.name', 'Mimi') }} - Built with NativePHP ： welcome to foxdevelop.com</title>
</head>
<body>
<div class="fixed top-0 left-0 w-full bg-red-500">
Barra de Navegação Superior
</div>
</body>
</html>
Code language: HTML, XML (xml)Salve o arquivo, abra o prompt de comando na pasta do projeto e execute o comando abaixo:
php artisan native:jumpCode language: CSS (css)D:\phpproject\my-app>php artisan native:jumpCode language: CSS (css)
URL de pré-visualização: http://127.0.0.1:8000
A pré-visualização no navegador de computador não mostra o efeito de adaptação mobile; é necessário testar em aparelho real.
Depuração em Aparelho Real
O procedimento é igual ao desenvolvimento de apps Android: prepare um celular Android, conecte ao computador via cabo USB e ative o modo desenvolvedor no celular (você encontra o tutorial facilmente na internet). Também instale a ferramenta ADB, criada pelo Google para controlar o celular do PC; ela vem junto com o Android Studio.
Instale o Android Studio completo com Android SDK e SDK Platform Tools (contém ADB).
Verifique se o ADB foi instalado corretamente:
Abra o terminal e digite: adb devices
D:\phpproject\my-app>adb devices
List of devices attached
a34354354354352 deviceCode language: PHP (php)Esse exemplo significa que um celular está conectado com sucesso.
Acesse a pasta do projeto no CMD e execute esse comando para compilar e instalar o app Android: php artisan native:run android
D:\phpproject\my-app>php artisan native:run android
Running NativePHP for Android
Build log: D:\phpproject\my-app\nativephp\android-build.log
Updating Android configuration ....................................................................... 903.01ms DONE
Copying Laravel source .................................................................................... 18s DONE
Installing Composer dependenciesCode language: PowerShell (powershell)A compilação instala automaticamente várias dependências como Kotlin e Gradle; garanta uma conexão de internet estável.
Se usar proxy de rede, edite o arquivo de configuração neste caminho: D:\phpproject\my-app\nativephp\android\gradle\wrapper\gradle-wrapper.properties
Troque o endereço de download do Gradle por um mirror nacional, exemplo:
#Mon Feb 10 07:33:27 EST 2025
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
#distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-bin.zip
distributionUrl=https\://mirrors.aliyun.com/maven/gradle/gradle-8.13-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
Code language: Properties (properties)