Class Protection

保护

访问和修改受保护的范围和工作表。受保护的范围可以保护静态单元格范围或命名范围。受保护的工作表可以包含不受保护的区域。对于使用旧版 Google 表格创建的电子表格，请改用 PageProtection 类。 

// Protect range A1:B10, then remove all other users from the list of editors.
const ss = SpreadsheetApp.getActive();
const range = ss.getRange('A1:B10');
const protection = range.protect().setDescription('Sample protected range');

// Ensure the current user is an editor before removing others. Otherwise, if
// the user's edit permission comes from a group, the script throws an exception
// upon removing the group.
const me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}
 
// Remove all range protections in the spreadsheet that the user has permission
// to edit.
const ss = SpreadsheetApp.getActive();
const protections = ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);
for (let i = 0; i < protections.length; i++) {
  const protection = protections[i];
  if (protection.canEdit()) {
    protection.remove();
  }
}
 
// Protect the active sheet, then remove all other users from the list of
// editors.
const sheet = SpreadsheetApp.getActiveSheet();
const protection = sheet.protect().setDescription('Sample protected sheet');

// Ensure the current user is an editor before removing others. Otherwise, if
// the user's edit permission comes from a group, the script throws an exception
// upon removing the group.
const me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

方法

方法返回类型简介
addEditor(emailAddress)Protection将指定用户添加到受保护工作表或范围的编辑者列表中。
addEditor(user)Protection将指定用户添加到受保护工作表或范围的编辑者列表中。
addEditors(emailAddresses)Protection将指定的用户数组添加到受保护工作表或范围的编辑者列表中。
addTargetAudience(audienceId)Protection将指定的目标对象群组添加为受保护范围的编辑者。
canDomainEdit()Boolean确定拥有电子表格的网域中的所有用户是否有权修改受保护的范围或工作表。
canEdit()Boolean确定用户是否有权修改受保护的范围或工作表。
getDescription()String获取受保护范围或工作表的说明。
getEditors()User[]获取受保护范围或工作表的编辑者列表。
getProtectionType()ProtectionType获取受保护区域的类型，RANGE 或 SHEET。
getRange()Range获取要保护的范围。
getRangeName()String获取受保护范围的名称（如果与命名范围相关联）。
getTargetAudiences()TargetAudience[]返回可以修改受保护范围的目标受众群体的 ID。
getUnprotectedRanges()Range[]获取受保护工作表中不受保护的范围的数组。
isWarningOnly()Boolean确定受保护区域是否使用“基于警告”保护。
remove()void取消保护范围或工作表。
removeEditor(emailAddress)Protection从受保护工作表或范围的编辑者列表中移除指定用户。
removeEditor(user)Protection从受保护工作表或范围的编辑者列表中移除指定用户。
removeEditors(emailAddresses)Protection从受保护工作表或范围的编辑者列表中移除指定的用户数组。
removeTargetAudience(audienceId)Protection移除指定目标对象群组作为受保护范围的编辑者。
setDescription(description)Protection设置受保护范围或工作表的说明。
setDomainEdit(editable)Protection设置电子表格所属网域中的所有用户是否有权修改受保护的范围或工作表。
setNamedRange(namedRange)Protection将受保护的范围与现有的命名范围相关联。
setRange(range)Protection调整要保护的范围。
setRangeName(rangeName)Protection将受保护的范围与现有的命名范围相关联。
setUnprotectedRanges(ranges)Protection取消保护受保护工作表中的给定范围数组。
setWarningOnly(warningOnly)Protection设置此受保护范围是否使用“基于警告”保护。

详细文档

addEditor(emailAddress)

将指定用户添加到受保护工作表或范围的编辑者列表中。此方法不会自动向用户授予修改电子表格本身的权限；如需执行此操作，请另外调用 Spreadsheet.addEditor(emailAddress)。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Adds an editor to the spreadsheet using an email address.
// TODO(developer): Replace the email address with a valid email.
ss.addEditor('cloudysanfrancisco@gmail.com');

// Gets a sheet by its name and protects it.
const sheet = ss.getSheetByName('Sheet1');
const sampleProtectedSheet = sheet.protect();

// Adds an editor of the protected sheet using an email address.
// TODO(developer): Replace the email address with a valid email.
sampleProtectedSheet.addEditor('cloudysanfrancisco@gmail.com');

// Gets the editors of the protected sheet.
const editors = sampleProtectedSheet.getEditors();

