升級 Android

本指南說明如何修改 Android 專案，以從舊版 Cordova 升級。大多數這些指示適用於使用早於 cordova CLI 工具的一組舊命令行工具建立的專案。請參閱命令行介面以瞭解如何更新 CLI 版本。

升級至 10.x.x

升級至 10.X.X 的最佳方式是直接從您的專案中移除 Android 平台，並使用新版本重新新增它。例如，

cordova platform remove android
cordova platform add android@10.X.X

如果您使用上述方法，請注意，您對 android 平台資料夾所做的任何變更都將遺失（不建議編輯此資料夾的內容）。

重大變更

10.0.0 版引入了應用程式內 URL 的載入方式的重大變更。先前的版本透過檔案協定載入應用程式的 Web 檔案，例如 index.html。這表示應用程式從 URL file:///android_asset/www/index.html 開始。載入 file:/// URL 被認為是不安全的，並且 Android 已棄用支援。Cordova Android 10.0.0 現在使用一個名為 WebViewAssetLoader 的 Android API，預設透過 HTTP(S) 方案（https://127.0.0.1）載入 Web 內容。因此，應用程式現在從 URL https://127.0.0.1/ 而不是 file:///android_asset/www/index.html 開始。由於這是一個新的來源，您可能會遇到資料遺失，並且需要遷移您的 Web 資料（本地儲存、IndexedDB 等）。

您可以使用 config.xml 偏好設定 <preference name="AndroidInsecureFileModeEnabled" value="true" /> 來選擇退出新的 WebViewAssetLoader 並切換回檔案 URL。

升級至 7.X.X

升級至 7.X.X 的最佳方式是直接從您的專案中移除 Android 平台，並使用新版本重新新增它。例如，

cordova platform remove android
cordova platform add android@7.X.X

如果您使用上述方法，請注意，您對 android 平台資料夾所做的任何變更都將遺失（不建議編輯此資料夾的內容）。

遺憾的是，由於檔案結構的更新，非 CLI 專案必須手動更新，或者必須建立新的 Cordova 專案，並將檔案傳輸到新專案。這是因為遷移到 Android Studio。

升級至 6.X.X

升級至 6.X.X 的最佳方式是直接從您的專案中移除 Android 平台，並使用新版本重新新增它。例如，

cordova platform remove android
cordova platform add android@6.X.X

如果您使用上述方法，請注意，您對 android 平台資料夾所做的任何變更都將遺失（不建議編輯此資料夾的內容）。

或者，您可以嘗試使用平台更新腳本。對於非 CLI 專案，請執行

bin/update path/to/project

升級至 5.X.X

升級至 5.X.X 的最佳方式是直接從您的專案中移除 Android 平台，並使用新版本重新新增它。例如，

cordova platform remove android
cordova platform add android@5.X.X

如果您使用上述方法，請注意，您對 android 平台資料夾所做的任何變更都將遺失（不建議編輯此資料夾的內容）。

或者，您可以嘗試使用平台更新腳本。對於非 CLI 專案，請執行

bin/update path/to/project

對於 CLI 專案

  1. 更新 cordova CLI 版本。請參閱命令行介面。

  2. 在您現有的專案中執行 cordova platform update android@5.0.0。

升級 Android Marshmallow 的外掛

5.0.0 版新增了對 Android API 第 23 級 (Marshmallow) 的支援。Android Marshmallow 引入了一個新的權限模型，可能需要您更新一些已安裝的外掛，以確保它們與較新的手機相容。不正確處理權限的舊版外掛可能會導致您的應用程式意外崩潰。請注意，這並非影響每個外掛，而僅影響那些存取被視為危險的 Android 權限的外掛（請參閱危險權限的表格）。

下列核心外掛會受到此變更的影響，且必須升級才能與 cordova-android 5.0.0+ 一起使用

外掛 最低相容版本
cordova-plugin-camera 2.0.0
cordova-plugin-contacts 2.0.0
cordova-plugin-file 4.0.0
cordova-plugin-geolocation 2.0.0
cordova-plugin-media 2.0.0

