Referência de recursos do Excel

Além das funções, um ambiente pode conter dez tipos de artefacto do Excel — gráficos, tabelas, diálogos, formatação e mais — que o agent aplica em direto a partir da configuração. Esta página cobre os dez, em profundidade para os três mais inovadores (gráficos, vistas de grelha, diálogos) e de forma direta para o resto.

O separador Resources de cada ambiente guarda mais do que funções. Dez tipos de recurso — Charts, Tables & Pivots, Dialogs, Conditional formatting, Named ranges, Comments, Protections, Data validations, Image inserts e Worksheet events — permitem-te moldar o aspeto e o comportamento do Excel sem escreveres uma única linha de Office.js.

Apenas configuração, aplicado em direto — sem manifesto, sem redeploy

Os dez são recursos passthrough: o dashboard guarda a configuração, essa configuração viaja pelo mesmo canal de snapshot que as tuas funções, e o connxl-agent aplica-a diretamente (desenha o gráfico, escreve o comentário, regista o handler do evento, e por aí adiante) em vez de a executar como uma função. Nenhum deles toca no manifesto do Office, por isso uma alteração fica em direto na próxima vez que um utilizador abrir o painel de tarefas — sem redeploy, sem repetir o sideload. Guarda uma versão em direto do ambiente para publicar, exatamente como uma alteração de função.

Charts

Um gráfico do Excel desenhado sobre a saída derramada de uma função com forma de matriz (saída Table, Row ou JSON — vê Referência de funções). Recorre a um gráfico quando quiseres a mesma visualização que um utilizador construiria à mão a partir de um derrame, atualizada a cada inserção.

Configura-se a partir do separador Resources → Charts: escolhe a função de origem, um tipo de gráfico (ColumnClustered, ColumnStacked, BarClustered, BarStacked, Line, LineMarkers, Pie, Doughnut, Area ou XYScatter), e opcionalmente um título, um interruptor de legenda, e títulos de eixo de categoria/valor.

Field	Type	Description
`series`Optional	`repetível`	Deixa em branco para que o agent derive as séries automaticamente a partir do intervalo derramado. Ou adiciona séries explícitas, cada uma a nomear uma coluna `valuesFrom` (e uma cor fixa opcional) — para uma fonte em modo tabela com colunas declaradas, o construtor oferece um seletor sobre os cabeçalhos reais.

Séries que conhecem a forma

Se a função de origem declarar as suas colunas de saída, o seletor de séries mostra os cabeçalhos reais (colunas numéricas primeiro) e a pré-visualização desenha as séries realmente resolvidas — uma série que nomeia uma coluna que já não existe aparece riscada na pré-visualização e seria descartada silenciosamente pelo agent, para detetares o desvio antes de publicar.

No Excel: abrir o recurso a partir do cartão incorporado do painel de tarefas derrama a função de origem e depois desenha o gráfico sobre o resultado como um objeto de gráfico real do Excel (não uma imagem) — o utilizador pode movê-lo, redimensioná-lo e restilizá-lo depois como qualquer outro gráfico.

Grid views (Tables & PivotTables)

Transforma a saída derramada de uma função matriz numa Table ou PivotTable real do Excel, em vez de um simples derrame de matriz dinâmica. É o separador "Tables & Pivots" de Resources.

Configura-se: escolhe a função de origem (apenas com forma de matriz), depois uma lista ordenada de Arguments — os valores posicionais passados à função quando é derramada (p. ex. "West", 10) — seguida de opções específicas do tipo:

Field	Type	Description
`kind`Required	`table \| pivot`	Em que objeto do Excel o derrame é envolvido.
`table.style / table.hasHeaders`Optional	`string / bool`	Apenas tipo table — o nome do estilo de tabela do Excel e se a primeira linha derramada é uma linha de cabeçalho.
`pivot.rows / pivot.columns`Optional	`string[]`	Apenas tipo pivot — nomes de campo que orientam as hierarquias de linhas e colunas.
`pivot.values`Optional	`{ field, aggregation }[]`	Apenas tipo pivot — um ou mais campos de valor, cada um com uma agregação: sum, count, average, max, min, product, countNumbers, stdDev ou variance.
`pivot.refreshOnOpen`Optional	`bool`	Apenas tipo pivot — volta a obter os dados de origem sempre que o livro é aberto.

Quando a função de origem declara as suas colunas de saída, os seletores de linhas/colunas/valor são apresentados como chips selecionáveis sobre os cabeçalhos reais (um campo guardado e já desatualizado aparece como um chip de perigo removível) em vez de texto livre.

