Plugin.xml

Файл Plugin.xml определяет структуру и настройки, необходимые для вашего плагина. Он содержит несколько элементов для предоставления подробной информации о вашем плагине.

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="my-plugin-id"
    version="1.0.2">

engines and engine

Подэлементы элемента <engines> задают версии Apache Cordova-базированных фреймворков, которые поддерживает этот плагин. CLI завершается с ненулевым кодом для любого плагина, целевой проект которого не соответствует ограничениям движка. Если теги не указаны, CLI пытается установить плагин в указанный каталог проекта cordova без проверки соответствия.

ПРИМЕЧАНИЕ: В Cordova 6.1.0+ рекомендуется указывать зависимости платформы, плагина и CLI в package.json плагина. Подробнее см. указание зависимостей Cordova.

Примеры:

<engines>
  <engine name="cordova-android" version="=1.8.0" />
</engines>

Элементы движка также могут указывать нестрогие соответствия с помощью '>', '>=' и т.п. для избежания повторений и уменьшения поддержки при обновлении базовой платформы.

<engines>
  <engine name="cordova-android" version=">=1.8.0" />
</engines>

Теги <engine> также поддерживают все основные платформы Cordova. Указание тега cordova engine означает, что все версии Cordova на любой платформе должны соответствовать атрибуту версии движка. Вы также можете перечислить конкретные платформы и их версии, чтобы переопределить универсальный тег cordova engine:

<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>

Пример пользовательского фреймворка:

<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>

name

Элемент name используется для указания имени плагина. Этот элемент пока не поддерживает локализации.

Пример:

<name>Foo</name>

description

Элемент description используется для указания описания плагина. Этот элемент пока не поддерживает локализации.

Пример:

<description>Foo plugin description</description>

author

Содержание элемента author содержит имя автора плагина.

Пример:

<author>Foo plugin author</author>

keywords

Содержание элемента keywords содержит разделенные запятыми ключевые слова для описания плагина.

Пример:

<keywords>foo,bar</keywords>

license

Этот элемент используется для указания лицензии плагина.

Пример:

<license>Apache 2.0 License</license>

asset

Этот элемент используется для перечисления файлов или каталогов, которые должны быть скопированы в каталог www приложения Cordova. Любые элементы <asset>, которые вложены в элементы <platform>, определяют платформенно-специфичные веб-активы.

Примеры:

<!-- 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" />

Активы могут быть ориентированы на подкаталоги. Это создаст каталог js/experimental внутри каталога www, если он еще не существует, и скопирует файл new-foo.js, переименовав его в foo.js.

<asset src="www/new-foo.js" target="js/experimental/foo.js" />

js-module

Большинство плагинов содержат один или несколько JavaScript-файлов. Каждый тег <js-module> соответствует JavaScript-файлу и предотвращает необходимость добавления пользователем тега <script> для каждого файла. Не используйте обертки cordova.define, так как она добавляется автоматически. Модуль обернут в closure с модулем, exports и require в области видимости, как это обычно делается для AMD-модулей. Вложение элементов <js-module> в элементы <platform> определяет платформенно-специфичные JavaScript-модульные связи.

Пример:

При установке плагина с примером ниже, socket.js копируется в www/plugins/my-plugin-id/socket.js, и добавляется в www/cordova_plugins.js. Во время загрузки код в cordova.js использует XHR для чтения каждого файла и вставляет тег <script> в HTML.

<js-module src="socket.js" name="Socket">
</js-module>

Также для этого примера, с идентификатором плагина chrome-socket, имя модуля будет chrome-socket.Socket.

clobbers

Разрешено внутри элемента <js-module>. Используется для указания пространства имен под объектом window, куда вставляется module.exports. Вы можете использовать несколько элементов <clobbers>. Любой объект, отсутствующий в window, создается.

Пример:

<js-module src="socket.js" name="Socket">
  <clobbers target="chrome.socket" />
</js-module>

Здесь module.exports вставляется в объект window как window.chrome.socket.

merges

Разрешено внутри элемента <js-module>. Используется для указания пространства имен под объектом window, где module.exports сливается с любым существующим значением. Если ключ уже существует, версия модуля переопределяет исходную. Вы можете использовать несколько элементов <merges>. Любой объект, отсутствующий в window, создается.

Пример:

<js-module src="socket.js" name="Socket">
  <merges target="chrome.socket" />
</js-module>

