Seu primeiro projeto com Cordova

Posted on Ago 01, 2026 by

Na aula anterior, conseguimos instalar o Cordova. Nesta aula, vamos utilizar comandos da CLI para criar um projeto.

1. Criar um projeto Cordova

Abra o terminal, navegue até a pasta onde quer armazenar o projeto e execute o comando de criação:

cordova create hello com.foxdevelop.hello HelloWorldCode language: CSS (css)

Explicação dos parâmetros:

  1. hello: nome da pasta do projeto
  2. com.example.hello: pacote do aplicativo (identificador único para Android, é obrigatório alterá-lo antes de publicar)
  3. HelloWorld: nome visível do aplicativo

Veja um exemplo prático: criamos uma pasta na unidade D e geramos o projeto dentro dela.

C:\Users>d:

D:\>mkdir cordovademo

D:\>cd cordovademo

D:\cordovademo>cordova create hello com.foxdevelop.hello HelloWorld
Creating a new cordova project.Code language: CSS (css)

Depois você conseguirá visualizar a pasta cordovademo na unidade D, e dentro dela haverá uma subpasta chamada hello.

Pasta principal do código fonte: hello/www/

Página de entrada: www/index.html

Não modifique nenhum arquivo dentro da pasta platforms, pois esses arquivos serão sobrescritos durante a compilação!

2. Acessar o projeto e adicionar plataformas

cd hello

Adicionar plataformas

# Plataforma Android (funciona no Windows)
cordova platform add android

# Plataforma iOS [não é possível compilar no Windows! Apenas computadores Mac suportam]
# cordova platform add iosCode language: PHP (php)

Registro da execução

D:\cordovademo>cd hello

D:\cordovademo\hello>cordova platform add android
Using cordova-fetch for cordova-android
Adding android project...
Creating Cordova project for the Android platform:
        Path: platforms\android
        Package: com.foxdevelop.hello
        Name: HelloWorld
        Activity: MainActivity
        Android Target SDK: android-36
        Android Compile SDK: 36
Subproject Path: CordovaLib
Subproject Path: app
Android project created with cordova-android@15.1.0

D:\cordovademo\hello>cordova platform ls
Installed platforms:
  android 15.1.0
Available platforms:
  browser
  electronCode language: CSS (css)

3. Verificação prévia do ambiente (importante)

cordova requirements

Esse comando verifica se o ambiente do sistema está configurado corretamente, como a instalação do JDK e outros componentes.

D:\cordovademo\hello>cordova requirements
Android SDK is missing cmdline-tools directory.

Requirements check results for android:
Java JDK: installed 11.0.31
Android SDK: installed true
Android target: not installed
Command failed with exit code 1: avdmanager list target
'avdmanager' �����ڲ����ⲿ���Ҳ���ǿ����еij���
���������ļ���
Gradle: not installed
Could not find an installed version of Gradle either in Android Studio,
or on your system to install the gradle wrapper. Please include gradle
in your path, or install Android Studio
Some of requirements check failedCode language: PHP (php)

O resultado esperado é esse:

Java JDK: installed
Android SDK: installed
Gradle: installed

No meu caso, apareceu Gradle: not installed

Se você ainda não tem o JDK instalado, será necessário baixá-lo. Você pode consultar outras aulas para ver o guia de instalação do JDK.

Estou utilizando a versão 11 do JDK.

O erro que apareceu na minha máquina:

D:\cordovademo\hello>cordova build android
Checking Java JDK and Android SDK versions
ANDROID_HOME=undefined (recommended setting)
ANDROID_SDK_ROOT=undefined (DEPRECATED)
Android SDK is missing cmdline-tools directory.
Using Android SDK: D:\Sortware\ADB
Could not find an installed version of Gradle either in Android Studio,
or on your system to install the gradle wrapper. Please include gradle
in your path, or install Android StudioCode language: JavaScript (javascript)

Você precisa instalar o Android Studio, ele já vem com o SDK incluso.

Para saber mais sobre o Android Studio, consulte nossas outras aulas.

Abra o Android Studio e acesse o menu superior: Tools → SDK Manager. Depois localize o caminho do SDK exibido na tela.

Agora configure as variáveis de ambiente

Nome da variável: ANDROID_HOME
Valor da variável: C:\Users\xxxxx\AppData\Local\Android\Sdk

Além de criar a variável, adicione esses caminhos na variável Path:

%ANDROID_HOME%\platform-tools
%ANDROID_HOME%\cmdline-tools\latest\bin

Instalar ferramentas de linha de comando no Android Studio

Abra o Android Studio → Tools → SDK Manager

Selecione a aba SDK Tools

Baixar pacote binário do Gradle

Download pelo site oficial: https://gradle.org/releases/

