Plugin.xml API

Plugin.xml 檔案定義了外掛所需的結構和設定。它具有多個元素來提供有關外掛的詳細資訊。

plugin

plugin 元素是外掛資訊清單的頂層元素。

屬性	描述
xmlns 字串	必要外掛命名空間，`http://apache.org/cordova/ns/plugins/1.0`。如果文件包含來自其他命名空間的 XML，例如在 Android 的情況下要新增到 `AndroidManifest.xml` 檔案的標籤，則這些命名空間也應包含在元素中。
id 字串	必要外掛的 npm 風格識別碼。
version 字串	必要外掛的版本號碼。支援 Semver 語法。

範例

<?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+ 中，建議在外掛的 package.json 中指定平台、外掛和 CLI 相依性。請參閱指定 Cordova 相依性以取得更多資訊

屬性	描述
name 字串	必要引擎的名稱。以下是支援的預設引擎：`cordova`、`cordova-plugman`、`cordova-android`、`cordova-browser`、`cordova-ios`、`windows-os`、`android-sdk` (傳回安裝的最高 Android api 層級)、`apple-xcode` (傳回 xcode 版本)、`apple-ios` (傳回安裝的最高 iOS 版本)、`apple-osx` (傳回 macOS 版本)。您也可以指定預設框架以外的自訂框架。
version 字串	必要安裝時框架必須具有的版本。支援 Semver 語法。
scriptSrc 字串	僅適用於自訂框架必要告知 plugman 自訂框架版本的腳本檔案。理想情況下，此檔案應位於外掛目錄的頂層目錄中。
platform 字串	僅適用於自訂框架必要您的框架支援的平台。您可以使用萬用字元 `*` 來表示支援所有平台，使用管道字元 (例如 `android\|ios`) 來指定多個平台，或只指定單一平台 (例如 `android`)。

範例

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

引擎元素也可以使用 '>'、'>=' 等來指定模糊比對，以避免重複，並減少基礎平台更新時的維護工作。

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

<engine> 標籤也預設支援 Cordova 存在的所有主要平台。指定 cordova 引擎標籤表示任何平台上的所有 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>

自訂框架範例

<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

此元素用於列出要複製到 Cordova 應用程式 www 目錄中的檔案或目錄。任何巢狀於 <platform> 元素中的 <asset> 元素都會指定特定於平台的網頁資產。

屬性	描述
src 字串	必要檔案或目錄在相對於 `plugin.xml` 文件的外掛套件中的位置。如果指定的 src 位置不存在檔案，CLI 會停止並復原安裝程序、發出有關衝突的通知，並以非零程式碼結束。
target 字串	必要檔案或目錄在相對於 `www` 目錄的 Cordova 應用程式中的位置。如果檔案已存在於目標位置，CLI 會停止並復原安裝程序、發出有關衝突的通知，並以非零程式碼結束。

範例

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

資產也可以以子目錄為目標。這將在 www 目錄中建立 js/experimental 目錄 (如果尚不存在)，並將 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 包裝檔案，因為它會自動新增。模組會包裝在閉包中，範圍內具有 module、exports 和 require，這對於 AMD 模組來說是正常的。在 <platform> 中巢狀 <js-module> 元素會宣告特定於平台的 JavaScript 模組繫結。

屬性	描述
src 字串	參考外掛目錄中相對於 `plugin.xml` 檔案的檔案。如果 src 未解析為現有檔案，CLI 會停止並復原安裝、發出問題通知，並以非零程式碼結束。
name 字串	提供模組名稱的最後一部分。它通常可以是您喜歡的任何內容，並且只有當您想要使用 cordova.require 在 JavaScript 程式碼中匯入外掛的其他部分時，才重要。`<js-module>` 的模組名稱是您的外掛 ID 後面接著名稱的值。

範例

安裝具有以下範例的外掛時，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>

同樣對於此範例，如果外掛 ID 為 chrome-socket，則模組名稱將為 chrome-socket.Socket。

clobbers

