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 и 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, так как он добавляется автоматически. Модуль обернут в замыкание, с модулем, экспортом и 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"/>

<!-- 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 останутся неизменными.

edit-config

Подобно 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 в основной файл проекта build.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>