Це керівництво показує, як створити додатки та розгорнути їх на різних мобільних платформах з використанням 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 (Windows)
- Firefox OS (Mac, Linux, Windows)
На Mac командний рядок доступна за допомогою програми Термінал. На ПК він доступний як додаток командного рядка в розділі Додаткові пристрої.
Примітка. Для Windows платформ, ви як і раніше можете вести свою розробку на Mac запускаючи Windows у віртуальній машині або в режимі подвійного завантаження. Доступні параметри см. В розділах "Керівництво для платформи Windows Phone 8" або "Керівництво по платформі Windows".
Швидше за все, ви будете запускати CLI з різних комп'ютерів, тим більше має сенс підтримувати віддалений репозиторій, звідки ви будете забирати робочі матеріали в локальні каталоги.
Установка CLI Cordova
Засіб командного рядка Cordova поширюється як пакет npm в готовому до використання форматі. Немає необхідності для його компіляції з вихідного коду.
Щоб встановити інструмент командного рядка cordova. виконайте наступні дії:
Скачайте і встановіть Node.js. Після установки ви повинні бути можливість виконувати node і npm в командному рядку. При бажанні, ви можете додатково використовувати інструмент, як наприклад nvm або nave для управління вашої установкою Node.js.
Скачайте і встановіть git клієнт. якщо у вас його ще немає. Після установки ви повинні бути здатні викликати git з вашої командного рядка. Навіть незважаючи на те, що ви не будете використовувати git вручну, CLI використовувати для завантаження деяких ресурсів при створенні нового проекту.
Встановіть модуль cordova за допомогою інструменту npm Node.js. Модуль cordova буде автоматично завантажений npm.
створення програми
Перейдіть в каталог, де ви зберегли ваш вихідний код і виконати команду такого вигляду:
Завершення команди може тривати довше декількох секунд, тому будьте терплячі. Запуск команди з опцією -d буде показувати інформацію про прогрес операції.
Перший аргемент - hello вказує каталог в якому буде сформований ваш проект. Цей каталог не повинен існувати, Cordova створить його для вас. Підкаталог www створеної директорії буде містити домашню сторінку вашого додатка, спільно з ресурсами в каталогах css. js. і img. що відповідає загальноприйнятим угодами по найменуванню файлів і каталогів прийнятих в веб-розробці. Ці активи будуть зберігатися в локальній файлової системи пристрою, не служив віддалено. Файл config.xml містить важливі метадані необхідні для формування і поширення програми.
Другий аргумент com.example.hello вказує ідентифікатор вашого проекту в зворотному форматі доменних імен. Цей аргумент необов'язковий, але тільки якщо ви також пропустіть третій аргумент, тому що аргументи визначаються в залежності від їх позицій. Ви можете змінити це значення пізніше в файлі config.xml. але вам треба враховувати що можливо код сформований поза config.xml використовує це значення, як наприклад імена Java пакетів. Значення за замовчуванням io.cordova.hellocordova. але рекомендується щоб ви вибрали відповідне значення.
Додавання платформ
Всі наступні команди повинні бути виконуватися в каталозі проекту або будь-яких підкаталогах в його межах:
Перед тим, як можна побудувати проект, необхідно вказати набір цільових платформ. Ваші можливості по запуску цих команд залежать від того підтримує ваш комп'ютер кожне SDK, і встановили ви відповідне SDK. Запустіть будь-яку з цих команд на Mac:
Запустіть будь-яку з цих команд на Windows комп'ютері, де wp посилається на різні версії операційної системи Windows Phone:
Виконайте це, щоб перевірити ваш поточний набір платформ:
(Зверніть увагу, що команди platform і platforms є синонімами.)
Виконайте одну з наступних команд, які є синонімами, щоб видалити платформу:
Виконання команд для додавання або видалення платформ зачіпає вміст каталогу 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 для роботи з інструментами платформи.
побудова додатки
За замовчуванням скрипт cordova create створює каркас веб додатки чия домашня сторінка це файл проекту www / index.html. Змінюйте це додатки як ви бажаєте, але будь-яка ініціалізація повинна бути вказана як частина обробника події [deviceready] (../../ cordova / events / events.deviceready.html). використовуваного за замовчуванням з www / js / index.js.
Виконайте наступну команду для ітеративного побудови проекту:
Це створює код платформи в підкаталозі проекту platforms. При необхідності можна обмежити застосування кожної збірки для обраних платформ:
Команда cordova build це скорочення для наступних команд, які в цьому прикладі націлені на одну платформу:
У цьому випадку, як тільки ви запустили prepare. ви можете використовувати Xcode SDK компанії Apple як альтернативу для зміни і компіляції від платформи залежного коду, який Кордова створила в каталозі platforms / ios. Ви можете використовувати той же підхід для SDK інших платформ.
Тестування програми на емуляторі або пристрої
SDK для мобільних платформ часто поставляються з емуляторами які виконують образ пристрою, таким чином що ви можете запустити ваш додаток з головного екрану і подивитися як воно взаємодіє з різними функціями платформи. Виконайте команду як зазначено нижче для перепостроенія додатки запуску його в емуляторі зазначеної платформи:
Деякі мобільні платформи емулюють певний пристрій за умовчанням, як наприклад iPhone для проектів iOS. Для інших платформи, вам може знадобитися спершу асоціювати пристрій з емулятором.
Примітка. Підтримка емулятора в даний час недоступна для Amazon Fire ОС.
(Див. "Керівництво по підтримуваним платформ" для докладної інформації). Наприклад ви можете спочатку виконати команду android для запуску Android SDK, а потім запустити образ конкретного пристрою, який запускає його згідно поведінки за замовчуванням:
Подальша команда cordova emulate оновлює образ емулятор для відображення останньої версії додаток, який тепер доступний для запуску з головного екрану:
Перед виконанням цієї команди, необхідно налаштувати пристрій для тестування, слідуючи процедурам, які розрізняються для кожної платформи. У пристроях Android і Amazon Fire ОС вам доведеться включити функцію Налагодження USB на пристрої і можливо додати драйвер, USB в залежності від вашого оточення розробки. Дивіться розділ "Керівництво по підтримуваним платформ" за подробицями про вимоги кожної платформи.
Додати функції плагіна
Плагін це трохи додаткового коду які надає інтерфейс до вбудованим компонентів платформи. Ви можете створити свій власний інтерфейс плагіна, до приклади для проектування гібридного додатки яке поєднує Cordova WebView з вбудованими компонентами. (За детальною інформацією дивіться "Інтеграція WebViews" і Керівництво по розробці плагінів.) В основному, ви будете додавати плагін щоб включити одну з базових функцій Cordova описаному в розділі "Довідник по API".
Починаючи з версії 3.0 при створенні проекту Cordova вона не містить будь-яких плагінів справжньою. Це нове поведінка за умовчанням. Які плагіни ви хочете, навіть основні плагіни, повинен бути явно доданий.
Пошук тільки по слову bar повертає додатковий результат:
Команда cordova plugin add вимагає щоб ви вказали репозиторій для коду плагіна. Ось приклад як ви можете використовувати CLI для додавання функцій в додаток:
Базова інформація пристрої (Device API):
Примітка. CLI додає код плагіна відповідним чином для кожної платформи. Якщо ви хочете розробити з використанням інструментів низького рівня або SDK платформи, як описано в розділі "Введення", необхідно запустити утиліту Plugman яка додасть плагіни окремо для кожної платформи. (Для отримання додаткової інформації, див. Розділ "Використання Plugman для управління розширеннями".)
Щоб видалити плагін, пошліться до нього за тим же ідентифікатором, який з'являється в списку. Наприклад таким чином ви б видалили підтримку для консолі налагодження з версії релізу:
Ви можете видаляти або додавати плагіни пакетно вказуючи більш ніж один аргумент для відповідної команди:
Розширені параметри плагіна
При додаванні плагіна, деякі параметри дозволяють вказати звідки взяти плагін. Наведені вище приклади використання загальноприйнятого реєстру registry.cordova.io. і плагін визначається по його id:
Id також може включати номер версії плагіна, доданий після символу @. Версія latest - це псевдонім для самої останньої версії. наприклад:
Установка з тега:
або git-ref також може також бути конкретним коммітов:
Якщо плагін (і його файл plugin.xml) знаходиться в підкаталозі репозитария git, ви можете вказати його після символу. Зверніть увагу, що символ # все ще необхідний:
Ви також можете об'єднати як посилання git так і підкаталоги:
Як варіант вкажіть локальний шлях до папки плагіна, який містить файл plugin.xml:
Використання каталогу merges налаштовувати кожну платформи
Хоча Cordova дозволяє легко розгортати додаток на різних платформах, іноді необхідно додати індивідуальні настройки. В цьому випадку ви не хочете змінити вихідні файли в різних каталогах www в каталозі верхнього рівня платформи. тому що вони регулярно замінюються з крос-платформного джерела - каталогу верхнього рівня www.
Замість цього в каталог верхнього рівня merges надає місце для вказівки ресурсів для розгортання на певних платформах. Кожен платформо-залежний підкаталог merges відображає повторює структуру директорії www. і дозволяє перевизначити або додати файли, як це необхідно. Наприклад ось як ви, можливо, використовує merges щоб збільшити розмір шрифта для пристроїв Android і Amazon Fire ОС:
Змініть файл www / index.html. додавши посилання на додатковий CSS-файл, overrides.css в даному випадку:
При необхідності створіть порожній www / css / overrides.css файл, який буде застосовуватися для всіх побудов відмінних від Android, запобігаючи помилку відсутнього файлу.
Створіть css підкаталог всередині merges / android. потім додайте відповідний файл overrides.css. Вкажіть CSS, який перекриває 12 пунктовий розмір шрифта, зазначений в www / css / index.css. наприклад:
При повторному побудові проекту, Android версія буде містити змінений розмір шрифту, в той час як інші платформи залишаються незмінними.
Можна також використовувати merges для додавання файлів, з самого початку не присутніх в каталозі www. Наприклад додаток може включити зображення для кнопки НАЗА в інтерфейсі iOS, доглянутому в merges / ios / img / back_button.png. в той час як версія Android натомість може перехоплювати захопити події [backbutton] (../../ cordova / events / events.backbutton.html) від відповідної апаратної кнопки.
команди довідки
Cordova має кілька глобальних команд, які можуть допомогти вам, якщо ви застрягли або виникли проблеми. Команда help відображає всі доступні команди Cordova і їх синтаксис:
Крім того ви можете отримати більш детальну довідку по певній команді. наприклад:
Команда info формує список потенційно корисних відомостей, наприклад встановлених платформ і плагінів, версії SDK для кожної платформи і версії CLI і node.js:
Вона являє інформацію на екран і перенаправляє вихідні дані в локальний файл info.txt.
Примітка. в даний час, доступні тільки відомості про платформах iOS і Android.
Оновлення Cordova і вашого проекту
Після установки утиліти cordova. ви можете завжди оновити її до останньої версії, виконавши наступну команду:
Використовуйте цей синтаксис для установки певної версії:
Запустіть cordova - v. щоб побачити, яка версія в даний час встановлена. Виконайте команду npm info для більш довгого списку, який включає в себе поточну версію і інші доступні номери версій:
Кордова 3.0 є перша версія підтримує інтерфейс командного рядка, описані в цьому розділі. У разі оновлення проект з версії раніше ніж 3.0, необхідно створити новий проект, як описано вище, а потім скопіювати старі ресурси програми в каталог верхнього рівня www. Там, де це може бути застосовано, далі відомості про оновлення до 3.0 доступні в розділі "Керівництво по підтримуваним платформ". Після поновлення до інтерфейсу командного рядка cordova використовуйте npm update щоб залишатися актуальним, більш тривалі процедури, описані там більше не актуальні.
Cordova 3.0 + і раніше може вимагати різних змін структури каталогів рівня проекту та інших залежностей. Після того, як ви виконаєте команду npm зазначену вище для поновлення Cordova, необхідно переконатися, що ресурси вашого проекту відповідають вимогам останньої версії. Виконайте команди зазначену нижче для кожної платформи, під яку ви створюєте додаток: