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 的保護設定 (該 Range 剛好是已命名範圍)，但未呼叫 setRangeName(rangeName)，就無法建立關聯。不過，如果在 Google 試算表 UI 中使用已命名範圍建立受保護範圍，系統會自動建立關聯。

// 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 的保護措施，而該 Range 剛好是命名範圍，但未呼叫 setRangeName(rangeName)，就無法建立關聯。不過，如果在 Google 試算表 UI 中，從已命名範圍建立受保護的範圍，系統會自動建立關聯。

// 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 的保護措施，而該 Range 剛好是命名範圍，但未呼叫 setRangeName(rangeName)，就無法建立關聯。不過，如果在 Google 試算表 UI 中，從已命名範圍建立受保護的範圍，系統會自動建立關聯。

// 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