Office.AsyncResult interface

用于封装异步请求的结果的对象,包括状态和错误信息(如果请求失败)。

执行传递给 callback “Async”方法参数的函数时,它将接收一个 AsyncResult 对象,你可以从函数的唯一参数访问该 callback 对象。

注解

示例

// The following is an example applicable to content and task pane add-ins.
// The example shows a call to the getSelectedDataAsync method of the Document object.
Office.context.document.getSelectedDataAsync(
    Office.CoercionType.Text,
    {
        valueFormat: Office.ValueFormat.Unformatted,
        filterType: Office.FilterType.All
    },
    (result) => {
        if (result.status === Office.AsyncResultStatus.Succeeded) {
            const dataValue = result.value; // Get selected data.
            console.log('Selected data is ' + dataValue);
        } else {
            const err = result.error;
            console.log(err.name + ": " + err.message);
        }
    }
);
// The anonymous function passed as the callback argument ((result) => {...}) has a single 
// parameter named result that provides access to an AsyncResult object when the function executes.
// When the call to the getSelectedDataAsync method completes, the callback function executes, 
// and the following line of code accesses the value property of the AsyncResult object to 
// return the data selected in the document:
// const dataValue = result.value;
// Note that other lines of code in the function use the result parameter of the callback function 
// to access the status and error properties of the AsyncResult object.

属性

asyncContext

获取传递给所调用方法的可选 asyncContext 参数的用户定义项,其状态与传入时的状态相同。 这将返回用户定义的项 (,该项可以是任何 JavaScript 类型:String、Number、Boolean、Object、Array、Null 或 Undefined) 传递给调用方法的可选 asyncContext 参数。 如果您未向 asyncContext 参数传递任何东西,则返回 Undefined 。

diagnostics

获取一个 对象,该对象可在发生 错误 时提供其他信息。

error

获取一个 Office.Error 对象,该对象提供错误说明(如果发生任何错误)。

status

获取异步操作的 Office.AsyncResultStatus

value

获取此异步操作的负载或内容(如有)。

属性详细信息

asyncContext

获取传递给所调用方法的可选 asyncContext 参数的用户定义项,其状态与传入时的状态相同。 这将返回用户定义的项 (,该项可以是任何 JavaScript 类型:String、Number、Boolean、Object、Array、Null 或 Undefined) 传递给调用方法的可选 asyncContext 参数。 如果您未向 asyncContext 参数传递任何东西,则返回 Undefined 。

asyncContext: any;

属性值

any

示例

function getDataWithContext() {
    const format = "Your data: ";
    Office.context.document.getSelectedDataAsync(
        Office.CoercionType.Text, 
        { asyncContext: format }, 
        showDataWithContext);
}

function showDataWithContext(asyncResult) {
    write(asyncResult.asyncContext + asyncResult.value);
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

diagnostics

获取一个 对象,该对象可在发生 错误 时提供其他信息。

diagnostics: any;

属性值

any

注解

如果这些支持的 API 出现以下错误,此属性将返回其他信息。

支持的 API

Office.context.mailbox.item.getCallbackTokenAsync , Office.context.mailbox.item.getUserIdentityTokenAsync

支持的错误

AsyncResult.error.name AsyncResult.error.message 返回的诊断对象的说明
HTTPRequestFailure 请求失败。 请查看诊断对象,了解 HTTP 错误代码。 JSON 对象中的 HTTP 错误代码, {"HTTPCode":"401"}例如 。
InternalServerError Exchange 服务器返回了错误。 请查看诊断对象,了解详细信息。 来自 JSON 对象中的 Exchange 服务器的错误消息, {"ErrorText": "The mailbox database is temporarily unavailable"}例如 。

error

获取一个 Office.Error 对象,该对象提供错误说明(如果发生任何错误)。

error: Office.Error;

属性值

示例

function getData() {
    Office.context.document.getSelectedDataAsync(Office.CoercionType.Table, function(asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
        }
        else {
            write(asyncResult.value);
        }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

status

获取异步操作的 Office.AsyncResultStatus

status: AsyncResultStatus;

属性值

示例

function getData() {
    Office.context.document.getSelectedDataAsync(Office.CoercionType.Table, function(asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
        }
        else {
            write(asyncResult.value);
        }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

value

获取此异步操作的负载或内容(如有)。

value: T;

属性值

T

注解

访问作为参数传递给“Async”方法的回调参数的函数中的 AsyncResult 对象,例如 getSelectedDataAsyncDocument 对象的 和 setSelectedDataAsync 方法。

注意:值属性为特定“异步”方法返回的内容因该方法的用途和上下文而异。 若要确定 value 属性为 "Async" 方法返回了什么内容,请参阅该方法主题的“回调值”部分。

示例

function getData() {
    Office.context.document.getSelectedDataAsync(Office.CoercionType.Table, function(asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
        }
        else {
            write(asyncResult.value);
        }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}