// Logs the editors' email addresses to the console.
for (const editor of editors) {
  console.log(editor.getEmail());
}

参数

名称类型说明
emailAddressString要添加的用户的电子邮件地址。

返回

Protection - 表示保护设置的对象，用于链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

addEditor(user)

将指定用户添加到受保护工作表或范围的编辑者列表中。此方法不会自动向用户授予修改电子表格本身的权限；如需执行此操作，请另外调用 Spreadsheet.addEditor(user)。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Adds the active user as an editor of the protected sheet.
sampleProtectedSheet.addEditor(Session.getActiveUser());

// Gets the editors of the protected sheet.
const editors = sampleProtectedSheet.getEditors();

// Logs the editors' email addresses to the console.
for (const editor of editors) {
  console.log(editor.getEmail());
}

参数

名称类型说明
userUser要添加的用户的表示法。

返回

Protection - 表示保护设置的对象，用于链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

addEditors(emailAddresses)

将指定的用户数组添加到受保护工作表或范围的编辑者列表中。此方法不会自动向用户授予修改电子表格本身的权限；如需执行此操作，请另外调用 Spreadsheet.addEditors(emailAddresses)。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Creates variables for the email addresses to add as editors.
// TODO(developer): Replace the email addresses with valid ones.
const TEST_EMAIL_1 = 'cloudysanfrancisco@gmail.com';
const TEST_EMAIL_2 = 'baklavainthebalkans@gmail.com';

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Adds editors to the protected sheet using the email address variables.
sampleProtectedSheet.addEditors([TEST_EMAIL_1, TEST_EMAIL_2]);

// Gets the editors of the protected sheet.
const editors = sampleProtectedSheet.getEditors();

// Logs the editors' email addresses to the console.
for (const editor of editors) {
  console.log(editor.getEmail());
}

参数

名称类型说明
emailAddressesString[]要添加的用户的电子邮件地址的数组。

返回

Protection - 表示保护设置的对象，用于链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

addTargetAudience(audienceId)

将指定的目标对象群组添加为受保护范围的编辑者。

参数

名称类型说明
audienceIdString要添加的目标对象群组的 ID。

返回

Protection - 表示保护设置的对象，用于链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

canDomainEdit()

确定拥有电子表格的网域中的所有用户是否有权修改受保护的范围或工作表。如果用户无权修改受保护的范围或工作表，则会抛出异常。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Logs whether domain users have permission to edit the protected sheet to the
// console.
console.log(sampleProtectedSheet.canDomainEdit());

返回

Boolean - 如果电子表格的所有者网域中的所有用户都有权修改受保护的范围或工作表，则为 true；如果没有权限，则为 false。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

canEdit()

确定用户是否有权修改受保护的范围或工作表。电子表格所有者始终可以修改受保护的范围和工作表。 

// Remove all range protections in the spreadsheet that the user has permission
// to edit.
const ss = SpreadsheetApp.getActive();
const protections = ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);
for (let i = 0; i < protections.length; i++) {
  const protection = protections[i];
  if (protection.canEdit()) {
    protection.remove();
  }
}

返回

Boolean - 如果用户有权修改受保护的范围或工作表，则为 true；否则为 false

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getDescription()

获取受保护范围或工作表的说明。如果未设置任何说明，此方法会返回一个空字符串。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet and sets the description.
const sampleProtectedSheet =
    sheet.protect().setDescription('Sample sheet is protected');

// Gets the description of the protected sheet and logs it to the console.
const sampleProtectedSheetDescription = sampleProtectedSheet.getDescription();
console.log(sampleProtectedSheetDescription);

返回

String - 受保护的范围或工作表的说明；如果未设置说明，则为空字符串。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getEditors()

获取受保护范围或工作表的编辑者列表。如果用户无权修改受保护的范围或工作表，则会抛出异常。 

// Protect the active sheet, then remove all other users from the list of
// editors.
const sheet = SpreadsheetApp.getActiveSheet();
const protection = sheet.protect().setDescription('Sample protected sheet');

// Ensure the current user is an editor before removing others. Otherwise, if
// the user's edit permission comes from a group, the script throws an exception
// upon removing the group.
const me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

返回

User[] - 有权修改受保护范围或工作表的用户数组

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getProtectionType()

获取受保护区域的类型，RANGE 或 SHEET。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Gets the type of the protected area.
const protectionType = sampleProtectedSheet.getProtectionType();