對於非核心外掛，您可以透過檢查外掛的 plugin.xml 檔案來驗證外掛是否請求危險權限。如果外掛使用 Android 權限，您將在 plugin.xml 中看到宣告它們的項目。例如

<uses-permission android:name="android.permission.PERMISSION_NAME" />

其中 PERMISSION_NAME 會被 Android 權限的名稱取代。plugin.xml 檔案可以在您 Cordova 專案中的外掛資料夾中找到（例如 plugins/example-plugin/plugin.xml）。請參閱使用危險權限的任何外掛的文件，以判斷需要採取哪些步驟來確保 cordova-android 5.0.0+ 的相容性。

升級至 4.0.0

需要特定的升級步驟才能利用 4.0.0 中的重大變更。首先，需要以下常見的升級步驟。

對於非 CLI 專案，請執行

bin/update path/to/project

對於 CLI 專案

  1. 更新 cordova CLI 版本。請參閱命令行介面。

  2. 在您現有的專案中執行 cordova platform update android@4.0.0。

升級允許清單

所有允許清單功能現在都透過外掛實作。如果沒有外掛，您的應用程式在升級至 4.0.0 後將不再受允許清單保護。Cordova 有兩個允許清單外掛，它們提供不同層級的保護。

  1. cordova-plugin-whitelist 外掛（建議）
    • 強烈建議使用此外掛，因為它比先前版本的允許清單更安全且更可設定
    • 請參閱cordova-plugin-whitelist 以瞭解所需的設定變更詳細資訊
    • 執行：cordova plugin add cordova-plugin-crosswalk-webview
  2. cordova-plugin-legacy-whitelist 外掛
    • 此外掛提供的允許清單行為與先前版本相同。請參閱cordova-plugin-legacy-whitelist
    • 不需要進行設定變更，但它提供的保護比建議的外掛少
    • 執行：cordova plugin add cordova-plugin-legacy-whitelist

使用 Crosswalk WebView

依預設，您的應用程式將繼續使用裝置提供的系統 WebView。如果您希望改用 Crosswalk WebView，只需新增 Crosswalk 外掛

cordova plugin add cordova-plugin-crosswalk-webview

新增外掛後，您的應用程式將正確安裝和設定 Crosswalk WebView。

升級至啟動畫面外掛

如果您的應用程式使用啟動畫面，該功能已移至外掛。啟動畫面的設定選項不變。唯一需要的升級步驟是新增外掛

cordova plugin add cordova-plugin-splashscreen

從 3.6.0 升級至 3.7.1

對於非 CLI 專案，請執行

bin/update path/to/project

對於 CLI 專案

  1. 更新 cordova CLI 版本。請參閱命令行介面。

  2. 在您現有的專案中執行 cordova platform update android。

從 3.2.0 升級至 3.3.0

請遵循與 3.2.0 相同的指示。

從 3.3.0 開始，Cordova 執行階段現在編譯為 Android 程式庫而不是 Jar。這對於命令行用法應該沒有影響，但是 IDE 使用者將需要將新新增的 MyProject-CordovaLib 專案匯入其工作區。

從 3.1.0 升級至 3.2.0

對於使用 cordova CLI 建立的專案

  1. 更新 cordova CLI 版本。請參閱命令行介面。

  2. 執行 cordova platform update android

對於未使用 cordova CLI 建立的專案，請執行

    bin/update <project_path>

警告：在 Android 4.4 - Android 4.4.3 上，建立具有 type="file" 的檔案輸入元素不會開啟檔案選擇器對話方塊。這是 Android 上 Chromium 的一個退步，並且可以在 Android 上的獨立 Chrome 瀏覽器中重現該問題（請參閱 https://code.google.com/p/android/issues/detail?id=62220）建議的因應措施是針對 Android 4.4 使用 FileTransfer 和 File 外掛。您可以從 input type="file" 監聽 onClick 事件，然後彈出檔案選擇器 UI。為了將表單資料與上傳連結在一起，您可以使用 JavaScript 將表單值附加到 FileTransfer 建立的多部分 POST 請求。

