Создание вашего первого приложения 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.