Fwmsexcelxlsx Generator

FwMsExcelXlsx Generator

Visão geral

FwMsExcelXlsx é a classe de framework recomendada para gerar planilhas Excel .xlsx nativas no Protheus. Tem a mesma API básica da família FWMsExcel (AddWorkSheet, AddTable, AddColumn, AddRow, Activate, GetXMLFile), mas o arquivo é montado pela printer.exe do AppServer, o que elimina o aviso de "formato e extensão não correspondem" do Excel.

Este repositório é de customização: todo código gerado é User Function (pública) com Static Function para os auxiliares. Function é proibido.

Qual classe usar — regra de decisão

FWMsExcelEx e FWMsExcel são legadas (geram XML Spreadsheet 2003, .xml). Não as use por iniciativa própria. Se o pedido citar FWMsExcelEx (ou grafias como FWMsExcelExv) sem dizer que quer a versão antiga, avise que a classe é legada, proponha FwMsExcelXlsx e só siga com a legada se o usuário confirmar.

Não use esta skill para relatórios impressos (TReport/Smart View) nem para importar planilhas.

Pré-requisitos do ambiente

Todo fonte gerado deve verificar a printer.exe com PrinterVersion():fromServer() antes de montar a planilha e, se não atender, informar o requisito ao usuário em vez de deixar a exceção estourar.

Ciclo de vida

New()
 └─ [SetWriteinFile(.T.) | SetWriteinDB(.T.)]   // opcional, grandes volumes, ANTES de qualquer AddRow
 └─ [SetFont / SetFontSize / SetBold ...]        // opcional, vale para a planilha inteira
 └─ para cada aba (uma de cada vez):
      AddWorkSheet(cAba)
      AddTable(cAba, cTabela)
      AddColumn(cAba, cTabela, cTitulo, nAlign, nFormat, lTotal, cPicture)   // N vezes
      AddRow(cAba, cTabela, aLinha)                                           // N vezes
Activate()
GetXMLFile(cArquivo.xlsx)      // grava no servidor
DeActivate()  +  FreeObj(oExcel)

Assinaturas completas: references/fwmsexcelxlsx-api-reference.md.

Workflow de geração

1. Levante o requisito: tabela(s), filtros, colunas, totais, número de abas, volume esperado e onde a rotina roda (menu SmartClient, WebApp ou job/schedule). Se o usuário pedir cores ou destaque por célula, explique que a FwMsExcelXlsx só tem fonte global e ofereça uma coluna de "situação" (ver exemplo 2) ou a FwPrinterXlsx.
2. Valide o dicionário: confirme que cada campo existe na tabela de origem (SX3) antes de usá-lo; títulos via FWX3Titulo(), tipo/tamanho via TamSX3(). Nunca digite títulos de coluna à mão quando o campo é do SX3.
3. Monte a consulta com FWExecStatement e parâmetros ? (valores via SetString/SetDate/SetNumeric, na ordem dos ?): RetSqlName() para o nome físico, filtro de filial com xFilial(), D_E_L_E_T_ = ' ' em todas as tabelas do FROM/JOIN, ChangeQuery() e TCSetField() para datas e numéricos. Feche o alias e chame oExec:Destroy() ao final.
4. Verifique a printer.exe antes de criar o objeto.
5. Descreva as colunas uma única vez (aCols) e use o mesmo array para AddColumn e para montar cada aLinha.
6. Escolha o modo de gravação: memória (padrão) para volumes pequenos e médios; SetWriteinFile(.T.) para grandes volumes; SetWriteinDB(.T.) como alternativa quando o DBAccess for ≥ 22.1.1.0. Não combine os dois.
7. Gere seguindo o ciclo de vida, uma aba completa por vez.
8. Grave no servidor e entregue: GetXMLFile() em pasta do servidor (MV_XDIRXLS, padrão \spool\); depois CpyS2T() + ShellExecute() no SmartClient, CpyS2TW() no WebApp (GetRemoteType() == 5) ou apenas FWLogMsg() em job (IsBlind()).
9. Libere recursos: DeActivate(), FreeObj(oExcel), (cAlias)->(DbCloseArea()), oExec:Destroy().
10. Salve o fonte em Windows-1252 (CP1252) e compile. O compilador do Protheus não aceita UTF-8: acentos em strings e comentários ficam corrompidos. Em Linux/macOS, converta com iconv -f UTF-8 -t WINDOWS-1252 origem.prw > destino.prw; no VS Code, use "Save with Encoding → Western (Windows 1252)".

Template base reutilizável e 4 exemplos completos: references/fwmsexcelxlsx-examples.md. Leia esse arquivo sempre antes de gerar código.

Boas práticas obrigatórias nos fontes gerados

• User Function para a rotina e Static Function para auxiliares. Em .prw, nome da User Function com no máximo 8 caracteres (o U_ ocupa 2 dos 10 significativos); em .tlpp nomes longos são permitidos.
• Includes em minúsculas: #include "totvs.ch"; em TLPP, #include "tlpp-core.th" primeiro.
• Bloco /*/{Protheus.doc} em cada função; notação húngara; todos os Local no topo.
• Sem IIf() (use If/Else/EndIf), sem ConOut() (use FWLogMsg), sem concatenar entrada do usuário em SQL (use FWExecStatement com ?), sem SuperGetMV() dentro de laço (leia antes), sem UI quando IsBlind().
• #define para alinhamento, formato e posições de array.
• Pasta do servidor vinda de parâmetro (SuperGetMV("MV_XDIRXLS", .F., "\spool\")) e nome de arquivo único (prefixo + data + hora + thread).