允許在 <js-module> 元素內使用。用於指定在 window 物件下插入 module.exports 的命名空間。您可以根據需要使用任意數量的 <clobbers>。任何在 window 上不可用的物件都會被建立。

屬性	描述
target 字串	將 module.exports 插入到的命名空間。

範例

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

在此，module.exports 會以 window.chrome.socket 的形式插入到 window 物件中。

merges

允許在 <js-module> 元素內使用。用於指定在 window 物件下 module.exports 與任何現有值合併的命名空間。如果任何金鑰已存在，則模組的版本會覆寫原始版本。您可以根據需要使用任意數量的 <merges>。任何在 window 上不可用的物件都會被建立。

屬性	描述
target 字串	module.exports 合併到的命名空間。

範例

<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 ID 或 github URL 進行參考。

屬性	描述
id 字串	提供外掛的 ID。
url 字串	外掛的 URL。這應參考 CLI 嘗試複製的 git 儲存庫。
commit 字串	這是 `git checkout` 可以理解的任何 git 參考：分支或標籤名稱 (例如，`master`、`0.3.1`) 或提交雜湊 (例如，`975ddb228af811dd8bb37ed1dfd092a3d05295f9`)。
subdir 字串	指定目標外掛相依性作為 git 儲存庫的子目錄存在。這很有幫助，因為它允許儲存庫包含多個相關的外掛，每個外掛都單獨指定。如果您將 `<dependency>` 標籤的 `url` 設定為 `"."` 並提供 `subdir`，則會從與指定 `<dependency>` 標籤的父外掛相同的本機或遠端 git 儲存庫中安裝相依的外掛。請注意，`subdir` 始終指定相對於 git 儲存庫根目錄的路徑，而不是父外掛。即使您使用直接指向它的本機路徑安裝外掛，情況也是如此。CLI 會找到 git 儲存庫的根目錄，然後從那裡找到其他外掛。
version 字串	所依賴的外掛版本。支援 Semver 語法。

範例

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

platform

識別具有相關原生程式碼或需要修改其設定檔的平台。使用此規格的工具可以識別支援的平台，並將程式碼安裝到 Cordova 專案中。沒有 <platform> 標籤的外掛會被視為僅限 JavaScript，因此可以安裝在任何和所有平台上。

屬性	描述
name 字串	必要允許的值：ios、android、browser、electron 識別支援的平台，並將元素的子元素與該平台建立關聯。

範例

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

source-file

識別應安裝到專案中的可執行原始程式碼。

屬性	描述
src 字串	必要檔案相對於 `plugin.xml` 的位置。如果找不到 src 檔案，CLI 會停止並復原安裝、發出有關問題的通知，並以非零程式碼結束。
target-dir 字串	應將檔案複製到的目錄，相對於 Cordova 專案的根目錄。實際上，這對於基於 Java 的平台最為重要，其中 `com.alunny.foo` 套件中的檔案必須位於 `com/alunny/foo` 目錄中。對於原始碼目錄不重要的平台，應省略此屬性。
framework 布林值	預設值：false 如果設定為 true，也會將指定檔案作為框架新增至專案。
compiler-flags 字串	如果設定，則會為特定的原始碼檔案指定指定的編譯器旗標。

範例

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

header-file

這類似於 <source-file> 元素，但專門用於區分原始碼檔案、標頭和資源的平台 (例如 iOS 和 Android)。

屬性	描述
src 字串	必要檔案相對於 `plugin.xml` 的位置。如果找不到 src 檔案，CLI 會停止並復原安裝、發出有關問題的通知，並以非零程式碼結束。
target-dir 字串	應將檔案複製到的目錄，相對於 Cordova 專案的根目錄。
type 字串	如果此值為 `BridgingHeader`，則會將檔案匯入到 `Bridging-Header.h` 中，並可從 swift 程式呼叫。

範例

適用於 iOS

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

resource-file

這類似於 <source-file> 元素，但專門用於像 iOS 和 Android 這種區分原始碼檔案、標頭檔和資源的平台。

