对文档或电子表格中的活动选择执行数据读取和写入操作

项目
04/07/2023

通过 Document 对象公开的方法，你可以读取文档或电子表格中用户的当前选区或向其中写入内容。为此， Document 对象提供 getSelectedDataAsync 和 setSelectedDataAsync 方法。本主题还介绍了如何读取、写入和创建事件处理程序，以检测对用户选定内容所做的更改。

方法 getSelectedDataAsync 仅适用于用户的当前选择。如果需要在文档中保留选区，以便使用相同的选区在运行加载项的各个会话中读取和写入，必须使用 Bindings.addFromSelectionAsync 方法添加绑定（或创建一个与 Bindings 对象其他“addFrom”方法的绑定）。有关创建对文档区域的绑定，然后读取和写入绑定的信息，请参阅绑定到文档或电子表格中的区域。

读取选择的数据

以下示例演示如何使用 getSelectedDataAsync 方法从文档的选定内容中获取数据。

Office.context.document.getSelectedDataAsync(Office.CoercionType.Text, function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    }
    else {
        write('Selected data: ' + asyncResult.value);
    }
});

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

在此示例中，第一个参数 coercionType 指定为 Office.CoercionType.Text (也可以使用文本字符串 "text") 指定此参数。这意味着在回调函数的 asyncResult 参数中提供的 AsyncResult 对象的 value 属性将返回一个包含文档中选定文本的 string。指定不同强制类型将产生不同的值。 Office.CoercionType 是可用的强制类型值的枚举。 Office.CoercionType.Text 计算结果为字符串“text”。

提示

何时应使用矩阵与表格 coercionType 数据访问？ 如果需要在添加行和列时动态增长所选表格数据，并且必须使用表标题，则应通过将方法的 getSelectedDataAsynccoercionType 参数指定为 "table" 或 Office.CoercionType.Table) ，使用表数据类型 (。表格数据和矩阵数据中都支持在数据结构内添加行和列，但仅支持对表格数据追加行和列。如果不打算添加行和列，并且数据不需要标头功能，则应通过将方法的 getSelectedDataAsynccoercionType 参数指定为 "matrix" 或 Office.CoercionType.Matrix) 来使用矩阵数据类型 (，从而提供与数据交互的更简单模型。

作为第二个参数回调传递到方法的匿名函数在操作完成时getSelectedDataAsync执行。调用该函数时使用单个参数 asyncResult，后者包含调用的结果和状态。如果调用失败，则对象的 error 属性 AsyncResult 提供对 Error 对象的访问权限。您可以检查 Error.name 和 Error.message 属性的值，以确定设置操作失败的原因。否则，会显示文档中选定的文本。

AsyncResult.status 属性在 if 语句中用于测试调用是否成功。 Office.AsyncResultStatus 是可用 AsyncResult.status 属性值的枚举。 Office.AsyncResultStatus.Failed 计算结果为字符串“failed” (，也可以再次指定为该文本字符串) 。

向选定内容中写入数据

以下示例演示如何将选定内容设置为显示"Hello World!"。

Office.context.document.setSelectedDataAsync("Hello World!", function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write(asyncResult.error.message);
    }
});

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

为数据参数传入不同的对象类型会产生不同的结果。结果取决于文档中当前选择的内容、托管加载项的 Office 客户端应用程序，以及传入的数据是否可以强制设置为当前选择。

作为 callback 参数传入 setSelectedDataAsync 方法的匿名函数在异步调用完成时执行。使用 setSelectedDataAsync 方法将数据写入所选内容时，回调的 asyncResult 参数仅提供对调用状态的访问权限，如果调用失败，则提供对 Error 对象的访问。

检测选择中的更改

以下示例演示如何通过使用 Document.addHandlerAsync 方法为文档中的 SelectionChanged 事件添加事件处理程序来检测选定内容中的更改。

Office.context.document.addHandlerAsync("documentSelectionChanged", myHandler, function(result){}
);

// Event handler function.
function myHandler(eventArgs){
    write('Document Selection Changed');
}

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

第一个参数 eventType 指定要订阅的事件的名称。传递此参数的字符串 "documentSelectionChanged" 等效于传递 Office.EventType.DocumentSelectionChangedOffice.EventType 枚举的事件类型。

myHandler()作为第二个参数处理程序传递到方法中的函数是在文档上更改选定内容时执行的事件处理程序。调用该函数时使用单个参数 eventArgs，后者在异步操作完成时将包含对 DocumentSelectionChangedEventArgs 对象的引用。可以使用 DocumentSelectionChangedEventArgs.document 属性访问引发事件的文档。

注意

可以通过再次调用 addHandlerAsync 方法并为 handler 参数传入其他事件处理程序函数，为给定事件添加多个 事件处理程序 。只要每个事件处理程序函数的名称保持唯一，此方法就有用。

停止检测选择中的更改

以下示例演示如何通过调用 document.removeHandlerAsync 方法停止侦听 Document.SelectionChanged 事件。

Office.context.document.removeHandlerAsync("documentSelectionChanged", {handler:myHandler}, function(result){});

myHandler作为第二个参数处理程序传递的函数名称指定将从事件中删除的SelectionChanged事件处理程序。

重要

如果在调用方法时removeHandlerAsync省略可选的 handler 参数，则将删除指定 eventType 的所有事件处理程序。

通过

对文档或电子表格中的活动选择执行数据读取和写入操作

读取选择的数据

向选定内容中写入数据

检测选择中的更改

停止检测选择中的更改

其他资源