license: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing,
     software distributed under the License is distributed on an
     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     KIND, either express or implied.  See the License for the
     specific language governing permissions and limitations
     under the License.

Интерфейс командной строки

Это руководство показывает, как создать приложения и развернуть их на различных мобильных платформах с использованием cordova интерфейса командной строки (CLI). Эта программа позволяет вам создавать новые проекты, собирать их на различных платформах, и запускать ваше приложение на устройствах или в эмуляторах. CLI является основным инструментом используемым для кросс платформенного процесса разработки, описанного в разделе “Введение”. В другом случае вы также можете использовать CLI для инициализации кода проекта, а затем переключиться на использование SDK различных платформ и другие инструменты командной строки для дальнейшей разработки.

Необходимые условия

Перед запуском любого средства командной строки, необходимо установить пакет SDK для каждой платформы, для которой вы хотите разрабатывать. (См. раздел “Руководство по поддерживаемым платформам” для получения более подробной информации.)

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

  • iOS (Mac)
  • Amazon Fire OS (Mac, Linux, Windows)
  • Android (Mac, Linux, Windows)
  • BlackBerry 10 (Mac, Linux, Windows)
  • Windows Phone 8 (Windows)
  • Окна (Windows)
  • Firefox OS (Mac, Linux, Windows)

На Mac командная строка доступна с помощью приложения Терминал. На ПК он доступен как приложение Командная строка в разделе Аксессуары.

Примечание: Для Windows платформ, вы по прежнему можете вести свою разработку на Mac запуская Windows в виртуальной машине или в режиме двойной загрузки. Доступные параметры см. в разделах “Руководство для платформы Windows Phone 8” или “Руководство по платформе Windows”.

Скорее всего, вы будете запускать CLI с различных компьютеров, тем больше имеет смысл поддерживать удаленный репозиторий, откуда вы будете забирать рабочие материалы в локальные каталоги.

Установка CLI Cordova

