Спецификация расширений
Файл plugin.xml
представляет собой документ XML c пространством имен plugins
: http://apache.org/cordova/ns/plugins/1.0
. Он содержит узел верхнего уровня plugin
, который определяет сам плагин, и дочерние узлы, которые определяют структуру плагина.
Простой пример элемента plugin:
<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
xmlns:android="http://schemas.android.com/apk/res/android"
id="com.alunny.foo"
version="1.0.2">
Элемент plugin
Элементом plugin
является элементом верхнего уровня в файле манифеста плагина. Он имеет следующие атрибуты:
xmlns
(обязательно): пространство имен plugin,http://apache.org/cordova/ns/plugins/1.0
. Если документ содержит XML из другого пространства имен, такие как теги для добавленияAndroidManifest.xml
файл, эти пространства имен также должны быть включены в элемент верхнего уровня.id
(обязательный): уникальный идентификатор плагина, записывается в обратном формате доменных имен, напримерcom.alunny.foo
version
(обязательный): номер версии плагина, который соответствует условиям следующего регулярного выражения:^\d+[.]\d+[.]\d+$
Элементы engines и engine
Дочерние элементы для элемента <engines>
определяют основанный на Apache Cordova фреймоворк, который поддерживается данным плагином. Пример:
<engines>
<engine name="cordova" version="1.7.0" />
<engine name="cordova" version="1.8.1" />
<engine name="worklight" version="1.0.0" platform="android" scriptSrc="worklight_version"/>
</engines>
Аналогично атрибуту version
элемента <plugin>
, указанная версия должна соответствовать регулярному выражению:
^\d+[.]\d+[.]\d+$
Элементы engine также могут указывать нечеткие параметры совпадения версий, чтобы избежать повторений или по упрощению поддержки, во время обновления платформы. Инструментарий проверяющий совместимость должен поддерживать как минимум определения содержащие >
, >=
, <
и <=
, например:
<engines>
<engine name="cordova" version=">=1.7.0" />
<engine name="cordova" version="<1.8.1" />
</engines>
Теги <engine>
также поддерживаются на всех платформах, на которых работает Cordova. Указание имени cordova
для тега engine означает, что все версии Cordova на любой платформе должны соответствовать версии указанной в атрибуте version. Для того, чтобы переопределить включающий в себя все платформы тег engine со значением cordova
, вы можете указывать индивидуальные платформы и их версии:
<engines>
<engine name="cordova" version=">=1.7.0" />
<engine name="cordova-android" version=">=1.8.0" />
<engine name="cordova-ios" version=">=1.7.1" />
</engines>
Вот список платформ, который тег 'engine
- 'android-sdk' // возвращает наивысший установленный уровень Android API * 'apple-xcode' // возвращает версию xcode * 'apple-ios' // возвращает наивысшую, установленную версию iOS * 'apple-osx' // возвращает версию OSX * 'blackberry-ndk' // возвращает версию нативную BlackBerry SDK
Указание пользовательских фреймвёрков на основе Apache Cordova должны быть перечислены с использованием тега engine следующим образом:
<engines>
<engine name="my_custom_framework" version="1.0.0" platform="android" scriptSrc="path_to_my_custom_framework_version"/>
<engine name="another_framework" version=">0.2.0" platform="ios|android" scriptSrc="path_to_another_framework_version"/>
<engine name="even_more_framework" version=">=2.2.0" platform="*" scriptSrc="path_to_even_more_framework_version"/>
</engines>
При указании пользовательского фреймвёрка основанного на Apache Cordova обязательно, чтобы элемент engine включал в себя следующие атрибуты: name
, version
, scriptSrc
, иplatform
.
name
(обязательно): Отображаемое пользователю имя вашего фреймвёрка.version
(обязательно): минимальная версия вашего фреймвёрка, которая требуется для установки плагина.scriptSrc
(обязательно): файл сценария, который говорит plugman, какая версия пользовательского фреймвёрка установлена. В идеале этот файл должен быть в каталоге верхнего уровня каталога plugin.platform
(обязательно): какие платформы, поддерживает ваш фреймвёрк. Вы можете использовать подстановочный знак*
для указания того что поддерживаются все платформ, или укажите имена платформ разделенные символом |, напримерandroid|ios|blackberry10
или просто одну платформу, например:android
.
plugman завершает выполнение с ненулевым кодом ошибки для любого плагина, который будет добавляться в проект, параметры которого не соответствует ограничениям необходимого фреймвёрка для данного плагина.
Если теги <engine>
не указаны, plugman пытается установить плагин в каталог проекта Cordova без проверки ограничений.
Элемент name
Текст содержащий название плагина, как оно будет отображаться пользователям. Например:
<name>Foo</name>
Этот элемент (пока) не поддерживает локализацию.
Элемент description
Текст содержащий описание плагина, как оно будет отображаться пользователям. Например:
<description>Foo plugin description</description>
Этот элемент (пока) не поддерживает локализацию.
Элемент author
Имя автора плагина. Текстовое содержимое элемента содержит имя автора плагина. Например:
<author>Foo plugin description</author>
Элемент keywords
Ключевые слова для плагина. Текстовое содержимое элемента содержит разделенные запятыми ключевые слова характеризующие плагин. Например:
<keywords>foo,bar</keywords>
Элемент Лицензия
Лицензия на использование плагина. Текстовое содержимое элемента содержит лицензию для плагина. Например:
<license>Apache 2.0 License</license>
Элемент asset
Один или несколько элементов указывающие файлы или каталоги, которые будут копироваться в каталог www
приложения Cordova. Примеры:
<!-- a single file, to be copied in the root directory -->
<asset src="www/foo.js" target="foo.js" />
<!-- a directory, also to be copied in the root directory -->
<asset src="www/foo" target="foo" />
Все теги <asset>
должны содержать атрибуты src
и target
. Веб-плагины состоят в основном из элементов <asset>
. Любые теги <asset>
, вложенные в теги <platform>
определяют ресурсы, которые специфичны для определенной платформы, как описано ниже. Атрибуты включают в себя:
src
(обязательно): расположение файла или каталога, в пакете плагина, относительно документаplugin.xml
. Если файл не существует в указанном вsrc
расположении, plugman останавливается и отменяет процесс установки, выдает уведомление о конфликте и выходит с ненулевым кодом.target
(обязательно):Месторасположение файла или каталога, в приложении Cordova, где должны располагаться ресурсы указанные в теге src. Месторасположение указывается относительно каталога
www
. Ресурсы могут быть перемещены в подкаталогах, например:создает каталог
js/experimental
в пределах каталогаwww
, если только этот каталогу уже не существует, затем копируетnew-foo.js
файл и переименовывает его вfoo.js
. Если файл уже существует в целевом расположении, plugman останавливается и отменяет процесс установки, выдает уведомление о конфликте и выходит с ненулевым кодом.
Элемент js-module
Большинство плагинов включают один или несколько файлов JavaScript. Каждый элемент <js-module>
соответствует файлу JavaScript и устраняет необходимость в добавлении тега <script>
для каждого файла, в файле index.html. В то время как теги <asset>
просто копируют файл из подкаталога плагина в каталог www
, теги <js-module>
являются гораздо более сложными конструкциями. Они выглядят так:
<js-module src="socket.js" name="Socket">
<clobbers target="chrome.socket" />
</js-module>
При установке плагина в примере указанном выше, socket.js
копируется в www/plugins/my.plugin.id/socket.js
и для этого файла добавляется запись в файле www/cordova_plugins.js
. Во время загрузки, код в cordova.js
использует XHR для считывания каждого файла, зарегистрированного в www/cordova_plugins.js и добавляет тег <script>
в HTML, для каждого такого файла. Он добавляет сопоставление, описывающее необходимо добавить содержимое файла в общее пространство имен, или расширить уже существующее описание JS объекта, как описано ниже.
Не оборачивайте файл с использованием cordova.define
, так как это будет осуществляться автоматически. Модуль упаковывается в замыкания(closure), с параметрами module
, exports
, и require
в области видимости, как это принято для AMD модулей.
Подробная информация о теге <js-module>
:
src
: Ссылается на файл в каталоге плагина относительно файлаplugin.xml
.name
: Определяет последнюю часть имени модуля, определенного в данном файле. Как правило, может быть, все, что вам нравится. Это значение важно только в том случае если вы хотите использоватьcordova.require
для импорта других частей вашего плагина в коде JavaScript. Полное имя AMD модуля для<js-module>
этоid
вашего плагин со следующим значениемname
. Из примера указанного выше, для плагина сid
-chrome.socket
, полное имя модуляchrome.socket.Socket
.Три теги разрешены внутри
<js-module>
:-
<clobbers target="some.value"/>
Указывает, что значениеmodule.exports
добавляется в объектwindow
таким образом, что становится доступно какwindow.some.value
. Вы можете иметь столько<clobbers>
сколько вам нравится. Любой объект, отсутствующий в объектеwindow
будет создан при необходимости. -
<merges target="some.value"/>
Указывает, что модуль должны быть объединены с любым уже существующим значением вwindow.some.value
. Если какой либо ключ уже существует в объекте window, объект указанный в модуле переопределяет оригинал. Вы можете иметь столько<merges>
сколько вам нравится. Любой объект, отсутствующий в объектеwindow
будет создан при необходимости. -
<runs/>
означает, что ваш код должен быть указан сcordova.require
, но не добавлен к объектуwindow
. Это полезно при инициализации модуля, присоединения обработчиков событий или в других случаях. Вы можете иметь не более одного тега<runs/>
. Обратите внимание, что использование<runs/>
совместно с<clobbers/>
или<merges/>
является излишним, так как эти директивы тоже загружают ваш модуль с помощьюcordova.require
. - Пустой
<js-module>
также загружается и может быть доступен в других модулях с помощьюcordova.require
.
-
Если src
не указывает на существующий файл, plugman останавливается и отменяет установку, выдает уведомление о проблеме и выходит с ненулевым кодом.
Вложение тега <js-module>
внутри элемента <platform>
объявляет JavaScript модуль, специфический для выбранной платформы.
Элемент зависимость
Тег <dependency>
позволяет указать другие плагины, от которых зависит текущий плагин. В то время как будущих версий будет доступ к ним из репозиториев плагинов, в краткосрочной перспективе плагины прямо упоминается по URL в тегах <dependency>
. Они выглядят следующим образом:
<dependency id="com.plugin.id" url="https://github.com/myuser/someplugin" commit="428931ada3891801" subdir="some/path/here" />
id
: определяет идентификатор плагина. Он должен быть глобально уникальным и выраженной в обратном формате доменных имен. Хотя ни одно из этих ограничений в настоящее время не применяется, это может произойти в будущем.url
: URL-адрес для плагина. Этот адрес должен указывать на репозиторий git, который plugman будет пытаться клонировать.commit
: Это любая ссылка git, понятная дляgit checkout
: имя ветки или тега (например,master
,0.3.1
), или хеша коммита (например,975ddb228af811dd8bb37ed1dfd092a3d05295f9
).subdir
: Указывает, что зависимость целевого плагина существует как подкаталог git-репозитория. Это полезно, потому что она позволяет определять репозиторий содержащий несколько связанных плагинов, и указывать каждый из них индивидуально.
В будущем будут введены ограничения версии, и репозиторий плагинов будет существовать для поддержки выбора плагина по имени вместо явного URL-адреса.
Относительные пути для зависимостей
Если задать url
для тега<dependency>
как "."
и указать subdir
, зависимый плагин будет установлен из того же локального или удаленного репозитория что и основной плагин, который определил тег <dependency>
.
Обратите внимание, что subdir
всегда указывает путь относительно корня git-репозитория, а не папки основного плагина. Это верно, даже если вы установили плагин с указанием локального пути к нему. Plugman находит корень репозитория git, а затем находит там же другой плагин.
Элемент platform
<platform>
Тег определяет платформы, которые имеют связанные исходные файлы или требуют изменения в их конфигурационных файлах. Инструменты, с помощью этой спецификации могут определить поддерживаемые платформы и установить код в проекты Cordova.
Плагины без тегов <platform>
считаются содержащими только JavaScript и поэтому устанавливаются на любых платформах.
Образец тега platform:
<platform name="android">
<!-- android-specific elements -->
</platform>
<platform name="ios">
<!-- ios-specific elements -->
</platform>
Обязательный атрибут name
поддерживаемую платформу, связывая дочерние элементы с этой платформой.
Имена платформ должны быть в нижнем регистре. Перечислены имена платформ, в произвольном порядке:
- amazon-fireos
- android
- blackberry10
- iOS
- wp7
- wp8
Элемент source-file
Элемент <source-file>
определяет исполняемый файл исходного кода, который должен быть установлен в проект. Примеры:
<!-- android -->
<source-file src="src/android/Foo.java"
target-dir="src/com/alunny/foo" />
<!-- ios -->
<source-file src="src/ios/CDVFoo.m" />
<source-file src="src/ios/someLib.a" framework="true" />
<source-file src="src/ios/someLib.a" compiler-flags="-fno-objc-arc" />
Он поддерживает следующие атрибуты:
src
(обязательно): расположение файла относительноplugin.xml
. Еслиsrc
файл не найден, plugman останавливается и отменяет установку, выдает уведомление об этой проблеме и выходит с ненулевым кодом.target-dir
: Каталог, в который должны быть скопированы файлы, относительно корня проекта Cordova. На практике это наиболее важно для платформ на базе Java, где файл в пакетеcom.alunny.foo
должен быть расположен в каталогеcom/alunny/foo
. Для платформ, где исходный каталог не имеет значения этот атрибут должен быть опущен.Как и в случае с ресурсами, если
target
изsource-file
будет перезаписывать существующий файл, plugman остановится и отменит установку. После чего выдаст уведомление об этой проблеме и выйдет с ненулевым кодом.framework
(только для iOS-устройств): Если значениеtrue
, также добавляет указанный файл в качестве фреймвёрка в проект.compiler-flags
(только для iOS-устройств): Если установлено, присваивает указанный флаги компилятора для конкретного исходного файла.
Элемент config-file
Идентифицирует XML файл конфигурации который будет изменен, где в этом документе необходимо произвести изменения, и что следует изменить.
Два типа файлов, которые были протестированы на модификацию с использованием этого элемента, xml
и plist
файлы.
Элемент config-file
позволяет только добавить новые дочерние элементы в XML-дерево документа. Дочерние элементы это XML-литералы которые должны быть вставлены в целевой документ.
Пример для XML:
<config-file target="AndroidManifest.xml" parent="/manifest/application">
<activity android:name="com.foo.Foo" android:label="@string/app_name">
<intent-filter>
</intent-filter>
</activity>
</config-file>
Пример для plist
:
<config-file target="*-Info.plist" parent="CFBundleURLTypes">
<array>
<dict>
<key>PackageName</key>
<string>$PACKAGE_NAME</string>
</dict>
</array>
</config-file>
Элемент поддерживает следующие атрибуты:
target
:Файл который будет изменен и путь к нему относительно корня проекта Cordova.
Целевой объект может включать подстановочный знак (
*
) для элементов. В этом случае plugman рекурсивно просматривает структуру каталогов проекта и использует первое совпадение.На iOS, расположение файлов конфигурации относительно корневого каталога проекта не известно, поэтому указание приёмника для
config.xml
определяется какcordova-ios-project/MyAppName/config.xml
.Если указанный файл не существует, инструмент игнорирует изменения конфигурации и продолжает установку.
parent
: Селектор XPath, ссылающийся на на родительский элемент, для добавляемых в конфигурационный файл элементов. Если вы используете абсолютные селекторы, можно использовать подстановочный знак (*
) для указания корневого элемента, например,/*/plugins
.Для
plist
файлов,parent
определяет, в каком родительском ключе следует добавить указанные XML-данные.Если селектор не находит элемент в указанном документе, инструмент останавливается и процесс установки отменяется, после чего выдает предупреждение и выходит с ненулевым кодом.
Элемент plugins-plist
Это устаревший элемент, как он применяется только к cordova-ios 2.2.0 и ниже. Используйте тег <config-file>
для новых версий Cordova.
Пример:
<config-file target="config.xml" parent="/widget/plugins">
<feature name="ChildBrowser">
<param name="ios-package" value="ChildBrowserCommand"/>
</feature>
</config-file>
Указывает ключ и значение для добавления в корректный файл AppInfo.plist
в проекте Cordova iOS. Например:
<plugins-plist key="Foo" string="CDVFoo" />
Элементы resource-file и header-file
Как и исходные файлы (source-file), но специально для платформ, таких как iOS, которые делают различия между исходными файлами, заголовками и ресурсами. Например:
<resource-file src="CDVFoo.bundle" />
<resource-file src="CDVFooViewController.xib" />
<header-file src="CDVFoo.h" />
Пример для Android:
<resource-file src="FooPluginStrings.xml" target="res/values/FooPluginStrings.xml" />
Элемент lib-file
Также как исходные файлы, файлы ресурсов и заголовков, но специально для платформ, таких как BlackBerry 10 которые использут созданные пользователем библиотеки. Например:
<lib-file src="src/BlackBerry10/native/device/libfoo.so" arch="device" />
<lib-file src="src/BlackBerry10/native/simulator/libfoo.so" arch="simulator" />
Поддерживаемые атрибуты:
src
(обязательно): расположение файла относительноplugin.xml
. Еслиsrc
не удается найти, plugman останавливается и отменяет установку, выдает предупреждение о проблеме и выходит с ненулевым кодом.arch
: Архитектура для которой.so
файл был построен, либоdevice
илиsimulator
.
Элемент framework
Определяет фреймвёрк (обычно часть OS/платформы) от которого зависит плагин.
Примеры:
<framework src="libsqlite3.dylib" />
<framework src="social.framework" weak="true" />
src
Атрибут определяет фреймвёрки, которые plugman пытается добавить в проект Cordova, наиболее подходящим для данной платформы образом.
Необязательный атрибут weak
– это логическое значение, указывающее, должен ли фреймвёрк быть слабо связан с результирующим исполняемым файлом проекта. Значение по умолчаниюfalse
.
Элемент info
Дополнительная информация для пользователей. Это полезно, когда требуется дополнительные шаги, которые не могут быть легко автоматизированы или выходят за рамки работы plugman. Примеры:
<info>
You need to install __Google Play Services__ from the `Android Extras` section using the Android SDK manager (run `android`).
You need to add the following line to your `local.properties`
android.library.reference.1=PATH_TO_ANDROID_SDK/sdk/extras/google/google_play_services/libproject/google-play-services_lib
</info>
Переменные
В некоторых случаях плагину может потребоваться внести изменения в конфигурацию в зависимости от целевого приложения. Например, чтобы зарегистрироваться для C2DM на Android, приложение чей идентификатор пакета com.alunny.message
потребует разрешения, такие как:
<uses-permission
android:name="com.alunny.message.permission.C2D_MESSAGE"/>
В таких случаях, когда добавляемое содержание из файл plugin.xml
не известно заранее, можно указывать переменные с использованием знака доллара, за которым следует серия заглавных букв, цифр или знаками подчеркивания. Для приведенного выше примера, файл plugin.xml
будет включать следующий тег:
<uses-permission
android:name="$PACKAGE_NAME.permission.C2D_MESSAGE"/>
plugman заменяет ссылки на переменные, указанным значением, или пустой строкой, если значение переменной не найдено. Значение переменной могут быть обнаружено (в данном случае, из AndroidManifest.xml
файла) или указанно пользователем инструмента; точный процесс зависит от конкретного инструмента.
plugman может запросить пользователя указать переменные необходимые плагину. Например можно указать ключи API для C2M и Карт Google как аргумент командной строки:
plugman --platform android --project /path/to/project --plugin name|git-url|path --variable API_KEY=!@CFATGWE%^WGSFDGSDFW$%^#$%YTHGsdfhsfhyer56734
Чтобы сделать переменную обязательной, тег <platform>
должен содержать тег <preference>
. Например:
<preference name="API_KEY" />
plugman проверяет, переданы ли ему эти необходимые настройки. Если нет, то он должен предупредить пользователя как указать переменную и выйти с ненулевым кодом.
Некоторые имена переменных должны быть зарезервированы, как указано ниже.
$PACKAGE_NAME
Уникальный идентификатор в обратном стиле доменных имен, соответствующий пакету CFBundleIdentifier
на iOS или атрибут package
корневого элемента manifest
в файле AndroidManifest.xml
файл.