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.
Файл 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 является элементом верхнего уровня в файле манифеста плагина. Он имеет следующие атрибуты:
xmlns (обязательно): пространство имен, http://apache.org/cordova/ns/plugins/1.0. Если документ содержит XML из других пространств имен, таких как теги, которые будут добавлены к AndroidManifest.xml файл, эти пространства имен также должны быть включены в элемент верхнего уровня.
id (обязательный): уникальный идентификатор плагина, записывается в формате доменных имен, например com.alunny.foo
version (обязательно): номер версии плагина, который соответствует условиям следующего регулярного выражения:
^\d+[.]\d+[.]\d+$
Дочерние элементы элемента < engines > указывают версии 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’ тег поддерживает: * «cordova» * «cordova-plugman» * «cordova Амазонки fireos» * «cordova-android» * «cordova-ios» * «cordova-blackberry10» * «cordova-wp8» * «cordova-windows8»
Указание пользовательских фреймвёрков на основе 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>Foo</name>
Этот элемент (пока) не поддерживает локализацию.
Текст содержащий описание плагина, как оно будет отображаться пользователям. Например:
<description>Foo plugin description</description>
Этот элемент (пока) не поддерживает локализацию.
Имя автора плагина. Текстовое содержимое элемента содержит имя автора плагина. Например:
<author>Foo plugin description</author>
Ключевые слова для плагина. Текстовое содержимое элемента содержит разделенные запятыми ключевые слова характеризующие плагин. Например:
<keywords>foo,bar</keywords>
Лицензия на использование плагина. Текстовое содержимое элемента содержит лицензию для плагина. Например:
<license>Apache 2.0 License</license>
Один или несколько элементов указывающие файлы или каталоги, которые будут копироваться в каталог 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. Ресурсы могут быть перемещены в подкаталогах, например:
<asset src="www/new-foo.js" target="js/experimental/foo.js" />
создает каталог js/experimental в пределах каталога www, если только этот каталогу уже не существует, затем копирует new-foo.js файл и переименовывает его в foo.js . Если файл уже существует в целевом расположении, plugman останавливается и отменяет процесс установки, выдает уведомление о конфликте и выходит с ненулевым кодом.
Большинство плагинов включают один или несколько файлов 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> Тег определяет платформы, которые имеют связанные исходные файлы или требуют изменения в их конфигурационных файлах. Инструменты, с помощью этой спецификации могут определить поддерживаемые платформы и установить код в проекты Cordova.
Плагины без тегов <platform> считаются содержащими только JavaScript и поэтому устанавливаются на любых платформах.
Образец тега platform:
<platform name="android">
<!-- android-specific elements -->
</platform>
<platform name="ios">
<!-- ios-specific elements -->
</platform>
Обязательный атрибут name поддерживаемую платформу, связывая дочерние элементы с этой платформой.
Имена платформ должны быть в нижнем регистре. Перечислены имена платформ, в произвольном порядке:
Элемент <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-устройств): Если установлено, присваивает указанный флаги компилятора для конкретного исходного файла.
Идентифицирует 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-данные.
Если селектор не находит элемент в указанном документе, инструмент останавливается и процесс установки отменяется, после чего выдает предупреждение и выходит с ненулевым кодом.
after: Приоритетный список принятых братьев и сестер, после которого нужно добавить XML-фрагмент. Полезно для задания изменения в файлах, которые требуют строгий порядок элементов XML как http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff769509%28v=vs.105%29.aspx#BKMK _EXTENSIONSelement
Платформа Windows поддерживает два дополнительных атрибута (оба необязательных) затрагивающих meta-name package.appxmanifest:
Атрибут device-target указывает, что следует включить только при построении для указанного типа целевого устройства. Поддерживаемыми значениями являются win, phoneили all.
Атрибут versions указывает, что манифесты приложений для определенных версий Windows следует изменить только для версий, которые соответствуют указанной строке версии. Значение может быть любое допустимое значение для строки семантической диапазона версий.
Примеры использования этих атрибутов Windows:
<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions="<8.1.0">
<Capability Name="picturesLibrary" />
<DeviceCapability Name="webcam" />
</config-file>
<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions=">=8.1.0" device-target="phone">
<DeviceCapability Name="webcam" />
</config-file>
Приведенный выше пример установит pre-8.1 платформы (Windows 8, в частности) и запросит общие возможности устройства webcam и picturesLibrary, затем применит возможности устройства webcam только для проектов Windows 8.1 которые собираются для Windows Phone. Настольные системы Windows 8.1 остаются неизмененными.
Это устаревший элемент, как он применяется только к 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" />
Как и исходные файлы (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" />
Также как исходные файлы, файлы ресурсов и заголовков, но специально для платформ, таких как 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.
Для платформы Windows элемент <lib-file> позволяет включение <SDKReference> в создаваемых файлах проекта Windows.
Поддерживаемые атрибуты:
src (обязательно): имя пакета SDK для включения (который будет использоваться как значение атрибута Include создаваемого элемента <SDKReference> ).
arch: указывает, что <SDKReference> следует включить только при построении для заданной архитектуры. Поддерживаются следующие значения x86, x64 или ARM.
device-target: указывает, что <SDKReference> следует включить только при построении для указанного типа целевого устройства. Поддерживаются следующие значения win (или windows), phone или all.
versions: указывает, что <SDKReference> следует включить только при построении версий, которые соответствуют заданной строке версии. Значение может быть любое допустимое значение для строки семантической диапазона версий.
Примеры:
<lib-file src="Microsoft.WinJS.2.0, Version=1.0" arch="x86" /> <lib-file src="Microsoft.WinJS.2.0, Version=1.0" versions=">=8.1" /> <lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="phone" /> <lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="win" versions="8.0" arch="x86" />
Определяет фреймвёрк (обычно часть OS/платформы) от которого зависит плагин.
Примеры:
<framework src="libsqlite3.dylib" /> <framework src="social.framework" weak="true" /> <framework src="relative/path/to/my.framework" custom="true" /> <framework src="path/to/project/LibProj.csproj" custom="true" type="projectReference"/>
src Атрибут определяет фреймвёрки, которые plugman пытается добавить в проект Cordova, наиболее подходящим для данной платформы образом.
Необязательный атрибут weak – это логическое значение, указывающее, должен ли фреймвёрк быть слабо связан с результирующим исполняемым файлом проекта. Значение по умолчаниюfalse.
Необязательный атрибут custom – это логическое значение, указывающее, входит ли фреймворк в состав файлов плагина (таким образом это не системный фреймворк). По умолчанию — false. На Android он определяет как обрабатывать src. Если true src это относительный путь из каталога проекта приложения, в противном случае, из каталога Android SDK.
Необязательный атрибут type является строкой, указывающая тип фреймворка для добавления. В настоящее время только projectReference поддерживается и только для Windows. Использование custom='true' и type='projectReference' будет добавлять ссылку на проект, который будет добавляться к этапам компиляции + линковки проекта Cordova. По сути, это единственный способ в настоящее время указать что что «custom» фреймворк может ориентироваться на нескольких архитектур, так как как явно они построены как зависимость в ссылающемся cordova-приложении.
Не обязательный parent атрибут в настоящее время поддерживается только на Андроиде. Он задает относительный путь к каталогу, содержащему подпроект, на который необходимо добавить ссылку. Значение по умолчанию — ., то есть проект приложения. Она позволяет добавлять ссылки между под-проектами как в этом примере:
<framework src="FeedbackLib" custom="true" /> <framework src="extras/android/support/v7/appcompat" custom="false" parent="FeedbackLib" />
Платформа Windows поддерживает три дополнительные атрибуты (все необязательные) для уточнения когда фреймворк должны быть включен:
Атрибут arch указывает, что фреймворк следует включить только при создании для заданной архитектуры. Поддерживаются следующие значения x86, x64 или ARM.
Атрибут device-target указывает, что следует включить только при построении для указанного типа целевого устройства. Поддерживаются следующие значения win (или windows), phone или all.
Атрибут versions указывает, что фреймворк следует включить только при построении для версий, которые соответствуют заданной строке версии. Значение может быть любое допустимое значение для строки семантической диапазона версий.
Примеры использования этих атрибутов Windows:
<framework src="src/windows/example.dll" arch="x64" /> <framework src="src/windows/example.dll" versions=">=8.0" /> <framework src="src/windows/example.vcxproj" type="projectReference" target="win" /> <framework src="src/windows/example.vcxproj" type="projectReference" target="all" versions="8.1" arch="x86" />
Дополнительная информация для пользователей. Это полезно, когда требуется дополнительные шаги, которые не могут быть легко автоматизированы или выходят за рамки работы 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 the `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 проверяет, переданы ли ему эти необходимые настройки. Если нет, то он должен предупредить пользователя как указать переменную и выйти с ненулевым кодом.
Некоторые имена переменных должны быть зарезервированы, как указано ниже.
Уникальный идентификатор в обратном стиле доменных имен, соответствующий пакету CFBundleIdentifier на iOS или атрибут package корневого элемента manifest в файле AndroidManifest.xml файл.