Office.AsyncResult interface

参考

包:: office

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

执行传递给 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;

属性值

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;

属性值

Office.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;

属性值

注解

访问作为参数传递给“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; 
}