Artigo Técnico

Proteção de planilha XLSX no Delphi: 15 opções Allow

Você entrega uma pasta de trabalho pronta a um colega e pede que ele filtre o conteúdo, não que o reescreva. Então você protege a planilha. O atalho tentador é gravar um único elemento fixo no arquivo, <sheetProtection sheet="1" objects="1" scenarios="1"/>, sempre. A planilha é bloqueada, o hash da senha é anexado, e o usuário não pode fazer nada, nem mesmo a ordenação e o filtro que você realmente queria deixar abertos. A caixa de diálogo "Proteger Planilha" do próprio Excel tem quinze caixas de seleção exatamente por esse motivo, e o modelo de proteção do HotXLS expressa todas elas

O HotXLS é um componente VCL nativo de planilhas para Delphi e C++Builder que lê e grava XLS e XLSX sem o Excel instalado. Este artigo trata do lado XLSX da proteção de planilhas: o enum TXLSXSheetProtectionOption, a propriedade AllowOption que alterna cada permissão, e a única regra de codificação OOXML que derruba todo mundo que escreve um elemento <sheetProtection> à mão

O que a proteção de planilha de fato protege

Primeiro, o limite, porque ele decide quanto você deve confiar em tudo isso. A proteção de planilha no formato de planilhas OOXML (ECMA-376) é uma política de interação, não criptografia. Ela diz a um aplicativo em conformidade quais edições recusar enquanto a planilha está protegida. Os valores das células continuam sentados em xl/worksheets/sheetN.xml em texto puro; descompacte o .xlsx e eles estão bem ali. A senha opcional é armazenada como um hash legado curto, não como uma chave que embaralha qualquer coisa. Qualquer pessoa que renomeie o arquivo, abra a parte e remova a linha <sheetProtection> lê e edita tudo

Então a proteção responde a "impedir que meu colega estrague uma fórmula por acidente", e não a "manter estes dados em segredo de alguém motivado". São problemas diferentes, com ferramentas diferentes. Se você precisa de confidencialidade, quer a criptografia no nível do workbook coberta em saída XLSX protegida por AES, que de fato cifra o pacote. Proteção de planilha e criptografia de workbook se combinam sem atrito, mas só a segunda é um cadeado. Mantenha essa linha reta e o resto desta página é só encanamento

Diagrama contrastando a proteção de planilha XLSX no Delphi com HotXLS como uma política de interação e a criptografia AES do workbook como o único cadeado de verdade
A proteção de planilha recusa edições enquanto os valores ficam em texto puro; só a criptografia do workbook cifra o pacote

As quinze opções e a propriedade AllowOption

Cada planilha carrega um conjunto de valores TXLSXSheetProtectionOption que descrevem o que o usuário ainda pode fazer enquanto a planilha está protegida. Os membros se mapeiam um a um para os atributos OOXML e para as caixas de seleção da caixa de diálogo do Excel:

  • xlsxSpoEditObjects, xlsxSpoEditScenarios — editar objetos de desenho e cenários what-if
  • xlsxSpoFormatCells, xlsxSpoFormatColumns, xlsxSpoFormatRows — reformatar células, colunas, linhas
  • xlsxSpoInsertColumns, xlsxSpoInsertRows, xlsxSpoInsertHyperlinks — inserir colunas, linhas, links
  • xlsxSpoDeleteColumns, xlsxSpoDeleteRows — excluir colunas, linhas
  • xlsxSpoSelectLockedCells, xlsxSpoSelectUnlockedCells — mover a seleção para células bloqueadas ou desbloqueadas
  • xlsxSpoSort, xlsxSpoAutoFilter, xlsxSpoPivotTables — ordenar intervalos, usar dropdowns do AutoFilter, trabalhar com PivotTables

Você lê e escreve bits individuais pela propriedade indexada AllowOption no TXLSXWorksheet. AllowOption[Opt] = True significa que a ação é permitida; defini-la como False a proíbe. O conjunto inteiro também é acessível de uma vez por SheetProtectionOptions, um TXLSXSheetProtectionOptions (um set of Pascal comum), então você pode salvá-lo, restaurá-lo ou substituí-lo por inteiro

O padrão importa e é deliberado: uma planilha recém-criada começa com toda opção permitida. O construtor semeia SheetProtectionOptions com a faixa completa, [Low(TXLSXSheetProtectionOption)..High(TXLSXSheetProtectionOption)]. Você estreita a partir daí, excluindo as ações que quer proibir, em vez de construir um conjunto de permissões do zero. Essa escolha é o que faz a regra de codificação do writer, abaixo, se alinhar com o comportamento do Excel

