Plugin.xml

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

плагин

Элемент 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 и 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>Foo</name>

описание

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

Пример:

<description>Foo plugin description</description>

автор

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

Пример:

<author>Foo plugin author</author>

ключавые слова

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

Пример:

<keywords>foo,bar</keywords>

лицензия

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

Пример:

<license>Apache 2.0 License</license>

ресурс

Этот элемент используется для перечисления файлов или каталогов, которые необходимо скопировать в каталог 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

Большинство плагинов содержат один или несколько JavaScript файлов. Каждый тег <js-module> соответствует JavaScript файлу и освобождает пользователей плагина от необходимости добавлять тег <script> для каждого файла. Не заключайте файл в cordova.define, так как он добавляется автоматически. Модуль заключён в замыкание с модулем, экспортом и 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> позволяет вам указать другие плагины, от которых зависит текущий плагин. Плагины ссылаются по уникальному id 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"/>

<!-- Example of referencing  -->
<resource-file src="x86/foo.dll" target="foo.dll" arch="x86" reference="true" />
<resource-file src="x64/foo.dll" target="foo.dll" arch="x64" reference="true" />

ПРИМЕЧАНИЕ: target следует использовать обратные слэши, чтобы избежать ошибки DEP2100 при развертывании в Visual Studio.

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

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

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

Пример:

Предположим, плагин plugin-1 из примера выше уже установлен. Попытка установить плагин plugin-2 ниже вызовет ошибку, потому что plugin-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>

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

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

Удаление edit-config из плагина plugin-2 и объединение его с плагином plugin-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>

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

Результат AndroidManifest.xml после принудительного добавления плагина plugin-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 в проекте Cordova на iOS. Это устарело, так как применяется только к cordova-ios 2.2.0 и ниже. Используйте тег <config-file> для более новых версий Cordova.

Пример:

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

lib-file

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

Для Android элемент <lib-file> используется для установки файлов .jar в каталоге libs проекта. Он поддерживает только атрибут src, который содержит относительный путь к файлу .jar.

Примеры:

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

framework

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

Примеры:

Для 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. По сути, это единственный способ в настоящее время, позволяющий «пользовательскому» фреймворку ориентироваться на несколько архитектур, так как они явно строятся как зависимость от ссылающегося приложения 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"/>

Ещё один пример использования атрибутов Windows для добавления ссылки на компоненты WinMD, написанные на C# и C++, чья API будет доступна во время выполнения:

<!-- C# component that consists of one .winmd file -->
<framework src="lib\windows\component.winmd" versions="<10.0" />
<!-- C++ component with separated metadata and implementation-->
<framework src="lib\windows\x86\cppcomponent.winmd"
           implementation="lib\windows\x86\cppcomponent.dll"
           target-dir="component\x86" arch="x86" versions=">=10.0" />

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>