// Logs 'SHEET'to the console since the type of the protected area is a sheet.
console.log(protectionType.toString());

返回

ProtectionType - 受保护区域的类型，即 RANGE 或 SHEET。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getRange()

获取要保护的范围。如果保护范围应用于工作表（而非范围），此方法会返回跨整个工作表的范围。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range 'A1:B10' of Sheet1.
const range = sheet.getRange('A1:B10');

// Makes cells A1:B10 a protected range.
const sampleProtectedRange = range.protect();

// Gets the protected ranges on the sheet.
const protections = sheet.getProtections(SpreadsheetApp.ProtectionType.RANGE);

// Logs the A1 notation of the first protected range on the sheet.
console.log(protections[0].getRange().getA1Notation());

返回

Range - 要保护的范围。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getRangeName()

获取受保护范围的名称（如果与命名范围相关联）。如果保护措施未与命名范围相关联，则返回 null。请注意，脚本必须显式调用 setRangeName(rangeName) 才能将受保护的范围与命名范围相关联；如果调用 Range.protect() 从恰好是命名范围的 Range 创建保护，而未调用 setRangeName(rangeName)，则不足以将它们相关联。不过，在 Google 表格界面中根据命名范围创建受保护范围时，系统会自动建立关联。 

// Protect a named range in a spreadsheet and log the name of the protected
// range.
const ss = SpreadsheetApp.getActive();
const range = ss.getRange('A1:B10');
const protection = range.protect();
ss.setNamedRange('Test', range);  // Create a named range.
protection.setRangeName(
    'Test');  // Associate the protection with the named range.
Logger.log(
    protection.getRangeName());  // Verify the name of the protected range.

返回

String - 受保护的命名范围的名称；如果受保护的范围未与命名范围相关联，则为 null

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getTargetAudiences()

返回可以修改受保护范围的目标受众群体的 ID。

返回

TargetAudience[] - 目标受众群体的 ID 数组。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getUnprotectedRanges()

获取受保护工作表中不受保护的范围的数组。如果 Protection 对象对应的是受保护的范围（而非受保护的工作表），此方法会返回一个空数组。如需更改未保护的范围，请使用 setUnprotectedRanges(ranges) 设置新的范围数组；如需重新保护整张工作表，请设置空数组。 

// Unprotect cells E2:F5 in addition to any other unprotected ranges in the
// protected sheet.
const sheet = SpreadsheetApp.getActiveSheet();
const protection = sheet.protect();
const unprotected = protection.getUnprotectedRanges();
unprotected.push(sheet.getRange('E2:F5'));
protection.setUnprotectedRanges(unprotected);

返回

Range[] - 受保护的工作表中不受保护的范围的数组

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

isWarningOnly()

确定受保护区域是否使用“基于警告”保护。基于警告的保护意味着，每位用户都可以修改该区域中的数据，但在修改时系统会显示警告，要求用户确认修改。默认情况下，受保护的范围或工作表不会显示警告。如需更改为警告状态，请使用 setWarningOnly(warningOnly)。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Sets the warning status for the protected sheet as true.
sampleProtectedSheet.setWarningOnly(true);

const protectedSheetWarningStatus = sampleProtectedSheet.isWarningOnly();

// Logs the warning status of the protected sheet to the console.
console.log(protectedSheetWarningStatus);

返回

Boolean - 如果受保护的范围或工作表仅使用基于警告的保护，则为 true。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

remove()

取消保护范围或工作表。 

// Remove all range protections in the spreadsheet that the user has permission
// to edit.
const ss = SpreadsheetApp.getActive();
const protections = ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);
for (let i = 0; i < protections.length; i++) {
  const protection = protections[i];
  if (protection.canEdit()) {
    protection.remove();
  }
}
 
// Remove sheet protection from the active sheet, if the user has permission to
// edit it.
const sheet = SpreadsheetApp.getActiveSheet();
const protection = sheet.getProtections(SpreadsheetApp.ProtectionType.SHEET)[0];
if (protection?.canEdit()) {
  protection.remove();
}

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

removeEditor(emailAddress)