屬性	描述
src 字串	必要檔案相對於 `plugin.xml` 的位置。如果找不到 src 檔案，CLI 會停止並復原安裝、發出有關問題的通知，並以非零程式碼結束。
target 字串	檔案將複製到您目錄中的路徑。

Android 範例

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

config-file

識別要修改的基於 XML 的設定檔、應在該文件中進行修改的位置以及應修改的內容。經過測試可使用此元素進行修改的兩種檔案類型是 xml 和 plist 檔案。config-file 元素僅允許您將新的子元素附加到 XML 文件樹中。這些子元素是要插入目標文件中的 XML 字面值。

屬性	描述
target 字串	要修改的檔案，以及相對於 Cordova 專案根目錄的路徑。如果指定的檔案不存在，該工具會忽略設定變更並繼續安裝。目標可以包含萬用字元 (`*`) 元素。在這種情況下，CLI 會遞迴搜尋整個專案目錄結構，並使用第一個符合項。在 iOS 上，相對於專案目錄根目錄的設定檔位置未知，因此指定 `config.xml` 目標會解析為 `cordova-ios-project/MyAppName/config.xml`。
parent 字串	一個 XPath 選擇器，引用要新增至設定檔的元素的父元素。如果您使用絕對選擇器，則可以使用萬用字元 (``) 來指定根元素，例如 `//plugins`。如果選擇器無法解析為指定文件的子元素，該工具將停止並還原安裝過程、發出警告，並以非零代碼退出。對於 `plist` 檔案，`parent` 決定應在哪個父索引鍵下插入指定的 XML。
after 字串	一個已接受的兄弟節點的優先順序列表，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>

edit-config

與 config-file 類似，edit-config 識別要修改的基於 XML 的設定檔、應在該文件中進行修改的位置以及應修改的內容。edit-config 並非將新的子元素附加到 XML 文件樹中，而是修改 XML 元素的屬性。有兩種模式將決定要進行哪種類型的屬性修改：merge 或 overwrite。edit-config 有一個子元素，該子元素將包含要新增的屬性。

屬性	描述
file 字串	要修改的檔案，以及相對於 Cordova 專案根目錄的路徑。如果指定的檔案不存在，該工具會忽略設定變更並繼續安裝。目標可以包含萬用字元 (`*`) 元素。在這種情況下，CLI 會遞迴搜尋整個專案目錄結構，並使用第一個符合項。在 iOS 上，相對於專案目錄根目錄的設定檔位置未知，因此指定 `config.xml` 目標會解析為 `cordova-ios-project/MyAppName/config.xml`。
target 字串	一個 XPath 選擇器，引用要對其進行屬性修改的目標元素。如果您使用絕對選擇器，則可以使用萬用字元 (``) 來指定根元素，例如 `//plugins`。如果選擇器無法解析為指定文件的子元素，該工具將停止並還原安裝過程、發出警告，並以非零代碼退出。
mode 字串	決定要進行哪種類型的屬性修改的模式。 `merge` - 將指定的屬性新增至目標元素。如果指定的屬性已存在於目標元素中，則會取代屬性值。 `overwrite` - 將目標元素中的所有屬性取代為指定的屬性。

範例

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

新增外掛程式 1 前的 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|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>

新增外掛程式 1 後的 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="16" android:targetSdkVersion="23" />
</manifest>

管理 edit-config 衝突

多個外掛程式無法修改相同的屬性，因為這可能會導致應用程式出現問題。將會擲回錯誤，且外掛程式安裝會失敗。在新增外掛程式之前，必須先解決衝突的 edit-config 標籤。修改衝突的標籤以解決衝突，然後移除並重新新增更新的外掛程式。

對於確定應該安裝外掛程式而忽略衝突的使用者，有一個選項可以使用。--force 旗標可以用於 cordova plugin add。強制新增外掛程式將會還原其他外掛程式的衝突變更，使其可以順利新增。應謹慎使用 --force，因為還原其他外掛程式的變更可能會導致應用程式無法如預期般運作。

如果外掛程式的狀態異常，請移除所有外掛程式並重新新增。

範例

