Создание вашего первого приложения Cordova

Это руководство показывает, как создать приложение Cordova на основе JS/HTML и развернуть его на различных мобильных платформах с использованием командной строки (CLI) cordova. Для получения подробных сведений о командной строке Cordova просмотрите справочник по CLI.

Установка Cordova CLI

Инструмент командной строки Cordova распространяется как пакет npm.

Чтобы установить инструмент командной строки cordova, выполните следующие действия:

1. Загрузите и установите Node.js. После установки вы должны иметь возможность вызвать node и npm в командной строке.

2. (Необязательно) Загрузите и установите клиент Git, если у вас его ещё нет. После установки вы должны иметь возможность вызвать git в командной строке. CLI использует его для загрузки ресурсов, когда они ссылаются по URL на репозиторий Git.

3. Установите модуль cordova с помощью утилиты npm Node.js. Модуль cordova будет автоматически загружен утилитой npm.

• на OS X и Linux:

  $ sudo npm install -g cordova
  

  На OS X и Linux, возможно, потребуется добавить префикс npm к команде sudo, чтобы установить этот инструмент разработки в каталоги с ограниченным доступом, например, /usr/local/share. Если вы используете утилиту nvm/nave или имеете права записи в каталог установки, возможно, префикс sudo можно опустить. Есть дополнительные советы по использованию npm без sudo, если вы хотите это сделать.

• на Windows:

  C:\>npm install -g cordova
  

Флаг -g выше сообщает npm установить cordova глобально. В противном случае он будет установлен в подкаталоге node_modules текущего рабочего каталога.

После установки вы должны иметь возможность запустить cordova в командной строке без аргументов, и она должна вывести справку.

Создание приложения

Перейдите в каталог, где вы храните исходный код, и создайте проект Cordova:

$ cordova create hello com.example.hello HelloWorld

Это создает необходимую структуру каталогов для вашего приложения Cordova. По умолчанию скрипт cordova create генерирует каркас веб-приложения, домашняя страница которого — файл www/index.html проекта.

См. также

• Документация по команде Cordova create
• Структура каталогов проекта Cordova
• Шаблоны проектов Cordova

Добавление платформ

Все последующие команды необходимо запускать в каталоге проекта или в любом его подкаталоге:

$ cd hello

Добавьте целевые платформы для вашего приложения. Мы добавим платформы 'ios' и 'android' и убедимся, что они сохранены в config.xml и package.json:

$ cordova platform add ios
$ cordova platform add android

Чтобы проверить текущий набор платформ:

$ cordova platform ls

Выполнение команд для добавления или удаления платформ влияет на содержимое каталога platforms проекта, где каждая указанная платформа отображается как подкаталог.

Примечание: при использовании CLI для сборки приложения не следует редактировать файлы в каталоге /platforms/. Файлы в этом каталоге регулярно перезаписываются при подготовке приложений к сборке или при повторной установке плагинов.

См. также

• Справочная документация по команде Cordova platform

Установка предварительных требований для сборки

Для сборки и запуска приложений вам необходимо установить SDK для каждой целевой платформы. В качестве альтернативы, если вы используете браузер для разработки, вы можете использовать платформу browser, которая не требует SDK платформ.

Чтобы проверить, соответствуют ли требованиям требования для сборки платформы:

$ cordova requirements
Requirements check results for android:
Java JDK: installed .
Android SDK: installed
Android target: installed android-19,android-21,android-22,android-23,Google Inc.:Google APIs:19,Google Inc.:Google APIs (x86 System Image):19,Google Inc.:Google APIs:23
Gradle: installed

Requirements check results for ios:
Apple OS X: not installed
Cordova tooling for iOS requires Apple OS X
Error: Some of requirements check failed

См. также

• Требования к платформе Android
• Требования к платформе iOS
• Требования к платформе Windows

Сборка приложения

По умолчанию скрипт cordova create генерирует каркас веб-приложения, стартовая страница которого — файл www/index.html проекта. Любую инициализацию необходимо указать в обработчике события deviceready, определённом в www/js/index.js.

Запустите следующую команду, чтобы собрать проект для всех платформ:

$ cordova build

Вы можете ограничить область каждой сборки определёнными платформами — 'ios' в данном случае:

$ cordova build ios

См. также

• Справочная документация по команде Cordova build

Тестирование приложения

SDK для мобильных платформ часто поставляются с эмуляторами, которые выполняют образ устройства, чтобы вы могли запустить приложение с главного экрана и увидеть, как оно взаимодействует со многими функциями платформы. Запустите команду, подобную следующей, чтобы пересобрать приложение и просмотреть его в эмуляторе конкретной платформы:

$ cordova emulate android