从受保护工作表或范围的编辑者列表中移除指定用户。请注意，如果用户是具有修改权限的 Google 群组的成员，或者网域中的所有用户都具有修改权限，则用户仍可以修改受保护区域。您无法移除电子表格的所有者或当前用户。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Creates a variable for an email address.
// TODO(developer): Replace the email address with a valid one.
const TEST_EMAIL = 'baklavainthebalkans@gmail.com';

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Adds an editor to the protected sheet using the email address variable.
sampleProtectedSheet.addEditor(TEST_EMAIL);

// Removes the editor from the protected sheet using the email address variable.
sampleProtectedSheet.removeEditor(TEST_EMAIL);

// Gets the editors of the protected sheet.
const editors = sampleProtectedSheet.getEditors();

// Logs the editors' email addresses to the console.
for (const editor of editors) {
  console.log(editor.getEmail());
}

参数

名称类型说明
emailAddressString要移除的用户的电子邮件地址。

返回

Protection - 表示保护设置的对象，用于链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

removeEditor(user)

从受保护工作表或范围的编辑者列表中移除指定用户。请注意，如果用户是具有修改权限的 Google 群组的成员，或者网域中的所有用户都具有修改权限，则该用户仍然可以修改受保护区域。您无法移除电子表格的所有者或当前用户。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Removes the active user from the editors of the protected sheet.
sampleProtectedSheet.removeEditor(Session.getActiveUser());

// Gets the editors of the protected sheet.
const editors = sampleProtectedSheet.getEditors();

// Logs the editors' email addresses to the console.
for (const editor of editors) {
  console.log(editor.getEmail());
}

参数

名称类型说明
userUser要移除的用户的表示法。

返回

Protection - 表示保护设置的对象，用于链接

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

removeEditors(emailAddresses)

从受保护的工作表或范围的编辑者列表中移除指定的用户数组。 请注意，如果任何用户都是具有修改权限的 Google 群组的成员，或者网域中的所有用户都具有修改权限，则这些用户仍然可以修改受保护区域。您无法移除电子表格的所有者或当前用户。 

// Protect the active sheet, then remove all other users from the list of
// editors.
const sheet = SpreadsheetApp.getActiveSheet();
const protection = sheet.protect().setDescription('Sample protected sheet');

// Ensure the current user is an editor before removing others. Otherwise, if
// the user's edit permission comes from a group, the script throws an exception
// upon removing the group.
const me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

参数

名称类型说明
emailAddressesString[]要移除的用户的电子邮件地址的数组。

返回

Protection - 表示保护设置的对象，用于链接

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

removeTargetAudience(audienceId)

移除指定目标对象群组作为受保护范围的编辑者。

参数

名称类型说明
audienceIdString要移除的目标对象群组的 ID。

返回

Protection - 表示保护设置的对象，用于链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

setDescription(description)

设置受保护范围或工作表的说明。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets the sheet 'Sheet1' by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Sets the sheet description to 'Sheet1 is protected.'
sampleProtectedSheet.setDescription('Sheet1 is protected');

// Gets the description of the protected sheet.
const sampleProtectedSheetDescription = sampleProtectedSheet.getDescription();

// Logs the description of the protected sheet to the console.
console.log(sampleProtectedSheetDescription);

参数

名称类型说明
descriptionString受保护范围或工作表的说明。

返回

Protection - 表示保护设置的对象，用于链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

setDomainEdit(editable)

设置电子表格所属网域中的所有用户是否有权修改受保护的范围或工作表。请注意，无论此设置如何，具有明确修改权限的任何用户都可以修改受保护区域。如果电子表格不属于 Google Workspace 网域（即归 @gmail.com 账号所有），则会抛出异常。

参数

名称类型说明
editableBooleantrue，如果电子表格的所有者所在网域中的所有用户都应有权修改受保护的范围或工作表；否则，请选择 false。

返回

Protection - 表示保护设置的对象，用于链接

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

setNamedRange(namedRange)

将受保护的范围与现有的命名范围相关联。如果命名范围与当前受保护范围涵盖的区域不同，此方法会将保护范围移至命名范围。命名范围必须与当前受保护的范围位于同一工作表中。请注意，脚本必须显式调用此方法才能将受保护的范围与命名范围相关联；调用 Range.protect() 从恰好是命名范围的 Range 创建保护，而不调用 setRangeName(rangeName)，不足以将它们相关联。不过，在 Google 表格界面中根据命名范围创建受保护范围时，系统会自动建立关联。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Protects cells A1:D10 on Sheet1.
const sheet = ss.getSheetByName('Sheet1');
const protectedRange = sheet.getRange('A1:D10').protect();

