範例：CustomErrors 應用程式 --Flash CS3

CustomErrors 應用程式會示範在建立應用程式時，處理自訂錯誤的技巧。這些技巧包括：

若要取得此樣本的應用程式檔案，請參閱 www.adobe.com/go/learn_programmingAS3samples_flash_tw。您可以在 Samples/CustomError 檔案夾中找到 CustomErrors 應用程式檔案，它是由下列檔案組成：

檔案	說明
CustomErrors.mxml 或 CustomErrors.fla	Flash (FLA) 或 Flex (MXML) 中的主應用程式檔案。
com/example/programmingas3/errors/ApplicationError.as	類別，可做為 FatalError 和 WarningError 類別的基底錯誤類別。
com/example/programmingas3/errors/FatalError.as	類別，用來定義應用程式可能擲回的 FatalError 錯誤。此類別會擴充自訂的 ApplicationError 類別。
com/example/programmingas3/errors/Validator.as	類別，會定義用來驗證使用者所提供之employee XML 封包的單一方法。
com/example/programmingas3/errors/WarningError.as	類別，用來定義應用程式可能擲回的 WarningError 錯誤。此類別會擴充自訂的 ApplicationError 類別。

副主題

CustomErrors 應用程式概觀

CustomErrors.mxml 檔案包含自訂錯誤應用程式的使用者介面和部分邏輯。一旦傳送應用程式的 creationComplete 事件之後，就會叫用 initApp() 方法。此方法會定義 Validator 類別所要驗證的樣本 XML 封包。下列程式碼會顯示 initApp() 方法：

private function initApp():void
{
    employeeXML = 
        <employee id="12345">
            <firstName>John</firstName>
            <lastName>Doe</lastName>
            <costCenter>12345</costCenter>
            <costCenter>67890</costCenter>
        </employee>;
}

XML 封包稍後會顯示在「舞台」的 TextArea 組件實體上。這可以讓您在嘗試重新驗證 XML 封包前加以修改。

當使用者按下「驗證」按鈕時，就會呼叫 validateData() 方法。這個方法會使用 Validator 類別中的 validateEmployeeXML() 方法，驗證 employee XML 封包。下列程式碼會顯示 validateData() 方法：

public function validateData():void
{
    try
    {
        var tempXML:XML = XML(xmlText.text);
        Validator.validateEmployeeXML(tempXML);
        status.text = "The XML was successfully validated.";
    }
    catch (error:FatalError)
    {
        showFatalError(error);
    }
    catch (error:WarningError)
    {
        showWarningError(error);
    }
    catch (error:Error)
    {
        showGenericError(error);
    }
}

首先使用 TextArea 組件實體 xmlText 的內容，建立暫時性的 XML 物件。接著叫用自訂 Validator 類別 (com.example.programmingas3/errors/Validator.as) 中的 validateEmployeeXML() 方法，並將暫時性的 XML 物件當做參數來傳遞。如果 XML 封包有效，status Label 元件實體就會顯示成功的訊息，而應用程式也會結束。如果 validateEmployeeXML() 方法擲回自訂錯誤 (也就是 FatalError、WarningError 或一般 Error)，則會執行適當的 catch 陳述式，並呼叫 showFatalError()、showWarningError() 或 showGenericError() 方法。這些方法都會在 Alert 元件中顯示適當的訊息，明確通知使用者發生了什麼錯誤。每一種方法也都會以明確的訊息，更新 status Label 元件實體。

如果在嘗試驗證 employee XML 封包時發生嚴重錯誤，則會在 Alert 元件中顯示錯誤訊息，而且 xmlText TextArea 元件實體和 validateBtn Button 元件實體都會停用，如下列程式碼所示：

public function showFatalError(error:FatalError):void
{
    var message:String = error.message + "\n\n" + "Click OK to end.";
    var title:String = error.getTitle();
    Alert.show(message, title);
    status.text = "This application has ended.";
    this.xmlText.enabled = false;
    this.validateBtn.enabled = false;
}

如果發生的是警告錯誤而非嚴重錯誤，錯誤訊息同樣會顯示在 Alert 組件實體中，但是並不會停用 TextField 和 Button 組件實體。showWarningError() 方法會在 Alert 元件實體中顯示自訂錯誤訊息。此訊息也會要求使用者決定，是要繼續驗證 XML 還是要中止 Script。下列摘錄會顯示 showWarningError() 方法：

public function showWarningError(error:WarningError):void
{
    var message:String = error.message + "\n\n" + "Do you want to exit this application?";
    var title:String = error.getTitle();
    Alert.show(message, title, Alert.YES | Alert.NO, null, closeHandler);
    status.text = message;
}

當使用者以「是」或「否」按鈕關閉 Alert 組件實體時，就會叫用 closeHandler() 方法。下列摘錄會顯示 closeHandler() 方法：

private function closeHandler(event:CloseEvent):void
{
    switch (event.detail)
    {
        case Alert.YES:
            showFatalError(new FatalError(9999));
            break;
        case Alert.NO:
            break;
    }
}

如果使用者選擇以按下警告錯誤 Alert 對話中的「是」來中止 Script，則會擲回 FatalError，並造成應用程式的終止。

建立自訂的驗證工具

自訂的 Validator 類別包含單一方法 validateEmployeeXML()。validateEmployeeXML() 方法會採用單一引數 employee，而這就是您要驗證的 XML 封包。validateEmployeeXML() 方法如下所示：

