插入外部数据

下面的参考图和步骤解释了在 ONLYOFFICE 文档服务器中通过外部链接将数据插入电子表格的过程。

用户将单元格值从源电子表格的 文档编辑器 复制到剪贴板。同时，特殊数据也被复制。
用户将复制的数据插入到目标电子表格的 文档编辑器 中。
文档编辑器 通过将数据发送到 文档管理器来请求到源文件的链接。
文档管理器 将源电子表格链接发送给 文档编辑器。
文档编辑器 向 文档编辑服务 发送电子表格下载请求。
文档编辑服务 从 文档存储服务下载源电子表格。
文档编辑服务 发送所有必要的数据以显示在目标电子表格的 文档编辑器 中。

如何在实践中做到这一点

创建将从中复制数据的源电子表格。

在源电子表格的初始化配置中指定 document.referenceData 参数：

var docEditor = new DocsAPI.DocEditor("placeholder", {
    "document": {
        "referenceData": {
            "fileKey": "BCFA2CED",
            "instanceId": "https://example.com",
            "key": "Khirz6zTPdfd7"
        },
        ...
    },
    ...
});

当用户从源电子表格中复制数据时，剪贴板会收到以下值的列表：
- 工作表名称和复制数据的范围，稍后将用于刷新复制的数据；
- document.referenceData 对象，用于检查通过外部链接将数据插入目标电子表格的可用性；
- 将用于在编辑器中显示公式的文件名。
创建将插入外部数据的目标电子表格。

在要显示的 “粘贴链接” 和 “更新值” 按钮的目标电子表格的初始化配置中指定 onRequestReferenceData 事件处理程序：

var docEditor = new DocsAPI.DocEditor("placeholder", {
    "events": {
        "onRequestReferenceData": onRequestReferenceData,
        ...
    },
    ...
});

如果剪贴板具有在步骤 3 中指定的源电子表格数据，并且目标电子表格在初始化配置中具有 onRequestReferenceData 事件处理程序，则 “粘贴链接” 按钮将显示在对话框中。

当用户单击 “粘贴链接” 按钮时，公式将插入到当前单元格中，并将 referenceData 对象保存到目标文件中。插入的公式显示如下：

='[fileName]sheetName'!cell

参数	描述	类型	示例
cell	从中复制数据的单元格。	string	E5
fileName	从中复制数据的文件名。	string	new.xlsx
sheetName	从中复制数据的工作表名称。	string	Sheet1

对文件的数据更新请求将发送到文件URL。

请注意，您可以在单元格中输入指定格式的公式，来自外部文件的数据也会被插入。但在这种情况下， onRequestReferenceData 事件将仅使用 path 参数执行。

当用户尝试通过单击数据选项卡的外部链接对话框中的更新值按钮来刷新源文件中的数据时，调用 onRequestReferenceData 事件。含有从源文件接收的唯一文件数据的对象、文件路径或名称以及文件 URL 在 data 参数中发送。
要将数据发送到setReferenceData方法，建议首先通过referenceData参数搜索文件。如果没有这样的字段或找不到文件，则使用path或link参数。
```
var onRequestReferenceData = function (event) {
    var link = event.data.link;
    var referenceData = event.data.referenceData;
    var path = event.data.path;
    ...
 };
```

为了刷新源文件中的数据，必须调用 setReferenceData 方法。 When calling this method, the token must be added to validate the parameters.

请注意，仅当用户对源文件具有权限时才会执行此方法。

docEditor.setReferenceData({
    "fileType": "xlsx",
    "link": "https://example.com/url-to-file-editor.xlsx",
    "path": "sample.xlsx",
    "referenceData": {
        "fileKey": "BCFA2CED",
        "instanceId": "https://example.com",
        "key": "Khirz6zTPdfd7"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxlVHlwZSI6Inhsc3giLCJwYXRoIjoic2FtcGxlLnhsc3giLCJyZWZlcmVuY2VEYXRhIjp7ImZpbGVLZXkiOiJCQ0ZBMkNFRCIsImluc3RhbmNlSWQiOiJodHRwczovL2V4YW1wbGUuY29tIn0sInVybCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXJsLXRvLWV4YW1wbGUtZG9jdW1lbnQueGxzeCJ9.UXosmM-E_Cu9j9QGSlcj9FEoSu5m-zCS4b6FxO_2k7w",
    "url": "https://example.com/url-to-example-document.xlsx"
});

其中 example.com 是安装了 文档管理器 和 文档存储服务 的服务器的名称。有关文档服务器服务"客户端-服务器交互"的更多信息，请参阅 "它是如何运作的" 部分。

使用外部链接

指定要在文档编辑器初始化的配置脚本中显示的打开源按钮的事件处理程序。当用户尝试通过单击打开源按钮打开外部链接时， onRequestOpen 事件被调用。

要在新选项卡中打开包含 path 或 referenceData 参数引用的外部文件的编辑器，您必须通过调用带有 path 和 windowName 参数的 window.open 方法来传递指向此选项卡的链接。

具有唯一文件数据、文件路径和新浏览器选项卡名称的对象将在 data 参数中发送。

示例
```
var onRequestOpen = function (event) {
    var path  = event.data.path;
    var referenceData = event.data.referenceData;
    var windowName  = event.data.windowName;
    window.open({
        "path": "https://example.com/external-url.docx",
        "windowName": event.data.windowName
    });
};

var docEditor = new DocsAPI.DocEditor("placeholder", {
    "events": {
        "onRequestOpen": onRequestOpen,
        ...
    },
    ...
});
```
其中 example.com 是安装文档管理器和文档存储服务的服务器的名称。请参阅工作原理部分，了解有关文档服务器服务客户端与服务器交互的更多信息。

指定要在文档编辑器初始化的配置脚本中显示的更改源按钮的事件处理程序。当用户尝试通过单击更改源按钮更改外部链接时，onRequestReferenceSource 事件被调用。

具有唯一文件数据和文件路径或名称的对象在 data 参数中发送。

单击该按钮时，必须调用 setReferenceSource 方法来更改外部数据的来源。调用该方法时，必须添加token来验证参数。如果未声明事件，则不会显示更改源按钮。

要将数据发送到setReferenceSource方法，建议首先通过referenceData参数搜索文件。如果没有这样的字段或找不到文件，则使用 path 参数。 Change source

示例

var onRequestReferenceSource = function () {
    var referenceData =  event.data.referenceData;
    var path = event.data.path;
    ...

    docEditor.setReferenceSource({
        "fileType": "xlsx",
        "path": "sample.xlsx",
        "referenceData": {
            "fileKey": "BCFA2CED",
            "instanceId": "https://example.com",
            "key": "Khirz6zTPdfd7"
        },
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxlVHlwZSI6Inhsc3giLCJwYXRoIjoic2FtcGxlLnhsc3giLCJyZWZlcmVuY2VEYXRhIjp7ImZpbGVLZXkiOiJCQ0ZBMkNFRCIsImluc3RhbmNlSWQiOiJodHRwczovL2V4YW1wbGUuY29tIn0sInVybCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXJsLXRvLWV4YW1wbGUtZG9jdW1lbnQueGxzeCJ9.UXosmM-E_Cu9j9QGSlcj9FEoSu5m-zCS4b6FxO_2k7w",
        "url": "https://example.com/url-to-example-document.xlsx"
    });
};

var docEditor = new DocsAPI.DocEditor("placeholder", {
    "events": {
        "onRequestReferenceSource": onRequestReferenceSource,
        ...
    },
    ...
});