Здесь module.exports сливается с любым существующим значением в window.chrome.socket.

runs

Разрешено внутри элемента <js-module>. Это означает, что ваш код должен быть указан с cordova.require, но не устанавливается в объект window. Это полезно при инициализации модуля, прикреплении обработчиков событий или иных операциях. Вы можете иметь только один тег <runs/>. Обратите внимание, что включение тега <runs/> с <clobbers/> или <merges/> избыточно, так как они также cordova.require ваш модуль.

Пример:

<js-module src="socket.js" name="Socket">
  <runs/>
</js-module>

dependency

Тег <dependency> позволяет указать другие плагины, от которых зависит текущий плагин. Плагины ссылаются на них по уникальным идентификаторам npm или URL GitHub.

Примеры:

<dependency id="cordova-plugin-someplugin" url="https://github.com/myuser/someplugin" commit="428931ada3891801" subdir="some/path/here" />
<dependency id="cordova-plugin-someplugin" version="1.0.1">

платформа

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

Пример:

<platform name="android">
  <!-- android-specific elements -->
</platform>

файл-источник

Идентифицирует исполняемый исходный код, который должен быть установлен в проект.

Примеры:

<!-- 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" />

файл-заголовок

Это похоже на элемент <source-file>, но специально для таких платформ, как iOS и Android, которые различают исходные файлы, заголовки и ресурсы. Не поддерживается Windows.

Пример:

Для iOS:

<header-file src="CDVFoo.h" />

файл-ресурс

Это похоже на элемент <source-file>, но специально для платформ, таких как iOS и Android, которые различают исходные файлы, заголовки и ресурсы.

Примеры:

Для Android:

<resource-file src="FooPluginStrings.xml" target="res/values/FooPluginStrings.xml" />

Для Windows:

<resource-file src="src/windows/win81/MobServices.pri" target="win81/MobServices.pri" device-target="windows" versions="8.1" arch="x64"/>

файл-конфигурации

Идентифицирует 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>

Для атрибутов, специфичных для Windows:

<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions="&lt;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>

Приведённый выше пример установит для платформ до 8.1 (Windows 8, в частности) необходимость использования устройства webcam и общей функции picturesLibrary, и применит функцию устройства webcam только к проектам Windows 8.1, которые собираются для Windows Phone. Системы Windows desktop 8.1 останутся неизменными.

изменить-конфигурацию

Аналогично config-file, edit-config идентифицирует XML-файл конфигурации для изменения, указывая, где в документе должны быть внесены изменения, и что должно быть изменено. Вместо добавления новых дочерних элементов в дерево XML-документа, edit-config вносит изменения в атрибуты XML-элементов. Существует два режима, определяющие тип изменения атрибутов: merge или overwrite. У edit-config есть один дочерний элемент, содержащий атрибуты, которые нужно добавить.

Пример:

<!-- plugin-1 -->
<edit-config file="AndroidManifest.xml" target="/manifest/uses-sdk" mode="merge">
    <uses-sdk android:minSdkVersion="16" android:maxSdkVersion="23" />
</edit-config>
<edit-config file="AndroidManifest.xml" target="/manifest/application/activity[@android:name='MainActivity']" mode="overwrite">
    <activity android:name="MainActivity" android:label="NewLabel" android:configChanges="orientation|keyboardHidden" />
</edit-config>

AndroidManifest.xml до добавления плагина plugin-1:

<manifest android:hardwareAccelerated="true" android:versionCode="1" android:versionName="0.0.1" package="io.cordova.hellocordova" xmlns:android="http://schemas.android.com/apk/res/android">
    ...
        <activity android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale" android:label="@string/activity_name" android:launchMode="singleTop" android:name="MainActivity" android:theme="@android:style/Theme.DeviceDefault.NoActionBar" android:windowSoftInputMode="adjustResize">
            ...
        </activity>
    ...
    <uses-sdk android:minSdkVersion="14" android:targetSdkVersion="23" />
</manifest>

AndroidManifest.xml после добавления плагина plugin-1:

<manifest android:hardwareAccelerated="true" android:versionCode="1" android:versionName="0.0.1" package="io.cordova.hellocordova" xmlns:android="http://schemas.android.com/apk/res/android">
    ...
        <activity android:configChanges="orientation|keyboardHidden" android:label="NewLabel" android:name="MainActivity">
            ...
        </activity>
    ...
    <uses-sdk android:maxSdkVersion="23" android:minSdkVersion="16" android:targetSdkVersion="23" />