假設上述的外掛程式 1 已安裝。嘗試安裝下列的外掛程式 2 將會導致錯誤，因為外掛程式 1 已修改 AndroidManifest.xml 中的 uses-sdk 元素。

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

有幾種方式可以新增外掛程式 2

解決衝突的一種可能方式是從外掛程式 2 中移除 edit-config 標籤，並將其合併到外掛程式 1 的 edit-config 標籤中 (假設外掛程式 1 對此變更沒有問題)。移除這兩個外掛程式並重新新增，並進行這些變更。這次應該可以順利新增外掛程式 2。

從外掛程式 2 中移除 edit-config 並將其合併到外掛程式 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 新增外掛程式。外掛程式 1 的衝突 edit-config 變更將會還原，且外掛程式 2 的變更將會套用。產生的 AndroidManifest.xml 將包含外掛程式 2 的 uses-sdk 變更以及外掛程式 1 的 activity 變更。請注意，只有外掛程式 1 的 uses-sdk 變更已消失，因為這是唯一的衝突變更。

強制新增外掛程式 2 後產生的 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:minSdkVersion="15" android:targetSdkVersion="23" />
</manifest>

注意：--force 還原的變更將永遠消失。移除強制新增的外掛程式後，這些變更將不會再次出現。如果需要還原的變更，則應移除所有相關的外掛程式並重新新增。

plugins-plist

指定要附加到 iOS Cordova 專案中正確的 AppInfo.plist 檔案的索引鍵和值。這是過時的，因為它僅適用於 cordova-ios 2.2.0 及更低版本。針對更新版本的 Cordova，請使用 <config-file> 標籤。

範例

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

lib-file

<lib-file> 元素可用於在專案的 libs 目錄中安裝 .jar 檔案。

屬性	描述
src 字串	必要 `.jar` 檔案相對於 `plugin.xml` 的位置。如果找不到 `src` 檔案，CLI 會停止並還原安裝、發出關於問題的警告，並以非零代碼退出。

範例

<lib-file src="src/android/libs/foobar.jar"/>

framework

識別外掛程式所依賴的框架 (通常是作業系統/平台的一部分)。

屬性	描述
src 字串	必要系統框架的名稱，或是包含在您的外掛程式檔案中的框架的相對路徑。
custom 布林值	指出框架是否包含在您的外掛程式檔案中。
weak 布林值	預設值：false 指出是否應弱式連結框架。
type 字串	指出要新增的框架類型。
parent 字串	預設值：. 設定包含子專案的目錄的相對路徑，以將參考新增至該子專案。預設值 `.` 表示應用程式專案。
spec 字串	與 `type="podspec"` 配對使用，這是您要安裝的 CocoaPod 的規格字串 (僅限靜態程式庫)。CocoaPod 支援僅存在於 `cordova-ios 4.3.0` 和 `cordova-cli 6.4.0` 中。對於您的外掛程式，請務必新增適當的 `<engine>` 標籤和 `package.json` 相依性，以確保向後相容的支援。
embed 布林值	預設值：false 與 `custom="true"` 配對使用，如果您想要將自訂框架嵌入應用程式套件中，以便在執行階段動態載入 (動態框架)，則將此設定為 true。這會將您的自訂框架放置在 Xcode 專案設定的「內嵌二進位檔」區段中。僅在 `cordova-ios@4.4.0` 和 `cordova-cli@7.0.0` 組合的情況下支援。
link 布林值	預設值：!embed 如果您想要連結框架，則將此設定為 true。這會將框架放置在 Xcode 專案設定的「連結二進位檔與程式庫」區段中。

範例

適用於 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 開始)，框架標籤用於包含 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" />

框架也可以用於將自訂的 .gradle 檔案子包含到主要專案的 build.gradle 檔案中

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

podspec

識別提供外掛程式所依賴之相依性的 CocoaPods Podfile。

此元素包含一個 <config> 和一個 <pods> 標籤。

config

<config> 元素識別擷取 CocoaPods 規格的來源 URL。

此元素包含一個或多個 <source> 標籤。

source

屬性	描述
url 字串	必要 pod 規格的來源 URL。