Uma Table a partir de um derrame é uma fotografia estática

Envolver um derrame numa Table substitui a fórmula de matriz dinâmica subjacente pelos seus valores — uma restrição rígida do Office.js, não uma limitação do ConnXL. Não se atualiza em direto se os dados de origem mudarem por si só; volta a inseri-la (ou associa um worksheet event, mais adiante nesta página, para a reaplicar) para a atualizar.

No Excel: ao clicar na grid view no painel de tarefas, a função de origem é derramada com os seus argumentos configurados e depois o resultado é envolvido — uma Table via worksheet.tables.add, ou uma PivotTable via workbook.pivotTables.add com a disposição de linhas/colunas/valores configurada.

Dialogs

Um lançador baseado em formulário para uma função que recebe vários parâmetros. Em vez de pedir a um utilizador para escrever =NAMESPACE.MODULE.FN(v1, v2, v3) à mão, um dialog abre um formulário com etiquetas e compõe a chamada por ele.

Configura-se: escolhe uma função de origem — só são oferecidas funções com parâmetros. Ao escolher uma, a lista de campos do dialog é gerada automaticamente a partir dos parâmetros dessa função, por ordem (chave, etiqueta, marcador de posição opcional); a chave de cada campo está restrita a um dos próprios nomes de parâmetro da função, e só os parâmetros opcionais no final podem ser removidos da lista de campos — tudo o resto é rejeitado, tanto no construtor como na API, para que um dialog nunca possa desviar-se da assinatura da sua função.

Um dialog abre uma janela separada, não um formulário inline

O dialog não faz parte do DOM próprio do painel de tarefas. Ao abri-lo (a partir do cartão Dialogs incorporado no painel de tarefas, ou de um botão do friso ligado a ele) é lançada uma janela de Office Dialog genuinamente separada via Office.context.ui.displayDialogAsync. Apresenta um <input> com etiqueta por cada campo configurado. Ao submeter, a janela devolve os valores recolhidos ao painel de tarefas (messageParent), que compõe e insere a fórmula — argumentos pela mesma ordem que a lista de campos:

fórmula compostaexcel

=NAMESPACE.MODULE.FN(v1, v2, v3)

Um dialog não precisa de nenhuma entrada no manifesto — a janela é servida a partir da mesma origem que o host do agent, o que já satisfaz a regra de mesma origem da Office Dialog API, por isso não há nada a acrescentar a <AppDomains> nem redeploy.

Conditional formatting

Regras de valor de célula configuradas no dashboard e aplicadas sobre o intervalo derramado de uma função matriz — para destacar limiares, valores atípicos ou categorias sem que um utilizador configure à mão a caixa de formatação condicional do Excel.

Configura-se: escolhe a função de origem, depois adiciona uma ou mais regras, cada uma com um operador (greaterThan, lessThan, between, equalTo, notEqualTo, greaterThanOrEqual, lessThanOrEqual) comparado com um limite de fórmula (dois para between), com uma cor de preenchimento e/ou de tipo de letra opcionais. As regras aplicam-se por ordem — a primeira correspondência vence. A pré-visualização do construtor é um depurador de regras: deriva valores de amostra a partir dos próprios limites numéricos das tuas regras e tinge cada célula de amostra segundo a primeira regra que corresponde (um limite de fórmula fica por avaliar, marcado com um selo ƒ).

No Excel: aplicado ao mesmo intervalo onde a função de origem se derrama, usando as regras reais de formatação condicional por valor de célula do Excel — reavalia-se à medida que os valores subjacentes mudam, não é uma pintura de uma só vez.

Named ranges

Associa um nome definido do Excel à saída derramada de uma função matriz, para que o intervalo possa ser referenciado pelo nome — noutras fórmulas, ou através da Caixa de nomes — em vez de por coordenadas de célula.

Configura-se: escolhe a função de origem, um âmbito (workbook ou worksheet), e um comentário opcional sobre o nome definido.

No Excel: a função de origem é derramada e depois o intervalo resultante é nomeado como um nome definido real do Excel (workbook.names.add ou worksheet.names.add) — utilizável de imediato em qualquer outra fórmula do livro.

Comments

Um comentário de célula estático (nota), ancorado a uma célula concreta — ao contrário dos recursos acima, um comentário não provém de uma função; é apenas texto sobre uma célula.

Configura-se: um endereço de destino (opcionalmente qualificado por folha, p. ex. Sheet1!B2) e o texto do comentário.