Diagrama dos quinze valores de TXLSXSheetProtectionOption do HotXLS agrupados em seis famílias e alternados pela propriedade indexada AllowOption e pelo conjunto SheetProtectionOptions no Delphi
As quinze opções se agrupam em seis famílias, cada uma alternada bit a bit ou trocada por inteiro como um set Pascal

Proteger a planilha deixando ordenação e filtro abertos

Aqui está o caso comum de ponta a ponta: proteger um relatório pronto para que o layout não possa ser remodelado, mas deixar o leitor ordenar e filtrar. Note que Protect e as opções são independentes. O Protect coloca a planilha no estado protegido e armazena o hash opcional da senha; ele não toca no conjunto de opções. Você ajusta AllowOption separadamente, e as alternâncias entram em vigor quando a planilha está protegida e salva

var
  wb: TXLSXWorkbook;
  sh: TXLSXWorksheet;
begin
  wb := TXLSXWorkbook.Create;
  try
    sh := wb.Sheets.Add('Protected');
    sh.Cells[1, 1].Value := 'Region'; sh.Cells[1, 2].Value := 'Units';
    sh.Cells[2, 1].Value := 'North';  sh.Cells[2, 2].Value := 120;
    sh.Cells[3, 1].Value := 'South';  sh.Cells[3, 2].Value := 98;

    // Protege com senha. Isso só define o estado protegido + o hash;
    // o conjunto de opções fica no padrão tudo-permitido.
    sh.Protect('HotXLS-2026');

    // Estreita: mantém sort + AutoFilter, proíbe remodelar e reformatar.
    sh.AllowOption[xlsxSpoSort]          := True;
    sh.AllowOption[xlsxSpoAutoFilter]    := True;
    sh.AllowOption[xlsxSpoFormatCells]   := False;
    sh.AllowOption[xlsxSpoFormatColumns] := False;
    sh.AllowOption[xlsxSpoFormatRows]    := False;
    sh.AllowOption[xlsxSpoInsertRows]    := False;
    sh.AllowOption[xlsxSpoDeleteRows]    := False;

    if wb.SaveAs('protection.xlsx') <> 1 then
      Writeln('SaveAs failed');
  finally
    wb.Free;
  end;
end;

Duas coisas para ler nesse snippet. As linhas de Sort e AutoFilter estão escritas explicitamente embora ambas padronizem para True; isso é documentação para o próximo mantenedor, não um requisito funcional. E como os padrões são permissivos, as únicas linhas que mudam o arquivo de saída são as que definem uma opção como False. Isso não é um acidente desta API, é o formato de arquivo do OOXML se mostrando, o que nos leva à próxima seção

A regra de codificação: omitir significa permitir, attr=0 significa proibir

Este é o único fato contraintuitivo em toda a funcionalidade, e é onde o <sheetProtection> escrito à mão costuma dar errado. No OOXML, cada atributo por ação é uma flag de proibição, e sua ausência é permissão. Um atributo ausente significa que a ação é permitida. Um atributo escrito como "0" significa que a ação é proibida enquanto a planilha está protegida. Não existe formatCells="1" num arquivo bem-formado para significar "a formatação é permitida"; você simplesmente deixa o atributo de fora. (O padrão para um atributo ausente é o padrão booleano do OOXML, true, e esses atributos têm nomes tais que "true" significa que a edição correspondente é permitida.)

Diagrama da regra de codificação sheetProtection XLSX do HotXLS no Delphi em que um atributo omitido permite a ação e attr=0 a proíbe, contrastando uma linha gravada na mão com a saída mínima só-de-proibição do writer
Uma ação permitida não contribui com atributo nenhum; só as ações proibidas aparecem como attr=0

O writer do HotXLS espelha isso exatamente. Ele emite sheet="1" para ligar a proteção, depois percorre o conjunto de opções e grava attr="0" só para as opções que você definiu como False. Ações permitidas não contribuem com nada para a saída. Assim, o workbook da seção anterior serializa para algo assim, carregando só as ações proibidas mais o hash da senha:

