使用Excel JavaScript API添加允许编辑范围时遇报错求助

在浏览器端的Excel加载项（在线场景）中，使用Excel JavaScript API为工作表保护对象添加允许编辑范围时，持续触发错误：Cannot read properties of undefined (reading 'add')。我尝试通过worksheet.load("protection/protected", "protection/allowEditRanges")加载相关属性，但不确定写法是否存在问题。

我的代码如下：

async function protect(worksheetName) {
await Excel.run(async (context) => {
    worksheet = context.workbook.worksheets.getItem(worksheetName);
    worksheet.load("protection/protected", "protection/allowEditRanges");
    await context.sync();
    //can't add without pausing protection 
    worksheet.protection.unprotect("");
           
    var wholerange = worksheet.getRange();
    wholerange.format.protection.locked = true;                            

    worksheet.protection.allowEditRange.add({title: "Range1", rangeAddress: "A4:G500"});
    worksheet.protection.allowEditRange.add({title: "Range2", rangeAddress: "I4::L500"});        

    worksheet.protection.protect({
        allowFormatCells: true,
        allowAutoFilter: true,
        allowDeleteRows: true,
        allowEditObjects: true,
        //allowFormatColumns: true,
        allowFormatRows: true,
        allowInsertHyperlinks: true,
        allowInsertRows: true,
        allowPivotTables: true,
        allowSort: true
    }, "");

    await context.sync();

});
}

补充说明：此前有人认为错误源于独立O365 Excel桌面应用，但实际并非如此，该错误出现在浏览器标签页的Excel加载项（在线场景）。

问题原因与修正方案 #

1. API对象名称错误
   你调用的worksheet.protection.allowEditRange是错误的，正确的对象名应为复数形式allowEditRanges，对应API中的AllowEditRangeCollection集合对象，只有通过这个集合才能调用add方法。

2. 加载语句语法问题
   worksheet.load()的第一个参数是属性路径字符串，多个路径需用逗号分隔在同一字符串中，正确写法为：

   worksheet.load("protection/protected, protection/allowEditRanges");
   

   不过实际调用allowEditRanges.add前，无需提前加载该集合，可省略此加载步骤。

3. 范围地址格式错误
   第二个允许编辑范围的地址写为I4::L500，多了一个冒号，修正为I4:L500。

4. 冗余代码优化
   执行worksheet.protection.protect()时，默认会锁定所有单元格，无需手动设置wholerange.format.protection.locked = true，可移除该冗余代码。

5. 同步时机补充
   解除保护后建议增加一次context.sync()，确保工作表保护状态更新完成后再执行后续操作。

修正后的完整代码 #

async function protect(worksheetName) {
    await Excel.run(async (context) => {
        const worksheet = context.workbook.worksheets.getItem(worksheetName);
        // 可选：加载保护状态用于判断
        worksheet.load("protection/protected");
        await context.sync();

        // 仅当工作表已保护时执行解除操作
        if (worksheet.protection.protected) {
            worksheet.protection.unprotect("");
            await context.sync();
        }

        // 使用正确的复数集合对象allowEditRanges
        worksheet.protection.allowEditRanges.add({title: "Range1", rangeAddress: "A4:G500"});
        worksheet.protection.allowEditRanges.add({title: "Range2", rangeAddress: "I4:L500"});        

        worksheet.protection.protect({
            allowFormatCells: true,
            allowAutoFilter: true,
            allowDeleteRows: true,
            allowEditObjects: true,
            allowFormatRows: true,
            allowInsertHyperlinks: true,
            allowInsertRows: true,
            allowPivotTables: true,
            allowSort: true
        }, "");

        await context.sync();
    });
}

内容的提问来源于stack exchange，提问作者user552769