Office-js Excel 插件：何时 return context.sync()

Question

我很难理解何时使用 context.sync()。

这是一个基本的例子，但它恢复了我的理解不足：

Excel.run(function (context){
    const wb = context.workbook;
    const ws = wb.worksheets.getActiveWorksheet();

    // should never happened, but is it correct to check like this ?
    if (wb === null) {
        // IS IT CORRECT TO DO THIS ?
        // I just want to exit the function
        // return; would be enough ? What's going on in the callstack?
        return context.sync();
    }
    ws.load("name");
    return context.sync().then(function() {
        var name = wb.name;
        // do stuff
        var range = ws.getRangeByIndexes(1,1,10,10);
        return context.sync().then(function() {
             ws.names.add("NEWRANGE", range);
             // mandatory return context.sync() to refresh Excel object ?
             // doesn't work otherwise for me
             return context.sync();
        });
    }
}).catch(function(error) {
  // do stuff
}

如果有人能解释一下，我们将非常欢迎:)

干杯。

Answer 1

我认为如果您将这些对象视为代理对象，将会有所帮助。它们只是真实对象的表示，并非所有属性在代理对象上都可用，因为它们不需要可用。同样，对代理对象所做的更改不会更新真实对象。 context.sync() 用于将代理对象与真实对象同步。

查看您的代码，第一个 context.sync() 是不必要的，因为您不需要检索任何内容或进行任何更改。实际上整个条件 if (wb === null) 是不必要的，因为 context.workbook 不能为空。

一旦您尝试 ws.load("name");，您就需要 context.sync()，因为您已尝试访问需要从中加载的代理对象上的属性实物。

当您调用 var range = ws.getRangeByIndexes(1,1,10,10); 时，您不需要 context.sync()，因为您只是获取另一个代理对象，但没有进行任何更改，也没有访问任何属性。

但是由于 ws.names.add("NEWRANGE", range); 是一个真正的变化，你需要一个 context.sync() 来反映真实对象的变化。从技术上讲，最后的 context.sync() 不是必需的，因为 Excel.run 实际上会在运行之后调用 context.sync() Excel.run() 中的所有内容。就是说，不管怎样，结尾 context.sync() 是个好习惯。

您还可以在一个 context.sync() 中批量独立操作。由于 var range = ws.getRangeByIndexes(1,1,10,10); 与 ws.names.add("NEWRANGE", range); 无关，您实际上可以将它们放在单个 context.sync() 后面。

我还建议改用 TypeScript 以使您的代码更简洁、更易于理解。尝试在 Excel 中使用 ScriptLab。有很多示例可以帮助您总体上理解 context.sync() 和 office-js。

最后，这是您可以编写的代码来完成同样的事情。

Excel.run(function (context) {
    const wb = context.workbook;
    const ws = wb.worksheets.getActiveWorksheet();

    ws.load("name");
    return context.sync().then(function () {
        var name = wb.name;
        // do stuff
        var range = ws.getRangeByIndexes(1, 1, 10, 10);
        ws.names.add("NEWRANGE", range);
        return context.sync();
    });
}).catch(function (error) {
    // do stuff
});

哦，你应该按照 Cindy 的建议看一看 Michael 的书。

Office-js Excel 插件：何时 return context.sync()

Office-js Excel addin : when to return context.sync()

javascript

excel

office-addins

office365-apps

office-js