ExcelScript.WorksheetProtection interface

Pacote:

ExcelScript

Representa a proteção de um objeto de folha de cálculo.

Comentários

Exemplos

/**
 * This script pauses the protection of a worksheet by using the provided password.
 * This password could come from a Power Automate flow.
 */
function main(workbook: ExcelScript.Workbook, password: string) {
  // Get the worksheet named "Sales".
  const sheet = workbook.getWorksheet("Sales");
  const protection: ExcelScript.WorksheetProtection = sheet.getProtection();
  
  // Check if the provided password works.
  if (protection.checkPassword(password)) {
    protection.pauseProtection(password);

    // Edit the worksheet...

    protection.resumeProtection();
  } else {
    console.log("Incorrect password");
  }
}

Métodos

addAllowEditRange(title, rangeAddress, options)	Adiciona um AllowEditRange objeto à folha de cálculo. A proteção da folha de cálculo tem de ser desativada ou colocada em pausa para que este método funcione corretamente. Se a proteção da folha de cálculo estiver ativada e não estiver em pausa, este método gera um AccessDenied erro e a operação de adição falha.
checkPassword(password)	Especifica se a palavra-passe pode ser utilizada para desbloquear a proteção da folha de cálculo. Este método não altera o estado de proteção da folha de cálculo. Se for introduzida uma palavra-passe, mas não for necessária nenhuma palavra-passe para desbloquear a proteção da folha de cálculo, este método devolverá false.
getAllowEditRange(key)	Obtém o AllowEditRange objeto pelo respetivo título.
getAllowEditRanges()	Especifica o AllowEditRangeCollection objeto encontrado nesta folha de cálculo. Esta é uma coleção de AllowEditRange objetos, que funcionam com propriedades de proteção de folhas de cálculo. Quando a proteção da folha de cálculo está ativada, um AllowEditRange objeto pode ser utilizado para permitir a edição de um intervalo específico, mantendo a proteção no resto da folha de cálculo.
getCanPauseProtection()	Especifica se a proteção pode ser colocada em pausa para esta folha de cálculo.
getIsPasswordProtected()	Especifica se a folha está protegida por palavra-passe.
getIsPaused()	Especifica se a proteção da folha de cálculo está em pausa.
getOptions()	Especifica as opções de proteção para a folha de cálculo.
getProtected()	Especifica se a folha de cálculo está protegida.
getSavedOptions()	Especifica as opções de proteção guardadas na folha de cálculo. Esta ação irá devolver o mesmo WorksheetProtectionOptions objeto, independentemente do estado de proteção da folha de cálculo.
pauseProtection(password)	Coloca em pausa a proteção da folha de cálculo para o objeto de folha de cálculo especificado para o utilizador na sessão atual. Este método não faz nada se a proteção da folha de cálculo não estiver ativada ou já estiver em pausa. Se a palavra-passe estiver incorreta, este método gera um InvalidArgument erro e não interrompe a proteção. Este método não altera o estado de proteção se a proteção da folha de cálculo não estiver ativada ou já estiver em pausa.
pauseProtectionForAllAllowEditRanges(password)	Coloca em pausa a proteção da folha de cálculo para todos os AllowEditRange objetos encontrados nesta folha de cálculo que tenham a palavra-passe especificada para o utilizador na sessão atual. Este método não faz nada se a proteção da folha de cálculo não estiver ativada ou estiver em pausa. Se não for possível colocar a proteção da folha de cálculo em pausa, este método gera um UnsupportedOperation erro e falha ao colocar em pausa a proteção do intervalo. Se a palavra-passe não corresponder a nenhum AllowEditRange objeto na coleção, este método gera um BadPassword erro e falha ao colocar em pausa a proteção de qualquer intervalo na coleção.
protect(options, password)	Protege uma planilha. Falha se a folha de cálculo já tiver sido protegida.
resumeProtection()	Retoma a proteção da folha de cálculo para o objeto de folha de cálculo especificado para o utilizador numa determinada sessão. A proteção da folha de cálculo tem de ser colocada em pausa para que este método funcione. Se a proteção da folha de cálculo não estiver em pausa, este método não alterará o estado de proteção da folha de cálculo.
setPassword(password)	Altera a palavra-passe associada ao WorksheetProtection objeto. Definir a palavra-passe como uma cadeia vazia ("") ou removerá null a proteção por palavra-passe do WorksheetProtection objeto. A proteção da folha de cálculo tem de estar ativada e colocada em pausa para que este método funcione corretamente. Se a proteção da folha de cálculo estiver desativada, este método gera um InvalidOperation erro e não altera a palavra-passe. Se a proteção da folha de cálculo estiver ativada e não estiver em pausa, este método gera um AccessDenied erro e não altera a palavra-passe.
unprotect(password)	Desprotege uma planilha.
updateOptions(options)	Altere as opções de proteção da folha de cálculo associadas ao WorksheetProtection objeto. A proteção da folha de cálculo tem de ser desativada ou colocada em pausa para que este método funcione corretamente. Se a proteção da folha de cálculo estiver ativada e não estiver em pausa, este método gera um AccessDenied erro e não altera as opções de proteção da folha de cálculo.