從 3.0.0 升級至 3.1.0

對於使用 cordova CLI 建立的專案

  1. 更新 cordova CLI 版本。請參閱命令行介面。

  2. 執行 cordova platform update android

對於未使用 cordova CLI 建立的專案，請執行

    bin/update <project_path>

從 2.9.0 升級至 CLI (3.0.0)

  1. 使用 cordova CLI 建立新的 Apache Cordova 3.0.0 專案，如命令行介面中所述。

  2. 將您的平台新增至 cordova 專案，例如：cordova platform add android。

  3. 將您專案 www 目錄的內容複製到您剛建立的 cordova 專案根目錄下的 www 目錄。

  4. 將任何原生資產從您的舊專案複製到 platforms/android 下的適當目錄：此目錄是您的原生 cordova-android 專案所在的位置。

  5. 使用 cordova CLI 工具安裝您需要的任何外掛。請注意，CLI 將所有核心 API 作為外掛處理，因此可能需要新增它們。只有 3.0.0 外掛與 CLI 相容。

從 2.9.0 升級至 3.0.0

  1. 建立新的 Apache Cordova Android 專案。

  2. 將 www 目錄的內容複製到新專案。

  3. 將任何原生 Android 資產從 res 目錄複製到新專案。

  4. 將您從 src 子目錄安裝的任何外掛複製到新專案。

  5. 請務必將您舊的 config.xml 檔案中任何已棄用的 <plugin> 參考更新為新的 <feature> 規格。

  6. 將 org.apache.cordova.api 套件的任何參考更新為 org.apache.cordova。

    注意：所有核心 API 都已移除，並且必須安裝為外掛。請參閱使用 Plugman 管理外掛指南以瞭解詳細資訊。

從 2.8.0 升級至 2.9.0

  1. 執行 bin/update <project_path>。

從 2.7.0 升級至 2.8.0

  1. 從專案的 libs 目錄中移除 cordova-2.7.0.jar。

  2. 將 cordova-2.8.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  1. 將新的 cordova.js 複製到您的專案。

  2. 更新您的 HTML 以使用新的 cordova.js 檔案。

  3. 複製 res/xml/config.xml 檔案以符合 framework/res/xml/config.xml。

  4. 更新 framework/res/xml/config.xml 以使其具有與之前類似的設定。

  5. 將檔案從 bin/templates/cordova 複製到專案的 cordova 目錄。

從 2.6.0 升級至 2.7.0

  1. 從專案的 libs 目錄中移除 cordova-2.6.0.jar。

  2. 將 cordova-2.7.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-2.7.0.js 複製到您的專案。

  5. 更新您的 HTML 以使用新的 cordova-2.7.0.js 檔案。

  6. 複製 res/xml/config.xml 以符合 framework/res/xml/config.xml。

  7. 更新 framework/res/xml/config.xml 以使其具有與之前類似的設定。

  8. 將檔案從 bin/templates/cordova 複製到專案的 cordova 目錄。

從 2.5.0 升級至 2.6.0

  1. 從專案的 libs 目錄中移除 cordova-2.5.0.jar。

  2. 將 cordova-2.6.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-2.6.0.js 複製到您的專案。

  5. 更新您的 HTML 以使用新的 cordova-2.6.0.js 檔案。

  6. 複製 res/xml/config.xml 以符合 framework/res/xml/config.xml。

  7. 更新 framework/res/xml/config.xml 以使其具有與之前類似的設定。

  8. 將檔案從 bin/templates/cordova 複製到專案的 cordova 目錄。

使用 Cordova 原始碼目錄中列出的專案路徑執行 bin/update <project>。