Extraia para o caminho: C:\gradle\gradle-8.5

Gradle by Develocity | Releases

Configurar variáveis de ambiente do sistema

Nome da variável: GRADLE_HOME
Valor da variável: C:\gradle-8.7

Criar uma nova【variável de sistema】

Adicione esse caminho na variável Path

Verificar se a instalação funcionou

Abra o Prompt de Comando (cmd)

gradle -v

Teste novamente. Se aparecer um resultado similar ao abaixo, a configuração está concluída:

D:\cordovademo\hello>cordova requirements

Requirements check results for android:
Java JDK: installed 11.0.31
Android SDK: installed true
Android target: not installed
No android targets (SDKs) installed!
Gradle: installed C:\gradle-8.7\bin\gradle.BAT
Some of requirements check failedCode language: CSS (css)

Problema 2: Versão do JDK

Ao executar o comando cordova run android, recebi o seguinte erro:

D:\cordovademo\hello>cordova run android
Checking Java JDK and Android SDK versions
ANDROID_HOME=C:\Users\maiwu\AppData\Local\Android\Sdk (recommended setting)
ANDROID_SDK_ROOT=undefined (DEPRECATED)

BUILD SUCCESSFUL in 1sCUTING [91ms]
1 actionable task: 1 up-to-date
Subproject Path: CordovaLib
Subproject Path: app

[Incubating] Problems report is available at: file:///D:/cordovademo/hello/platforms/android/build/reports/problems/problems-report.html

FAILURE: Build failed with an exception.

* Where:
Build file 'D:\cordovademo\hello\platforms\android\app\build.gradle' line: 20

* What went wrong:
A problem occurred evaluating project ':app'.
> Failed to apply plugin 'com.android.internal.application'.
   > Android Gradle plugin requires Java 17 to run. You are currently using Java 11.
      Your current JDK is located in C:\Program Files\Zulu\zulu-11
      You can try some of the following options:
       - changing the IDE settings.
       - changing the JAVA_HOME environment variable.
       - changing `org.gradle.java.home` in `gradle.properties`.

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

For more on this, please refer to https://docs.gradle.org/8.14.2/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.

BUILD FAILED in 2s
Command failed with exit code 1: D:\cordovademo\hello\platforms\android\tools\gradlew.bat cdvBuildDebugCode language: JavaScript (javascript)

No meu ambiente eu utilizava o JDK11, mas o AGP (Android Gradle Plugin) usado pela plataforma Android do Cordova exige obrigatoriamente o JDK17, causando falha na compilação.

Eu usava o Zulu JDK 11, então fiz a atualização para o Zulu JDK 17.

Faça o download aqui: Java 8, 11, 17, 21, 25 Download for Linux, Windows and macOS

O arquivo baixado é um instalador MSI. Execute o arquivo e marque as opções mostradas para que o instalador configure automaticamente as variáveis JAVA_HOME e Path.

Abra o CMD para verificar a versão do Java

java -version

openjdk version "17.0.20" 2026-07-21 LTS
OpenJDK Runtime Environment Zulu17.68+17-CA (build 17.0.20+8-LTS)
OpenJDK 64-Bit Server VM Zulu17.68+17-CA (build 17.0.20+8-LTS, mixed mode, sharing)Code language: CSS (css)

Se aparecer esse resultado, a instalação foi bem-sucedida.

4. Compilar o aplicativo

# Compilar todas as plataformas (no momento apenas Android)
cordova build

# Compilar apenas para Android
cordova build android
Code language: PHP (php)

Após compilar com sucesso, o arquivo APK estará neste caminho:

hello\platforms\android\app\build\outputs\apk\debug\app-debug.apk

Execução real

D:\cordovademo\hello>cordova build android
Checking Java JDK and Android SDK versions
ANDROID_HOME=C:\Users\maiwu\AppData\Local\Android\Sdk (recommended setting)
ANDROID_SDK_ROOT=undefined (DEPRECATED)
Using Android SDK: C:\Users\maiwu\AppData\Local\Android\Sdk

BUILD SUCCESSFUL in 9s
1 actionable task: 1 up-to-date
Subproject Path: CordovaLib
Subproject Path: app

> Task :CordovaLib:compileDebugJavaWithJavac
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.

[Incubating] Problems report is available at: file:///D:/cordovademo/hello/platforms/android/build/reports/problems/problems-report.html

BUILD SUCCESSFUL in 11s
50 actionable tasks: 50 executed
Built the following apk(s):
        D:\cordovademo\hello\platforms\android\app\build\outputs\apk\debug\app-debug.apkCode language: JavaScript (javascript)

Você conseguirá localizar o APK dentro da pasta D:\cordovademo\hello\platforms\android\app\build\outputs\apk\debug\