public static function validateEmployeeXML(employee:XML):void
{
    // checks for the integrity of items in the XML
    if (employee.costCenter.length() < 1)
    {
        throw new FatalError(9000);
    }
    if (employee.costCenter.length() > 1)
    {
        throw new WarningError(9001);
    }
    if (employee.ssn.length() != 1)
    {
        throw new FatalError(9002);
    }
}

您要驗證的員工必須屬於一個 (唯一一個) 成本中心。如果員工不屬於任何成本中心，此方法便會擲回 FatalError，並反昇至主應用程式檔案中 validateData() 方法。如果員工屬於一個以上的成本中心，則會擲回 WarningError。XML 驗證工具的最終檢查，是使用者只有一個所定義的社會安全號碼 (XML 封包中的 ssn 節點)。如果 ssn 節點不是剛好一個，則會擲回 FatalError 錯誤。

您可以為 validateEmployeeXML() 方法新增其它檢查。例如，為確定 ssn 節點包含一個有效數字，或是員工至少定義了一個電話號碼和電子郵件位址，而且這兩個值都是有效的。您也可以修改 XML，讓每位員工都有唯一的 ID，並指定其經理的 ID。

定義 ApplicationError 類別

ApplicationError 類別可做為 FatalError 和 WarningError 類別的基底類別。ApplicationError 類別會擴充 Error 類別，同時定義自己的自訂方法和屬性，包括定義錯誤 ID、嚴重性，以及包含自訂錯誤代碼和訊息的 XML 物件。此類別也會定義兩個靜態常數，用來定義每種錯誤類型的嚴重性。

public function ApplicationError()
{
    messages = 
        <errors>
            <error code="9000">
                <![CDATA[Employee must be assigned to a cost center.]]>
            </error>
            <error code="9001">
                <![CDATA[Employee must be assigned to only one cost center.]]>
            </error>
            <error code="9002">
                <![CDATA[Employee must have one and only one SSN.]]>
            </error>
            <error code="9999">
                <![CDATA[The application has been stopped.]]>
            </error>
        </errors>;
}

XML 物件中的每個錯誤節點都包含唯一的數值代碼和錯誤訊息。您可以使用 E4X，藉由錯誤碼輕鬆地查詢錯誤訊息，如下列 getMessageText() 方法所示：

public function getMessageText(id:int):String
{
    var message:XMLList = messages.error.(@code == id);
    return message[0].text();
}

getMessageText() 方法會採用單一整數引數 id，並且傳回字串。id 引數就是您要查詢的錯誤代碼。例如，若您傳遞的 id 為 9001，則會擷取到一個錯誤，告訴您只能為員工指定一個成本中心。如果有一個以上的錯誤具有相同的錯誤代碼，ActionScript 只會針對第一個找到的結果 (所傳回 XmLList 物件中的 message[0]) 傳回錯誤訊息。

此 getTitle() 類別中的下一個方法不會採用任何參數，並且會傳回字串值，其中內含此一特定錯誤的錯誤 ID。這個值會用於 Alert 元件的標題中，協助您輕鬆識別在驗證 XML 封包期間，所發生的明確錯誤。下列摘錄會顯示 getTitle() 方法：

public function getTitle():String
{
    return "Error #" + id;
}

ApplicationError 類別中的最後一個方法是 toString()。這個方法會覆寫 Error 類別所定義的函數，讓您自訂錯誤訊息的顯示方式。這個方法會傳回字串，用以識別特定的錯誤號碼以及所發生的訊息。

public override function toString():String
{
    return "[APPLICATION ERROR #" + id + "] " + message;
}

定義 FatalError 類別

FatalError 類別會擴充自訂的 ApplicationError 類別，並定義三種方法：FatalError 建構函式、getTitle() 以及 toString()。第一種方法是 FatalError 建構函式，它會採用單一整數引數 errorID，並使用 ApplicationError 類別中定義的靜態常數值來設定錯誤的嚴重性，以及呼叫 ApplicationError 類別的 getMessageText() 方法，取得特定錯誤的錯誤訊息。FatalError 建構函式如下所示：

public function FatalError(errorID:int)
{
    id = errorID;
    severity = ApplicationError.FATAL;
    message = getMessageText(errorID);
}

FatalError 類別的下一個方法是 getTitle()，它會覆寫之前在 ApplicationError 類別中定義的 getTitle() 方法，並將文字 "-- FATAL" 附加到標題中，通知使用者發生了嚴重錯誤。getTitle() 方法如下所示：

public override function getTitle():String
{
    return "Error #" + id + " -- FATAL";
}

此類別最後一個方法是 toString()，會覆寫 ApplicationError 類別中定義的 toString() 方法。toString() 方法是

public override function toString():String
{
    return "[FATAL ERROR #" + id + "] " + message;
}

定義 WarningError 類別

WarningError 類別會擴充 ApplicationError 類別，而且幾乎和 FatalError 類別相同，只有幾個字串的小變動，以及將錯誤嚴重性設定為 ApplicationError.WARNING 而非 ApplicationError.FATAL，如下列程式碼所示：

public function WarningError(errorID:int)
{
    id = errorID;
    severity = ApplicationError.WARNING;
    message = super.getMessageText(errorID);
}