</manifest>

Управление конфликтами edit-config

Несколько плагинов не могут изменять одни и те же атрибуты, так как это может привести к проблемам с приложением. Будет выброшено исключение, и установка плагина завершится неудачей. Конфликтные edit-config теги необходимо разрешить перед добавлением плагина. Внесите изменения в конфликтные теги, чтобы разрешить конфликт, а затем удалите и повторно добавьте обновленные плагины.

Существует возможность для тех, кто уверен, что плагин должен быть установлен, несмотря на конфликты. Флаг --force может быть использован с cordova plugin add. Принудительное добавление плагина вернёт конфликтующие изменения других плагинов, чтобы его можно было добавить без проблем. --force следует использовать с осторожностью, так как откат изменений других плагинов может привести к тому, что приложение не будет работать должным образом.

Если плагины попадут в странное состояние, удалите все плагины и добавьте их заново.

Пример:

Предположим, что плагин-1 из примера уже установлен. Попытка установить плагин-2 ниже вызовет ошибку, потому что плагин-1 уже изменил uses-sdk элемент в AndroidManifest.xml.

<!-- plugin-2 -->
<edit-config file="AndroidManifest.xml" target="/manifest/uses-sdk" mode="merge">
    <uses-sdk android:minSdkVersion="15" />
</edit-config>

Существует несколько способов добавления плагина-2:

Одно из возможных решений конфликта — удалить edit-config тег из плагина-2 и объединить его с edit-config тегом плагина-1 (предполагая, что плагин-1 не имеет проблем с этим изменением). Удалите оба плагина и добавьте их заново с этими изменениями. Плагин-2 должен быть добавлен без проблем.

Удаление edit-config из плагина-2 и объединение его с плагином-1:

<!-- plugin-1 -->
<edit-config file="AndroidManifest.xml" target="/manifest/uses-sdk" mode="merge">
    <uses-sdk android:minSdkVersion="15" android:maxSdkVersion="23" />
</edit-config>
<edit-config file="AndroidManifest.xml" target="/manifest/application/activity[@android:name='MainActivity']" mode="overwrite">
    <activity android:name="MainActivity" android:label="NewLabel" android:configChanges="orientation|keyboardHidden" />
</edit-config>

Результат AndroidManifest.xml после удаления и повторного добавления обоих плагинов:

<manifest android:hardwareAccelerated="true" android:versionCode="1" android:versionName="0.0.1" package="io.cordova.hellocordova" xmlns:android="http://schemas.android.com/apk/res/android">
    ...
        <activity android:configChanges="orientation|keyboardHidden" android:label="NewLabel" android:name="MainActivity">
            ...
        </activity>
    ...
    <uses-sdk android:maxSdkVersion="23" android:minSdkVersion="15" android:targetSdkVersion="23" />
</manifest>

Второй способ добавления плагина-2 включает добавление плагина с --force. Конфликтное edit-config изменение из плагина-1 будет отменено, и изменение плагина-2 будет применено. Результирующий AndroidManifest.xml будет содержать uses-sdk изменение из плагина-2 и activity изменение из плагина-1. Обратите внимание, что только uses-sdk изменение из плагина-1 исчезло, так как это единственное конфликтующее изменение.

Результат AndroidManifest.xml после принудительного добавления плагина-2:

<manifest android:hardwareAccelerated="true" android:versionCode="1" android:versionName="0.0.1" package="io.cordova.hellocordova" xmlns:android="http://schemas.android.com/apk/res/android">
    ...
        <activity android:configChanges="orientation|keyboardHidden" android:label="NewLabel" android:name="MainActivity">
            ...
        </activity>
    ...
    <uses-sdk android:minSdkVersion="15" android:targetSdkVersion="23" />
</manifest>

Примечание: Отменённые изменения из --force исчезнут навсегда. Они не появятся после удаления плагина, который был добавлен принудительно. Если отменённые изменения необходимы, все связанные плагины должны быть удалены и добавлены заново.

plugins-plist

Указывает ключ и значение для добавления к соответствующему файлу AppInfo.plist в проекте iOS Cordova. Это устаревший способ, так как он применяется только для cordova-ios 2.2.0 и ниже. Используйте тег <config-file> для более новых версий Cordova.

Пример:

<plugins-plist key="Foo" string="CDVFoo" />