// Saída conceitual para o snippet acima (atributos omitidos por brevidade):
// <sheetProtection sheet="1"
//   formatCells="0" formatColumns="0" formatRows="0"
//   insertRows="0" deleteRows="0"
//   password="...4-hex..."/>
// Note o que NÃO está lá: sem sort, sem autoFilter, sem selectLockedCells.
// A ausência deles é exatamente o que diz ao Excel que essas ações seguem permitidas.

Se você esperava ver todos os atributos escritos, isso parece esparso, quase errado. Está correto. Um arquivo que listasse sort="1" e autoFilter="1" significaria a mesma coisa para um leitor em conformidade, mas o próprio Excel grava a forma mínima só-de-proibição, e acompanhá-lo mantém os diffs pequenos e os round-trips sem surpresa. Os atributos objects e scenarios seguem a regra idêntica: são permitidos por padrão, então só aparecem como "0" quando você os proíbe, o inverso de um objects="1" scenarios="1" gravado na mão

Ler a proteção de volta: fidelidade no round-trip

Um modelo de permissões que você consegue gravar mas não ler é uma porta de mão única, e o sintoma usual é um ciclo de abrir-editar-salvar que silenciosamente amplia as permissões. O HotXLS evita isso. Quando o ParseWorksheetXml encontra um elemento <sheetProtection>, ele marca a planilha como protegida, captura o hash da senha se presente, e então decodifica cada atributo por ação de volta para AllowOption usando a mesma convenção ao contrário: um atributo presente e igual a "0" proíbe a ação; um atributo ausente deixa a opção no padrão permitido

var
  wb: TXLSXWorkbook;
  sh: TXLSXWorksheet;
begin
  wb := TXLSXWorkbook.Create;
  try
    wb.Open('protection.xlsx');
    sh := wb.Sheets[1];                  // as planilhas XLSX são baseadas em 1
    if sh.IsProtected then
    begin
      Writeln('Protected; password hash present: ',
        sh.SheetProtectHash <> '');
      Writeln('Sort allowed:       ', sh.AllowOption[xlsxSpoSort]);
      Writeln('AutoFilter allowed: ', sh.AllowOption[xlsxSpoAutoFilter]);
      Writeln('FormatCells allowed:', sh.AllowOption[xlsxSpoFormatCells]);
    end;
  finally
    wb.Free;
  end;
end;

Carregue o arquivo que o writer produziu e você recebe Sort e AutoFilter de volta como True, FormatCells como False — o conjunto que você salvou, intacto. Essa simetria é o ponto central: edite uma célula em uma planilha protegida com permissões parciais e salve de novo, e as quatorze permissões que você não tocou sobrevivem em vez de colapsar de volta para um padrão tudo-ou-nada

Notas práticas e limites

Algumas coisas que valem saber antes de ligar isto num pipeline de relatórios:

  • A senha é fraca por design. A proteção de planilha XLSX armazena um hash legado de 16 bits (o mesmo que o Excel usa há décadas), mantido aqui por interoperabilidade. Ele desencoraja edições acidentais; não resiste a um atacante. Não o trate como guardião de segredos. Para proteção de verdade, criptografe o workbook
  • Definir opções antes de proteger é válido. O AllowOption pode ser atribuído esteja a planilha protegida ou não; as alternâncias simplesmente descrevem o que a proteção vai permitir assim que o Protect estiver em efeito. O UnProtect limpa o estado protegido e o hash, mas deixa seu conjunto de opções no lugar para a próxima vez
  • A semântica de células bloqueadas continua valendo. A proteção só bloqueia edições em células cujo atributo Locked está definido (o padrão do workbook). Deixar uma região de entrada editável é trabalho do estilo de célula, não uma opção de proteção; as duas camadas se combinam do mesmo jeito que no Excel
  • Este é o motor XLSX. O modelo de opções espelha as propriedades Allow* mais antigas do motor XLS, mas os nomes de enum e propriedade aqui (xlsxSpo*, AllowOption) pertencem ao TXLSXWorksheet no lxHandleX. Se você também controla o layout de impressão nas mesmas planilhas, o passo a passo de proteção e configuração de página cobre como essas configurações convivem com áreas de impressão e cabeçalhos, e validação de dados, AutoFilter e tabelas combina naturalmente com deixar o xlsxSpoAutoFilter aberto num relatório bloqueado

O modelo de proteção refinado e o resto do motor de leitura e escrita XLSX vêm no HotXLS Delphi Component para Delphi e C++Builder; a página do produto carrega a API completa de planilhas, incluindo a referência completa das opções de proteção