[cordova] 使用 Vue 與 Cordova 產生 iOS 應用程式

2021-02-05

4321
0
Cordova

使用 Vue 與 Cordova 進行 app 開發，並且部署到虛擬器及實體手機進行測試。

前言

筆者先前有協助團隊使用 Vue 及 Cordova 完成一個 web 大小網銀及 ios / android app 的經驗，當時筆者手持 iPhone 但用著 windows 的筆電，實在尷尬地不知道該從哪個 platform 著手原生功能的開發測試，所以 app 原生功能開發是交給強者同事處理；而最近年末剛好有些時間，筆者開始嘗試著將家中 MacBook 娛樂機轉為工作機，畢竟 ASP.NET Core 發展已經相當成熟，可以不必再被微軟相關的開發所綁住，另一方面也想補足先前專案上遺落的缺憾，所以就當個初心者好好學習 Cordova 吧！

小小目標

筆者對於 app 開發經驗可說是趨近於零啊！好在公司遍佈原生 ios 及 android 開發工程師高手，所以若是真的擋不住時可以尋找救援，但筆者預期是在開發 Cordova Plugin 時可以討教討教，如果一開始 Hello World 就掛掉那還真的是信心受挫啊！本次目標就放在建立專案及順利將 app 放到筆者實體 iPhone 手機上測試，我想這樣應該可以稍稍提升 app 開發的信心指數吧！接著就開始囉～

開始之前請記得先把 Xcode 裝好裝滿喔！

建立 cordova 專案

由於筆者近期都使用 react.js 進行開發，所以剛好藉這個機會複習 vue.js 語法，因此本系列文(~~如果有的話~~)會以 vue.js 作為 app 畫面的本體，搭配 Cordova 將一個 SPA 網頁應用程式包裝成 app 在手持式裝置上使用。

首先安裝 vue-cli 及 cordova 全域套件。

npm install -g cordova
npm install -g @vue/cli

目前各套件版本如下

接著建立一個 app 名字叫 toolset 的 Cordova 專案，資料會建立於在當前目錄下的 toolset-app 資料夾中，並且給予此 app 獨一無二的 com.wasichris.toolset 識別 ID。

$ cordova create toolset-app com.wasichris.toolset toolset

專案預設自帶 www 資料夾下的範例網頁，也就是 app 內容主體，後續只要把 vue 開發的網頁放入即可。

接著透過 platform add 指令於 Cordova 專案中加入指定平台，多數都是針對 ios 及 android 兩大平台，而本範例僅先針對 ios 開發。如果需要移除特定平台，可以使用 platform rm 指令執行；另外如果想要看看目前已經安裝的平台清單，可以使用 platform ls 指令執行。

$ cordova platform add ios

資料夾中看到已經產生 ios 平台的相關檔案了。

先不做任何更動，直接透過 build 指令進行建置；當不指定替定平台時，就會把所有已加入平台全部建置。

$ cordova build ios

如果在建置時發生 ‘xcodebuild’ requires Xcode 錯誤訊息，可參考此文章執行以下指令進行排除。

$ sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

建置成功後會在 ios 資料夾下會產生 build 相關檔案。

最後就可以透過以下指令輸出 app 到模擬器；如下圖順利地顯示出 Cordova 專案下 www 網頁內容。

$ cordova emulate ios

建立 vue 專案

先前步驟已經初步將 Cordova 專案建立完成，接著就是要來產生 app 內容主體 vue 專案。先切換至 Cordova 專案目錄下，透過以下指令建立一個名為 toolset 的 vue SPA 專案。

vue create toolset

直接選擇 Vue 3 後就會開始建立專案。

完成後的資料夾結構如下，最外層就是稍早建立名為 toolset-app 資料夾的 Cordova 專案，然後剛剛建立的 toolset vue 專案就位於 Cordova 專案中的 toolset 資料夾內，而 vue 專案開發完畢後會將 js, css, html, img 等資料打包放置在 www 資料夾中，最後在 Cordova 專案中建置 ios app 時就會從 www 中取用到最新的內容了。

若是單純要開發 app 內容且不牽涉到 app 原生功能時，最好以 toolset 資料夾作為根目錄於 vs code 開啟專案，因為有些插件會去辨識根目錄的 package.json 來釐清 vue 版本，提供不同版本程式碼檢核的差異化 (例如在 vue v3 開始 template 中的第一層允許多個 elements 存在，此時若以 toolset-app 為根目錄開啟後，插件 vetur 會無法分辨版本而顯示錯誤提示，這點需要注意一下)。

來瞧瞧預設網站長怎樣，先切換至 vue 專案路徑並且啟動服務。

cd toolset
npm run serve

我們的 vue SPA 順利運作，後續跟原生裝置無關的部分(頁面互動及資料收發)將會如同開發一般網站般地進行。

這個 vue SPA 最終要透過 Cordova 擺到 app 中運行，所以一定要載入 cordova.js 才行，因此我們可以模仿 Cordova 預設提供在 www 資料夾中的網頁設置來設定我們的 index.html 內容。

調整後的 toolset-app\toolset\public\index.html 如下。

<!doctype html>
<html lang="en">

<head>
  <meta charset="utf-8">

  <meta name="format-detection" content="telephone=no">
  <meta name="msapplication-tap-highlight" content="no">
  <meta name="viewport" content="initial-scale=1, width=device-width, viewport-fit=cover">

  <!-- 設定條件將 cordova 相關的代碼只在正式建置時候才使用，避免影響網頁的開發 -->
  <% if (process.env.NODE_ENV==='production' ) { %>
    <!--
     Customize this policy to fit your own app's needs. For more guidance, see:
         https://github.com/apache/cordova-plugin-whitelist/blob/master/README.md#content-security-policy
     Some notes:
         * gap: is required only on iOS (when using UIWebView) and is needed for JS->native communication
         * https://ssl.gstatic.com is required only on Android and is needed for TalkBack to function properly
         * Disables use of inline scripts in order to mitigate risk of XSS vulnerabilities. To change this:
         * Enable inline JS: add 'unsafe-inline' to default-src
    -->
    <meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *; img-src 'self' data: content:;">
    <script src="cordova.js"></script>
  <% } %>

  <link rel="icon" href="<%= BASE_URL %>favicon.ico">
  <title>
    <%= htmlWebpackPlugin.options.title %>
  </title>

</head>

<body>
  <noscript>
    <strong>We're sorry but <%= htmlWebpackPlugin.options.title %> doesn't work properly without JavaScript enabled.
        Please enable it to continue.</strong>
  </noscript>

  <div id="app"></div>
  <!-- built files will be auto injected -->
</body>

</html>

剛有提到要將 vue 專案打包的檔案放到 www 資料夾中，因此需要在 toolset 資料夾中加入 vue.config.js 檔案來設定 outputDir 路徑；另外由於這個 vue SPA 是運作在手機中，所以相關載入的資源檔路徑都要以相對路徑來獲得，因此在此一併設定 pubicPath 路徑。

// vue.config.js 是一個可選的配置文件，如果項目的 (和 package.json 同級的) 根目錄中存在這個文件，
// 那麼它會被 @vue/cli-service 自動加載。你也可以使用 package.json 中的 vue 字段，
// 但是注意這種寫法需要你嚴格遵照 JSON 的格式來寫。

module.exports = {
    publicPath: './',
    outputDir: '../www'
}

萬事俱備就直接執行建置，而打包後的檔案會被輸出到 Cordova 需要的 www 資料夾中。

npm run build

接著將當前目錄切換至 toolset-app 這個 Cordova 專案下，建置 ios 平台來將 www 資料夾中的新內容部署到 app 上，然後在模擬器中驗證一下。

cordova build ios
cordova emulate ios

成功將 vue SPA 放入 app 囉！

將 app 部署到手機

怎麼模擬還是不如在手機上呈現的爽度高，因此最後一步就是要將 app 部署到手機上，先拿條線把手機跟電腦連起來吧！透過以下指令把部署套件安裝起來。

npm install -g ios-deploy

執行以下指令將 app 部署到手機

cordova run ios --device

登登... 挑戰失敗，收到以下錯誤訊息，內容提示我們必須選擇一個 development team 才能簽署 toolset 這個 app 的憑證，因為要部署到實體機器上一定要有憑證，這樣才會知道這個 app 是誰開發的。

error: Signing for "toolset" requires a development team. Select a development team in the Signing & Capabilities editor. (in target 'toolset' from project 'toolset')

點 toolset.xcodeproj 兩下透過 Xcode 開啟這個專案。