lib-файл

Подобно файлам source, resource и header, но специально для платформ, таких как BlackBerry 10, которые используют пользовательские библиотеки. Для платформы Windows элемент <lib-file> позволяет включить <SDKReference> в сгенерированные файлы проекта Windows.

Примеры:

<lib-file src="src/BlackBerry10/native/device/libfoo.so" arch="device" />
<lib-file src="src/BlackBerry10/native/simulator/libfoo.so" arch="simulator" />

Для Windows:

<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" />

фреймворк

Идентифицирует фреймворк (обычно часть ОС/платформы), от которого зависит плагин.

Примеры:

Для iOS:

<framework src="libsqlite3.dylib" />
<framework src="social.framework" weak="true" />
<framework src="relative/path/to/my.framework" custom="true" />
<framework src="GoogleCloudMessaging" type="podspec" spec="~> 1.2.0" />

В Android (по состоянию на cordova-android@4.0.0) теги framework используются для включения зависимостей Maven или для включения связанных проектов библиотек.

<!-- Depend on latest version of GCM from play services -->
<framework src="com.google.android.gms:play-services-gcm:+" />
<!-- Depend on v21 of appcompat-v7 support library -->
<framework src="com.android.support:appcompat-v7:21+" />
<!-- Depend on library project included in plugin -->
<framework src="relative/path/FeedbackLib" custom="true" />

Framework также может использоваться для добавления пользовательских файлов .gradle в основной файл .gradle проекта:

<framework src="relative/path/rules.gradle" custom="true" type="gradleReference" />

В Windows использование custom='true' и type='projectReference' добавит ссылку на проект, которая будет добавлена к этапам компиляции и компоновки проекта Cordova. По сути, это единственный способ в настоящее время, которым 'custom' фреймворк может нацеливаться на несколько архитектур, поскольку они явно строятся как зависимость ссылающимся приложением Cordova.

<framework src="path/to/project/LibProj.csproj" custom="true" type="projectReference"/>

Примеры использования этих атрибутов, специфичных для 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" />
<framework src="src/windows/example.dll" target-dir="bin/x64" arch="x64" custom="true"/>

info

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

Пример:

<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>

hook

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

Пример:

<hook type="after_plugin_install" src="scripts/afterPluginInstall.js" />

uses-permission

В некоторых случаях плагину может потребоваться вносить изменения в конфигурацию, зависящие от целевого приложения. Например, для регистрации в C2DM на Android приложению с идентификатором пакета my-app-id может потребоваться разрешение, например:

<uses-permission android:name="my-app-id.permission.C2D_MESSAGE"/>

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

<uses-permission android:name="$PACKAGE_NAME.permission.C2D_MESSAGE"/>

CLI заменяет ссылки на переменные указанным значением или пустой строкой, если значение не найдено. Значение ссылки на переменную может быть обнаружено (в этом случае из файла AndroidManifest.xml) или указано пользователем инструмента; точный процесс зависит от конкретного инструмента.

Plugman может попросить пользователей указать необходимые переменные плагина. Например, ключи API для C2M и Google Maps можно указать в качестве аргумента командной строки:

plugman --platform android --project /path/to/project --plugin name|git-url|path --variable API_KEY=!@CFATGWE%^WGSFDGSDFW$%^#$%YTHGsdfhsfhyer56734

Некоторые имена переменных следует оставлять зарезервированными, например, $PACKAGE_NAME. Это уникальный идентификатор стиля обратной области имени для пакета, соответствующий CFBundleIdentifier в iOS или атрибуту package верхнего уровня элемента manifest в файле AndroidManifest.xml.

preference

Как видно из предыдущего раздела, иногда плагину может потребоваться, чтобы пользователь указал значения для своих переменных. Чтобы сделать эти переменные обязательными, тег <platform> должен содержать тег <preference>. CLI проверяет, переданы ли эти необходимые настройки. Если нет, он должен предупредить пользователя, как передать переменную, и завершиться с ненулевым кодом. Настройки могут ссылаться друг на друга в plugin.xml с помощью синтаксиса $PREFERENCE_NAME.

Пример:

<preference name="MY_CUSTOM_STRING" default="default-value" />

<!--
    The preference may be referenced elsewhere in plugin.xml like so:
-->
<config-file target="./res/values/strings.xml" parent="/resources">
    <string name="custom">$MY_CUSTOM_STRING</string>
</config-file>