Detalhes do método

addAllowEditRange(title, rangeAddress, options)

Adiciona um AllowEditRange objeto à folha de cálculo. A proteção da folha de cálculo tem de ser desativada ou colocada em pausa para que este método funcione corretamente. Se a proteção da folha de cálculo estiver ativada e não estiver em pausa, este método gera um AccessDenied erro e a operação de adição falha.

addAllowEditRange(
            title: string,
            rangeAddress: string,
            options?: AllowEditRangeOptions
        ): void;

Parâmetros

title

string

A cadeia de título do AllowEditRange objeto a adicionar.

rangeAddress

string

O endereço de intervalo do AllowEditRange objeto a adicionar.

options

ExcelScript.AllowEditRangeOptions

Opções adicionais a adicionar ao AllowEditRange objeto, como a palavra-passe.

Retornos

void

Exemplos

/**
 * This script adds a password-protected, editable range
 * to an otherwise protected worksheet.
 */
function main(workbook: ExcelScript.Workbook, password: string) {
    // Get the protection object for the "Data" worksheet.
    const dataSheet = workbook.getWorksheet("Data");
    const sheetProtection = dataSheet.getProtection();

    // Set the password needed to edit the range to be the user provided string.
    const editRangeProperties : ExcelScript.AllowEditRangeOptions = {
        password: password
    };

    // Set range "D2:D6" to be editable if the password is provided.
    sheetProtection.addAllowEditRange("Notes Section", "D2:D6", editRangeProperties);
    
    // Protect the worksheet.
    sheetProtection.protect();
}

checkPassword(password)

Especifica se a palavra-passe pode ser utilizada para desbloquear a proteção da folha de cálculo. Este método não altera o estado de proteção da folha de cálculo. Se for introduzida uma palavra-passe, mas não for necessária nenhuma palavra-passe para desbloquear a proteção da folha de cálculo, este método devolverá false.

checkPassword(password?: string): boolean;

Parâmetros

password

string

A palavra-passe a marcar na folha de cálculo protegida.

Retornos

boolean

getAllowEditRange(key)

Obtém o AllowEditRange objeto pelo respetivo título.

getAllowEditRange(key: string): AllowEditRange | undefined;

Parâmetros

key

string

O título do AllowEditRange.

Retornos

ExcelScript.AllowEditRange | undefined

getAllowEditRanges()

Especifica o AllowEditRangeCollection objeto encontrado nesta folha de cálculo. Esta é uma coleção de AllowEditRange objetos, que funcionam com propriedades de proteção de folhas de cálculo. Quando a proteção da folha de cálculo está ativada, um AllowEditRange objeto pode ser utilizado para permitir a edição de um intervalo específico, mantendo a proteção no resto da folha de cálculo.

getAllowEditRanges(): AllowEditRange[];

Retornos

ExcelScript.AllowEditRange[]

getCanPauseProtection()

Especifica se a proteção pode ser colocada em pausa para esta folha de cálculo.

getCanPauseProtection(): boolean;

Retornos

boolean

getIsPasswordProtected()

Especifica se a folha está protegida por palavra-passe.

getIsPasswordProtected(): boolean;

Retornos

boolean

getIsPaused()

Especifica se a proteção da folha de cálculo está em pausa.

getIsPaused(): boolean;

Retornos

boolean

getOptions()

Especifica as opções de proteção para a folha de cálculo.

getOptions(): WorksheetProtectionOptions;

Retornos

ExcelScript.WorksheetProtectionOptions

getProtected()

Especifica se a folha de cálculo está protegida.

getProtected(): boolean;

Retornos

boolean

getSavedOptions()

Especifica as opções de proteção guardadas na folha de cálculo. Esta ação irá devolver o mesmo WorksheetProtectionOptions objeto, independentemente do estado de proteção da folha de cálculo.