從 2.4.0 升級至 2.5.0

  1. 從專案的 libs 目錄中移除 cordova-2.4.0.jar。

  2. 將 cordova-2.5.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-2.5.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 cordova-2.5.0.js 檔案。

  6. 複製 res/xml/config.xml 以符合 framework/res/xml/config.xml。

  7. 更新 framework/res/xml/config.xml 以使其具有與之前類似的設定。

  8. 將檔案從 bin/templates/cordova 複製到專案的 cordova 目錄。

從 2.3.0 升級至 2.4.0

  1. 從專案的 libs 目錄中移除 cordova-2.3.0.jar。

  2. 將 cordova-2.4.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-2.4.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 cordova-2.4.0.js 檔案。

  6. 複製 res/xml/config.xml 以符合 framework/res/xml/config.xml。

  7. 將檔案從 bin/templates/cordova 複製到專案的 cordova 目錄。

從 2.2.0 升級至 2.3.0

  1. 從專案的 libs 目錄中移除 cordova-2.2.0.jar。

  2. 將 cordova-2.3.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-2.3.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 cordova-2.3.0.js 檔案。

  6. 複製 res/xml/config.xml 以符合 framework/res/xml/config.xml。

  7. 將檔案從 bin/templates/cordova 複製到專案的 cordova 目錄。

從 2.1.0 升級至 2.2.0

  1. 從專案的 libs 目錄中移除 cordova-2.1.0.jar。

  2. 將 cordova-2.2.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-2.2.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 cordova-2.2.0.js 檔案。

  6. 複製 res/xml/config.xml 以符合 framework/res/xml/config.xml。

  7. 將檔案從 bin/templates/cordova 複製到專案的 cordova 目錄。

從 2.0.0 升級至 2.1.0

  1. 從專案的 libs 目錄中移除 cordova-2.0.0.jar。

  2. 將 cordova-2.1.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-2.1.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 cordova-2.1.0.js 檔案。

  6. 複製 res/xml/config.xml 以符合 framework/res/xml/config.xml。

  7. 將檔案從 bin/templates/cordova 複製到專案的 cordova 目錄。

從 1.9.0 升級至 2.0.0

  1. 從專案的 libs 目錄中移除 cordova-1.9.0.jar。

  2. 將 cordova-2.0.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-2.0.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 cordova-2.0.0.js 檔案。

  6. 複製 res/xml/config.xml 以符合 framework/res/xml/config.xml。

在 2.0.0 版本中，config.xml 檔案合併並取代了 cordova.xml 和 plugins.xml。舊檔案已過時，雖然它們在 2.0.0 中仍然可以使用，但在未來的版本中將停止工作。

從 1.8.1 升級至 1.9.0

  1. 從專案的 libs 目錄中移除 cordova-1.8.0.jar。

  2. 將 cordova-1.9.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-1.9.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 cordova-1.9.0.js 檔案。

  6. 更新 res/xml/plugins.xml 以符合 framework/res/xml/plugins.xml。

由於在 1.9.0 版本中引入了 CordovaWebView，第三方外掛程式可能無法運作。這些外掛程式需要使用 getContext() 或 getActivity() 從 CordovaInterface 取得內容。如果您不是經驗豐富的 Android 開發人員，請聯繫外掛程式維護人員並將此任務新增至他們的錯誤追蹤器。

從 1.8.0 升級至 1.8.0

  1. 從專案的 libs 目錄中移除 cordova-1.8.0.jar。

  2. 將 cordova-1.8.1.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-1.8.1.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 cordova-1.8.1.js 檔案。

  6. 更新 res/xml/plugins.xml 以符合 framework/res/xml/plugins.xml。

從 1.7.0 升級至 1.8.0

  1. 從專案的 libs 目錄中移除 cordova-1.7.0.jar。

  2. 將 cordova-1.8.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-1.8.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 cordova-1.8.0.js 檔案。

  6. 更新 res/xml/plugins.xml 以符合 framework/res/xml/plugins.xml。

從 1.7.0 升級至 1.8.0

  1. 從專案的 libs 目錄中移除 cordova-1.7.0.jar。

  2. 將 cordova-1.8.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-1.8.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 cordova-1.8.0.js 檔案。

  6. 更新 res/xml/plugins.xml 以符合 framework/res/xml/plugins.xml。

