ApplicationUpdaterUI  - AS3

設定 delay 和 updateURL 屬性值的組態設定檔所在位置。該檔案中的設定也將決定應用程式是否在更新程序期間顯示各種確認對話方塊。如果這個屬性指向不存在的檔案，呼叫 initialize() 方法將導致擲出錯誤。

以下是組態設定檔的樣本：

 <?xml version="1.0" encoding="utf-8"?> 
         <configuration xmlns="http://ns.adobe.com/air/framework/update/configuration/1.0" >
           <url>app:/server/update.xml</url>
           <delay>1</delay>
           <defaultUI>
              <dialog name="checkForUpdate" visible="true" />
               <dialog name="downloadUpdate" visible="false" />
               <dialog name="downloadProgress" visible="true" />
               <dialog name="installUpdate" visible="true" />    
           </defaultUI>
        </configuration>

除了載入組態設定檔，您也可以使用 ActionScript 程式碼，設定 ApplicationUpdaterUI 物件的下列屬性：delay、isCheckForUpdateVisible、isDownloadProgressVisible、isDownloadUpdateVisible、isFileUpdateVisible、isInstallUpdateVisible 和 updateURL 屬性。

相關 API 元素

應用程式的目前版本。這個屬性是在 initialize() 方法呼叫期間所設定。其值設定為應用程式描述器檔案提供的版本。

定期檢查新的更新之天數間隔。

值為 0 (預設值) 代表計時器非作用中，因而不會執行定期檢查。您可以透過這個屬性或是組態設定檔來設定延遲值。如果同時透過這兩種方式設定其值，將使用以此屬性設定的值。

預設值為 0。

相關 API 元素

啟用「檢查更新」、「沒有更新」和「更新錯誤」對話方塊的可見性。如果設定為 true，更新程式便會在更新程序期間顯示這些對話方塊。您也可以透過更新組態設定檔設定此值。由這個屬性所設定的值會覆寫更新組態設定檔中的設定。

啟用「下載更新」對話方塊的可見性。如果設定為 true，更新程式便會在更新程序期間顯示該對話方塊。您也可以透過更新組態設定檔設定此值。由這個屬性所設定的值會覆寫更新組態設定檔中的設定。

啟用「下載更新」對話方塊的可見性。如果設定為 true，更新程式便會在更新程序期間顯示這些對話方塊。您也可以透過更新組態設定檔設定此值。由這個屬性所設定的值會覆寫更新組態設定檔中的設定。

啟用「檔案更新」、「檔案沒有更新」和「檔案錯誤」對話方塊的可見性。如果設定為 true，更新程式便會在更新程序期間顯示這些對話方塊。您也可以透過更新組態設定檔設定此值。由這個屬性所設定的值會覆寫更新組態設定檔中的設定。

是否為成功更新後第一次執行 (true = 是，false = 否)。更新程式會在 initialize() 方法呼叫期間設定此值。若因版本變更而需要移轉資料，開發人員即應檢查 isFirstRun 是否已設定為 true。

相關 API 元素

啟用「安裝更新」對話方塊的可見性。如果設定為 true，更新程式便會在更新程序期間顯示該對話方塊。您也可以透過更新組態設定檔設定此值。由這個屬性所設定的值會覆寫更新組態設定檔中的設定。

更新程式用來執行版本比較的函數。根據預設，更新架構會進行版本比較，以偵測來自遠端網站的版本是否比已安裝應用程式的版本新。但是，預設的比較方式有時並不符合開發人員的版本設定配置。設定這個屬性可提供另一函數以進行比較。

預設的比較函數接受 x.y.z 之類的版本，其中 x、y 和 z 可包含字母及數字。預設的比較函數也能辨識某些特殊狀況。如果測試函數在版本字串中發現 "alpha"、"beta" 或 "rc"，其順序即為 alpha < beta < rc。

appUpdate.isNewerVersionFunction = customFn; 

function customFn (currentVersion:String, updateVersion:String):Boolean 
{
    return updateVersion > currentVersion;
}

啟用「未預期的錯誤」對話方塊的可見性。如果設定為 true，應用程式更新程式便會在更新程序期間顯示該對話方塊。您也可以透過更新組態設定檔設定此值。由這個屬性所設定的值會覆寫更新組態設定檔中的設定。

