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
plugin.xmlファイル内の XML ドキュメントは、 plugins 名前空間: http://apache.org/cordova/ns/plugins/1.0 。 トップが含まれています 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> 要素のこのプラグインをサポートしている Apache コルドバ ベースのフレームワークのバージョンを指定します。例:
<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>
同様に、 <plugin> 要素の version 属性、指定されたバージョン文字列は正規表現に適合する主要マイナー パッチ文字列と一致する必要があります。
^\d+[.]\d+[.]\d+$
エンジン要素ファジーマッチの繰り返しを避けるために、基になるプラットフォームが更新されたときにメンテナンスを減らすためにも指定できます。 ツールの最小値をサポートする必要があります > 、 >= 、 < 、 <= 、例えば。
<engines>
<engine name="cordova" version=">=1.7.0" />
<engine name="cordova" version="<1.8.1" />
</engines>
<engine>タグはまたすべての主要なプラットフォーム上に存在するコルドバのデフォルト サポートをしています。 指定する、 cordova エンジン タグは任意のプラットフォーム上のコルドバのすべてのバージョンがエンジンのバージョン属性を満たす必要がありますを意味します。 キャッチ オールをオーバーライドするために、特定のプラットフォームとバージョンをリストすることも可能性があります 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>
ここでは、エンジンの既定の一覧を ‘‘タグをサポートしています： * ‘コルドバ’ *’ コルドバ-plugman’ * ‘コルドバ-アマゾン-fireos’ ' コルドバ人造人間 '' コルドバ ios' * ‘コルドバ-blackberry10’ *' コルドバ wp8' * ' コルドバ-windows8'
カスタム Apache コルドバ ベース フレームワークはエンジン タグの下に表示する必要がありますを指定しましょう。
<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 コルドバ ベース フレームワーク エンジン要素に次の属性が含まれている必要があります： name 、 version 、 scriptSrc とplatform.
name(必須): カスタム フレームワークの人間が判読できる名前。
version（必須）： バージョンをインストールするために、フレームワークがあります。
scriptSrc(必須): カスタム フレームワークのバージョンは plugman に指示するスクリプト ファイルです。理想的には、このファイルは、プラグイン ディレクトリの最上位レベル ディレクトリ内する必要があります。
platform(必須): あなたのフレームワークをサポートするプラットフォーム。 ワイルドカードを使用することがあります * すべてのプラットフォームのサポートされていることのようなパイプ文字で複数指定 android|ios|blackberry10 またはちょうどのような単一のプラットフォームandroid.
plugman は、そのターゲット プロジェクトがエンジンの制約を満たしていない任意のプラグインのためのゼロ以外のコードを中止します。
いいえの場合 <engine> タグを指定すると、plugman は盲目的に指定したコルドバ プロジェクト ディレクトリにインストールしようとしました。
テキスト コンテンツを持つプラグインの名前が含まれているプラグインを人間が判読できる名前。たとえば。
<name>Foo</name>
この要素はない （まだ） ローカライズを処理します。
プラグインを人間が判読できる説明。要素のテキスト コンテンツには、プラグインの説明が含まれます。例:
<description>Foo plugin description</description>
この要素はない （まだ） ローカライズを処理します。
プラグインの作成者の名前。要素のテキスト コンテンツには、プラグインの作者の名前が含まれます。例:
<author>Foo plugin description</author>
プラグインのキーワード。要素のテキスト コンテンツには、プラグインを記述するコンマで区切られたキーワードが含まれます。例:
<keywords>foo,bar</keywords>
プラグインのライセンス。要素のテキスト コンテンツには、プラグインのライセンスが含まれます。例:
<license>Apache 2.0 License</license>
1 つまたは複数の要素に Cordova アプリをコピーするディレクトリまたはファイル一覧 www ディレクトリ。例:
<!-- 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 の属性。 Web だけのプラグインが含まれている主 <asset> の要素。 どんな <asset> 要素内にネストされた <platform> 要素プラットフォーム固有の web 資産を指定して、以下のとおりです。 属性は次のとおりです。
src(必須): ファイルまたはディレクトリが含まれているプラグイン パッケージを基準に、 plugin.xml ドキュメント。 指定されたファイルが存在しない場合 src 、plugman 停止し、場所と、インストール プロセスを逆に、競合について通知を発行 0 以外のコードで終了します。
target(必須)。
ファイルまたはディレクトリ場所 Cordova アプリでは、相対的に、 www ディレクトリ。資産などのサブディレクトリを対象とすることができます。
<asset src="www/new-foo.js" target="js/experimental/foo.js" />
作成、 js/experimental ディレクトリ内で、 www ディレクトリ、しない限り、既に存在し、コピー、 new-foo.js ファイルし、名前が変更されます foo.js 。 ターゲットの場所にファイルが既に存在する場合 plugman 停止しインストール プロセスを逆に、競合について通知を発行し、ゼロ以外のコードで終了します。
ほとんどのプラグインには、1 つまたは複数の JavaScript ファイルが含まれます。 各 <js-module> タグ、JavaScript ファイルなどに対応し、なくなりますプラグインのユーザーを追加する、 <script> の各ファイルのタグ。 一方 <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 を使用して各ファイルの読み取りを注入、 <script> タグを HTML に。 それを壊したくまたは以下に示すように適切なマージ マッピングを追加します。
持つファイルをラップしない cordova.define 、それが自動的に追加されます。 モジュールで、閉鎖に包まれて module 、 exports と require スコープでは、AMD モジュールのために正常です。
詳細は <js-module> タグ。
srcを基準としてプラグイン ディレクトリ内のファイルを参照して、 plugin.xml ファイル。
nameモジュール名の最後の部分を提供します。 それは一般的にあなたが好きをすることができ、使用する場合にのみ問題 cordova.require の JavaScript コードであなたのプラグインの他の部分をインポートします。 モジュール名は <js-module> は、プラグインの id の値が続く name 。 上記の例のために、 id の chrome.socket 、モジュール名がchrome.socket.Socket.
3 つのタグ内で許可される <js-module> :
<clobbers target="some.value"/>示す、 module.exports が挿入されます、 window オブジェクトとして window.some.value 。 多くとして持つことができます <clobbers> あなたのよう。 任意のオブジェクトでは使用できません window が作成されます。
<merges target="some.value"/>モジュールで既存の値とマージされることを示します window.some.value 。 任意のキーが既に存在する場合、モジュールのバージョン、元より優先されます。 多くとして持つことができます <merges> あなたのよう。 任意のオブジェクトでは使用できません window が作成されます。
<runs/>あなたのコードで指定する必要があることを意味します cordova.require にインストールされていないが、 window オブジェクト。 イベント ハンドラーをアタッチするモジュールを初期化する場合に便利ですまたはそれ以外の場合。 あなただけ 1 つまで持つことができます <runs/> タグ。 メモを含む、 <runs/> と <clobbers/> または <merges/> は冗長ですのでまた cordova.require あなたのモジュール。
空の <js-module> まだロードし、他のモジュール経由でアクセスすることができますcordova.require.
場合 src plugman 停止インストールを逆に、問題の通知を発行し、0 以外のコードで終了します、既存のファイルに解決されません。
ネスト <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： プラグインの ID を提供します。 グローバルにユニークで逆ドメイン スタイルで表現をする必要があります。 どちらもこれらの制限は、現在適用されている間彼らは将来的にあるかもしれないです。
url： プラグインの URL。これはクローンを作成しようとする plugman、git リポジトリを参照ください。
commit: これは git の参照を理解して git checkout ： 分岐またはタグ名 (例えば、 master 、 0.3.1 )、またはコミットのハッシュ (例えば、975ddb228af811dd8bb37ed1dfd092a3d05295f9).
subdir: 対象となるプラグインの依存関係が git リポジトリのサブディレクトリとして存在することを指定します。 いくつかの関連プラグインを格納するリポジトリができるため、これは便利です、それぞれ個別に指定します。
将来的には、バージョンの制約が導入され、プラグイン ・ リポジトリーは明示的な Url の代わりに名前でフェッチをサポートするために存在します。
設定した場合、 url の <dependency> タグを "." を提供し、 subdir 、従属プラグインをインストールする同じローカルからまたは親プラグインとしてリモート git リポジトリを指定する、 <dependency> タグ。
注意してください、 subdir 常に親のプラグインではないの git リポジトリのルートからの相対パスを指定します。 これは、それを直接ローカルのパスで、プラグインをインストールする場合でも当てはまります。 Plugman は、git リポジトリのルートを検索し、そこから他のプラグインを検索します。
<platform>タグが関連付けられているネイティブ コードまたはその構成ファイルへの変更を必要とするプラットフォームを識別します。 この仕様を使用してツールはサポートされているプラットフォームを識別およびコルドバのプロジェクトにコードをインストールできます。
プラグインなし <platform> タグは JavaScript だけ、したがって、すべてのプラットフォームでインストール可能と見なされます。
サンプル プラットフォーム タグ:
<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 停止逆に、インストールの問題に関する通知を発行し、0 以外のコードで終了します。
target-dir: をファイルがコピー、コルドバ プロジェクトのルートからの相対ディレクトリです。 実習では、これでファイルの場所に Java ベースのプラットフォームのために最も重要なは、 com.alunny.foo パッケージ内に配置する必要があります、 com/alunny/foo ディレクトリ。 ソース ディレクトリが重要でないプラットフォームでは、この属性を省略してください。
同様に、資産場合、 target の source-file は既存のファイルを上書き、plugman 停止逆に、インストールの問題に関する通知を発行し、0 以外のコードで終了します。
framework(iOS の場合のみ): 場合に設定されている true 、またフレームワークとして、プロジェクト指定ファイルに追加されます。
compiler-flags(iOS の場合のみ): 場合設定、特定のソース ファイルの指定したコンパイラ フラグを割り当てます。
ドキュメントに変更を行う場所、および何を変更する必要があります変更する XML ベースの構成ファイルを示します。
この要素を変更するためにテストされている 2 つのファイルの種類は 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:
変更されるファイルとコルドバ プロジェクトのルートからの相対パス。
ターゲットは、ワイルドカードを含めることができます ( * ) 要素。この場合、plugman を再帰的にプロジェクトのディレクトリ構造を検索し、最初の一致を使用します。
IOS、上のプロジェクト ディレクトリのルートを基準にして構成ファイルの場所は知られていない、だからのターゲットを指定する config.xml を解決しますcordova-ios-project/MyAppName/config.xml.
指定したファイルが存在しない場合、ツール、構成の変更は無視され、インストールが続行されます。
parent構成ファイルに追加する要素の親を参照する: XPath セレクター。 絶対的なセレクターを使用する場合はワイルドカードを使用できます ( * ) 例えば、ルート要素を指定するには/*/plugins.
plist、ファイル、 parent どのような親キーの下で指定した XML を挿入するを決定します。
セレクターで指定したドキュメントの子を解決しない場合、ツールが停止した逆インストール プロセスにより警告が発行し、0 以外のコードで終了します。
after: XML スニペットを追加する後受け入れられた兄弟の優先順位一覧。 Http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff769509%28v=vs.105%29.aspx#BKMK _EXTENSIONSelementのような XML 要素の厳密な順序付けが必要なファイルの変更を指定するために便利です。
これは古いコルドバ ios 2.2.0 へとの下にのみ適用されます。使用、 <config-file> コルドバの新しいバージョンのタグ。
例:
<config-file target="config.xml" parent="/widget/plugins">
<feature name="ChildBrowser">
<param name="ios-package" value="ChildBrowserCommand"/>
</feature>
</config-file>
キーと、適切に追加する値を指定します AppInfo.plist iOS コルドバ プロジェクト内のファイル。たとえば。
< プラグイン plist キー文字列"Foo"= ="CDVFoo"/>
ソース ファイルのようなが iOS などのプラットフォームのために特別にソース ファイル、ヘッダー、およびリソース間区別します。iOS の例:
<resource-file src="CDVFoo.bundle" /> <resource-file src="CDVFooViewController.xib" /> <header-file src="CDVFoo.h" />
Android の例:
< リソース ファイル src="FooPluginStrings.xml"target="res/values/FooPluginStrings.xml"/>
ブラックベリー 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 停止、インストール、問題、問題について警告を反転し、0 以外のコードで終了します。
arch: 対象アーキテクチャ、 .so ファイルが作成されたら、どちらか device またはsimulator.
Windows プラットフォーム用 <lib-file> 要素は、< SDKReference > 生成された Windows プロジェクト ファイルに含めることができます。
サポートされている属性:
src(必須): を含む SDK の名前 (が生成された < SDKReference > 要素の Include 属性の値として使用されます)。
arch: を < SDKReference > のみ含めるように指定したアーキテクチャの構築を示します。 サポートされる値は x 86、x64 または ARM.
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 を与えられたプラットホームのための正しい方法のコルドバ プロジェクトに追加しようとしています。 フレームワークを識別します。
省略可能な weak 属性はフレームワークが弱いリンクする必要があるかどうかを示すブール値です。既定値は false.
省略可能な custom 属性が、フレームワークがプラグイン ファイルの一部として含まれているかどうかを示すブール値 (従ってないシステム フレームワークです)。 既定値は false です。 Android の src を治療する方法を指定します。 場合 true src アプリケーション プロジェクトのディレクトリからの相対パスそれ以外の場合--人造人間 SDK ディレクトリから。
オプションの type 属性に追加するフレームワークの型を示す文字列です。 現在のところ projectReference がサポートされていると Windows 用のみ。 使用して custom='true' と type='projectReference'、プロジェクトのコンパイルに追加されます + コルドバ プロジェクトの手順のリンクへの参照を追加します。 これは本質的に唯一の方法は現在 ‘カスタム’ フレームワークが対象にする複数のアーキテクチャ参照コルドバ アプリケーションである依存関係として構築されている明示的にです。
オプションの parent 属性は、現在 Android 上でのみサポートされます。 参照を追加するサブ プロジェクトを含むディレクトリへの相対パスを設定します。 既定値は .、すなわちアプリケーション プロジェクト。 この例でのようなサブ プロジェクト間参照を追加することができます。
<framework src="FeedbackLib" custom="true" /> <framework src="extras/android/support/v7/appcompat" custom="false" parent="FeedbackLib" />
Windows プラットフォームを絞り込むときに、フレームワークが含まれてする必要があります (すべて省略可能) の 3 つの追加属性をサポートします。
arch 属性をフレームワークのみ含めるように指定したアーキテクチャの構築を示します。 サポートされる値は x 86、x64 または ARM.
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>
特定の場合、プラグインは構成の変更、ターゲット アプリケーションに依存する必要があります。 たとえば、Android 上 C2DM を登録するパッケージ id が 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 が存在しない、指定された値または空の文字列に変数の参照を置き換えます。 変数参照の値 (この場合から 与えます ファイル) を検出したり、ツール; のユーザーによって指定されました。正確なプロセスは、特定のツールに依存します。
plugman は、プラグインの必要な変数を指定するユーザーを要求できます。たとえば、c2m-更新と Google Maps API キーは、コマンドライン引数として指定できます。
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 はこれらの必要な設定が渡されたことを確認します。それ以外の場合はそれに変数を渡すし、0 以外のコードで終了する方法をユーザーに警告する必要があります。
以下に示す特定の変数名を予約する必要があります。
逆ドメイン スタイル CFBundleIdentifier iOS または 与えます ファイルの最上位の マニフェストの 要素の パッケージ 属性に対応するパッケージの一意の識別子。