Последовавшее за этим выполнение команды cordova emulate обновляет образ эмулятора, чтобы отобразить последнее приложение, которое теперь доступно для запуска с главного экрана:

В качестве альтернативы вы можете подключить телефон к компьютеру и протестировать приложение напрямую:

$ cordova run android

Перед выполнением этой команды необходимо настроить устройство для тестирования, следуя инструкциям, которые различаются для каждой платформы.

См. также

• Настройка эмулятора Android
• Справочная документация по команде Cordova run
• Справочная документация по команде Cordova emulate

Добавление плагинов

Вы можете изменить сгенерированное по умолчанию приложение, чтобы использовать стандартные веб-технологии, но для доступа к функциям устройства необходимо добавить плагины.

Плагин предоставляет JavaScript-API для функций родного SDK. Плагины обычно размещаются на npm, и вы можете найти их на странице поиска плагинов. Некоторые ключевые API предоставляются проектом Apache Cordova с открытым исходным кодом, и они называются Core Plugin APIs. Вы также можете использовать CLI для перехода на страницу поиска:

$ cordova plugin search camera

Чтобы добавить и сохранить плагин камеры в config.xml и package.json, мы укажем имя пакета npm для плагина камеры:

$ cordova plugin add cordova-plugin-camera
Fetching plugin "cordova-plugin-camera@~2.1.0" via npm
Installing "cordova-plugin-camera" for android
Installing "cordova-plugin-camera" for ios

Плагины также можно добавлять, используя каталог или репозиторий Git.

ПРИМЕЧАНИЕ: CLI добавляет код плагина соответствующим образом для каждой платформы. Если вы хотите разрабатывать с помощью инструментов командной строки или SDK платформ, как описано в Обзоре, вам необходимо запустить утилиту Plugman, чтобы добавить плагины отдельно для каждой платформы. (Для получения дополнительной информации см. Использование Plugman для управления плагинами.)

Используйте plugin ls (или plugin list, или plugin само по себе), чтобы просмотреть установленные плагины. Каждый отображается по своему идентификатору:

$ cordova plugin ls
cordova-plugin-camera 2.1.0 "Camera"
cordova-plugin-whitelist 1.2.1 "Whitelist"

См. также

• Справочная документация по команде Cordova plugin
• Страница поиска плагинов Cordova
• Core Plugin APIs

Использование слияний для настройки каждой платформы

Хотя Cordova позволяет легко развернуть приложение для многих платформ, иногда вам нужно добавить настройки. В этом случае вам не следует изменять исходные файлы в различных каталогах www в каталоге верхнего уровня platforms, так как они регулярно замещаются исходниками многоплатформенного каталога верхнего уровня www.

Вместо этого каталог верхнего уровня merges предлагает место для указания ресурсов, которые нужно развернуть на определённых платформах. Каждый подкаталог, соответствующий конкретной платформе в merges, отражает структуру каталогов исходного дерева www, позволяя вам переопределять или добавлять файлы по мере необходимости. Например, вот как вы можете использовать merges для увеличения размера шрифта по умолчанию для устройств Android:

• Отредактируйте файл www/index.html, добавив ссылку на дополнительный файл CSS, overrides.css в данном случае:

  <link rel="stylesheet" type="text/css" href="css/overrides.css" />
  

• Необязательно создать пустой файл www/css/overrides.css, который будет применяться для всех сборок, не относящихся к Android, предотвращая ошибку отсутствия файла.

• Создайте подкаталог css в merges/android, а затем добавьте соответствующий файл overrides.css . Укажите CSS, который переопределяет значение размера шрифта по умолчанию 12 пунктов, указанное в www/css/index.css, например:

  body { font-size:14px; }
  

При повторной сборке проекта версия Android будет иметь настроенный размер шрифта, в то время как другие останутся без изменений.

Вы также можете использовать merges для добавления файлов, отсутствующих в исходном каталоге www. Например, приложение может включить графический элемент кнопки назад в интерфейс iOS, хранящийся в merges/ios/img/back_button.png, в то время как версия Android может вместо этого обрабатывать события backbutton соответствующей аппаратной кнопки.

Обновление Cordova и вашего проекта

После установки утилиты cordova, вы всегда можете обновить её до последней версии, выполнив следующую команду:

$ sudo npm update -g cordova

Используйте этот синтаксис для установки определённой версии:

$ sudo npm install -g cordova@3.1.0-0.2.0

Запустите cordova -v , чтобы увидеть текущую версию. Чтобы найти последнюю релизную версию cordova, вы можете запустить:

$ npm info cordova version

Чтобы обновить платформы, на которые вы нацеливаетесь:

$ cordova platform update android --save
$ cordova platform update ios --save
...etc.