從 1.6.1 升級至 1.7.0

  1. 從專案的 libs 目錄中移除 cordova-1.6.1.jar。

  2. 將 cordova-1.7.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-1.7.0.js 複製到您的專案中。

  5. 更新 res/xml/plugins.xml 以符合 framework/res/xml/plugins.xml。

從 1.6.0 升級至 1.6.1

  1. 從專案的 libs 目錄中移除 cordova-1.6.0.jar。

  2. 將 cordova-1.6.1.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-1.6.1.js 複製到您的專案中。

  5. 更新 res/xml/plugins.xml 以符合 framework/res/xml/plugins.xml。

從 1.5.0 升級至 1.6.0

  1. 從專案的 libs 目錄中移除 cordova-1.5.0.jar。

  2. 將 cordova-1.6.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-1.6.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 cordova-1.6.0.js 檔案。

  6. 更新 res/xml/plugins.xml 以符合 framework/res/xml/plugins.xml。

  7. 將 res/xml/phonegap.xml 替換為 res/xml/cordova.xml，以符合 framework/res/xml/cordova.xml。

從 1.4.0 升級至 1.5.0

  1. 從專案的 libs 目錄中移除 phonegap-1.4.0.jar。

  2. 將 cordova-1.5.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 cordova-1.5.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 cordova-1.5.0.js 檔案。

  6. 更新 res/xml/plugins.xml 以符合 framework/res/xml/plugins.xml。

  7. 將 res/xml/phonegap.xml 替換為 res/xml/cordova.xml，以符合 framework/res/xml/cordova.xml。

從 1.3.0 升級至 1.4.0

  1. 從專案的 libs 目錄中移除 phonegap-1.3.0.jar。

  2. 將 phonegap-1.4.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 phonegap-1.4.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 phonegap-1.4.0.js 檔案。

  6. 更新 res/xml/plugins.xml 以符合 framework/res/xml/plugins.xml。

  7. 更新 res/xml/phonegap.xml 以符合 framework/res/xml/phonegap.xml。

從 1.2.0 升級至 1.3.0

  1. 從專案的 libs 目錄中移除 phonegap-1.2.0.jar。

  2. 將 phonegap-1.3.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 phonegap-1.3.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 phonegap-1.2.0.js 檔案。

  6. 更新 res/xml/plugins.xml 以符合 framework/res/xml/plugins.xml。

  7. 更新 res/xml/phonegap.xml 以符合 framework/res/xml/phonegap.xml。

從 1.1.0 升級至 1.2.0

  1. 從專案的 libs 目錄中移除 phonegap-1.1.0.jar。

  2. 將 phonegap-1.2.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 phonegap-1.2.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 phonegap-1.2.0.js 檔案。

  6. 更新 res/xml/plugins.xml 以符合 framework/res/xml/plugins.xml。

  7. 更新 res/xml/phonegap.xml 以符合 framework/res/xml/phonegap.xml。

從 1.0.0 升級至 1.1.0

  1. 從專案的 libs 目錄中移除 phonegap-1.0.0.jar。

  2. 將 phonegap-1.1.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 phonegap-1.1.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 phonegap-1.1.0.js 檔案。

  6. 更新 res/xml/plugins.xml 以符合 framework/res/xml/plugins.xml。

從 0.9.6 升級至 1.0.0

  1. 從專案的 libs 目錄中移除 phonegap-0.9.6.jar。

  2. 將 phonegap-1.0.0.jar 新增至專案的 libs 目錄。

  3. 如果您使用 Eclipse，請重新整理您的 Eclipse 專案並執行清除。

  4. 將新的 phonegap-1.0.0.js 複製到您的專案中。

  5. 更新您的 HTML 以使用新的 phonegap-1.0.0.js 檔案。

  6. 新增 res/xml/plugins.xml 以符合 framework/res/xml/plugins.xml。