// Logs the current protected range, A1:D10.
console.log(protectedRange.getRange().getA1Notation());

// Creates a named range for cells E1:J10 called 'NewRange.'
const newRange = sheet.getRange('E1:J10');
ss.setNamedRange('NewRange', newRange);
const namedRange = ss.getNamedRanges()[0];

// Updates the protected range to the named range, 'NewRange.'
// This updates the protected range on Sheet1 from A1:D10 to E1:J10.
protectedRange.setNamedRange(namedRange);

// Logs the updated protected range to the console.
console.log(protectedRange.getRange().getA1Notation());

参数

名称类型说明
namedRangeNamedRange要与受保护范围关联的现有命名范围。

返回

Protection - 表示保护设置的对象，用于链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

setRange(range)

调整要保护的范围。如果给定范围涵盖的区域与当前受保护范围不同，此方法会将保护范围移至涵盖新范围。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Protects cells A1:D10 on Sheet1 of the spreadsheet.
const sheet = ss.getSheetByName('Sheet1');
const protectedRange = sheet.getRange('A1:D10').protect();

// Logs the original protected range, A1:D10, to the console.
console.log(protectedRange.getRange().getA1Notation());

// Gets the range E1:J10.
const newRange = sheet.getRange('E1:J10');

// Updates the protected range to E1:J10.
protectedRange.setRange(newRange);

// Logs the updated protected range to the console.
console.log(protectedRange.getRange().getA1Notation());

参数

名称类型说明
rangeRange要保护免遭修改的新范围。

返回

Protection - 表示保护设置的对象，用于链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

setRangeName(rangeName)

将受保护的范围与现有的命名范围相关联。如果命名范围与当前受保护范围涵盖的区域不同，此方法会将保护范围移至命名范围。命名范围必须与当前受保护的范围位于同一工作表中。请注意，脚本必须显式调用此方法才能将受保护的范围与命名范围相关联；调用 Range.protect() 从恰好是命名范围的 Range 创建保护，而不调用 setRangeName(rangeName)，不足以将它们相关联。不过，在 Google 表格界面中根据命名范围创建受保护范围时，系统会自动建立关联。 

// Protect a named range in a spreadsheet and log the name of the protected
// range.
const ss = SpreadsheetApp.getActive();
const range = ss.getRange('A1:B10');
const protection = range.protect();
ss.setNamedRange('Test', range);  // Create a named range.
protection.setRangeName(
    'Test');  // Associate the protection with the named range.
Logger.log(
    protection.getRangeName());  // Verify the name of the protected range.

参数

名称类型说明
rangeNameString要保护的命名范围的名称。

返回

Protection - 表示保护设置的对象，用于链接

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

setUnprotectedRanges(ranges)

取消保护受保护工作表中的给定范围数组。如果 Protection 对象对应的是受保护的范围而非受保护的工作表，或者任何范围都不位于受保护的工作表中，则会抛出异常。如需更改未受保护的范围，请设置新的范围数组；如需重新保护整张工作表，请设置空数组。 

// Protect the active sheet except B2:C5, then remove all other users from the
// list of editors.
const sheet = SpreadsheetApp.getActiveSheet();
const protection = sheet.protect().setDescription('Sample protected sheet');
const unprotected = sheet.getRange('B2:C5');
protection.setUnprotectedRanges([unprotected]);

// Ensure the current user is an editor before removing others. Otherwise, if
// the user's edit permission comes from a group, the script throws an exception
// upon removing the group.
const me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

参数

名称类型说明
rangesRange[]要在受保护的工作表中保持不受保护的范围的数组。

返回

Protection - 表示保护设置的对象，用于链接

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

setWarningOnly(warningOnly)

设置此受保护范围是否使用“基于警告”保护。基于警告的保护意味着，每位用户都可以修改该区域中的数据，但修改时系统会显示警告，要求用户确认修改。默认情况下，受保护的范围或工作表不会显示警告。如需检查警告状态，请使用 isWarningOnly()。 

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets the sheet 'Sheet1' by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet and sets the protection to warning-based.
const sampleProtectedSheet = sheet.protect().setWarningOnly(true);

// Logs whether the protected sheet is warning-based to the console.
console.log(sampleProtectedSheet.isWarningOnly());

参数

名称类型说明
warningOnlyBoolean

返回

Protection - 表示保护设置的对象，用于链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets