Class Protection

保护

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

// Protect range A1:B10, then remove all other users from the list of editors.
var ss = SpreadsheetApp.getActive();
var range = ss.getRange('A1:B10');
var 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.
var 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.
var ss = SpreadsheetApp.getActive();
var protections = ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);
for (var i = 0; i < protections.length; i++) {
  var protection = protections[i];
  if (protection.canEdit()) {
    protection.remove();
  }
}
// Protect the active sheet, then remove all other users from the list of editors.
var sheet = SpreadsheetApp.getActiveSheet();
var 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.
var 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获取受保护区域的类型,即 RANGESHEET
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.
var ss = SpreadsheetApp.getActive();
var protections = ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);
for (var i = 0; i < protections.length; i++) {
  var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var 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.
var 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()

获取受保护区域的类型,即 RANGESHEET

// 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 - 受保护的区域的类型,即 RANGESHEET

授权

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

  • 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.
var ss = SpreadsheetApp.getActive();
var range = ss.getRange('A1:B10');
var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var protection = sheet.protect();
var 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.
var ss = SpreadsheetApp.getActive();
var protections = ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);
for (var i = 0; i < protections.length; i++) {
  var protection = protections[i];
  if (protection.canEdit()) {
    protection.remove();
  }
}
// Remove sheet protection from the active sheet, if the user has permission to edit it.
var sheet = SpreadsheetApp.getActiveSheet();
var protection = sheet.getProtections(SpreadsheetApp.ProtectionType.SHEET)[0];
if (protection && 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.
var sheet = SpreadsheetApp.getActiveSheet();
var 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.
var 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 帐号所有),则会抛出异常。

参数

名称类型说明
editableBoolean如果拥有此电子表格的网域中的所有用户都应有权编辑受保护的范围或工作表,则为 true;否则为 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.
var ss = SpreadsheetApp.getActive();
var range = ss.getRange('A1:B10');
var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var protection = sheet.protect().setDescription('Sample protected sheet');
var 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.
var 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