5. Executar para teste

Método 1: Executar em emulador Android

cordova emulate android

Método 2: Testar em celular físico via USB (ative a depuração USB)

cordova run android

Vamos fazer o teste em um celular físico, recomendo que você também faça assim. Conecte o celular Android com um cabo USB e habilite o modo de depuração no aparelho.

Dentro da pasta hello, abra o CMD e execute o comando cordova run android

Depois disso, o aplicativo será instalado no celular

A tela padrão do Cordova vai aparecer

6. Instalar plugins

Acessar recursos nativos do celular

Por si só, as páginas web do Cordova não conseguem acessar câmera, bluetooth, arquivos, notificações e outros hardwares. É obrigatório instalar plugins para isso.

Exemplo: Plugin da câmera

cordova plugin add cordova-plugin-camera

Listar plugins já instalados

cordova plugin ls

Para chamar APIs nativas via JavaScript, é preciso aguardar o disparo do evento deviceready. Não tente chamar plugins logo após o carregamento da página!

Exemplo de modelo básico (www/js/index.js)

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    // Dispositivo pronto, todos os plugins Cordova podem ser utilizados
    console.log("Cordova inicializado com sucesso");
}
Code language: JavaScript (javascript)

Execução real

D:\cordovademo\hello>cordova plugin add cordova-plugin-camera
Installing "cordova-plugin-camera" for android
Subproject Path: CordovaLib
Subproject Path: app
Adding cordova-plugin-camera to package.json

D:\cordovademo\hello>cordova plugin ls
cordova-plugin-camera 8.0.0 "Camera"Code language: CSS (css)

Agora modifique o arquivo index.html com o código abaixo para testar a funcionalidade da câmera

Primeiro, uma observação sobre a estrutura de pastas do projeto após criação:

D:\cordovademo\hello

Todo o código que você vai desenvolver fica dentro da pasta www

Altere o conteúdo do index.html para esse código:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Teste de Câmera</title>
    <script src="cordova.js"></script>
</head>
<body>
    <button id="btnTake">Tirar foto</button>
    <br>
    <img id="imgPreview" style="width:220px;">

    <script>
        let cameraReady = false;

        document.addEventListener("deviceready", onDeviceReady, false);

        function onDeviceReady() {
            console.log("Evento deviceready disparado, Cordova pronto");
            cameraReady = true;
        }

        // Usamos addEventListener para vincular o clique (onclick pode causar conflitos de tempo, essa forma é recomendada)
        document.getElementById("btnTake").addEventListener("click", function(){
            if(!cameraReady){
                alert("Aguarde a inicialização do Cordova!");
                return;
            }

            navigator.camera.getPicture(
                function(imageUri) {
                    console.log("Foto capturada com sucesso:", imageUri);
                    document.getElementById("imgPreview").src = imageUri;
                },
                function(error) {
                    alert("Falha ao capturar foto: " + error);
                },
                {
                    destinationType: 0, // Camera.DestinationType.FILE_URI = 0, usamos número para evitar erro de variável não definida
                    sourceType: 1,      // Camera.PictureSourceType.CAMERA = 1
                    quality: 80
                }
            );
        });
    </script>
</body>
</html>Code language: C# (cs)

Execute novamente o comando cordova run android

O aplicativo abrirá, você verá um botão. Ao clicar nele, a câmera será ativada e você conseguirá tirar fotos.

* 7. Pasta merges: arquivos diferenciados por plataforma

Por padrão, todas as plataformas compartilham os recursos da pasta www.

Se quiser usar interfaces ou recursos diferentes para Android e iOS, utilize a pasta merges:

merges/
├─android/
│  └─css/overrides.css  # Arquivo válido apenas para Android
└─ios/
Code language: PHP (php)

Durante a compilação, os arquivos dentro da pasta merges sobrescrevem arquivos com o mesmo nome na pasta www.

* 8. Atualizar o Cordova

# Atualizar a CLI do Cordova globalmente
npm update -g cordova

# Instalar uma versão específica
npm install -g cordova@12.0.0

# Atualizar a versão da plataforma Android dentro do projeto
cordova platform update android --save
Code language: PHP (php)

Resumo dos comandos

#1 Criar projeto
cordova create testapp com.mytest.app TestApp
cd testapp

#2 Adicionar plataforma Android
cordova platform add android

#3 Verificar ambiente
cordova requirements

#4 Compilar pacote de depuração
cordova build android

#5 Executar em celular físico
cordova run android
Code language: CSS (css)

Seu primeiro projeto com Cordova

Posted in Tutorial do Cordova

Deixe um comentário

O seu endereço de email não será publicado. Campos obrigatórios marcados com *