Boolean 屬性，如果更新正在執行即為 true，否則為 false。

定義使用者介面所使用之地區鏈結的陣列。通常，只有 JavaScript (HTML) 開發人員會用到這個屬性。

Flex 開發人員可以使用 ResourceManager 處理地區鏈結。

預設情況下，HTML 類型應用程式會將其語言排序為介於 Capabilities.languages 陣列內的語言以及使用者介面支援的 10 種語言之間。如果找不到相符的語言，使用者介面就會使用英文。

下列 JavaScript 範例使用了 AIR SDK 所提供的 AIR HTML 當地語系化架構。此範例先依據語言清單將語言排序，再將英文設定為預設的後援語言：

 appUpdater.addResources("ro_RO", {titleCheck: "Titlu", msgCheck: "Mesaj", btnCheck: "Buton"});
        appUpdater.addResources("hu", {titleCheck: "Cím", msgCheck: "Üzenet"}); 
        var languages = ["ro", "hu"];
        languages = languages.concat(air.Capabilities.languages);
        var sortedLanguages = air.Localizer.sortLanguagesByPreference(languages, air.Capabilities.language, "en-US");  
        sortedLanguages.push("en-US");
        appUpdater.localeChain = sortedLanguages;

相關 API 元素

應用程式儲存目錄先前的位置 (若該位置於更新後有所變更)。經由憑證移轉方式進行升級後，應用程式儲存目錄的位置就會變更。如果未經憑證移轉，使用者更新應用程式將不會造成應用程式儲存目錄變更，此時這個屬性即設定為 null。這個屬性是在 initialize() 方法呼叫期間所設定。

如果開發人員使用 ADT 搭配 -migrate 選項封裝 AIR 檔，即可使用新的憑證來簽署新版本的 AIR 應用程式。新版本的 AIR 應用程式若是使用新的簽署憑證，應用程式的本機儲存目錄將隨著使用者安裝新版本而變更。利用這個屬性可將舊的應用程式儲存目錄中的資料傳輸到新的應用程式儲存目錄 (File.applicationStorageDirectory)。如需詳細資訊，請參閱「Adobe AIR 開發人員指南」中，「使用命令列工具建立 AIR 應用程式」一章的「簽署 AIR 檔以變更應用程式憑證」。

應用程式的上一個版本。這個屬性是在 initialize() 方法呼叫期間所設定。傳回應用程式升級前的「上一個版本」(只有在 isfirstRun 為 true 時才會設定)；否則將設定為 null。

從更新 URL 下載之更新描述器檔案的內容。當更新程式物件傳送 updateStatus 事件後，這個屬性才為非 null。

更新描述器檔案的位置。接受任何有效的 URLRequest 路徑位置。更新程式必要的強制性設定惟獨此項。您可以透過這個屬性或是組態設定檔來設定更新 URL。如果同時透過這兩種方式設定其值，更新程式會使用以此屬性設定的值。

相關 API 元素

是否有延緩 (包括安裝失敗) 的更新 (true = 是，false = 否)。更新程式會在 initialize() 方法呼叫期間設定這個屬性。使用 wasPendingUpdate 和 isFirstRun 屬性可檢查是否有任何更新安裝失敗 (若 wasPendingUpdate 設定為 true 且 isFirstRun 設定為 false 即表示有此情況)。

相關 API 元素

建構函數。

動態地新增指定語言的新資源組合包。此方法讓 JavaScript 開發人員能為應用程式更新程式使用者介面的對話方塊動態地新增顯示語言 (Flex 開發人員則可直接將新的語言加入 "ApplicationUpdaterDialogs" 資源組合包)。

參數

相關 API 元素

取消更新程序。呼叫此方法將會取消任何等候中的下載、刪除任何下載不完全的檔案，並重新啟動定期檢查計時器。

只要更新程式不是處於 "uninitialized" 或 "initializing" 狀態，隨時皆可取消更新程序。若為 "uninitialized" 或 "initializing" 狀態，呼叫後不會執行任何動作。