getSavedOptions(): WorksheetProtectionOptions;

Retornos

ExcelScript.WorksheetProtectionOptions

pauseProtection(password)

Coloca em pausa a proteção da folha de cálculo para o objeto de folha de cálculo especificado para o utilizador na sessão atual. Este método não faz nada se a proteção da folha de cálculo não estiver ativada ou já estiver em pausa. Se a palavra-passe estiver incorreta, este método gera um InvalidArgument erro e não interrompe a proteção. Este método não altera o estado de proteção se a proteção da folha de cálculo não estiver ativada ou já estiver em pausa.

pauseProtection(password?: string): void;

Parâmetros

password

string

A palavra-passe associada à folha de cálculo protegida.

Retornos

void

pauseProtectionForAllAllowEditRanges(password)

Coloca em pausa a proteção da folha de cálculo para todos os AllowEditRange objetos encontrados nesta folha de cálculo que tenham a palavra-passe especificada para o utilizador na sessão atual. Este método não faz nada se a proteção da folha de cálculo não estiver ativada ou estiver em pausa. Se não for possível colocar a proteção da folha de cálculo em pausa, este método gera um UnsupportedOperation erro e falha ao colocar em pausa a proteção do intervalo. Se a palavra-passe não corresponder a nenhum AllowEditRange objeto na coleção, este método gera um BadPassword erro e falha ao colocar em pausa a proteção de qualquer intervalo na coleção.

pauseProtectionForAllAllowEditRanges(password: string): void;

Parâmetros

password

string

A palavra-passe para colocar em pausa a proteção nos AllowEditRange objetos.

Retornos

void

protect(options, password)

Protege uma planilha. Falha se a folha de cálculo já tiver sido protegida.

protect(options?: WorksheetProtectionOptions, password?: string): void;

Parâmetros

options

ExcelScript.WorksheetProtectionOptions

Opcional. Opções de proteção da planilha.

password

string

Opcional. Palavra-passe de proteção de folha.

Retornos

void

Exemplos

/**
 * This script protects cells from being selected on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the protection settings for the current worksheet.
  const currentSheet = workbook.getActiveWorksheet();
  const sheetProtection = currentSheet.getProtection();

  // Create a new WorksheetProtectionOptions object with the selectionMode property set to `none`.
  let protectionOptions : ExcelScript.WorksheetProtectionOptions = {
    selectionMode: ExcelScript.ProtectionSelectionMode.none
  }

  // Apply the given protection options.
  sheetProtection.protect(protectionOptions);
}

resumeProtection()

Retoma a proteção da folha de cálculo para o objeto de folha de cálculo especificado para o utilizador numa determinada sessão. A proteção da folha de cálculo tem de ser colocada em pausa para que este método funcione. Se a proteção da folha de cálculo não estiver em pausa, este método não alterará o estado de proteção da folha de cálculo.

resumeProtection(): void;

Retornos

void

setPassword(password)

Altera a palavra-passe associada ao WorksheetProtection objeto. Definir a palavra-passe como uma cadeia vazia ("") ou removerá null a proteção por palavra-passe do WorksheetProtection objeto. A proteção da folha de cálculo tem de estar ativada e colocada em pausa para que este método funcione corretamente. Se a proteção da folha de cálculo estiver desativada, este método gera um InvalidOperation erro e não altera a palavra-passe. Se a proteção da folha de cálculo estiver ativada e não estiver em pausa, este método gera um AccessDenied erro e não altera a palavra-passe.

setPassword(password?: string): void;

Parâmetros

password

string

A palavra-passe associada ao WorksheetProtection objeto.

Retornos

void

unprotect(password)

Desprotege uma planilha.

unprotect(password?: string): void;

Parâmetros

password

string

Palavra-passe de proteção de folha.

Retornos

void

updateOptions(options)

Altere as opções de proteção da folha de cálculo associadas ao WorksheetProtection objeto. A proteção da folha de cálculo tem de ser desativada ou colocada em pausa para que este método funcione corretamente. Se a proteção da folha de cálculo estiver ativada e não estiver em pausa, este método gera um AccessDenied erro e não altera as opções de proteção da folha de cálculo.

updateOptions(options: WorksheetProtectionOptions): void;

Parâmetros

options

ExcelScript.WorksheetProtectionOptions

A interface de opções associada ao WorksheetProtection objeto.

Retornos

void