pods

<pods> 元素識別 CocoaPods 程式庫。

此元素包含每個 CocoaPods 程式庫的 <pod> 標籤。

屬性	描述
use-frameworks 布林值	預設值：false 如果為 `true`，則會在 Podfile 中宣告 `use_frameworks!` 屬性。
inhibit-all-warnings 布林值	預設值：false 如果為 `true`，則會在 Podfile 中宣告 `inhibit_all_warnings!` 屬性。

pod

屬性 (類型)	描述
name 字串	必要 Pod 名稱
spec 字串	Pod 規格
swift-version 字串	指定 CocoaPods 程式庫的 Swift 版本
git 字串	Pod 的 `git` 選項。
branch 字串	Pod 的 `branch` 選項。
tag 字串	Pod 的 `tag` 選項。
commit 字串	Pod 的 `commit` 選項。
configurations 字串	Pod 的 `configurations` 選項。對於多個值，請使用逗號分隔。
http 字串	Pod 的 `http` 選項。
path 字串	Pod 的 `path` 選項。Pod 位於本機檔案系統上。
options 字串	以原始格式宣告的 Pod 選項。如果已宣告，則會覆寫其他 Pod 選項。範例：`options=":git => 'https://github.com/Alamofire/Alamofire.git', :tag => '3.1.1'"`

範例

    <podspec>
      <config>
        <source url="https://github.com/brightcove/BrightcoveSpecs.git" />
        <source url="https://github.com/CocoaPods/Specs.git"/>
      </config>
      <pods use-frameworks="true">
        <pod name="AFNetworking" spec="~> 3.2" />
        <pod name="SDWebImage" spec="~> 4.0" />
        <pod name="Eureka" swift-version="3.3" />
        <pod name="AcknowList" />
        <pod name="Brightcove-Player-Core" spec="~> 6.3.4" />
        <pod name="Foobar1" git="git@github.com:hoge/foobar1.git" configurations="Debug"/>
        <pod name="Foobar2" git="git@github.com:hoge/foobar2.git" branch="next" configurations="Debug,Release"/>
        <pod name="FoobarSwift" swift-version="4.1" />
      </pods>
    </podspec>

此範例導致 Podfile

# DO NOT MODIFY -- auto-generated by Apache Cordova
source 'https://github.com/brightcove/BrightcoveSpecs.git'
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '9.0'
use_frameworks!
target 'HelloCordova' do
	project 'HelloCordova.xcodeproj'
	pod 'AFNetworking', '~> 3.2'
	pod 'SDWebImage', '~> 4.0'
	pod 'Eureka'
	pod 'AcknowList'
	pod 'Brightcove-Player-Core', '~> 6.3.4'
	pod 'Foobar1', :git => 'git@github.com:hoge/foobar1.git', :configurations => ['Debug']
	pod 'Foobar2', :branch => 'next', :git => 'git@github.com:hoge/foobar2.git', :configurations => ['Debug','Release']
	pod 'FoobarSwift'
end

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 指南。

範例

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

uses-permission

在某些情況下，外掛程式可能需要根據目標應用程式進行設定變更。例如，若要在 Android 上註冊 C2DM，封裝 ID 為 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 可以要求使用者指定外掛程式所需的變數。例如，C2M 和 Google Maps 的 API 金鑰可以作為命令列引數指定。

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

某些變數名稱應該保留，例如 $PACKAGE_NAME。這是套件的反向網域樣式唯一識別碼，對應於 iOS 上的 CFBundleIdentifier 或 AndroidManifest.xml 檔案中頂層 manifest 元素的 package 屬性。

偏好設定

如前一節所述，有時外掛程式可能需要使用者為其變數指定值。為了使這些變數成為強制性的，<platform> 標籤需要包含 <preference> 標籤。CLI 會檢查是否傳入了這些必需的偏好設定。如果沒有，它應該警告使用者如何傳入變數，並以非零代碼退出。偏好設定可以使用語法 $PREFERENCE_NAME 在 plugin.xml 中的其他地方被引用。

屬性	描述
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>