Средство командной строки Cordova распространяется как пакет npm в готовом к использованию формате. Нет необходимости для его компиляции из исходного кода.

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

  1. Скачайте и установите Node.js. После установки вы должны быть возможность выполнять node и npm в командной строке. При желании, вы можете дополнительно использовать инструмент, как например nvm или nave для управления вашей установкой Node.js.

  2. Скачайте и установите git клиент, если у вас его еще нет. После установки вы должны быть способны вызвать git из вашей командной строки. Даже несмотря на то, что вы не будете использовать git вручную, CLI использовать для загрузки некоторых ресурсов при создании нового проекта.

  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` текущего рабочего каталога.

Вам может понадобиться добавить каталог `npm` в переменную `PATH` вашего окружения, для того чтобы вызывать глобально установленные `npm` модули. В Windows `npm` обычно можно найти в каталоге `C:\Users\username\AppData\Roaming\npm`. На OS X и Linux его обычно можно найти в каталоге `/usr/local/share/npm`.

Журнал установки может приводить к ошибкам, для любого не установленного SDK платформы.

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

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

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

    $ cordova create hello com.example.hello HelloWorld

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

Первый аргемент - hello указывает каталог в котором будет сформирован ваш проект. Этот каталог не должен существовать, Cordova создаст его для вас. Подкаталог www созданной директории будет содержать домашнюю страницу вашего приложения, совместно с ресурсами в каталогах css, js, и img, что соответствует общепринятым соглашениям по наименованию файлов и каталогов принятых в веб-разработке. Эти активы будут храниться в локальной файловой системе устройства, не служил удаленно. Файл config.xml содержит важные метаданные необходимые для формирования и распространения приложения.

Второй аргумент com.example.hello указывает идентификатор вашего проекта в обратном формате доменных имен. Этот аргумент необязателен, но только если вы также пропустите третий аргумент, потому что аргументы определяются в зависимости от их позиций. Вы можете изменить это значение позже в файле config.xml, но вам надо учитывать что возможно код сформированный вне config.xml использует это значение, как например имена Java пакетов. Значение по умолчанию io.cordova.hellocordova, но рекомендуется чтобы вы выбрали подходящее значение.

Третий аргумент HelloWorld указывает отображаемое имя приложения. Этот аргумент является необязательным. Вы можете изменить это значение позже в файле config.xml, но вам надо учитывать что возможно код сформированный вне config.xml использует это значение, как например имена Java классов. Значением по умолчанию является HelloCordova, но мы рекомендуем вам выбрать подходящее значение.

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

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

    $ cd hello

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

    $ cordova platform add ios
    $ cordova platform add amazon-fireos
    $ cordova platform add android
    $ cordova platform add blackberry10
    $ cordova platform add firefoxos

Запустите любую из этих команд на Windows компьютере, где wp ссылается на различные версии операционной системы Windows Phone:

    $ cordova platform add wp8 
    $ cordova platform add windows 
    $ cordova platform add amazon-fireos 
    $ cordova platform add android 
    $ cordova platform add blackberry10 
    $ cordova platform add firefoxos

Выполните это, чтобы проверить ваш текущий набор платформ:

    $ cordova platforms ls

(Обратите внимание, что команды platform и platforms являются синонимами.)

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

    $ cordova platform remove blackberry10
    $ cordova platform rm amazon-fireos
    $ cordova platform rm android

Выполнение команд для добавления или удаления платформ затрагивает содержимое каталога platforms проекта, где каждая указанная платформа представлена как подкаталог. Исходный каталог www повторяется в подкаталоге каждой платформы, например вы можете увидеть его в platforms/ios/www или platforms/android/assets/www. Потому что CLI постоянно копирует файлы из исходной папки www, следует изменять только эти файлы, а не файлы, расположенные в подкаталогах platforms. При использовании системы управления версиями, следует добавить папку с исходным кодом www, наряду с папкой merges в вашу систему управления версиями. (Дополнительные сведения о папке merges можно найти в разделе “Настройка каждой платформы” ниже.)

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

Если вы хотите в данный момент, можно использовать IDE, как например Eclipse или Xcode чтобы открыть проект который вы создали. Вам будет нужно открыть производный набор ресурсов из каталога /platforms/ для разработки с использованием SDK. Это потому что специфичные для SDK метаданные хранятся в соответствующем подкаталоге /platforms/. (См. раздел “Руководство по поддерживаемым платформам” для получения информации о том как разрабатывать приложение в каждой IDE.) Используйте этот подход, если вы просто хотите инициализироавть проект с использованием CLI и потом переключиться на SDK для работы с инструментами платформы.

Продолжайте читать если вы хотите использовать кросс-платформенный процесс разработки (CLI) для всего цикла разработки.

Построение приложения

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

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

    $ cordova build

Это создает код платформы в подкаталоге проекта platforms. При необходимости можно ограничить применения каждой сборки для выбранных платформ:

    $ cordova build ios

Команда cordova build это сокращение для следующих команд, которые в этом примере нацелены на одну платформу:

    $ cordova prepare ios
    $ cordova compile ios

В этом случае, как только вы запустили prepare, вы можете использовать Xcode SDK компании Apple как альтернативу для изменения и компиляции платформо-зависимого кода, который кордова создала в каталоге platforms/ios. Вы можете использовать тот же подход для SDK других платформ.

Тестирование приложения на эмуляторе или устройстве

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

    $ cordova emulate android

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

Примечание: Поддержка эмулятора в настоящее время недоступна для Amazon Fire ОС.

(См. “Руководство по поддерживаемым платформам” для подробной информации). Например вы можете сначала выполнить команду android для запуска Android SDK, а затем запустить образ конкретного устройства, которое запускает его согласно поведению по умолчанию:

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

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

    $ cordova run android

Перед выполнением этой команды, необходимо настроить устройство для тестирования, следуя процедурам, которые различаются для каждой платформы. В устройствах Android и Amazon Fire ОС вам придется включить функцию Отладка USB на устройстве и возможно добавить драйвер, USB в зависимости от вашего окружения разработки. Смотрите раздел “Руководство по поддерживаемым платформам” за подробностями о требованиях каждой платформы.

Добавить функции плагина

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

Плагин это немного дополнительного кода которые предоставляет интерфейс к встроенным компонентам платформы. ВЫ можете создать свой собственный интерфейс плагина, к примеры для проектирования гибридного приложения которое совмещает Cordova WebView с встроенными компонентами. (За подробной информацией смотрите “Интеграция WebViews” и Руководство по разработке плагинов.) В основном, вы будете добавлять плагин чтобы включить одну из базовых функций Cordova описанном в разделе “Справочник по API”.

Начиная с версии 3.0 при создании проекта Cordova она не содержит каких-либо плагинов настоящей. Это новое поведение по умолчанию. Какие плагины вы хотите, даже основные плагины, должен быть явно добавлен.

Список этих плагинов, включая дополнительные сторонние плагины, сообщества, можно найти в реестре по адресу plugins.cordova.io. Вы можете использовать CLI для поиска плагинов в этом реестре. К примеру поиск bar и code возвращает один результат который содержит оба слова без учета регистра:

    $ cordova plugin search bar code

    com.phonegap.plugins.barcodescanner - Scans Barcodes

Поиск только по слову bar возвращает дополнительный результат:

    cordova-plugin-statusbar - Cordova StatusBar Plugin

Команда cordova plugin add требует чтобы вы указали репозиторий для кода плагина. Вот пример как вы можете использовать CLI для добавления функций в приложение:

  • Базовая информация устройства (Device API):

    $ cordova plugin add cordova-plugin-device

  • Сетевое подключение и События батареи:

    $ cordova plugin add cordova-plugin-network-information
$ cordova plugin add cordova-plugin-battery-status

  • Акселерометр, компас и информация о расположении:

    $ cordova plugin add cordova-plugin-device-motion
$ cordova plugin add cordova-plugin-device-orientation
$ cordova plugin add cordova-plugin-geolocation

  • Камера, воспроизведение мультимедиа и съемка:

    $ cordova plugin add cordova-plugin-camera
$ cordova plugin add cordova-plugin-media-capture
$ cordova plugin add cordova-plugin-media

  • Доступ к файлам на устройстве или по сети (File API):

    $ cordova plugin add cordova-plugin-file
$ cordova plugin add cordova-plugin-file-transfer

  • Уведомление с помощью диалогового окна или вибрации:

    $ cordova plugin add cordova-plugin-dialogs
$ cordova plugin add cordova-plugin-vibration

  • Контакты:

    $ cordova plugin add cordova-plugin-contacts

  • Глобализация:

    $ cordova plugin add cordova-plugin-globalization

  • Заставка:

    $ cordova plugin add cordova-plugin-splashscreen

  • Открытие новых окон браузера (InAppBrowser):

    $ cordova plugin add cordova-plugin-inappbrowser

  • Консоль отладки:

    $ cordova plugin add cordova-plugin-console

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

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

    $ cordova plugin ls    # or 'plugin list'
    [ 'cordova-plugin-console' ]

Чтобы удалить плагин, сошлитесь к нему по тому же идентификатору, который появляется в списке. Например таким образом вы бы удалили поддержку для консоли отладки из версии релиза:

    $ cordova plugin rm cordova-plugin-console
    $ cordova plugin remove cordova-plugin-console    # same

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

    $ cordova plugin add cordova-plugin-console cordova-plugin-device

Расширенные параметры плагина

При добавлении плагина, некоторые параметры позволяют указать откуда взять плагин. Приведенные выше примеры использования общепринятого реестра registry.cordova.io, и плагин определяется по его id:

    $ cordova plugin add cordova-plugin-console

Id также может включать номер версии плагина, добавленный после символа @. Версия latest — это псевдоним для самой последней версии. Например:

    $ cordova plugin add cordova-plugin-console@latest
    $ cordova plugin add cordova-plugin-console@0.2.1

Если плагин не зарегистрирована в registry.cordova.io, но расположен в другом репозитории git, вы можете указать альтернативный URL-адрес:

    $ cordova plugin add https://github.com/apache/cordova-plugin-console.git

Приведенный выше пример git получает плагин из последней версии ветки master, но альтернативная git ссылка например тег или другая ветка могут быть добавлены после символа #:

    $ cordova plugin add https://github.com/apache/cordova-plugin-console.git#r0.2.0

Если плагин (и его файл plugin.xml) находится в подкаталоге репозитария git, вы можете указать его после символа :. Обратите внимание, что символ # все еще необходим:

    $ cordova plugin add https://github.com/someone/aplugin.git#:/my/sub/dir

Вы также можете объединить как ссылку git так и подкаталоги:

    $ cordova plugin add https://github.com/someone/aplugin.git#r0.0.1:/my/sub/dir

Как вариант укажите локальный путь к папке плагина, который содержит файл plugin.xml:

    $ cordova plugin add ../my_plugin_dir

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

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

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

  • Измените файл 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 имеет несколько глобальных команд, которые могут помочь вам, если вы застряли или возникли проблемы. Команда help отображает все доступные команды Cordova и их синтаксис:

$ cordova help
$ cordova        # same

Кроме того вы можете получить более подробную справку по определенной команде. Например:

$ cordova run --help

Команда info формирует список потенциально полезных сведений, например установленных платформ и плагинов, версии SDK для каждой платформы и версии CLI и node.js:

$ cordova info

Она представляет информацию на экран и перенаправляет выходные данные в локальный файл info.txt.

Примечание: в настоящее время, доступны только сведения о платформах iOS и Android.

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

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

    $ sudo npm update -g cordova

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

    $ sudo npm install -g cordova@3.1.0-0.2.0

Запустите cordova - v, чтобы увидеть, какая версия в настоящее время установлена. Выполните команду npm info для более длинного списка, который включает в себя текущую версию и другие доступные номера версий:

    $ npm info cordova

Кордова 3.0 является первая версия поддерживающая интерфейс командной строки, описанные в этом разделе. Если вы обновляете проект с версии ранее чем 3.0, необходимо создать новый проект, как описано выше, а затем скопировать старые ресурсы приложения в каталог верхнего уровня www. Там, где это применимо, далее сведения об обновлении до 3.0 доступны в разделе “Руководство по поддерживаемым платформам”. После обновления к интерфейсу командной строки cordova используйте npm update чтобы оставаться актуальным, более длительные процедуры, описанные там более не актуальны.

Cordova 3.0 + по-прежнему может требовать различных изменений структуры каталогов уровня проекта и других зависимостей. После того, как вы выполните команду npm указанную выше для обновления Cordova, необходимо убедиться, что ресурсы вашего проекта соответствуют требованиям последней версии. Выполните команды указанную ниже для каждой платформы, под которую вы создаете приложение:

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