啟動更新程序。呼叫此方法並不會停止定期計時器，但此方法會偵測是否有更新程序正在執行，並將略過目前的程序循環。

此方法只會在目前狀態為 "Ready" 時執行。

此方法可能導致更新程式物件傳送下列事件：

初始化更新程式。呼叫此方法將會執行下列動作：

1. 初始化更新架構，以無訊息方式同步安裝任何擱置的更新。在應用程式啟動時即應呼叫此方法，因為這可能會重新啟動應用程式。

2. 檢查是否有延緩的更新並加以安裝。

3. 如果先前的更新曾發生錯誤，即清除儲存區內的更新檔案和版本資訊。

4. 如果定期計時器延遲已到期，即啟動更新程序；否則將啟動定期計時器。然而，若是使用 AIR Debug Launcher (ADL) 應用程式來測試應用程式，試圖更新應用程式就會產生 IllegalOperationError 例外。

使用本機 AIR 檔啟動更新程序。

若有更新程序正在執行 (處於 "Downloaded" 以外的狀態)，呼叫此方法將毫無作用。

這項功能對於已將應用程式描述器檔案中的 customUpdateUI 元素設定為 true 的應用程式來說很有用。

使用 AIR Debug Launcher (ADL) 應用程式測試應用程式時，呼叫此方法會產生 IllegalOperationError 例外。

參數

在呼叫 installUpdate() 方法後，將要安裝更新之前傳送。有時候，此時暫且不要安裝更新會比較妥當，因為執行階段若結束應用程式準備安裝更新，可能導致使用者遺失所有目前的工作成果。

呼叫此事件的 preventDefault() 方法便能延緩到下次重新啟動才安裝。如果您呼叫了 preventDefault() 方法，則此應用程式工作階段期間將無法再啟動其他更新程序 (藉由呼叫 installUpdate() 方法或因定期檢查而引發)。

這個事件具有下列屬性：

在更新程式嘗試下載更新描述器檔案 (更新程序將要開始) 之前傳送。直接呼叫 checkNow() 方法或定期檢查計時器已到期時，更新程式便會傳送此事件。

這個事件具有下列屬性：

當更新檔案下載完成時傳送。

這個事件具有下列屬性：

若在連線或下載更新檔案時發生錯誤，便會傳送。若為無效的 HTTP 狀態 (例如「404 - 找不到檔案」)，也將傳送此事件。

一旦傳送此事件，即自動重新啟動定期計時器 (如果延遲值大於 0)。

DownloadErrorEvent 物件的 errorID 屬性為整數，用以定義錯誤資訊 (請參閱下表)。另外可能還有 subErrorID 屬性包含了更多的錯誤資訊。

在呼叫 downloadUpdate() 方法及建立伺服器連線之後傳送。使用 ApplicationUpdater 元件庫時，您可以透過此事件的事件處理常式，顯示進度列向使用者報告下載進度。

這個事件具有下列屬性：

若在初始化或更新程序期間發生錯誤 (發生未預期的事件)，便會傳送。

這個事件具有下列屬性：

若在驗證 installFromAIRFile() 方法呼叫中的 airFile 參數所傳遞的檔案時發生錯誤，便會傳送。

在更新程式成功驗證 installFromAIRFile() 方法呼叫中的檔案之後傳送。

這個事件具有下列屬性：

在初始化完成後傳送。

此事件具有下列唯讀屬性：

• isFirstRun (Boolean)：指出是否為成功更新後第一次執行 (true = 是，false = 否)。

• previousVersion (String)：應用程式升級前的上一個版本 (只有在 isfirstRun 為 true 時才會設定)。

• currentVersion (String)：目前已安裝版本的應用程式描述器檔案所提供的版本。

這個事件具有下列屬性：

下載更新檔案時傳送。

這個事件具有下列屬性：

若在嘗試下載或剖析更新描述器檔案時發生錯誤，便會傳送。

更新程式一旦傳送此事件，即自動重新啟動定期計時器 (如果延遲設定大於 0)。應用程式最好在更新程式傳送新的 checkForUpdate 事件時，隱藏任何錯誤對話方塊。

在更新程式成功下載並解譯更新描述器檔案之後傳送。

這個事件具有下列屬性：