No Excel: escrito na célula de destino através da API de comentários do Office quando o agent aplica o recurso.

Protections

Bloqueia uma folha de cálculo deixando disponível um conjunto escolhido de ações — útil para uma folha de relatório publicada que não queres que os utilizadores finais editem, permitindo-lhes ainda ordená-la ou filtrá-la.

Configura-se: uma folha de destino (em branco aplica-se à folha ativa no momento em que o recurso é aplicado), e nove interruptores allow-*: formatar células, formatar colunas, formatar linhas, inserir colunas, inserir linhas, eliminar colunas, eliminar linhas, ordenar, e AutoFilter.

Cada permissão viaja explicitamente

Os nove sinalizadores são sempre enviados ao agent, não só os que ativaste — por isso uma permissão desmarcada fica ativamente bloqueada em vez de ficar no que o Excel definiria por defeito.

No Excel: aplicado como uma proteção de folha (WorksheetProtectionOptions do Excel) com as permissões escolhidas deixadas abertas.

Data validations

Uma regra de validação de dados do Excel real e editável sobre um intervalo de destino — não uma verificação pontual, mas uma restrição contínua sobre o que um utilizador pode escrever nessas células.

Configura-se: um endereço de destino (uma única célula ou um intervalo, opcionalmente qualificado por folha), e um tipo:

Field	Type	Description
`list`Optional	`tipo`	Uma lista pendente de valores explícitos, com um interruptor para a seta pendente na célula.
`wholeNumber / decimal / date / textLength`Optional	`tipo`	Uma regra de comparação: escolhe um operador (between, notBetween, equalTo, notEqualTo, greaterThan, lessThan, greaterThanOrEqualTo, lessThanOrEqualTo) e um ou dois limites de fórmula (dois só para os operadores da família between).
`custom`Optional	`tipo`	Uma fórmula de validação arbitrária.

No Excel: aplicado via range.dataValidation.rule — o utilizador vê a mesma validação na célula (e a seta pendente, para uma list) como se a tivesse configurado ele próprio na caixa de validação de dados do Excel.

Image inserts

Coloca uma imagem da organização previamente carregada — da mesma biblioteca Assets → Images usada no resto do dashboard, partilhada entre todos os suplementos e ambientes da organização — na grelha da folha de cálculo, ancorada a uma célula.

Configura-se: escolhe uma imagem da organização, um endereço de célula de âncora (o seu canto superior esquerdo fica aí), e um fator de escala relativo ao tamanho natural da imagem.

No Excel: o agent obtém a imagem através do proxy de imagens do backend no momento da aplicação, e insere-a na célula de âncora. Se a imagem referenciada for depois eliminada da biblioteca Assets, a inserção é ignorada com elegância em vez de falhar todo o snapshot.

Worksheet events

Regista um handler de evento de folha que dispara uma ação configurada automaticamente — sem ser necessário nenhum clique do utilizador. É isto que faz com que os outros recursos passthrough pareçam "em direto".

Configura-se: um gatilho (onChanged ou onSelectionChanged), depois uma ação:

Reapply resource — nomeia um tipo de destino (chart ou gridView) e um id; quando o gatilho dispara, o agent reaplica esse recurso — redesenhando o gráfico, ou voltando a derramar e a envolver a grid view, sobre os seus dados de origem mais recentes.
Execute function — nomeia um id de função; quando o gatilho dispara, o agent executa essa função pelos seus efeitos secundários (p. ex. escrever nalgum lado), não por um valor devolvido a uma célula.

No Excel: o agent regista o handler com worksheet.onChanged ou worksheet.onSelectionChanged do Office.js quando o painel de tarefas abre. Combina isto com uma grid view (acima) que não tenha a sua própria via de atualização em direto — um evento onChanged é a forma habitual de manter uma Table nascida de um derrame sincronizada com as alterações a montante.

Promover recursos entre ambientes

Cada tipo de recurso acima segue a mesma regra estrutural que as funções: só pode ser criado ou editado no ambiente de origem (Development). Qualquer outro ambiente é um destino de promoção — levas um chart, uma grid view, um dialog ou qualquer um dos outros para um ambiente a jusante com Promote, a mesma ação que usarias para uma função ou uma ligação, a partir da página Versions do ambiente.

Nada aqui depende do manifesto

Como nenhum destes dez recursos toca no manifesto do Office, promovê-los ou editá-los é sempre uma alteração apenas de configuração — o agent do ambiente recetor recolhe-a através do seu canal de configuração existente, sem redeploy e sem repetir o sideload, exatamente como uma função.