Office Dev Scripts

Dê a sua opinião sobre a experiência de download do PDF.
Documentação de scripts do Office

Use Scripts do Office no Excel para automatizar suas tarefas comuns. Explore os artigos
a seguir para aprender como criar e editar scripts do Office, e comece a automatizar
ainda hoje.
Visão Geral
Saiba mais sobre os componentes dos Scripts do Office no Excel: o
Gravador de Ações e o Editor de Código.
Introdução
Crie e formate uma tabela com scripts do Office.
Integre-se com o Power Automate

Conecte o Excel a todo o fluxo de trabalho automatizado.
Exemplos
Experimente esses scripts e fluxos do Power Automate para ver scripts do Office em
ação.
Converter arquivos CSV em pastas de trabalho do Excel
Definir formatação condicional para comparações entre colunas

Email imagens de um gráfico e uma tabela
Outros recursos
Use os recursos a seguir para saber mais sobre as APIs de Scripts do Office, fazer
perguntas sobre scripts do Office ou solicitar recursos para Scripts do Office.
Scripts do Office
Referência da API
Fundamentos de script
Mais scripts de exemplo
Como compartilhar scripts
Configurações do administrador
Tire dúvidas
Scripts do Office no Excel
Artigo • 27/01/2024
Os Scripts do Office no Excel permitem automatizar suas tarefas diárias. Use o Gravador
de Ações para transformar etapas manuais em scripts reutilizáveis. Edite esses scripts ou
crie novos com o Editor de Código. Deixe que outras pessoas na pasta de trabalho
executem esses scripts com um único botão. Em seguida, compartilhe-os com colegas
de trabalho para que todos possam melhorar seu fluxo de trabalho.
Esta série de documentos ensina como usar essas ferramentas. Você encontrará uma
riqueza de exemplos que abrangem diferentes cenários do Excel. Use os tutoriais para
se apresentar ao Gravador de Ações e ao Editor de Código. Elas fornecem diretrizes
passo a passo sobre como registrar suas ações frequentes do Excel, editar esses scripts e
criar novos scripts do zero.
https://www.microsoft.com/pt-br/videoplayer/embed/RE4qdFF?
postJsllMsg=true&autoCaptions=pt-br
Quando usar Scripts do Office

Os scripts permitem gravar e reproduzir suas ações do Excel em diferentes pastas de
trabalho e planilhas. Se você perceber que vive fazendo as mesmas coisas o tempo
inteiro, experimente transformar todo esse trabalho em um Script do Office fácil de
executar. Execute seu script com um botão no Excel ou combine-o com o Power
Automate para simplificar todo o fluxo de trabalho.
Como exemplo, imagine no início de cada dia de trabalho que você abre um arquivo
.csv de um site de contabilidade no Excel. Então você gasta alguns minutos excluindo
colunas desnecessárias, formatando uma tabela, adicionando fórmulas e criando uma
tabela dinâmica em uma nova planilha. As ações repetidas diariamente podem ser
gravadas uma vez com o Gravador de ações. A partir daí, a execução do script cuidará
da sua conversão .csv. Além de remover o risco de esquecer as etapas, você poderá
compartilhar seu processo com outras pessoas sem precisar ensinar nada a elas. Os
Scripts do Office permitem que você automatize suas tarefas comuns para que você e
seu local de trabalho possam ser mais eficientes e produtivos.
Gravador de ações
O Gravador de Ações registra as ações que você executa no Excel e as salva na forma de
um script. Com o Gravador de ações em execução, você pode capturar as ações do Excel
enquanto edita células, altera a formatação e cria tabelas. O script resultante pode ser
executado em outras planilhas e pastas de trabalho para recriar suas ações originais.
Mais informações sobre o Gravador de Ações podem ser encontradas no artigo

Registrar suas ações como Script do Office .
Editor de códigos
Use o Editor de Código para editar scripts gravados com o Gravador de Ação ou fazer
um script novo. Essa ferramenta permite ajustar e personalizar scripts para atender
melhor às suas necessidades exatas. Você também pode adicionar lógica e
funcionalidade que não são acessíveis de forma direta pela interface do usuário do
Excel, como instruções condicionais (se/senão) e loops.
 Dica
O Gravador de Ações tem um botão Copiar como código para registrar as ações
no código do script sem salvar o script inteiro.
Nossos tutoriais fornecem uma maneira orientada e estruturada de aprender as
funcionalidades dos Scripts do Office. Depois de concluir os tutoriais, leia Fundamentos
para Scripts do Office no Excel para saber mais sobre o Editor de Código e como
escrever e editar seus próprios scripts. Para informações adicionais sobre o Editor de
Código e como seu código de script é interpretado, leia Ambiente do Editor de Código
de Scripts do Office.
Compartilhar Scripts do Office

Os Scripts do Office podem ser compartilhados com outros usuários em sua
organização. Quando você compartilha um script em uma pasta de trabalho
compartilhada, os membros da equipe com acesso à pasta de trabalho também podem
exibir e executar seu script. Para obter mais detalhes sobre o compartilhamento e o
compartilhamento de scripts, consulte Compartilhamento de scripts do Office no
Excel .
Adicione botões que executam scripts para ajudar seus colegas a descobrir suas
soluções valiosas e permitir que eles executem scripts diretamente da pasta de trabalho.
Saiba mais sobre os botões de script em Executar Scripts do Office com botões.
７ Observação
Saiba mais sobre como os scripts são armazenados no seu OneDrive em

Armazenamento de arquivos e propriedade de Scripts do Office.
Agendar scripts para serem executados

automaticamente
Defina seus scripts para serem executados todos os dias e mantenha sua pasta de
trabalho atualizada. Depois de ter seu script, você pode defini-lo para ser executado
automaticamente na pasta de trabalho em intervalos regulares. Um fluxo do Power
Automate nos bastidores garante que tudo aconteça, mesmo quando a pasta de
trabalho é fechada.
Para agendar um script, abra o script no Editor de Código. Abra a seção Agendamento
de script e conclua o processo de entrada no Excel por meio do Power Automate.
Defina com que frequência deseja que o script seja executado e selecione Criar fluxo
para começar.
Conectar Scripts do Office com o Power

Automate
O Power Automate é um serviço que ajuda você a criar fluxos de trabalho
automatizados entre vários aplicativos e serviços. Os scripts do Office podem ser usados
nesses fluxos de trabalho, permitindo que você controle seus scripts fora da pasta de
trabalho. Você pode executar seus scripts em um cronograma, dispará-los em resposta a
emails e muito mais. Visite o tutorial Executar Scripts do Office com o Power Automate
para aprender como se conectar a esses serviços de automação.
Próximas etapas
Conclua o tutorial Scripts do Office no Excel para saber como criar seu primeiro script.
Confira também
Fundamentos para scripts do Office no Excel
Referência da API de scripts do Office
Limites e requisitos da plataforma com scripts do Office
Configurações dos scripts do Office no M365
Compartilhamento de Scripts do Office no Excel
６ Colaborar conosco no
GitHub Comentários do Office Scripts
O Office Scripts é um projeto código aberto.
A fonte deste conteúdo pode
Selecione um link para fornecer
ser encontrada no GitHub, onde
comentários:
você também pode criar e
revisar problemas e solicitações
 Abrir um problema de documentação
de pull. Para obter mais
informações, confira o nosso
 Fornecer comentários sobre o produto
guia para colaboradores.
Tutorial: Criar e formatar uma tabela do
Excel
Artigo • 17/11/2023
Este tutorial ensina os conceitos básicos de gravação, edição e escrita de um Script do

Office para Excel. Você gravará um script que aplicará uma determinada formatação a
uma planilha de registro de vendas. Depois, você editará o script gravado para aplicar
outras formatações, criar e classificar uma tabela. Este padrão de registro e edição é
uma importante ferramenta para ver como suas ações no Excel são parecidas com um
código.
Pré-requisitos
Você precisará de acesso aos Scripts do Office para este tutorial. Examine o suporte da
Plataforma se a guia Automatizar não aparecer.
） Importante
Este tutorial é destinado a pessoas com conhecimento básico ou de nível

intermediário de JavaScript ou TypeScript. Se você é novo no JavaScript,
recomendamos começar com o tutorial da Mozilla sobre JavaScript . Visite o
ambiente do Editor de Código do Scripts do Office para saber mais sobre o
ambiente de script.
Adicione dados e grave um script básico

Primeiro, você precisará de alguns dados e um pequeno script inicial.
1. Crie uma nova pasta de trabalho do Excel.
2. Copie os seguintes dados de vendas de frutas e cole-os na planilha, começando na

célula A1.
Fruta 2018 2019
Laranjas 1000 1200
Limões 800 900
Limões-galego 600 500

Fruta 2018 2019
Toranjas 900 700
3. Abra a guia Automação. Se você não vir a guia Automação, verifique o excedente
da faixa de opções selecionando a seta suspensa. Se ainda não estiver lá, siga o
conselho do artigo Solução de Problemas de Scripts do Office .
4. Selecione o botão Gravar Ações.
5. Selecione as células A2:C2 (a linha "Laranjas") e defina a cor de preenchimento

como laranja.
6. Interrompa a gravação selecionando o botão Parar.
Sua planilha deve ficar assim (não se preocupe se a cor for diferente):
Edite um script existente

O script anterior coloriu a linha "Laranjas" para ficar laranja. Adicione uma linha amarela
para os "Limões".
1. No painel, agora aberto, Detalhes, selecione o botão Editar.
2. Você deve ver algo semelhante a este código:
TypeScript
function main(workbook: ExcelScript.Workbook) {

// Set fill color to FFC000 for range Sheet1!A2:C2
let selectedSheet = workbook.getActiveWorksheet();
selectedSheet.getRange("A2:C2").getFormat().getFill().setColor("FFC000"
);
}
Este código recebe a planilha atual da pasta de trabalho. Depois, defina a cor de
preenchimento do intervalo A2:C2.
Os intervalos são parte fundamental dos Scripts do Office no Excel. Um intervalo é
um bloco retangular e contíguo de células que contém valores, fórmula e
formatação. Eles são a estrutura básica das células através da qual você executará
a maioria das tarefas de script.
3. Adicione a seguinte linha no final do script (entre onde color está definido e o
encerramento } ):
TypeScript
selectedSheet.getRange("A3:C3").getFormat().getFill().setColor("yellow"
);
4. Teste o script selecionando Executar. Sua pasta de trabalho já deve ter esta
aparência:
Criar uma tabela

Em seguida, converta esses dados de vendas de frutas em uma tabela. Você continuará
modificando o primeiro script para todo o tutorial.
1. Adicione a seguinte linha no final do script (antes do encerramento } ):
TypeScript
let table = selectedSheet.addTable("A1:C5", true);
2. Essa chamada retorna um Table objeto. Use essa tabela para classificar os dados.
Classifique os dados em ordem crescente com base nos valores na coluna "Fruit".
Adicione a seguinte linha assim que criar a tabela:
TypeScript
table.getSort().apply([{ key: 0, ascending: true }]);
Seu script deve ter esta aparência:

TypeScript

// Set fill color to FFC000 for range Sheet1!A2:C2
selectedSheet.getRange("A2:C2").getFormat().getFill().setColor("FFC000"
);
selectedSheet.getRange("A3:C3").getFormat().getFill().setColor("yellow"
);
let table = selectedSheet.addTable("A1:C5", true);
table.getSort().apply([{ key: 0, ascending: true }]);
}
As tabelas possuem um objeto TableSort , acessado por meio do método

Table.getSort . Você pode aplicar critérios de classificação a esse objeto. O apply
método utiliza uma matriz de SortField objetos. Nesse caso, você só tem um
critério de classificação, portanto, você só usa um SortField . key: 0 define a
coluna com os valores que determinam a classificação como "0" (que nesse caso, é
a primeira coluna na tabela A ). ascending: true classifica os dados em ordem
crescente (em vez de ordem decrescente).
3. Execute o script. Você deve visualizar uma tabela como esta:
７ Observação
Se você executar novamente o script, receberá um erro. Isso ocorre porque

você não pode criar uma tabela em cima de outra tabela. No entanto, você
pode executar o script em uma planilha ou pasta de trabalho diferente.
Reexecute o script
1. Crie uma nova planilha na pasta de trabalho atual.
2. Copie os dados das frutas do início do tutorial e cole-os na nova planilha,
começando na célula A1.
3. Execute o script.
Próximas etapas
Tutorial completo: limpar e normalizar dados da pasta de trabalho do Excel. Ele ensina
como ler dados de uma pasta de trabalho com um script do Office.
Tutorial: Limpar e normalizar dados da
pasta de trabalho do Excel
Artigo • 29/11/2023
Este tutorial ensina como ler dados de uma pasta de trabalho com um Script do Office
para Excel. Você estará escrevendo um novo script que formatará um extrato bancário e
normalizará os dados desse extrato. Como parte desta limpeza de dados, seu script lerá
os valores das células de transação, aplicará uma fórmula simples a cada valor e gravará
a resposta resultante na pasta de trabalho. A leitura os dados da pasta de trabalho
permite a automatização de alguns dos seus processos de tomada de decisão no script.
 Dica
Se você for novo em Scripts do Office, recomendamos começar com Tutorial: Criar
e formatar uma tabela do Excel. Os Scripts do Office usam TypeScript e este
tutorial se destina a pessoas com conhecimento de nível iniciante a intermediário
em JavaScript ou TypeScript. Se você é novo no JavaScript, recomendamos começar
com o tutorial da Mozilla sobre JavaScript .
Pré-requisitos
Você precisará de acesso aos Scripts do Office para este tutorial. Examine o suporte da
Plataforma se a guia Automatizar não aparecer.
Ler uma célula

Os scripts feitos com o Gravador de Ação só podem gravar informações na pasta de
trabalho. Com o Editor de Códigos, é possível editar e criar scripts que também leem
dados de uma pasta de trabalho.
Comece fazendo um script que lê dados e age com base no que foi lido. Ao longo do
tutorial, você trabalhará com uma instrução bancária de exemplo. Essa instrução é um
relatório combinado de verificação de crédito. Infelizmente, o banco informa que o
saldo muda de forma diferente. A declaração de verificação exibe o rendimento como
crédito positivo e custos como débito negativo. O demonstrativo de crédito faz o
oposto.
Ao longo do restante do tutorial, você normalizará esses dados usando um script.
Primeiro, você precisa ler dados da pasta de trabalho.
1. Crie uma nova planilha na pasta de trabalho usada para o resto do tutorial.
2. Copie os seguintes dados e cole-os na nova planilha, começando na célula A1.
ﾉ Expand table
Data Conta Descrição Débito Crédito
10/10/2019 Verificando Vinícola Coho -20.05
11/10/2019 Crédito A Companhia Telefônica 99.95
13/10/2019 Crédito Vinícola Coho 154.43
15/10/2019 Verificando Depósito externo 1000
20/10/2019 Crédito Vinícola Coho – Reembolso -35.45
25/10/2019 Verificando Ideal para sua empresa de produtos -85.64

orgânicos
01/11/2019 Verificando Depósito externo 1000
3. Acesse a guia Automatizar e selecioneNovo Script.
4. Limpe a formatação. Este é um documento financeiro, portanto, faça com que seu
script altere a formatação de número nas colunas Débito e Crédito para mostrar
valores como valores em dólar. Também faça com que o script ajuste a largura da
coluna aos dados.
Substitua o conteúdo do script pelo código a seguir:
TypeScript

// Get the current worksheet.
// Format the range to display numerical dollar amounts.

selectedSheet.getRange("D2:E8").setNumberFormat("$#,##0.00");
// Fit the width of all the used columns to the data.

selectedSheet.getUsedRange().getFormat().autofitColumns();
}
5. Agora leia um valor de uma das colunas de número. Adicione o código a seguir ao
final do script (antes do fechamento } ).
TypeScript
// Get the value of cell D2.

let range = selectedSheet.getRange("D2");
console.log(range.getValues());
7. Você deverá ver [Array[1]] no console. Isso não é um número porque os

intervalos são matrizes bidimensionais de dados. Esse intervalo bidimensional está
sendo registrado diretamente no console. Felizmente, o Editor de Códigos permite
visualizar o conteúdo da matriz.
8. Quando uma matriz bidimensional é registrada no console, ela agrupa os valores

de coluna em cada linha. Expanda o registro da matriz selecionando o triângulo
azul.
9. Expanda o segundo nível da matriz selecionando o triângulo azul recém-revelado.

Agora, você deverá ver isto:
Modificar o valor de uma célula

Agora que seu script pode ler dados, use esses dados para modificar a pasta de
trabalho. Torne o valor da célula D2 positivo com a Math.abs função. O objeto
Matemática contém várias funções às quais seus scripts têm acesso. É possível
encontrar mais informações sobre Math e outros objetos internos Usando objetos
JavaScript internos nos scripts do Office.
1. Use getValue e setValue métodos para alterar o valor da célula. Esses métodos
funcionam em uma única célula. Ao lidar com intervalos de várias células, use
getValues e setValues . Adicione o código a seguir ao final do script.
TypeScript
// Run the `Math.abs` method with the value at D2 and apply that value
back to D2.
let positiveValue = Math.abs(range.getValue() as number);
range.setValue(positiveValue);
７ Observação
Estamos lançando o valor retornado de range.getValue() para um number

usando a palavra-chave as . Isso é necessário porque um intervalo pode ser
cadeias de caracteres, números ou booleanas. Nesta instância, precisamos
explicitamente de um número.
2. O valor da célula D2 agora deverá ser positivo.
Modificar os valores de uma coluna

Agora que você sabe como ler e gravar em uma única célula, você pode generalizar o
script para trabalhar em colunas de débito e crédito inteiras.
1. Remova o código que afeta apenas uma única célula (o código de valor absoluto
anterior), de modo que o script agora se pareça com este:
TypeScript

// Format the range to display numerical dollar amounts.

selectedSheet.getRange("D2:E8").setNumberFormat("$#,##0.00");
// Fit the width of all the used columns to the data.

selectedSheet.getUsedRange().getFormat().autofitColumns();
}
2. Adicione um loop que percorra as linhas nas duas últimas colunas. Para cada
célula, o script define o valor para o valor absoluto do valor atual.
Observe que a matriz que define a localização das células é baseada em zero. Isso
significa que a célula A1 é range[0][0] .
TypeScript
// Get the values of the used range.
let range = selectedSheet.getUsedRange();
let rangeValues = range.getValues();
// Iterate over the fourth and fifth columns and set their values to
their absolute value.
let rowCount = range.getRowCount();
for (let i = 1; i < rowCount; i++) {
// The column at index 3 is column "4" in the worksheet.
if (rangeValues[i][3] != 0) {
let positiveValue = Math.abs(rangeValues[i][3] as number);
selectedSheet.getCell(i, 3).setValue(positiveValue);
}
// The column at index 4 is column "5" in the worksheet.

if (rangeValues[i][4] != 0) {
let positiveValue = Math.abs(rangeValues[i][4] as number);
selectedSheet.getCell(i, 4).setValue(positiveValue);
}
}
Essa parte do script faz várias tarefas importantes. Primeiro, ela obtém os valores e
a contagem de linhas do intervalo usado. Isso permite que o script examine os
valores e saiba quando parar. Segundo, ela reitera através do intervalo usado,
verificando cada célula nas colunas Débito ou Crédito. Por fim, se o valor na célula
não for 0, ele será substituído pelo valor absoluto. O script ignora zeros, para que
você possa deixar as células em branco como estavam.
Sua instrução bancária agora deve ter formatado corretamente números positivos.
Próximas etapas
Abra o Editor de Código e experimente alguns dos nossos Scripts de exemplo para
Scripts do Office no Excel. Você também pode visitar fundamentos para scripts do Office
no Excel para saber mais sobre como criar scripts do Office.
A próxima série de tutoriais de Scripts do Office tem foco na utilização de Scripts do

Office com o Power Automate. Saiba mais sobre as vantagens que combinam as duas
plataformas em Executar Scripts do Office com o Power Automate ou tente Tutorial:
atualize uma planilha de um fluxo do Power Automate para criar um fluxo do Power
Automate que usa um Script do Office.
Tutorial: atualizar uma planilha de um
fluxo do Power Automate
Artigo • 07/12/2023
Este tutorial ensina como executar um Script do Office para Excel por meio do Power
Automate . Você fará um script que atualizará os valores de duas células com a hora
atual. Depois, você fará a conexão desse script a um fluxo do Power Automate acionado
manualmente, para que o script seja executado sempre que um botão no Power
Automate for selecionado. Depois de entender o padrão básico, você pode expandir o
fluxo para incluir outros aplicativos e automatizar ainda mais o seu fluxo de trabalho
diário.
 Dica
e formatar uma tabela do Excel. Os Scripts do Office usam TypeScript e este
tutorial se destina a pessoas com conhecimento de nível iniciante a intermediário
em JavaScript ou TypeScript. Se você é novo no JavaScript, recomendamos começar
com o tutorial da Mozilla sobre JavaScript .
Pré-requisitos
Você precisará de acesso aos Scripts do Office e ao Power Automate para este tutorial.
Examine o suporte da Plataforma se a guia Automatizar não aparecer. As perguntas
frequentes sobre a inscrição do Power Automate têm informações sobre como começar
com o Power Automate.
Preparar a pasta de trabalho

O Power Automate não pode usarreferências
relativascomo Workbook.getActiveWorksheet acessar componentes da pasta de trabalho.
Portanto, você precisa de uma pasta de trabalho e uma planilha com nomes
consistentes que o Power Automate pode referenciar.
1. Crie uma pasta de trabalho intitulada MyWorkbook.
2. Na pasta de trabalho MyWorkbook, crie uma planilha intitulada

TutorialWorksheet.
Criar um Script do Office
2. Substitua o script padrão pelo script abaixo. Esse script adiciona a data e hora
atuais às duas primeiras células da planilha TutorialWorksheet.
TypeScript

// Get the "TutorialWorksheet" worksheet from the workbook.
let worksheet = workbook.getWorksheet("TutorialWorksheet");
// Get the cells at A1 and B1.

let dateRange = worksheet.getRange("A1");
let timeRange = worksheet.getRange("B1");
// Get the current date and time using the JavaScript Date object.
let date = new Date(Date.now());
// Add the date string to A1.

dateRange.setValue(date.toLocaleDateString());
// Add the time string to B1.

timeRange.setValue(date.toLocaleTimeString());
}
3. Renomeie o script como Definir data e hora. Selecione o nome do script para
alterá-lo.
4. Salve o script selecionando Salvar script.
Criar um fluxo de trabalho automatizado com o

Power Automate
1. Entre no site do Power Automate .
2. No menu exibido no lado esquerdo da tela, selecione Criar. Isso leva você a uma
lista de maneiras de criar novos fluxos de trabalho.
3. Na seção Começar no espaço em branco, selecione Fluxo instantâneo. Isso irá

criar um fluxo de trabalho ativado manualmente. Você também pode fazer fluxos e
fluxos agendados que começam com base em eventos. Estes são abordados nos
próximos tutoriais.
4. Na caixa de diálogo exibida, insira o nome para seu fluxo na caixa de textoNome
de Fluxo. Em Escolher como disparar o fluxo, selecione Disparar manualmente
um fluxo na lista de opções. Selecione Criar para concluir a configuração inicial.
Observe que o fluxo acionado manualmente é apenas um entre os diversos tipos

de fluxo. No tutorial a seguir, você criará um fluxo que é executado
automaticamente quando você recebe um email.
5. No construtor de fluxos, selecione o + botão e Adicione uma ação.
6. No painel Adicionar uma tarefa de ação , pesquise "Script de execução do Excel".

Escolha a ação executar script do conector do Excel Online (Business). Essa ação
executa um script do OneDrive em uma pasta de trabalho. Se você quiser usar um
script armazenado na biblioteca do SharePoint da sua equipe, use o script
Executar de uma ação de biblioteca do SharePoint .
7. Você pode ser solicitado a entrar em sua conta do Microsoft 365. Faça isso para
continuar o tutorial.
8. Depois, você selecionará a pasta de trabalho e o script que será utilizado na etapa
do fluxo. Para o tutorial, você fará o uso da pasta de trabalho criada no seu
OneDrive, mas é possível usar qualquer pasta de trabalho em um site OneDrive ou
no Microsoft Office SharePoint Online. Especifique os seguintes parâmetros para a
ação Executar script :
Localização: OneDrive for Business

Biblioteca de Documentos: OneDrive
Arquivo: MyWorkbook.xlsx (Escolhido por meio do navegador de arquivos)
Script: Definir data e hora
9. Selecione Salvar.
Seu fluxo agora está pronto para ser executado por meio do Power Automate. Você
pode testá-lo usando o botão Testar no editor de fluxo ou seguir as etapas restantes do
tutorial para executar o fluxo a partir da sua coleção de fluxos.
Executar o script por meio da automação

1. Na página principal do Power Automate, selecione Meus fluxos.
2. Selecione Fluxo do meu tutorial na lista de fluxos exibida na guia Meus fluxos.
Isso irá lhe mostrar os detalhes do fluxo que criamos anteriormente.
3. Selecione Executar.
4. Um painel de tarefas irá aparecer para executar o fluxo. Se você for solicitado a
Entrar no Excel Online, entre selecionando Continuar.
5. Selecione Executar fluxo. Isso executará o fluxo, que, por sua vez, executará o
Script do Office relacionado.
6. Selecione Concluído. Você deve ver a atualização do histórico de execução de
acordo.
7. Atualize a página para ver os resultados do Power Automate. Se tiver falhado,

verifique as configurações do fluxo e execute-o novamente.
8. Abra a pasta de trabalho para ver as células atualizadas. Você deve ver a data atual
na célula A1 e a hora atual na célula B1. O Power Automate usa UTC (Tempo
Universal Coordenado), portanto, o tempo provavelmente será compensado do
fuso horário atual.
Próximas etapas
Tutorial completo: salve automaticamente o conteúdo de emails em uma pasta de
trabalho. O tutorial ensinará como transferir dados de um serviço de fluxo de trabalho
para o seu Script do Office e executar o fluxo do Power Automate quando certos
eventos ocorrerem.
Tutorial: salvar automaticamente o
conteúdo de emails em uma pasta de
trabalho
Artigo • 07/12/2023
Este tutorial ensina como usar um Script do Office para Excel com um fluxo de trabalho
automatizado do Power Automate . Seu script irá automaticamente ser executado
toda vez que você receber um email, gravando informações do email em uma pasta de
trabalho do Excel. Ser capaz de passar os dados de outros aplicativos para um Script do
Office oferece a você uma grande flexibilidade e liberdade nos seus processos
automatizados.
 Dica
e formatar uma tabela do Excel. Se você for novo no Power Automate,
recomendamos começar com o Tutorial: atualizar uma planilha de um fluxo do
Power Automate. Os Scripts do Office usam TypeScript e este tutorial se destina a
pessoas com conhecimento de nível iniciante a intermediário em JavaScript ou
TypeScript. Se você é novo no JavaScript, recomendamos começar com o tutorial
da Mozilla sobre JavaScript .
Pré-requisitos

O Power Automate não pode usarreferências
relativascomo Workbook.getActiveWorksheet acessar componentes da pasta de trabalho.
Portanto, você precisa de uma pasta de trabalho e uma planilha com nomes
consistentes para o Power Automate fazer referência.
1. Criar um nome para a pasta de trabalhoMyWorkbook.

3. Substitua o código existente pelo seguinte script e selecione Executar. Isso

instalará a pasta de trabalho com nomes consistentes de planilhas, tabela e tabela
dinâmica.
TypeScript

// Add a new worksheet to store the email table.
let emailsSheet = workbook.addWorksheet("Emails");
// Add data and create a table

emailsSheet.getRange("A1:D1").setValues([
["Date", "Day of the week", "Email address", "Subject"]
]);
let newTable = workbook.addTable(emailsSheet.getRange("A1:D2"),
true);
newTable.setName("EmailTable");
// Add a new PivotTable to a new worksheet

let pivotWorksheet = workbook.addWorksheet("Subjects");
let newPivotTable = workbook.addPivotTable("Pivot", "EmailTable",
pivotWorksheet.getRange("A3:C20"));
// Setup the pivot hierarchies

newPivotTable.addRowHierarchy(newPivotTable.getHierarchy("Day of the
week"));
newPivotTable.addRowHierarchy(newPivotTable.getHierarchy("Email
address"));
newPivotTable.addDataHierarchy(newPivotTable.getHierarchy("Subject"));
}

Crie um script que registra informações de um email. Você vai querer acompanhar quais
dias da semana você recebe mais emails e quantos remetentes exclusivos estão
enviando esse email. Sua pasta de trabalho tem uma tabela com colunas Data, Dia da
semana, Email endereço e Assunto. Sua planilha também tem uma Tabela Dinâmica que
está sendo dinâmica no dia da semana e Email endereço (essas são as hierarquias de
linha). A contagem de assuntos exclusivos são as informações agregadas que estão
sendo exibidas (a hierarquia de dados). O script atualizará essa Tabela Dinâmica depois
de atualizar a tabela de email.
1. No painel de tarefas do Editor de código, selecione Novo script.

2. O fluxo que você criará mais tarde no tutorial envia as informações de script sobre
cada email recebido. O script precisa aceitar essa entrada pelos parâmetros na
main função. Substitua o script padrão pelo script abaixo.
TypeScript
function main(
workbook: ExcelScript.Workbook,
from: string,
dateReceived: string,
subject: string) {
3. O script precisa acessar a tabela e a tabela dinâmica da pasta de trabalho. Adicione

o código a seguir ao corpo do script, após a abertura { .
TypeScript
// Get the email table.

let emailWorksheet = workbook.getWorksheet("Emails");
let table = emailWorksheet.getTable("EmailTable");
// Get the PivotTable.

let pivotTableWorksheet = workbook.getWorksheet("Subjects");
let pivotTable = pivotTableWorksheet.getPivotTable("Pivot");
4. O dateReceived parâmetro é do tipo string . Converta isso em um Date objeto para

que você possa facilmente obter o dia da semana. Depois de fazer isso, você
precisará mapear o valor do número do dia para uma versão mais legível. Adicione
o código a seguir ao final do script antes do fechamento } .
TypeScript
// Parse the received date string to determine the day of the week.
let emailDate = new Date(dateReceived);
let dayName = emailDate.toLocaleDateString("en-US", { weekday: 'long'
});
5. A cadeia subject pode incluir a marca de resposta "RE:". Remova isso da cadeia de
caracteres para que os emails no mesmo thread tenham o mesmo assunto para a
tabela. Adicione o código a seguir ao final do script antes do fechamento } .
TypeScript
// Remove the reply tag from the email subject to group emails on the
same thread.
let subjectText = subject.replace("Re: ", "");
subjectText = subjectText.replace("RE: ", "");
6. Agora que os dados de email foram formatados, adicione uma linha à tabela de
email. Adicione o código a seguir ao final do script antes do fechamento } .
TypeScript
// Add the parsed text to the table.

table.addRow(-1, [dateReceived, dayName, from, subjectText]);
7. Por fim, verifique se a Tabela Dinâmica está atualizada. Adicione o seguinte código
no final do script (antes do encerramento } ):
TypeScript
// Refresh the PivotTable to include the new row.

pivotTable.refresh();
8. Renomeie seu script Gravar Email e selecione Salvar script.
O seu script já está pronto para um fluxo de trabalho automatizado. Ele deve se parecer
com o script a seguir.
TypeScript
function main(
from: string,
dateReceived: string,
subject: string) {
// Get the email table.
let emailWorksheet = workbook.getWorksheet("Emails");
let table = emailWorksheet.getTable("EmailTable");
// Get the PivotTable.

let pivotTableWorksheet = workbook.getWorksheet("Subjects");
let pivotTable = pivotTableWorksheet.getPivotTable("Pivot");
// Parse the received date string to determine the day of the week.
let emailDate = new Date(dateReceived);
let dayName = emailDate.toLocaleDateString("en-US", { weekday: 'long' });
// Remove the reply tag from the email subject to group emails on the same
thread.
let subjectText = subject.replace("Re: ", "");
subjectText = subjectText.replace("RE: ", "");
// Add the parsed text to the table.

table.addRow(-1, [dateReceived, dayName, from, subjectText]);
// Refresh the PivotTable to include the new row.

pivotTable.refresh();
}

Power Automate
2. No menu exibido no lado esquerdo da tela, selecione Criar. Isso o conduzirá a uma
3. Na seção Começar no espaço em branco, selecione Fluxo automático. Isso cria

um fluxo de trabalho iniciado por um evento, como o recebimento de emails.
4. Na caixa de diálogo exibida, insira o nome para seu fluxo na caixa de textoNome
de Fluxo. Em Escolher o gatilho do fluxo, selecione Quando um novo email
chegar na lista de opções. Talvez seja necessário procurar pela opção usando a
caixa de pesquisa. Por fim, selecione Criar.
７ Observação
Este tutorial usa o Outlook. Sinta-se à vontade para usar o seu serviço de
email preferido, embora algumas opções possam ser diferentes.


Arquivo: MyWorkbook.xlsx (Escolhido por meio do navegador de arquivos)
Script: Gravar Email
ScriptParameters/from: From (conteúdo dinâmico do Outlook)
ScriptParameters/dateReceived: Hora recebida (conteúdo dinâmico do
Outlook)
ScriptParameters/subject: Assunto (conteúdo dinâmico do Outlook)
Observe que os parâmetros para o script só aparecerão quando o script for

selecionado.
Agora, o fluxo está habilitado. O seu script será automaticamente executado sempre
que você receber um email por meio do Outlook.
Gerenciar o script no Power Automate

1. Na página principal do Power Automate, selecione Meus fluxos.
2. Selecione o seu fluxo. Aqui você pode ver o histórico de execução. Você pode
atualizar a página ou selecionar o botão atualizar Executar Todos para atualizar o
histórico. O fluxo será disparado logo após o recebimento de um email. Testar o
fluxo enviando a si mesmo um email.
Quando o fluxo é acionado e executa seu script com sucesso, você deverá ver as
atualizações da planilha na pasta de trabalho e da tabela dinâmica.
Solução de problemas
Receber vários emails ao mesmo tempo pode causar conflitos de mesclagem no Excel.
Esse risco é mitigado configurando o conector de email para atuar apenas em um email
por vez. Para fazer isso:
1. Selecione a ação "email chega" e selecione Configurações.
2. Nas opções Configurações que aparecem, consulte o Controle de Simultaneidade

como Ativado. Em seguida, consulte o Grau de Paralelismo como 1.
Próximas etapas
Tutorial Completo: enviar lembretes de email semanais com base em dados de planilha.
Ele ensina como retornar dados de um script para o fluxo.
Você também pode conferir o exemplo de lembretes automáticos de tarefas para

aprender a combinar os Scripts do Office e Power Automate com as placas adaptáveis
de equipes.
Tutorial: Enviar lembretes de email
semanais com base em dados de
planilha
Artigo • 06/12/2023
Este tutorial ensina como retornar informações de um Script do Office para Excel como
parte de um fluxo de trabalho automatizado do Power Automate . Você fará um script
que olha através de uma programação e trabalha com um fluxo para enviar emails de
lembrete. Esse fluxo será executado em uma programação regular, fornecendo esses
lembretes em seu nome.
 Dica
e formatar uma tabela do Excel.
Se você for novo no Power Automate, recomendamos começar com o Tutorial:

atualizar uma planilha de um fluxo e tutorial do Power Automate: salve
automaticamente o conteúdo de emails em uma pasta de trabalho.
Os Scripts do Office usam TypeScript e este tutorial se destina a pessoas com

conhecimento de nível iniciante a intermediário em JavaScript ou TypeScript. Se
você é novo no JavaScript, recomendamos começar com o tutorial da Mozilla
sobre JavaScript .
Pré-requisitos

1. Baixe a pasta de trabalho on-call-rotation.xlsx para o seu OneDrive.
2. Abra on-call-rotation.xlsx no Excel.

3. Adicione uma linha à tabela com seu nome, endereço de email e datas de início e
fim que coincidam com a data atual.
） Importante
O roteiro que você vai escrever utiliza a primeira entrada correspondente na

tabela, portanto, certifique-se de que seu nome esteja acima de qualquer
linha com a semana atual.

2. Nomeie o script Obter uma Pessoa de Plantão.

3. Agora você deve ter um script vazio. Você deseja um script que obtenha um
endereço de email da planilha. Altere main para retornar uma cadeia de caracteres,
como esta:
TypeScript
function main(workbook: ExcelScript.Workbook) : string {

}
4. Em seguida, você precisa obter todos os dados da tabela. Isso permite que o script
examine cada linha. Adicione o seguinte código dentro da função main .
TypeScript
// Get the H1 worksheet.

let worksheet = workbook.getWorksheet("H1");
// Get the first (and only) table in the worksheet.

let table = worksheet.getTables()[0];
// Get the data from the table.

let tableValues = table.getRangeBetweenHeaderAndTotal().getValues();
5. As datas na tabela são armazenadas usando o Número de série da data do Excel

. Você precisa converter essas datas em datas JavaScript para compará-las.
Adicione a função auxiliar a seguir fora da main função.
TypeScript
// Convert the Excel date to a JavaScript Date object.

function convertDate(excelDateValue: number) {
let javaScriptDate = new Date(Math.round((excelDateValue - 25569) *
86400 * 1000));
return javaScriptDate;
}
6. Agora, você precisa descobrir qual pessoa está de plantão agora. A linha deles terá
uma data de início e de término em torno da data atual. O script pressupõe que
apenas uma pessoa esteja de plantão por vez. Os scripts podem retornar matrizes
para lidar com vários valores, mas você pode retornar o primeiro endereço de
email correspondente para este tutorial. Adicione o seguinte código ao final da
função main .
TypeScript
// Look for the first row where today's date is between the row's start
and end dates.
let currentDate = new Date();
for (let row = 0; row < tableValues.length; row++) {
let startDate = convertDate(tableValues[row][2] as number);
let endDate = convertDate(tableValues[row][3] as number);
if (startDate <= currentDate && endDate >= currentDate) {
// Return the first matching email address.
return tableValues[row][1].toString();
}
}
7. O script final deve ser semelhante a este:
TypeScript
function main(workbook: ExcelScript.Workbook) : string {

// Get the H1 worksheet.
let worksheet = workbook.getWorksheet("H1");
// Get the first (and only) table in the worksheet.

let table = worksheet.getTables()[0];
// Get the data from the table.

let tableValues =
table.getRangeBetweenHeaderAndTotal().getValues();
// Look for the first row where today's date is between the row's
start and end dates.
let currentDate = new Date();
for (let row = 0; row < tableValues.length; row++) {
let startDate = convertDate(tableValues[row][2] as number);
let endDate = convertDate(tableValues[row][3] as number);
if (startDate <= currentDate && endDate >= currentDate) {
// Return the first matching email address.
return tableValues[row][1].toString();
}
}
}

function convertDate(excelDateValue: number) {
let javaScriptDate = new Date(Math.round((excelDateValue - 25569) *
86400 * 1000));
return javaScriptDate;
}

Power Automate
2. No menu exibido no lado esquerdo da tela, selecione Criar. Isso o conduzirá a uma
3. Na seção Iniciar de um Modelo em Branco, selecione Fluxo de nuvem agendado.
4. Em seguida, defina a agenda para esse fluxo. Sua planilha tem uma nova atribuição
de chamada a partir de segunda-feira no primeiro semestre de 2024. Defina o
fluxo para ser executado na segunda de manhã. Use as seguintes opções para
configurar o fluxo a ser executado na segunda-feira de cada semana.
Nome do fluxo: Notificar a Pessoa de Plantão

Começando: 27/11/23 à 1h
Repetir a cada: 1 Semana
Nesses dias: M
5. Selecione Criar.


Arquivo: on-call-rotation.xlsx (Escolhido através do navegador de arquivos)
Script: Obter uma Pessoa de Plantão
11. Termine o fluxo enviando o email de lembrete. No painel Adicionar uma tarefa de
ação , procure por "enviar um email". Escolha a ação Enviar um email (V2) do
conector do Office 365 Outlook.
７ Observação
Este tutorial usa o Outlook. Sinta-se à vontade para usar o seu serviço de
email preferido, embora algumas opções possam ser diferentes.
12. Para o parâmetro To , selecione a caixa de texto e selecione Inserir valor

personalizado. Use o controle de conteúdo dinâmico para adicionar o endereço
de email retornado pelo script. Ele será rotulado como resultado com o ícone do
Excel próximo a ele. Você pode fornecer qualquer assunto e corpo de texto que
desejar.
Teste o script no Power Automate

Seu fluxo funcionará todas as segundas-feiras de manhã. Você pode testar o script
agora, selecionando o botão Testar no canto superior direito da tela. Selecione
Manualmente e, em seguida, selecione Executar teste para executar o fluxo agora e
testar o comportamento. Pode ser necessário conceder permissões ao Excel e Outlook
para continuar.
 Dica
Se o seu fluxo não enviar um email, verifique na planilha se um email válido está
listado para o intervalo de datas atual na parte superior da tabela.
Próximas etapas
Visite executar os Scripts do Office com o Power Automate para saber mais sobre como
conectar Scripts do Office com o Power Automate.
Você também pode conferir o exemplo de lembretes automáticos de tarefas para

aprender a combinar os Scripts do Office e Power Automate com as placas adaptáveis
de equipes.
Fundamentos para scripts do Office no
Excel
Artigo • 24/10/2023
Este artigo apresentará os aspectos técnicos dos scripts do Office. Você aprenderá as
partes críticas do código de script baseado em TypeScript e como os objetos Excel e as
APIs funcionam juntos.
Se preferir começar com uma experiência interativa, experimente o tutorial Gravar,

editar e criar scripts do Office no Excel ou visitar nossos exemplos.
TypeScript: A linguagem dos Scripts do Office

Os Scripts do Office são escritos em TypeScript , que é um superconjunto de
JavaScript . Se você está familiarizado com o JavaScript, seus conhecimentos serão
aproveitados porque muito do código é o mesmo em ambas as linguagens.
Recomendamos que você tenha algum conhecimento de programação de nível iniciante
antes de iniciar sua jornada de codificação nos Scripts do Office. Os recursos a seguir
podem ajudá-lo a entender o lado da codificação dos Scripts do Office.
Aprenda os conceitos básicos do JavaScript. Você deve se sentir confortável com

conceitos como variáveis, fluxo de controle, funções e tipos de dados. A Mozilla
oferece um bom e abrangente tutorial sobre JavaScript .
Saiba mais sobre os tipos no TypeScript. O TypeScript se baseia em JavaScript,
garantindo, no momento da compilação, que os tipos corretos sejam usados para
métodos de chamadas e atribuições. A documentação TypeScript em tipos de
objeto , tipo de inferência e tipo de compatibilidade será a mais útil.
Função main : O ponto de partida do script

Cada script deve conter uma função main com o tipo ExcelScript.Workbook como seu
primeiro parâmetro. Quando a função é executada, o aplicativo Excel invoca a função
main fornecendo a pasta de trabalho como seu primeiro parâmetro. Um
ExcelScript.Workbook deve sempre ser o primeiro parâmetro.
TypeScript

// Your code goes here
}
O código dentro da função main é executado quando o script é executado. main pode
chamar outras funções em seu script, mas o código que não estiver contido em uma
função não será executado. Os scripts não podem invocar ou chamar outros Scripts do
Office.
O Power Automate permite que você conecte scripts em fluxos. Os dados são
passados entre os scripts e o fluxo por meio dos parâmetros e retornos da função main .
Como integrar os Scripts do Office com o Power Automate é abordado em detalhes em
Executar Scripts do Office com o Power Automate .
Visão geral do modelo de objeto

Para escrever um script, você precisa entender como as APIs do Scripts do Office se
encaixam. Os componentes de uma pasta de trabalho têm relações específicas entre si.
De várias maneiras, essas relações correspondem às da interface do usuário do Excel.
Uma Pasta de trabalho contém uma ou mais Planilhas.

Uma Planilha concede acesso a células por meio de objetos de Intervalo.
Um Intervalo representa um grupo de células contíguas.
Os Intervalos são usados para criar e colocar Tabelas, Gráficos, Formas e outras
visualizações de dados ou objetos da organização.
Uma Planilha contém coleções desses objetos de dados que estão presentes na
planilha individual.
As Pastas de trabalho contêm coleções de alguns desses objetos de dados (por
exemplo, Tabelas) para toda a Pasta de trabalho.
A lista completa de objetos de API de Scripts do Office é detalhada no pacote

ExcelScript.
Pasta de Trabalho
Todo script é fornecido com um workbook objeto do tipo Workbook pela função main .
Isso representa o objeto de nível superior por meio do qual seu script interage com a
pasta de trabalho do Excel.
O script a seguir obtém a planilha ativa da pasta de trabalho e registra seu nome.
TypeScript
// Get the active worksheet.
let sheet = workbook.getActiveWorksheet();
// Display the current worksheet's name.

console.log(sheet.getName());
}
Intervalos
Um intervalo é um grupo de células contíguas na pasta de trabalho. Os scripts
costumam usar uma notação estilo A1 (por ex.: B3 para a única célula na coluna B e
linha 3 ou C2:F4 para as células das colunas C a F e linhas 2 a 4) para definir intervalos.
Os intervalos têm três propriedades principais: valores, fórmulas e formato. Essas

propriedades recebem ou definem os valores da célula, as fórmulas a serem avaliadas e
a formatação visual das células. Eles são acessados através de getValues , getFormulas e
getFormat . Os valores e fórmulas podem ser alterados com setValues e setFormulas ,
enquanto o formato é um objeto RangeFormat composto de vários objetos menores que

são configurados individualmente.
Os intervalo usam matrizes bidimensionais para gerenciar informações. Para obter mais
informações sobre como lidar com matrizes na estrutura de Scripts do Office, consulte
Trabalhar com intervalos.
Exemplo de intervalo
O exemplo a seguir mostra como criar registros de vendas. Este script usa Range objetos
para definir os valores, fórmulas e partes do formato.
TypeScript

// Create the headers and format them to stand out.

let headers = [["Product", "Quantity", "Unit Price", "Totals"]];
let headerRange = sheet.getRange("B2:E2");
headerRange.setValues(headers);
headerRange.getFormat().getFill().setColor("#4472C4");
headerRange.getFormat().getFont().setColor("white");
// Create the product data rows.

let productData = [
["Almonds", 6, 7.5],
["Coffee", 20, 34.5],
["Chocolate", 10, 9.54],
];
let dataRange = sheet.getRange("B3:D5");
dataRange.setValues(productData);
// Create the formulas to total the amounts sold.

let totalFormulas = [
["=C3 * D3"],
["=C4 * D4"],
["=C5 * D5"],
["=SUM(E3:E5)"],
];
let totalRange = sheet.getRange("E3:E6");
totalRange.setFormulas(totalFormulas);
totalRange.getFormat().getFont().setBold(true);
// Display the totals as US dollar amounts.

totalRange.setNumberFormat("$0.00");
}
Executar este script cria os seguintes dados na planilha atual:
Os tipos de valores do Intervalo

Cada célula tem um valor. Este valor é o valor subjacente inserido na célula, que pode
ser diferente do texto exibido no Excel. Por exemplo, você pode ver "2/5/2021" exibido
na célula como uma data, mas o valor real é 44318. Esta exibição pode ser alterada com
o formato de número, mas o valor real e o tipo na célula mudam apenas quando um
novo valor é definido.
Quando você estiver usando o valor da célula, é importante informar ao TypeScript qual
valor você espera obter de uma célula ou intervalo. Uma célula contém um dos
seguintes tipos: string , number , ou boolean . Para que seu script trate os valores
retornados como um desses tipos, você deve declarar o tipo.
O script a seguir obtém o preço médio da tabela do exemplo anterior. Observe o código
priceRange.getValues() as number[][] . Isso declara o tipo dos valores do intervalo
como um number[][] . Todos os valores nessa matriz podem então ser tratados como
números no script.
TypeScript

// Get the "Unit Price" column.

// The result of calling getValues is declared to be a number[][] so that
we can perform arithmetic operations.
let priceRange = sheet.getRange("D3:D5");
let prices = priceRange.getValues() as number[][];
// Get the average price.

let totalPrices = 0;
prices.forEach((price) => totalPrices += price[0]);
let averagePrice = totalPrices / prices.length;
console.log(averagePrice);
}
Gráficos, tabelas e outros objetos de dados

Os scripts podem criar e manipular estruturas de dados e visualizações no Excel. As
tabelas e gráficos são dois dos objetos mais usados, mas as APIs oferecem suporte a
tabelas dinâmicas, formas, imagens e muito mais. Eles são armazenados em coleções,
que serão discutidas mais adiante neste artigo.
Criar uma tabela

Criar tabelas usando intervalos de dados preenchidos. Controles de formatação e tabela
(por exemplo, filtros) são aplicados automaticamente ao intervalo.
O script a seguir cria uma tabela usando os intervalos do exemplo anterior.
TypeScript

// Add a table that has headers using the data from B2:E5.
sheet.addTable("B2:E5", true);
}
Executar esse script na planilha com os dados anteriores cria a tabela a seguir:
Criar um gráfico
Crie gráficos para visualizar os dados em um intervalo. Os scripts permitem inúmeras
variedades de gráficos que podem ser personalizadas de acordo com suas necessidades.
O script a seguir cria um gráfico de colunas simples para três itens e o coloca 100 pixels
abaixo da parte superior da planilha.
TypeScript

// Create a column chart using the data from B3:C5.

let chart = sheet.addChart(
ExcelScript.ChartType.columnStacked,
sheet.getRange("B3:C5")
);
// Set the margin of the chart to be 100 pixels from the top of the
screen.
chart.setTop(100);
}
Executar este script na planilha com a tabela anterior cria o seguinte gráfico:
Coleções
Quando um objeto do Excel tem uma coleção de um ou mais objetos do mesmo tipo,
ele os armazena em uma matriz. Por exemplo, um objeto Workbook contém um
Worksheet[] . Esta matriz é acessada pelo método Workbook.getWorksheets() . Os
métodos get que são plurais, como Worksheet.getCharts() , retornam toda a coleção de
objetos como uma matriz. Você verá este padrão em todas as APIs de Scripts do Office:
o objeto Worksheet tem um método getTables() que retorna um Table[] , o objeto
Table tem um método getColumns() que retorna um TableColumn[] , como assim em
diante.
A matriz retornada é uma matriz normal, portanto todas as operações regulares de

matriz estão disponíveis para seu script. Você também pode acessar objetos individuais
na coleção usando o valor do índice da matriz. Por exemplo, workbook.getTables()[0]
retorna a primeira tabela da coleção. Para saber mais sobre o uso da funcionalidade de
matriz interna com a estrutura de Scripts do Office, consulte Trabalhar com coleções.
Objetos individuais também são acessados a partir da coleção por meio de um método
get . Os métodos get que são singulares, como Worksheet.getTable(name) , retornam
um único objeto e requerem uma ID ou nome para o objeto específico. Esse ID ou

nome geralmente é definido pelo script ou por meio da IU do Excel.
O script a seguir obtém todas as tabelas na pasta de trabalho. Em seguida, garante que
os cabeçalhos sejam exibidos, os botões de filtro estejam visíveis e o estilo da tabela
seja definido como "TableStyleLight1".
TypeScript
// Get the table collection.
let tables = workbook.getTables();
// Set the table formatting properties for every table.

tables.forEach(table => {
table.setShowHeaders(true);
table.setShowFilterButton(true);
table.setPredefinedTableStyle("TableStyleLight1");
})
}
Adicionar objetos do Excel com um script

Você pode adicionar programaticamente objetos de documento, como tabelas ou
gráficos, chamando o método add correspondente disponível no objeto pai.
） Importante
Não adicione manualmente objetos as matrizes de coleção. Use os métodos add

nos objetos pai, por exemplo, adicione Table a Worksheet com o método
Worksheet.addTable .
O script a seguir cria, no Excel, uma tabela na primeira planilha da pasta de trabalho.
Observe que a tabela criada é enviada de volta pelo método addTable .
TypeScript

// Get the first worksheet.
let sheet = workbook.getWorksheets()[0];
// Add a table that uses the data in A1:G10.

let table = sheet.addTable(
"A1:G10",
true /* True because the table has headers. */
);
// Give the table a name for easy reference in other scripts.

table.setName("MyTable");
}
 Dica
A maioria dos objetos do Excel possui um método setName . Isso fornece uma
maneira fácil de acessar objetos do Excel posteriormente no script ou em outros
scripts para a mesma pasta de trabalho.
Verifique se existe um objeto na coleção

Os scripts geralmente precisam verificar se uma tabela ou objeto semelhante existe
antes de continuar. Use os nomes dados por scripts ou por meio da IU do Excel para
identificar os objetos necessários e agir de acordo. O métodos get retornam undefined
quando o objeto solicitado não está na coleção.
O script a seguir solicita uma tabela chamada "MinhaTabela" e utiliza uma instrução
if...else para verificar se a tabela foi encontrada.
TypeScript

// Get the table named "MyTable".
let myTable = workbook.getTable("MyTable");
// If the table is in the workbook, myTable will have a value.

// Otherwise, the variable will be undefined and go to the else clause.
if (myTable) {
let worksheetName = myTable.getWorksheet().getName();
console.log(`MyTable is on the ${worksheetName} worksheet`);
} else {
console.log(`MyTable is not in the workbook.`);
}
}
Um padrão comum em Scripts do Office é recriar uma tabela, gráfico ou outro objeto
sempre que o script for executado. Se você não precisa de dados antigos, é melhor
excluir o objeto antigo antes de criar o novo. Isso evita conflitos de nome ou outras
diferenças que possam ter sido introduzidas por outros usuários.
O script a seguir remove a tabela chamada "MinhaTabela", se houver, e adiciona uma

nova tabela com o mesmo nome.
TypeScript

// Get the table named "MyTable" from the first worksheet.
let tableName = "MyTable";
let oldTable = sheet.getTable(tableName);
// If the table exists, remove it.
if (oldTable) {
oldTable.delete();
}
// Add a new table with the same name.

let newTable = sheet.addTable("A1:G10", true);
newTable.setName(tableName);
}
Remova objetos do Excel com um script

Para excluir um objeto, chame o método delete do objeto.
７ Observação
Como na adição de objetos, não remova manualmente objetos de matrizes de

coleção. Use os métodos delete nos objetos do tipo coleção. Por exemplo, remova
um Table de um Worksheet usando Table.delete .
O script a seguir remove a primeira planilha da pasta de trabalho.
TypeScript

// Get first worksheet.
// Remove that worksheet from the workbook.

sheet.delete();
}
Leituras adicionais sobre o modelo de objeto

A documentação de referência de API dos scripts do Office é uma lista completa dos
objetos usados nos scripts do Office. Lá, você pode usar o sumário para navegar para
qualquer classe da qual quiser saber mais. Estas são várias páginas exibidas com
frequência.
Gráfico
Comentário
PivotTable
Range
RangeFormat
Formato
Table
Pasta de trabalho
Planilha
Para obter informações específicas para o modelo de objeto de Tabela Dinâmica,

consulte Trabalhar com Tabelas Dinâmicas no Office Scripts.
Confira também
Gravar, editar e criar scripts do Office no Excel
Ler dados de pasta de trabalho com scripts do Office no Excel
Trabalhar com Tabelas Dinâmicas no Office Scripts
Usar objetos internos do JavaScript nos scripts do Office
Práticas recomendadas nos Scripts do Office
Centro de Desenvolvimento de Scripts do Office
Executar scripts do Office com o Power
Automate
Artigo • 19/01/2024
O Power Automate permite adicionar scripts do Office a um fluxo de trabalho maior e

automatizado. Você pode usar o Power Automate para fazer coisas como adicionar o
conteúdo de um email à tabela de uma planilha ou criar ações em suas ferramentas de
gerenciamento de projetos com base em comentários de pasta de trabalho.
） Importante
Para usar scripts do Office no Power Automate , você deve ter uma licença
comercial do Microsoft 365.
 Dica
Procurando executar automaticamente um script sem se conectar a outros

aplicativos? Use o recurso de agendamento de script .
Introdução
Se você for novo no Power Automate, recomendamos visitar Introdução ao Power
Automate. Lá, você pode saber mais sobre todas as possibilidades de automação
disponíveis para você. Os documentos aqui se concentram em como os Scripts do
Office funcionam com o Power Automate e como isso pode ajudar a melhorar sua
experiência no Excel.
Tutoriais passo a passo

Há três tutoriais passo a passo para Power Automate e Scripts do Office. Estes mostram
como combinar os serviços de automatização e passar dados entre uma pasta de
trabalho e um fluxo.
Tutorial: atualizar uma planilha de um fluxo do Power Automate

Tutorial: salvar automaticamente o conteúdo de emails em uma pasta de trabalho
Tutorial: Enviar lembretes de email semanais com base em dados de planilha
Criar um fluxo do Excel
Você pode começar a usar o Power Automate no Excel com uma variedade de modelos
de fluxo. Na guia Automatizar , selecione Automatizar uma Tarefa.
Isso abre um painel de tarefas com várias opções para começar a conectar seus Scripts
do Office a soluções automatizadas maiores. Selecione qualquer opção para começar.
Seu fluxo é fornecido com a pasta de trabalho atual.
 Dica
Você também pode começar a fazer um fluxo no menu Mais opções (...) em um
script individual.
Conector do Excel
O conector do Excel Online (Business) fornece aos fluxos acesso às pastas de trabalho
do Excel. Há duas ações que chamam Scripts do Office.
Executar script. Essa é a ação a ser usada com scripts armazenados no local
padrão do Seu OneDrive.
Execute o script da biblioteca do SharePoint. Essa é a ação a ser usada quando os
scripts são armazenados no site do SharePoint da sua equipe.
Executar script
Para a ação Executar script , o local do script está sempre em seu OneDrive.
Segurança de dados em Scripts do Office com Power

Automate
A ação "Executar script" fornece às pessoas que usam o conector do Excel acesso
significativo à sua pasta de trabalho e seus dados. Além disso, há riscos de segurança
com scripts que fazem chamadas de API externas, conforme explicado em chamadas
externas do Power Automate. Se o administrador estiver preocupado com a exposição
de dados altamente confidenciais, ele poderá desativar o conector do Excel Online ou
restringir o acesso aos Scripts do Office por meio dos controles de administrador do
Office Scripts.
Para administradores que habilitaram políticas de Acesso Condicional para dispositivos

não gerenciados em seu locatário, é uma prática recomendada desabilitar o Power
Automate em dispositivos não gerenciados. Esse processo é detalhado na postagem do
blog Control Access to Power Apps and Power Automate with Azure AD Conditional
Access Policies .
Transferência de dados em fluxos para scripts

O Power Automate permite que você passe partes de dados entre ações de fluxo. Os
scripts podem ser configurados para aceitar as informações necessárias e retornar o que
você deseja da pasta de trabalho para o fluxo. Os dados são passados para scripts como
valores estáticos, expressões ou conteúdo dinâmico. Detalhes sobre o conector de um
serviço individual podem ser encontrados na documentação do Conector do Power
Automate.
Saiba os detalhes de como passar dados de e para seus scripts com a documentação a
seguir.
Saiba como fazer com o Tutorial: salve automaticamente o conteúdo de emails em

uma pasta de trabalho e tutorial: envie lembretes de email semanais com base em
dados de planilha.
Experimente o cenário de exemplo de lembretes de tarefas automatizados para ver
tudo em ação.
Leia Passar dados de e para scripts no Power Automate para obter mais cenários
de uso e os detalhes técnicos do TypeScript.
Exemplo
A captura de tela a seguir mostra um fluxo do Power Automate que é disparado sempre
que uma nova resposta a um Formulário é enviada. O fluxo executa um script que
adiciona o valor de satisfação do Formulário a uma tabela. A satisfação média atual é
retornada e enviada como um email.
A main função do script especifica o novo valor de satisfação como um parâmetro de
entrada ( newData ). O script retorna o valor médio de satisfação da tabela.
TypeScript
function main(workbook: ExcelScript.Workbook, newData: string): number {

// Add the new data to the table.
const table = workbook.getTable("SurveyTable");
table.addRow(-1, [newData]);
// Get the current satisfaction total.

const satisfactionColumn = table.getColumnByName("Current Satisfaction");
const values =
satisfactionColumn.getRangeBetweenHeaderAndTotal().getValues();
let total = 0.0;
values.forEach((value) => {
total += value[0] as number;
});
// Return the average satisfaction.

return total / values.length;
}
７ Observação
O parâmetro de script é do tipo string porque esse é o tipo que a ação Forms
retorna para todos os valores.
Encontre exemplos completos com passo a passo passo em exemplos e cenários de

Scripts do Office. Muitos usam scripts do Office no centro dos fluxos do Power
Automate.
Confira também
Passar dados de e para scripts no Power Automate
Solução de problemas de informações para o Power Automate com scripts do
Office
Começar a usar o Power Automate
Documentação de referência do conector do Excel Online (Business)
comentários:
Práticas recomendadas no Scripts do
Office
Artigo • 31/03/2023
Esses padrões e práticas são projetados para ajudar seus scripts a serem executados
com êxito todas as vezes. Use-as para evitar armadilhas comuns à medida que você
começa a automatizar seu fluxo de trabalho do Excel.
Usar o Gravador de Ações para aprender novos

recursos
O Excel faz muitas coisas. A maioria pode ser roteada. O Gravador de Ações registra
suas ações do Excel e as converte em código. Essa é a maneira mais fácil de aprender
sobre como diferentes recursos funcionam com scripts do Office. Se você precisar de
código para uma ação específica, alterne para o Gravador de Ações, execute as ações,
selecione Copiar como código e cole o código resultante em seu script.
） Importante
Ocasionalmente, o Gravador de Ações pode usar uma API que não tem suporte
fora de Excel na Web. Os usuários desse script em outras plataformas recebem um
aviso ao exibir esse script.
Verificar se um objeto está presente

Os scripts geralmente dependem de uma determinada planilha ou tabela que está
presente na pasta de trabalho. No entanto, eles podem ser renomeados ou removidos
entre execuções de script. Verificando se essas tabelas ou planilhas existem antes de
chamar métodos nelas, você pode garantir que o script não termine abruptamente.
O código de exemplo a seguir verifica se a planilha "Index" está presente na pasta de

trabalho. Se a planilha estiver presente, o script obterá um intervalo e continuará. Se ele
não estiver presente, o script registrará uma mensagem de erro personalizada.
TypeScript
// Make sure the "Index" worksheet exists before using it.

let indexSheet = workbook.getWorksheet('Index');
if (indexSheet) {
let range = indexSheet.getRange("A1");
// Continue using the range...
} else {
console.log("Index sheet not found.");
}
O operador TypeScript ? verifica se o objeto existe antes de chamar um método. Isso

pode tornar seu código mais simplificado se você não precisar fazer nada especial
quando o objeto não existir.
TypeScript
// The ? ensures that the delete() API is only called if the object exists.
workbook.getWorksheet('Index')?.delete();
Validar os dados e o estado da pasta de

trabalho primeiro
Verifique se todas as planilhas, tabelas, formas e outros objetos estão presentes antes
de trabalhar nos dados. Usando o padrão anterior, marcar para ver se tudo está na
pasta de trabalho e corresponde às suas expectativas. Fazer isso antes que qualquer
dado seja gravado garante que seu script não deixe a pasta de trabalho em um estado
parcial.
O script a seguir requer que duas tabelas chamadas "Table1" e "Table2" estejam
presentes. O script primeiro verifica se as tabelas estão presentes e, em seguida, termina
com a return instrução e uma mensagem apropriada se não estiverem.
TypeScript
// These tables must be in the workbook for the script.
const TargetTableName = 'Table1';
const SourceTableName = 'Table2';
// Get the table objects.

let targetTable = workbook.getTable(TargetTableName);
let sourceTable = workbook.getTable(SourceTableName);
// Check if the tables are there.

if (!targetTable || !sourceTable) {
console.log(`Required tables missing - Check that both the source
(${TargetTableName}) and target (${SourceTableName}) tables are present
before running the script.`);
return;
}
// Continue...
}
Se a verificação estiver acontecendo em uma função separada, você ainda deverá

terminar o script emitindo a return instrução da main função. Retornar da subfunção
não termina o script.
O script a seguir tem o mesmo comportamento que o anterior. A diferença é que a

main função chama a inputPresent função para verificar tudo. inputPresent retorna um
booliano ( true ou false ) para indicar se todas as entradas necessárias estão presentes.
A main função usa esse booliano para decidir sobre continuar ou encerrar o script.
TypeScript

if (!inputPresent(workbook)) {
return;
}
// Continue...
}
function inputPresent(workbook: ExcelScript.Workbook): boolean {


console.log(`Required tables missing - Check that both the source
before running the script.`);
return false;
}
return true;
}
Quando usar uma throw instrução

Uma throw instrução indica que ocorreu um erro inesperado. Ele termina o código
imediatamente. Na maioria das vezes, você não precisa de throw seu script.
Normalmente, o script informa automaticamente ao usuário que o script não foi
executado devido a um problema. Na maioria dos casos, é suficiente para terminar o
script com uma mensagem de erro e uma return instrução da main função.
No entanto, se o script estiver em execução como parte de um fluxo do Power

Automate, talvez você queira impedir que o fluxo continue. Uma throw instrução
interrompe o script e informa que o fluxo também será interrompido.
O script a seguir mostra como usar a throw instrução em nosso exemplo de verificação
de tabela.
TypeScript



// Immediately end the script with an error.
throw `Required tables missing - Check that both the source
before running the script.`;
}
Quando usar uma try...catch instrução
A try...catch instrução é uma maneira de detectar se uma chamada de API falhar e
continuar executando o script.
Considere o snippet a seguir que executa uma grande atualização de dados em um

intervalo.
TypeScript
range.setValues(someLargeValues);
Se someLargeValues for maior que Excel na Web puder lidar, a setValues() chamada
falhará. O script também falha com um erro de runtime. A try...catch instrução
permite que seu script reconheça essa condição, sem encerrar imediatamente o script e
mostrar o erro padrão.
Uma abordagem para dar ao usuário de script uma experiência melhor é apresentar
uma mensagem de erro personalizada. O snippet a seguir mostra uma try...catch
instrução registrando mais informações de erro para ajudar melhor o leitor.
TypeScript
try {
} catch (error) {
console.log(`The script failed to update the values at location
${range.getAddress()}. Please inspect and run again.`);
console.log(error);
return; // End the script (assuming this is in the main function).
}
Outra abordagem para lidar com erros é ter um comportamento de fallback que
manipula o caso de erro. O snippet a seguir usa o catch bloco para tentar um método
alternativo dividir a atualização em partes menores e evitar o erro.
 Dica
Para obter um exemplo completo sobre como atualizar um grande intervalo,

consulte Gravar um conjunto de dados grande.
TypeScript
try {
} catch (error) {
console.log(`The script failed to update the values at location
${range.getAddress()}. Trying a different approach.`);
handleUpdatesInSmallerBatches(someLargeValues);
}
// Continue...
}
７ Observação
Usar try...catch dentro ou ao redor de um loop reduz a velocidade do script. Para

obter mais informações de desempenho, consulte Evitar o uso de try...catch
blocos.
Confira também
Solução de problemas dos scripts do Office
Office
Limites de plataforma com scripts do Office
Melhorar o desempenho dos scripts do Office
Usar objetos JavaScript internos em
Scripts do Office
Artigo • 07/04/2023
O JavaScript fornece vários objetos internos que você pode usar em seus Scripts do
Office, independentemente de você estar fazendo scripts em JavaScript ou TypeScript
(um superconjunto de JavaScript). Este artigo descreve como usar alguns dos objetos
JavaScript internos em Scripts do Office para Excel.
７ Observação
Para obter uma lista completa de todos os objetos JavaScript internos, consulte o
artigo Objetos internos Standard da Mozilla.
Matriz
O objeto Array fornece uma maneira padronizada de trabalhar com matrizes em seu
script. Embora as matrizes sejam construções JavaScript padrão, elas se relacionam com
scripts do Office de duas maneiras principais: intervalos e coleções.
Trabalhar com intervalos

Os intervalos contêm várias matrizes bidimensionais que mapeiam diretamente para as
células nesse intervalo. Essas matrizes contêm informações específicas sobre cada célula
nesse intervalo. Por exemplo, Range.getValues retorna todos os valores nessas células
(com as linhas e colunas do mapeamento de matriz bidimensional para as linhas e
colunas dessa subseção de planilha). Range.getFormulas e Range.getNumberFormats são
outros métodos usados com frequência que retornam matrizes como Range.getValues .
O script a seguir pesquisa o intervalo A1:D4 para qualquer formato de número que
contenha um "$". O script define a cor de preenchimento nessas células como
"amarela".
TypeScript

// Get the range From A1 to D4.
let range = workbook.getActiveWorksheet().getRange("A1:D4");
// Get the number formats for each cell in the range.

let rangeNumberFormats = range.getNumberFormats();
// Iterate through the arrays of rows and columns corresponding to those
in the range.
rangeNumberFormats.forEach((rowItem, rowIndex) => {
rangeNumberFormats[rowIndex].forEach((columnItem, columnIndex) => {
// Treat the numberFormat as a string so we can do text comparisons.
let columnItemText = columnItem as string;
if (columnItemText.indexOf("$") >= 0) {
// Set the cell's fill to yellow.
range.getCell(rowIndex,
columnIndex).getFormat().getFill().setColor("yellow");
}
});
});
}
Trabalhar com coleções

Muitos objetos do Excel estão contidos em uma coleção. A coleção é gerenciada pela
API de Scripts do Office e exposta como uma matriz. Por exemplo, todas as formas em
uma planilha estão contidas em um Shape[] que é retornado pelo Worksheet.getShapes
método. Você pode usar essa matriz para ler valores da coleção ou acessar objetos
específicos dos métodos do get* objeto pai.
７ Observação
Não adicione ou remova manualmente objetos dessas matrizes de coleção. Use os

add métodos nos objetos pai e nos delete métodos nos objetos do tipo de
coleção. Por exemplo, adicione uma Tabela a uma planilha com o
Worksheet.addTable método e remova o uso de Table Table.delete .
O script a seguir registra o tipo de cada forma na planilha atual.
TypeScript

// Get the shapes in this worksheet.

let shapes = selectedSheet.getShapes();
// Log the type of every shape in the collection.

shapes.forEach((shape) => {
console.log(shape.getType());
});
}
O script a seguir exclui a forma mais antiga da planilha atual.
Typescript

// Get the first (oldest) shape in the worksheet.

// Note that this script will thrown an error if there are no shapes.
let shape = selectedSheet.getShapes()[0];
// Remove the shape from the worksheet.

shape.delete();
}
Data
O objeto Date fornece uma maneira padronizada de trabalhar com datas em seu
script. Date.now() gera um objeto com a data e hora atuais, o que é útil ao adicionar
carimbos de data/hora à entrada de dados do script.
O script a seguir adiciona a data atual à planilha. Observe que, usando o método, o
toLocaleDateString Excel reconhece o valor como uma data e altera o formato de
número da célula automaticamente.
TypeScript

// Get the range for cell A1.
let range = workbook.getActiveWorksheet().getRange("A1");
// Get the current date and time.

// Set the value at A1 to the current date, using a localized string.

range.setValue(date.toLocaleDateString());
}
A seção Trabalhar com datas dos exemplos tem mais scripts relacionados à data.
Matemática
O objeto Math fornece métodos e constantes para operações matemáticas comuns.
Elas fornecem várias funções também disponíveis no Excel, sem a necessidade de usar o
mecanismo de cálculo da pasta de trabalho. Isso salva o script de ter que consultar a
pasta de trabalho, o que melhora o desempenho.
O script a seguir usa Math.min para localizar e registrar o menor número no intervalo
A1:D4 . Observe que esse exemplo pressupõe que todo o intervalo contém apenas
números, não cadeias de caracteres.
TypeScript

// Get the range from A1 to D4.
let comparisonRange = workbook.getActiveWorksheet().getRange("A1:D4");
// Load the range's values.

let comparisonRangeValues = comparisonRange.getValues();
// Set the minimum values as the first value.

let minimum = comparisonRangeValues[0][0];
// Iterate over each row looking for the smallest value.

comparisonRangeValues.forEach((rowItem, rowIndex) => {
// Iterate over each column looking for the smallest value.
comparisonRangeValues[rowIndex].forEach((columnItem) => {
// Use `Math.min` to set the smallest value as either the current
cell's value or the previous minimum.
minimum = Math.min(minimum, columnItem);
});
});
console.log(minimum);
}
Não há suporte para o uso de bibliotecas

JavaScript externas
Os Scripts do Office não dão suporte ao uso de bibliotecas externas de terceiros. Seu
script só pode usar os objetos JavaScript internos e as APIs de Scripts do Office.
Confira também
Objetos internos padrão
Ambiente do Editor de Código de Scripts do Office
Ambiente do Editor de Código de
Scripts do Office
Artigo • 21/12/2023
Os Scripts do Office são escritos em TypeScript ou JavaScript e usam as APIs JavaScript

de Scripts do Office para interagir com uma pasta de trabalho do Excel. O Editor de
Código é baseado em Visual Studio Code, portanto, se você já usou esse ambiente
antes, você se sentirá em casa.
Linguagem de script: TypeScript ou JavaScript

Os Scripts do Office são escritos em TypeScript , que é um superconjunto de
JavaScript . O Gravador de Ações gera código no TypeScript e a documentação do
Office Scripts usa TypeScript. Como TypeScript é um superconjunto de JavaScript,
qualquer código de script que você escrever no JavaScript funcionará muito bem.
Os Scripts do Office são em grande parte peças de código independentes. Apenas uma
pequena parte da funcionalidade do TypeScript é usada. Portanto, você pode editar
scripts sem precisar aprender os meandros do TypeScript. O Editor de Código também
manipula a instalação, a compilação e a execução do código, portanto, você não precisa
se preocupar com nada além do script em si. É possível aprender o idioma e criar scripts
sem conhecimento de programação anterior. No entanto, se você for novo na
programação, recomendamos aprender alguns fundamentos antes de prosseguir com
scripts do Office.
Aprenda os conceitos básicos do JavaScript. Você deve se sentir confortável com

conceitos como variáveis, fluxo de controle, funções e tipos de dados. A Mozilla
oferece um bom e abrangente tutorial sobre JavaScript .
Saiba mais sobre os tipos no TypeScript. O TypeScript se baseia em JavaScript,
garantindo, no momento da compilação, que os tipos corretos sejam usados para
métodos de chamadas e atribuições. A documentação TypeScript em tipos de
objeto , tipo de inferência e tipo de compatibilidade será a mais útil.
Office Scripts JavaScript API

Os Scripts do Office usam uma versão especializada das APIs JavaScript do Office para
Suplementos do Office. Embora haja semelhanças nas duas APIs, você não deve supor
que o código possa ser portado entre as duas plataformas. As diferenças entre as duas
plataformas são descritas no artigo Diferenças entre Scripts do Office e Suplementos do
Office . Você pode exibir todas as APIs disponíveis para o script na documentação de
referência da API de Scripts do Office.
Suporte à biblioteca externa

Os Scripts do Office não dão suporte ao uso de bibliotecas JavaScript externas de
terceiros. Atualmente, você não pode chamar nenhuma biblioteca diferente das APIs de
Scripts do Office de um script. Você ainda tem acesso a qualquer objeto JavaScript
interno, como Matemática .
Intellisense
O IntelliSense é um conjunto de recursos do Editor de Código que ajudam você a
escrever código. Ele fornece realce de erro de sintaxe e preenchimento automático e
documentação de API embutida.
O IntelliSense dá sugestões conforme você digita, semelhante ao texto sugerido no

Excel. Pressionar a tecla Tab ou Enter insere o membro sugerido. Acione o IntelliSense
no local atual do cursor pressionando as teclas Ctrl+Space. Essas sugestões são
especialmente úteis ao concluir um método. A assinatura do método exibida pelo
IntelliSense contém uma lista de argumentos necessários, o tipo de cada argumento, se
um determinado argumento é necessário ou opcional e o tipo de retorno do método.
Passe o cursor sobre um método, classe ou outro objeto de código para ver mais
informações. Passe o mouse sobre um erro de sintaxe ou uma sugestão de código,
representada por uma linha vermelha ou amarela, para ver sugestões sobre como
corrigir o problema. Muitas vezes, o IntelliSense fornece uma opção "Correção Rápida"
para alterar automaticamente o código.
O Editor de Código de Scripts do Office usa o mesmo mecanismo IntelliSense que Visual
Studio Code. Para saber mais sobre o recurso, visite os recursos do IntelliSense do Visual
Studio Code .
Atalhos de teclado
A maioria dos atalhos de teclado para Visual Studio Code também funcionam no Editor
de Código de Scripts do Office. Use os seguintes PDFs para saber mais sobre as opções
disponíveis e aproveitar ao máximo o Editor de Código:
Atalhos de teclado para macOS .

Atalhos de teclado para Windows .
Confira também
Chamada de API externa nos scripts do
Office
Artigo • 05/05/2023
Scripts dão suporte a chamadas para serviços externos. Use esses serviços para fornecer
dados e outras informações para sua pasta de trabalho.
Ｕ Cuidado
Chamadas externas podem resultar em dados confidenciais sendo expostos a

pontos de extremidade indesejáveis. Seu administrador pode estabelecer o IRM
(Gerenciamento de Direitos de Informação) ou proteção de firewall contra essas
chamadas.
） Importante
Chamadas para APIs externas só podem ser feitas por meio do aplicativo Excel, não
por meio do Power Automate em circunstâncias normais. Também não há suporte
para chamadas externas para scripts armazenados em um site do SharePoint.
Configurar seu script para chamadas externas

As chamadas externas são assíncronas e exigem que o script seja marcado como
async . Adicione o async prefixo à sua main função e faça com que ele retorne um
Promise , conforme mostrado aqui:
TypeScript
async function main(workbook: ExcelScript.Workbook) : Promise <void>
７ Observação
Scripts que retornam outras informações podem retornar um Promise desse tipo.
Por exemplo, se o script precisar retornar um Employee objeto, a assinatura de
retorno será : Promise <Employee>
Você precisará aprender as interfaces do serviço externo para fazer chamadas para esse
serviço. Se você estiver usando fetch ou APIs REST , precisará determinar a estrutura
JSON dos dados retornados. Para entrada e saída do script, considere fazer um
interface para corresponder às estruturas JSON necessárias. Isso dá ao script mais
segurança de tipo. Você pode ver um exemplo disso em Usar buscar de Scripts do
Office.
Limitações com chamadas externas de Scripts do Office

Não há como entrar ou usar o tipo OAuth2 de fluxos de autenticação. Todas as
chaves e credenciais precisam ser codificadas (ou ler de outra fonte).
Não há infraestrutura para armazenar credenciais e chaves de API. Isso terá que ser
gerenciado pelo usuário.
Não há suporte para cookies de documento, localStorage e sessionStorage
objetos.
Chamadas externas podem resultar em dados confidenciais sendo expostos a
pontos de extremidade indesejáveis ou dados externos a serem trazidos para
pastas de trabalho internas. Seu administrador pode estabelecer proteção de
firewall contra essas chamadas. Certifique-se de marcar com políticas locais antes
de depender de chamadas externas.
Certifique-se de marcar a quantidade de taxa de transferência de dados antes de
fazer uma dependência. Por exemplo, retirar todo o conjunto de dados externo
pode não ser a melhor opção e, em vez disso, a paginação deve ser usada para
obter dados em partes.
Recuperar informações com fetch

A API de busca recupera informações de serviços externos. É uma async API,
portanto, você precisa ajustar a main assinatura do script. Faça a main função async .
Você também deve ter certeza await da chamada e json recuperação fetch . Isso
garante a conclusão dessas operações antes do término do script.
Todos os dados JSON recuperados por fetch devem corresponder a uma interface
definida no script. O valor retornado deve ser atribuído a um tipo específico porque os
Scripts do Office não dão suporte ao any tipo. Você deve consultar a documentação do
serviço para ver quais são os nomes e tipos das propriedades retornadas. Em seguida,
adicione a interface ou interfaces correspondentes ao script.
O script a seguir usa fetch para recuperar dados JSON do servidor de teste na URL
fornecida. Observe a JSONData interface para armazenar os dados como um tipo
correspondente.
TypeScript
async function main(workbook: ExcelScript.Workbook) {

// Retrieve sample JSON data from a test server.
let fetchResult = await
fetch('https://jsonplaceholder.typicode.com/todos/1');
// Convert the returned data to the expected JSON structure.

let json : JSONData = await fetchResult.json();
// Display the content in a readable format.

console.log(JSON.stringify(json));
}
/**
* An interface that matches the returned JSON structure.
* The property names match exactly.
*/
interface JSONData {
userId: number;
id: number;
title: string;
completed: boolean;
}
Outros fetch exemplos

O exemplo Usar chamadas de busca externa no Office Scripts mostra como obter
informações básicas sobre os repositórios do GitHub de um usuário.
Exemplos no artigo Usar JSON para passar dados de e para scripts do Office
mostram como passar dados de fetch e para comandos como JSON.
O cenário de exemplo de Scripts do Office: dados em nível de água da NOAA
demonstram o fetch comando que está sendo usado para recuperar registros do
banco de dados Marés e Correntes da Administração Nacional Oceânica e
Atmosférica.
O segundo exemplo em Adicionar imagens a uma pasta de trabalho contém uma
fetch chamada para obter uma imagem de um site.
Restringir chamadas externas com o IRM

(Gerenciamento de Direitos de Informação)
Você pode aplicar configurações de IRM a uma pasta de trabalho para evitar que
chamadas externas sejam feitas por scripts. Desabilite a política Copiar/EXTRACT para
evitar esse comportamento.
Chamadas externas do Power Automate

As chamadas de API externas falham quando um script é executado por meio do Power
Automate. Uma fetch chamada fornecerá a mensagem de erro "Erro de runtime: Linha
X: a busca não está definida". Certifique-se de marcar seus scripts para essas referências
antes de transformá-los em um fluxo.
Você terá que usar HTTP com Azure AD ou outras ações equivalentes para extrair dados
ou empurrá-los para um serviço externo.
２ Aviso
As chamadas externas feitas por meio do conector do Power Automate Excel

Online falham para ajudar a manter as políticas de prevenção de perda de dados
existentes. No entanto, scripts executados por meio do Power Automate são feitos
fora da sua organização e fora dos firewalls da sua organização. Para proteção
adicional contra usuários mal-intencionados nesse ambiente externo, o
administrador pode controlar o uso de Scripts do Office. Seu administrador pode
desabilitar o conector do Excel Online no Power Automate ou desativar scripts do
Office para Excel por meio dos controles de administrador do Office Scripts.
Confira também
Usar json para passar dados de e para scripts do Office
Usar chamadas de busca externa em Scripts do Office
Cenário de exemplo de Scripts do Office: dados de nível de água do graph da
NOAA
Armazenamento e propriedade de
arquivos do Office Scripts
Artigo • 12/01/2024
Os detalhes de como os scripts são armazenados e compartilhados dependem da

assinatura do Microsoft 365. Selecione a guia relevante para saber mais.
） Importante
O Office Scripts está em versão prévia para assinaturas pessoais e familiares do

Microsoft 365. Se você encontrar algum problema, denuncie-os por meio do botão
Comentários no Excel.
Armazenamento de arquivos
Para empresas e educação
Os Scripts do Office são armazenados no OneDrive por padrão. Os arquivos .osts

são encontrados na pasta /Documents/Office Scripts/ . Todas as edições feitas a
esses arquivos .osts , como renomear ou excluir arquivos, serão refletidas no Editor
de Código e na Galeria de Scripts. O Excel reconhece e executa apenas um script se
estiver na pasta do OneDrive, em uma pasta do Sharepoint ou compartilhado com
a pasta de trabalho. Isso significa que o Excel precisa de conectividade com a
Internet para acessar scripts do Office.
OneDrive
Os scripts compartilhados com uma de suas pastas de trabalho permanecem no
OneDrive do criador do script. Elas não são copiadas para nenhuma das pastas
locais ou do OneDrive quando você executa o script compartilhado no Excel. O
botão Mover mostrado ao renomear um script move o script para um novo local. O
botão Fazer uma Cópia do Editor de Código salva uma cópia separada do script em
seu OneDrive. As alterações na cópia não afetam o script original.
A menos que você compartilhe seus scripts pessoais, ninguém mais pode acessá-
los. As configurações do OneDrive controlam o acesso compartilhado e as
permissões para todos os arquivos .osts de script, independentemente de qualquer
configuração do Excel. Scripts não podem ser vinculados de um disco local ou
locais de nuvem personalizados.
SharePoint
Os Scripts do Office salvos em um site do SharePoint pertencem à sua equipe. Você
e os membros da sua organização com o acesso apropriado podem executar e
editar scripts do SharePoint. Você também verá esses scripts aparecerem na Galeria
de Scripts da guia Automatizar .
Para carregar um script do SharePoint, acesse Todos os scripts e selecione Exibir

mais scripts na parte inferior da lista. Isso traz um seletor de arquivos em que você
pode escolher arquivos .osts de qualquer site do SharePoint para o qual você tem
acesso. Observe que os scripts do SharePoint que você já abriu serão exibidos na
lista de scripts recentes.
Para mover um script para o SharePoint, abra um script no Editor de Código e

clique no nome do script, como se você estivesse renomeando-o. Na chamada,
clique no botão Mover . Isso abre um seletor de arquivos. Selecione a pasta de
destino em seu site do SharePoint. Mover o script para o novo local pode levar até
um minuto.
Para salvar uma cópia de um script no SharePoint, acesse o menu Mais opções (...)
e selecione Salvar como. Isso abre um seletor de arquivos em que você pode
selecionar pastas em seu site do SharePoint. Salvar em um novo local cria uma
cópia do script nesse local. A versão original ainda está em seu OneDrive ou em
outro local do SharePoint.
） Importante
Scripts com chamadas externas não podem ser executados no SharePoint.

Você receberá um erro dizendo que "as chamadas de acesso à rede não têm
suporte neste momento para scripts salvos em um site do SharePoint".
７ Observação
O Power Automate dá suporte à execução de scripts armazenados no

SharePoint com a ação Executar script da biblioteca do SharePoint (versão
prévia ). Esta ação está atualmente em versão prévia e está sujeita a alterações
com base em comentários. Se você encontrar problemas com essa ação,
denuncie-os por meio da opção Ajudar>a Dar Comentários no Power
Automate.
Compartilhar scripts
Para dar aos usuários que estão fora do site do SharePoint acesso ao script,
compartilhe o script com uma pasta de trabalho do Excel. Isso significa que você
está vinculando o script ao arquivo, não anexando-o. Quem tiver acesso ao arquivo
do Excel também poderá exibir, executar ou fazer uma cópia do script.
７ Observação
Administração configurações para acesso condicional no OneDrive e no

SharePoint afetam scripts do Office. Para obter mais informações, consulte a
seção Acesso Condicional dos limites e requisitos da plataforma com scripts
do Office.
Restaurar scripts excluídos

Quando você exclui um script no Excel, ele vai para a lixeira do OneDrive ou do
SharePoint. Para restaurar um script excluído, siga as etapas listadas em Como
recuperar itens ausentes, excluídos ou corrompidos no SharePoint e no OneDrive
para trabalho ou escola . Restaurar um arquivo .osts retorna-o à lista Todos os
scripts .
Um script excluído não é identificado com a pasta de trabalho. Quando você

restaura um script, ele não mantém o acesso ao script. Você precisará compartilhar
o script novamente.
Os scripts restaurados ainda funcionam conforme o esperado com fluxos do Power

Automate. Você não precisa recriar o conector de fluxo.
Propriedade e retenção de arquivos
Os Scripts do Office seguem as políticas de retenção e exclusão especificadas pelo

Microsoft OneDrive e pelo Microsoft SharePoint. Para saber como lidar com scripts
que foram criados e compartilhados por um usuário que está sendo removido de
sua organização, consulte Saiba mais sobre retenção para SharePoint e OneDrive.
Durante a edição, os arquivos são armazenados temporariamente no navegador.

Você deve salvar o script antes de fechar a janela do Excel para salvá-lo no local do
OneDrive. Não se esqueça de salvar o arquivo após edições ou então essas edições
estarão apenas na versão do arquivo do navegador.
Auditar o uso de Scripts do Office no nível do

administrador
Descubra quem está usando scripts do Office em sua organização com o log de
auditoria do centro de conformidade. Os detalhes sobre o log de auditoria são
encontrados em Pesquisar o log de auditoria na Central de Conformidade do & de
Segurança.
Para auditar especificamente a atividade relacionada ao Office Scripts como

administrador, siga as etapas a seguir.
1. Em uma janela do navegador InPrivate (ou Incognito ou outro modo de

acompanhamento limitado específico do navegador), abra e faça logon no Centro
de Conformidade .
2. Acesse a página Auditoria .
3. (Somente uma vez) Na guia Pesquisar , selecione Iniciar a atividade de usuário e

administrador de gravação.
） Importante
Pode levar uma ou duas horas depois de ativar a gravação antes que todas as
atividades em todo o locatário sejam gravadas.
4. Defina as opções de pesquisa desejadas e selecione Pesquisar. Filtre o campo
Arquivo, pasta ou site para .osts . Isso revela quem na sua organização está
criando ou modificando scripts.
Confira também
Compartilhamento de Scripts do Office no Excel
Configurações dos scripts do Office no M365
Desfazer os efeitos do Scripts do Office
Obter entrada do usuário para scripts
Artigo • 18/09/2023
Adicionar parâmetros ao script permite que outros usuários forneçam dados para o
script, sem a necessidade de editar código. Quando o script é executado por meio da
faixa de opções ou de um botão, aparece um prompt que pede entrada.
） Importante
Atualmente, somente Excel na Web usuários serão solicitados a inserir dados para
scripts parametrizados. Os fluxos do Power Automate também dão suporte à
distribuição de dados para scripts por meio de parâmetros.
Exemplo – Realçar valores grandes

O exemplo a seguir mostra um script que usa um número e uma cadeia de caracteres
do usuário. Para testá-la, abra uma pasta de trabalho vazia e insira alguns números em
várias células.
TypeScript
/**
* This script applies a background color to cells over a certain value.
* @param highlightThreshold The value used for comparisons.
* @param color A string representing the color to make the high value
cells.
* This must be a color code representing the color of the background,
* in the form #RRGGBB (e.g., "FFA500") or a named HTML color (e.g.,
"orange").
*/
function main(
highlightThreshold: number,
color: string) {
// Get the used cells in the current worksheet.
const currentSheet = workbook.getActiveWorksheet();
const usedRange = currentSheet.getUsedRange();
const rangeValues = usedRange.getValues();

for (let row = 0; row < rangeValues.length; row++) {
for (let column = 0; column < rangeValues[row].length; column++) {
if (rangeValues[row][column] >= highlightThreshold) {
usedRange.getCell(row,
column).getFormat().getFill().setColor(color);
}
}
}
}
main parâmetros: passar dados para um script

Toda a entrada de script é especificada como parâmetros adicionais para a main função.
Novos parâmetros são adicionados após o parâmetro obrigatório workbook:
ExcelScript.Workbook . Por exemplo, se você quisesse que um script aceitasse um
string que representasse um nome como entrada, alteraria a main assinatura para
function main(workbook: ExcelScript.Workbook, name: string) .
Parâmetros opcionais
Parâmetros opcionais não precisam que o usuário forneça um valor. Isso implica que
seu script tem comportamento padrão ou esse parâmetro só é necessário em um caso
de canto. Eles são denotados em seu script com o modificador ? opcional. Por
exemplo, no function main(workbook: ExcelScript.Workbook, Name?: string) parâmetro

Name é opcional.
Valores de parâmetro padrão
Os valores de parâmetro padrão preenchem automaticamente o campo da ação com
um valor. Para definir um valor padrão, atribua um valor ao parâmetro na main
assinatura. Por exemplo, no function main(workbook: ExcelScript.Workbook, location:
string = "Seattle") parâmetro location tem o valor "Seattle" , a menos que outra
coisa seja fornecida.
Listas suspensas para parâmetros

Ajude outras pessoas que usam seu script em seu fluxo fornecendo uma lista de opções
de parâmetro aceitáveis. Se houver um pequeno subconjunto de valores que o script
usa, crie um parâmetro que seja esses valores literais. Faça isso declarando que o tipo de
parâmetro é uma união de valores literais . Por exemplo, no function main(workbook:
ExcelScript.Workbook, location: "Seattle" | "Redmond") parâmetro location só pode
ser "Seattle" ou "Redmond" . Quando o script é executado, os usuários recebem uma

lista suspensa com essas duas opções.
Documentar o script
Comentários de código que seguem os padrões JSDoc serão mostrados às pessoas
quando executarem seu script. Quanto mais detalhes você colocar nas descrições, mais
fácil será para outras pessoas para os scripts. Descreva a finalidade de cada parâmetro
de entrada e quaisquer restrições ou limites. O exemplo a seguir JSDoc mostra como
documentar um script com um number parâmetro chamado taxRate .
TypeScript
/**
* A script to apply the current tax rate to sales figures.
* @param taxRate The current sales tax rate in the region as a decimal
number (enter 12% as .12).
*/
function main(workbook: ExcelScript.Workbook, taxRate: number)
７ Observação
Você não precisa documentar o ExcelScript.Workbook parâmetro em cada script.
Restrições de tipo
Ao adicionar parâmetros de entrada e valores retornados, considere os seguintes
subsídios e restrições.
1. O primeiro parâmetro deve ser do tipo ExcelScript.Workbook . Seu nome de

parâmetro não importa.
2. Os tipos string , number , boolean , unknown e object .
3. Há suporte para matrizes (ambos [] e Array<T> estilos) dos tipos listados

anteriormente. Matrizes aninhadas também têm suporte.
4. Os tipos de união são permitidos se forem uma união de literais pertencentes a

um único tipo (como "Left" | "Right" , não "Left" | 5 ).
5. Os tipos de objeto serão permitidos se contiverem propriedades do tipo string ,

number , boolean , matrizes com suporte ou outros objetos com suporte. O exemplo
a seguir mostra objetos aninhados com suporte como tipos de parâmetro.
TypeScript
// The Employee object is supported because Position is also composed

of supported types.
interface Employee {
name: string;
job: Position;
}
interface Position {
id: number;
title: string;
}
6. Os objetos devem ter sua interface ou definição de classe definida no script. Um

objeto também pode ser definido anonimamente embutido, como no exemplo a
seguir.
TypeScript
function main(workbook: ExcelScript.Workbook, contact: {name: string,

email: string})
Confira também
Passar dados de e para scripts no Power Automate
Executar scripts do Office no Excel com botões
Definir formatação condicional para comparações entre colunas
Passar dados de e para scripts no Power
Automate
Artigo • 29/11/2023
O Power Automate reúne programas separados em um único fluxo de trabalho

automatizado. Cada conector tem parâmetros diferentes que aceita e valores diferentes
que retorna. Seus scripts podem ser gravados para expandir a ação "Executar script" do
Power Automate para obter entrada adicional ou dar saída.
A entrada para o script é especificada adicionando parâmetros à main função. A saída

do script é declarada adicionando um tipo de retorno a main .
７ Observação
Quando você cria um bloco "Executar script" em seu fluxo, os parâmetros aceitos e
os tipos retornados são preenchidos. Se você alterar os parâmetros ou retornar
tipos do script, precisará refazer o bloco "Executar script" do fluxo. Isso garante que
os dados estão sendo analisados corretamente.
Passar dados para scripts com parâmetros

Adicione parâmetros aos scripts para fornecer entrada de outras partes do fluxo. É o
mesmo processo para adicionar parâmetros para scripts baseados em fluxo como é para
scripts executados por meio do cliente do Excel. Saiba mais sobre como fornecer
entrada para scripts em Obter entrada do usuário para scripts.
A captura de tela a seguir mostra qual script com a assinatura function main(workbook:
ExcelScript.Workbook, location: string = "Seattle") seria exibido.
Os menus suspensos criados por uniões de tipo também funcionam da mesma forma
no Power Automate.
Retornar dados de um script
Os scripts podem retornar dados da pasta de trabalho para serem usados como
conteúdo dinâmico em um fluxo do Power Automate. Para retornar um objeto, adicione
a sintaxe de tipo de retorno à main função. Por exemplo, se você quisesse retornar um
string valor do script, sua main assinatura seria function main(workbook:
ExcelScript.Workbook): string .
Os valores retornados são mostrados como conteúdo dinâmico da ação Executar script
no fluxo. O conteúdo dinâmico é chamado de "resultado".
Tipos aceitáveis para retornar dados são os mesmos que para parâmetros. Detalhes
sobre restrições de tipo são encontrados no artigo Obter entrada do usuário para
scripts.
Confira também
Obter entrada do usuário para scripts
Executar scripts do Office com o Power Automate
Office
Executar scripts do Office no Excel a
partir de botões
Artigo • 21/12/2023
Ajude seus colegas a encontrar e executar seus scripts adicionando botões de script a
uma pasta de trabalho.
Criar botões de script

Ao exibir um script, selecione Adicionar na pasta de trabalho. Isso cria um botão na
pasta de trabalho que executa o script associado. Ele também compartilha o script com
a pasta de trabalho, para que todos com permissões de gravação para a pasta de
trabalho possam usar sua automação útil.
Remover botões de script
Para parar de compartilhar um script por meio de um botão, selecione a seta ao lado de
Adicionar na pasta de trabalho e escolha a opção Remover da pasta de trabalho. Isso
remove todos os botões que executem o script. A exclusão de um único botão remove
o script desse botão, mesmo que a operação seja desfeita ou o botão seja cortado e
passado.
Versões mais antigas do Excel
Os botões de script não funcionarão quando abertos em versões do Excel que não dão
suporte a Scripts do Office. Nesse caso, o botão ainda aparece, mas selecioná-lo não
tem efeito.
Confira também
Limites e requisitos da plataforma com scripts do Office
Usar json para passar dados de e para
scripts do Office
Artigo • 29/11/2023
JSON (Notação de Objeto JavaScript) é um formato para armazenar e transferir dados.

Cada objeto JSON é uma coleção de pares de nome/valor que pode ser definido
quando criado. O JSON é útil com scripts do Office porque pode lidar com a
complexidade arbitrária de intervalos, tabelas e outros padrões de dados no Excel. O
JSON permite analisar dados de entrada dos serviços Web e passar objetos complexos
por meio de fluxos do Power Automate.
Este artigo se concentra no uso do JSON com scripts do Office. Recomendamos que
você primeiro saiba mais sobre o formato de artigos como Introdução JSON das
Escolas W3.
Analisar dados JSON em um intervalo ou

tabela
Matrizes de objetos JSON fornecem uma maneira consistente de passar linhas de dados
de tabela entre aplicativos e serviços Web. Nesses casos, cada objeto JSON representa
uma linha, enquanto as propriedades representam as colunas. Um Script do Office pode
fazer loop sobre uma matriz JSON e remontá-la como uma matriz 2D. Essa matriz é
então definida como os valores de um intervalo e armazenada em uma pasta de
trabalho. Os nomes da propriedade também podem ser adicionados como cabeçalhos
para criar uma tabela.
O script a seguir mostra dados JSON sendo convertidos em uma tabela. Observe que os
dados não são retirados de uma fonte externa. Isso é abordado posteriormente neste
artigo.
TypeScript
/**
* Sample JSON data. This would be replaced by external calls or
* parameters getting data from Power Automate in a production script.
*/
const jsonData = [
{ "Action": "Edit", /* Action property with value of "Edit". */
"N": 3370, /* N property with value of 3370. */
"Percent": 17.85 /* Percent property with value of 17.85. */
},
// The rest of the object entries follow the same pattern.
{ "Action": "Paste", "N": 1171, "Percent": 6.2 },
{ "Action": "Clear", "N": 599, "Percent": 3.17 },
{ "Action": "Insert", "N": 352, "Percent": 1.86 },
{ "Action": "Delete", "N": 350, "Percent": 1.85 },
{ "Action": "Refresh", "N": 314, "Percent": 1.66 },
{ "Action": "Fill", "N": 286, "Percent": 1.51 },
];
/**
* This script converts JSON data to an Excel table.
*/
// Create a new worksheet to store the imported data.
const newSheet = workbook.addWorksheet();
newSheet.activate();
// Determine the data's shape by getting the properties in one object.

// This assumes all the JSON objects have the same properties.
const columnNames = getPropertiesFromJson(jsonData[0]);
// Create the table headers using the property names.

const headerRange = newSheet.getRangeByIndexes(0, 0, 1,
columnNames.length);
headerRange.setValues([columnNames]);
// Create a new table with the headers.

const newTable = newSheet.addTable(headerRange, true);
// Add each object in the array of JSON objects to the table.

const tableValues = jsonData.map(row => convertJsonToRow(row));
newTable.addRows(-1, tableValues);
}
/**
* This function turns a JSON object into an array to be used as a table
row.
*/
function convertJsonToRow(obj: object) {
const array: (string | number)[] = [];
// Loop over each property and get the value. Their order will be the same
as the column headers.
for (let value in obj) {
array.push(obj[value]);
}
return array;
}
/**
* This function gets the property names from a single JSON object.
*/
function getPropertiesFromJson(obj: object) {
const propertyArray: string[] = [];
// Loop over each property in the object and store the property name in an
array.
for (let property in obj) {
propertyArray.push(property);
}
return propertyArray;
}
 Dica
Se você conhece a estrutura do JSON, pode criar sua própria interface para facilitar
a obtenção de propriedades específicas. Você pode substituir as etapas de
conversão JSON para matriz por referências de segurança de tipo. O snippet de
código a seguir mostra essas etapas (agora comentadas) substituídas por
chamadas que usam uma nova ActionRow interface. Observe que isso faz com que
a convertJsonToRow função não seja mais necessária.
TypeScript
// const tableValues = jsonData.map(row => convertJsonToRow(row));

// newTable.addRows(-1, tableValues);
// }
const actionRows: ActionRow[] = jsonData as ActionRow[];

// Add each object in the array of JSON objects to the table.
const tableValues = actionRows.map(row => [row.Action, row.N,
row.Percent]);
newTable.addRows(-1, tableValues);
}
interface ActionRow {
Action: string;
N: number;
Percent: number;
}
Obter dados JSON de fontes externas

Há duas maneiras de importar dados JSON para sua pasta de trabalho por meio de um
Script do Office.
Como um parâmetro com um fluxo do Power Automate.

Com uma fetch chamada para um serviço Web externo.
Modificar o exemplo para trabalhar com o Power Automate

Os dados JSON no Power Automate podem ser passados como uma matriz de objeto
genérico. Adicione uma object[] propriedade ao script para aceitar esses dados.
TypeScript
// For Power Automate, replace the main signature in the previous sample
with this one
// and remove the sample data.
function main(workbook: ExcelScript.Workbook, jsonData: object[]) {
Em seguida, você verá uma opção no conector do Power Automate para adicionar
jsonData à ação Executar script .
Modificar o exemplo para usar uma fetch chamada

Os serviços Web podem responder a fetch chamadas com dados JSON. Isso fornece ao
script os dados necessários ao mantê-lo no Excel. Saiba mais sobre fetch e chamadas
externas lendo suporte a chamadas de API externa em Scripts do Office.
TypeScript
// For external services, replace the main signature in the previous sample
with this one,
// add the fetch call, and remove the sample data.
// Replace WEB_SERVICE_URL with the URL of whatever service you need to
call.
const response = await fetch('WEB_SERVICE_URL');
const jsonData: object[] = await response.json();
Criar JSON de um intervalo

As linhas e colunas de uma planilha geralmente implicam relações entre seus valores de
dados. Uma linha de uma tabela mapeia conceitualmente para um objeto de
programação, com cada coluna sendo uma propriedade desse objeto. Considere a
tabela de dados a seguir. Cada linha representa uma transação registrada na planilha.
ﾉ Expand table
ID Data Valor Fornecedor
1 6/1/2022 $43.54 Melhor para você Organics Company
2 6/3/2022 $67.23 Liberty Bakery and Cafe
3 6/3/2022 $37.12 Melhor para você Organics Company
4 6/6/2022 $86.95 Vinícola Coho
5 6/7/2022 $13.64 Liberty Bakery and Cafe
Cada transação (cada linha) tem um conjunto de propriedades associadas a ela: "ID",
"Date", "Amount" e "Vendor". Isso pode ser modelado em um Script do Office como um
objeto.
TypeScript
// An interface that wraps transaction details as JSON.

interface Transaction {
"ID": string;
"Date": number;
"Amount": number;
"Vendor": string;
}
As linhas na tabela de exemplo correspondem às propriedades na interface, de modo

que um script pode converter facilmente cada linha em um Transaction objeto. Isso é
útil ao gerar os dados para o Power Automate. O script a seguir itera em cada linha da
tabela e o adiciona a um Transaction[] .
TypeScript

// Get the table on the current worksheet.
const table = workbook.getActiveWorksheet().getTables()[0];
// Create an array of Transactions and add each row to it.

let transactions: Transaction[] = [];
const dataValues = table.getRangeBetweenHeaderAndTotal().getValues();
for (let i = 0; i < dataValues.length; i++) {
let row = dataValues[i];
let currentTransaction: Transaction = {
ID: row[table.getColumnByName("ID").getIndex()] as string,
Date: row[table.getColumnByName("Date").getIndex()] as number,
Amount: row[table.getColumnByName("Amount").getIndex()] as number,
Vendor: row[table.getColumnByName("Vendor").getIndex()] as string
};
transactions.push(currentTransaction);
}
// Do something with the Transaction objects, such as return them to a

Power Automate flow.
console.log(transactions);
}
// An interface that wraps transaction details as JSON.

interface Transaction {
"ID": string;
"Date": number;
"Amount": number;
"Vendor": string;
}
Exportar JSON com fetch
Assim como importar dados com fetch , você pode enviar dados de sua pasta de
trabalho com um comando semelhante. Um POST comando usa todos os dados JSON
com cadeia de caracteres e os envia para o ponto de extremidade especificado.
Para ver isso em ação, substitua a console.log(transactions); linha no exemplo

anterior pelo código a seguir. Isso emite um POST comando para um servidor de teste e,
em seguida, lê os dados de volta.
TypeScript
const response = await fetch('https://jsonplaceholder.typicode.com/posts',

{
method: 'POST',
body: JSON.stringify(transactions),
headers: {
'Content-type': 'application/json; charset=UTF-8',
},
});
const jsonData: object[] = await response.json();
console.log(jsonData);
Usar um objeto genérico

O exemplo anterior pressupõe que os valores de cabeçalho da tabela sejam
consistentes. Se sua tabela tiver colunas variáveis, você precisará criar um objeto JSON
genérico. O script a seguir mostra um script que registra qualquer tabela como JSON.
TypeScript

// Get the table on the current worksheet.
const table = workbook.getActiveWorksheet().getTables()[0];
// Use the table header names as JSON properties.

const tableHeaders = table.getHeaderRowRange().getValues()[0] as string[];
// Get each data row in the table.

const dataValues = table.getRangeBetweenHeaderAndTotal().getValues();
let jsonArray: object[] = [];
// For each row, create a JSON object and assign each property to it based
on the table headers.
for (let i = 0; i < dataValues.length; i++) {
// Create a blank generic JSON object.
let jsonObject: { [key: string]: string } = {};
for (let j = 0; j < dataValues[i].length; j++) {
jsonObject[tableHeaders[j]] = dataValues[i][j] as string;
}
jsonArray.push(jsonObject);
}
// Do something with the objects, such as return them to a Power Automate

flow.
console.log(jsonArray);
}
Confira também
Chamada de API externa nos scripts do Office
Exemplo: usar chamadas de busca externas em Scripts do Office
Como usar arquivos habilitados para
macro em fluxos do Power Automate
Artigo • 25/10/2023
Os fluxos do Power Automate dão suporte a arquivos .xlsm no conector do Excel

Online (Business ).
） Importante
As macros contidas nos arquivos .xlsm não podem ser executadas por meio do
Power Automate. Somente scripts do Office estão habilitados lá.
A ação Executar script permite selecionar arquivos .xlsm. Outras ações do conector
exigem que você use a ID do arquivo. Obtenha essa ID com a ação Obter metadados de
arquivo dos conectores do OneDrive for Business ou do SharePoint . Use o
conteúdo dinâmico de ID retornado da ação Obter metadados de arquivo como o
argumento "Arquivo" para ações do conector do Excel.
２ Aviso
Alguns arquivos .xlsm, especialmente aqueles com controles ActiveX ou Form,

podem não funcionar no conector online do Excel. Certifique-se de testar antes de
implantar sua solução.
Confira também
Referência do conector do Excel Online (Business)
Trabalhar com Tabelas Dinâmicas no
Office Scripts
Artigo • 25/10/2023
As Tabelas Dinâmicas permitem analisar grandes coleções de dados rapidamente. Com

o poder deles vem a complexidade. As APIs de Scripts do Office permitem personalizar
uma Tabela Dinâmica para atender às suas necessidades, mas o escopo do conjunto de
API torna a introdução um desafio. Este artigo demonstra como executar tarefas
comuns de Tabela Dinâmica e explica classes e métodos importantes.
７ Observação
Para entender melhor o contexto dos termos usados pelas APIs, leia primeiro a
documentação da Tabela Dinâmica do Excel. Comece com Criar uma Tabela
Dinâmica para analisar dados de planilha .
Modelo de objetos
A Tabela Dinâmica é o objeto central para Tabelas Dinâmicas na API de Scripts do Office.
O objeto Workbook tem uma coleção de todas as Tabelas Dinâmicas. Cada Planilha
também contém uma coleção de Tabela Dinâmica que é local para essa planilha.
Uma Tabela Dinâmica contém PivotHierarchies. Uma hierarquia pode ser
considerada como uma coluna em uma tabela.
PivotHierarchies podem ser adicionados como linhas ou colunas
(RowColumnPivotHierarchy), dados (DataPivotHierarchy) ou filtros
(FilterPivotHierarchy).
Cada PivotHierarchy contém exatamente um PivotField. Estruturas de tabela
dinâmica fora do Excel podem conter vários campos por hierarquia, portanto, esse
design existe para dar suporte a opções futuras. Para Scripts do Office, campos e
hierarquias mapeiam para as mesmas informações.
Um PivotFieldcontém vários PivotItems. Cada PivotItem é um valor exclusivo no
campo. Pense em cada item como um valor na coluna de tabela. Os itens também
poderão ser valores agregados, como somas, se o campo estiver sendo usado para
dados.
O PivotLayout define como os PivotFields e PivotItems são exibidos .
PivotFilters filtram dados da Tabela Dinâmica usando critérios diferentes.
Para examinar como essas relações funcionam na prática, comece baixando a pasta de
trabalho de exemplo. Esses dados descrevem as vendas de frutas de várias fazendas. É a
base para todos os exemplos neste artigo. Execute os scripts de exemplo ao longo do
artigo para criar e explorar tabelas dinâmicas.
Baixar a pasta de trabalho de exemplo
Criar uma tabela dinâmica com campos

As tabelas dinâmicas são criadas com referências aos dados existentes. Intervalos e
tabelas podem ser a origem de uma Tabela Dinâmica. Eles também precisam de um
lugar para existir na pasta de trabalho. Como o tamanho de uma Tabela Dinâmica é
dinâmico, apenas o canto superior esquerdo do intervalo de destino é especificado.
O snippet de código a seguir cria uma Tabela Dinâmica com base em um intervalo de
dados. A Tabela Dinâmica não tem hierarquias, portanto, os dados ainda não estão
agrupados de forma alguma.
TypeScript
const dataSheet = workbook.getWorksheet("Data");

const pivotSheet = workbook.getWorksheet("Pivot");
const farmPivot = pivotSheet.addPivotTable(

"Farm Pivot", /* The name of the PivotTable. */
dataSheet.getUsedRange(), /* The source data range. */
pivotSheet.getRange("A1") /* The location to put the new PivotTable.
*/);
Hierarquias e campos
As tabelas dinâmicas são organizadas por meio de hierarquias. Essas hierarquias são
usadas para pivotar dados quando adicionadas como um tipo específico de hierarquia.
Há quatro tipos de hierarquias.
Linha: exibe itens em linhas horizontais.

Coluna: exibe itens em colunas verticais.
Dados: exibe agregações de valores com base nas linhas e colunas.
Filtro: adicionar ou remover itens da Tabela Dinâmica.
Uma Tabela Dinâmica pode ter tantos ou poucos de seus campos atribuídos a essas
hierarquias específicas. Uma Tabela Dinâmica precisa de pelo menos uma hierarquia de
dados para mostrar dados numéricos resumidos e pelo menos uma linha ou coluna para
pivotar esse resumo. O snippet de código a seguir adiciona duas hierarquias de linha e
duas hierarquias de dados.
TypeScript
farmPivot.addRowHierarchy(farmPivot.getHierarchy("Farm"));
farmPivot.addRowHierarchy(farmPivot.getHierarchy("Type"));
farmPivot.addDataHierarchy(farmPivot.getHierarchy("Crates Sold at Farm"));
farmPivot.addDataHierarchy(farmPivot.getHierarchy("Crates Sold
Wholesale"));
Intervalos de layout
Cada parte da Tabela Dinâmica é mapeada para um intervalo. Isso permite que seu
script obtenha dados da Tabela Dinâmica para uso posterior no script ou para ser
retornado em um fluxo do Power Automate. Esses intervalos são acessados por meio do
objeto PivotLayout adquirido de PivotTable.getLayout() . O diagrama a seguir mostra
os intervalos retornados pelos métodos em PivotLayout .
Saída total da Tabela Dinâmica
O local da linha total é baseado no layout. Use PivotLayout.getBodyAndTotalRange e
obtenha a última linha da coluna para usar os dados da Tabela Dinâmica em seu script.
O exemplo a seguir encontra a primeira Tabela Dinâmica na pasta de trabalho e registra

os valores nas células "Grand Total" (conforme realçado em verde na imagem abaixo).
TypeScript
// Get the first PivotTable in the workbook.
const pivotTable = workbook.getPivotTables()[0];
// Get the names of each data column in the PivotTable.

const pivotColumnLabelRange =
pivotTable.getLayout().getColumnLabelRange();
// Get the range displaying the pivoted data.

const pivotDataRange = pivotTable.getLayout().getBodyAndTotalRange();
// Get the range with the "grand totals" for the PivotTable columns.
const grandTotalRange = pivotDataRange.getLastRow();
// Print each of the "Grand Totals" to the console.

grandTotalRange.getValues()[0].forEach((column, columnIndex) => {
console.log(`Grand total of ${pivotColumnLabelRange.getValues()[0]
[columnIndex]}: ${grandTotalRange.getValues()[0][columnIndex]}`);
// Example log: "Grand total of Sum of Crates Sold Wholesale: 11000"
});
}
Filtros e segmentações
Há três maneiras de filtrar uma Tabela Dinâmica.
FilterPivotHierarchies
PivotFilters
Slicers
FilterPivotHierarchies
FilterPivotHierarchies adicione uma hierarquia adicional para filtrar cada linha de
dados. Qualquer linha com um item filtrado é excluída da Tabela Dinâmica e seus
resumos. Como esses filtros são baseados em itens, eles funcionam apenas em valores
discretos. Se "Classificação" for uma hierarquia de filtro em nosso exemplo, os usuários
poderão selecionar os valores de "Orgânico" e "Convencional" para o filtro. Da mesma
forma, se "Crates Sold Wholesale" for selecionado, as opções de filtro serão os números
individuais, como 120 e 150, em vez de intervalos numéricos.
FilterPivotHierarchies são criados com todos os valores selecionados. Isso significa
que nada é filtrado até que o usuário interaja manualmente com o controle de filtro ou
um PivotManualFilter seja definido no campo que pertence ao FilterPivotHierarchy .
O snippet de código a seguir adiciona "Classificação" como uma hierarquia de filtro.

TypeScript
farmPivot.addFilterHierarchy(farmPivot.getHierarchy("Classification"));
PivotFilters
O PivotFilters objeto é uma coleção de filtros aplicados a um único campo. Como
cada hierarquia tem exatamente um campo, você deve sempre usar o primeiro campo
em PivotHierarchy.getFields() ao aplicar filtros. Há quatro tipos de filtro.
Filtro de data: filtragem baseada em data de calendário.

Filtro de rótulo: filtragem de comparação de texto.
Filtro manual: filtragem de entrada personalizada.
Filtro de valor: filtragem de comparação de números. Isso compara itens na
hierarquia associada a valores em uma hierarquia de dados especificada.
Normalmente, apenas um dos quatro tipos de filtros é criado e aplicado ao campo. Se o

script tentar usar filtros incompatíveis, um erro será gerado com o texto "O argumento é
inválido ou ausente ou tem um formato incorreto".
O snippet de código a seguir adiciona dois filtros. O primeiro é um filtro manual que
seleciona itens em uma hierarquia de filtro "Classificação" existente. O segundo filtro
remove todas as fazendas que têm menos de 300 "Crates Sold Wholesale". Observe que
isso filtra a "Soma" dessas fazendas, não as linhas individuais dos dados originais.
TypeScript
const classificationField =
farmPivot.getFilterHierarchy("Classification").getFields()[0];
classificationField.applyFilter({
manualFilter: {
selectedItems: ["Organic"] /* The included items. */
}
});
const farmField = farmPivot.getHierarchy("Farm").getFields()[0];

farmField.applyFilter({
valueFilter: {
condition: ExcelScript.ValueFilterCondition.greaterThan, /* The
relationship of the value to the comparator. */
comparator: 300, /* The value to which items are compared. */
value: "Sum of Crates Sold Wholesale" /* The name of the data
hierarchy. Note the "Sum of" prefix. */
}
});
Segmentações de dados
Os segmentadores filtram dados em uma Tabela Dinâmica (ou tabela padrão). Eles
são objetos moveveis na planilha que permitem seleções de filtragem rápida. Uma
segmentação opera de forma semelhante ao filtro manual e PivotFilterHierarchy . Os
itens do PivotField são alternados para incluí-los ou excluí-los da Tabela Dinâmica.
O snippet de código a seguir adiciona uma segmentação para o campo "Tipo". Ele
define os itens selecionados como "Lemon" e "Lime", em seguida, move a segmentação
de 400 pixels para a esquerda.
TypeScript
const fruitSlicer = pivotSheet.addSlicer(

farmPivot, /* The table or PivotTale to be sliced. */
farmPivot.getHierarchy("Type").getFields()[0] /* What source to use as
the slicer options. */
);
fruitSlicer.selectItems(["Lemon", "Lime"]);
fruitSlicer.setLeft(400);
Confira também
Solucionar problemas de scripts do
Office
Artigo • 27/01/2024
À medida que você desenvolve scripts do Office, você pode cometer erros. Tudo bem,
está tudo bem. Você tem as ferramentas para ajudar a encontrar os problemas e fazer
com que seus scripts funcionem perfeitamente.
７ Observação
Para solucionar problemas de conselhos específicos dos Scripts do Office com o

Power Automate, consulte Solucionar problemas de scripts do Office em
execução no Power Automate.
Limites e requisitos da plataforma

Para obter uma lista detalhada de limitações na plataforma scripts do Office devido ao
Excel, Power Automate ou outras tecnologias, consulte Limites e requisitos de
plataforma com scripts do Office.
Erros de script
Os erros de Scripts do Office se enquadram em uma das duas categorias:
Erros ou avisos de tempo de compilação

Erros de runtime
Erros de tempo de compilação

Erros e avisos de tempo de compilação são mostrados inicialmente no Editor de Código.
Estes são mostrados pelos sublinhados vermelhos ondulados no editor. Eles também
são exibidos na guia Problemas na parte inferior do painel de tarefas Editor de Código.
Selecionar o erro fornece mais detalhes sobre o problema e sugere soluções. Erros de
tempo de compilação devem ser resolvidos antes de executar o script.
Você também pode ver sublinhados de aviso laranja e mensagens informativas cinzas.
Elas indicam sugestões de desempenho ou outras possibilidades em que o script pode
ter efeitos não intencionais. Tais avisos devem ser examinados de perto antes de
descartá-los.
Erros de runtime
Erros de runtime ocorrem devido a problemas lógicos no script. Isso pode ser porque
um objeto usado no script não está na pasta de trabalho, uma tabela é formatada de
forma diferente do previsto, ou alguma outra pequena discrepância entre os requisitos
do script e a pasta de trabalho atual. O script a seguir gera um erro quando uma
planilha chamada "TestSheet" não está presente.
TypeScript

let mySheet = workbook.getWorksheet('TestSheet');
// This will throw an error if there is no "TestSheet".

mySheet.getRange("A1");
}
Alguns erros de runtime são causados por exceder os limites da plataforma, como
tentar gravar muitos dados ao mesmo tempo com Excel na Web. Consulte Limites e
requisitos da plataforma com scripts do Office para obter uma lista completa de
possíveis armadilhas.
Mensagens de console
Erros de tempo de compilação e de runtime exibem mensagens de erro no console
quando um script é executado. Eles dão um número de linha onde o problema foi
encontrado. Tenha em mente que a causa raiz de qualquer problema pode ser uma
linha de código diferente do indicado no console.
A imagem a seguir mostra a saída do console para o erro explícito any do compilador.
Observe o texto [5, 16] no início da cadeia de caracteres de erro. Isso indica que o erro
está na linha 5, começando no caractere 16.
A imagem a seguir mostra a saída do console para um erro de runtime. Aqui, o script
tenta adicionar uma planilha com o nome de uma planilha existente. Novamente,
observe a "Linha 2" anterior ao erro para mostrar qual linha investigar.
Logs de console
Imprimir mensagens na tela com a instrução console.log . Esses logs podem mostrar o
valor atual de variáveis ou quais caminhos de código estão sendo disparados. Para fazer
isso, chame console.log com qualquer objeto como parâmetro. Normalmente, um
string é o tipo mais fácil de ler no console.
TypeScript
console.log("Logging myRange's address.");

console.log(myRange.getAddress());
As cadeias de caracteres passadas para console.log são exibidas no console de log do

Editor de Código, na parte inferior do painel de tarefas. Os logs são encontrados na guia
Saída , embora a guia ganhe automaticamente o foco quando um log é gravado.
Os logs não afetam a pasta de trabalho.

Guia Automatizar não aparecendo ou Scripts
do Office indisponíveis
As etapas a seguir devem ajudar a solucionar problemas relacionados à guia
Automatizar que não aparece no Excel.
1. Verifique se sua licença do Microsoft 365 inclui scripts do Office.

2. Verifique se cookies de terceiros estão habilitados (ao usar Excel na Web).
3. Verifique se o administrador não desabilitou scripts do Office no Centro de
administração do Microsoft 365.
4. Verifique se o administrador não configurou uma política de grupo para bloquear
scripts do Office (somente Windows).
5. Instale o WebView2 (somente Windows).
6. Verifique se você não está conectado como um usuário externo ou convidado ao
seu locatário.
） Importante
Ao usar o Excel com o Teams, os Scripts do Office só têm suporte no Teams na Web
(não no Teams para Windows, Mac, iOS ou Android).
７ Observação
Há um problema conhecido que impede que scripts armazenados no SharePoint

sempre apareçam na lista usada recentemente. Isso ocorre quando o administrador
desativa o EWS (Exchange Web Services). Seus scripts baseados em SharePoint
ainda estão acessíveis e utilizáveis por meio da caixa de diálogo de arquivo.
Problemas ao agendar um script

Agendar um script requer uma licença comercial para o Microsoft 365. Isso é necessário
para o fluxo do Power Automate que alimenta o script agendado. Erros desse fluxo são
mostrados quando há problemas de agendamento. Talvez seja necessário atualizar
manualmente seu fluxo no Power Automate , onde ele será listado em Meus fluxos.
A lista a seguir mostra erros comuns que você pode encontrar.
A hora UTC de expiração do token de acesso é anterior à hora UTC atual.: passou
muito tempo entre entrar no serviço e agendar o script. Reabra o script no Editor
de Código ou recarregue a pasta de trabalho e tente agendar novamente.
Recursos de ajuda
O Stack Overflow é uma comunidade de desenvolvedores dispostos a ajudar com
problemas de codificação. Muitas vezes, você poderá encontrar a solução para o
problema por meio de uma pesquisa rápida do Stack Overflow. Caso contrário, faça sua
pergunta e marque-a com a marca "office-scripts". Certifique-se de menção você está
criando um Script do Office, não um Suplemento do Office.
Confira também
Práticas recomendadas nos Scripts do Office
Limites de plataforma com scripts do Office
Solucionar problemas de scripts do Office em execução no PowerAutomate
comentários:
Solucionar problemas de scripts do
Office em execução no Power Automate
Artigo • 29/11/2023
O Power Automate executa scripts em seu nome em sessões independentes do Excel.

Isso causa algumas alterações comportamentais que podem criar problemas com
determinados scripts ou cenários. Há também limitações e comportamentos dos
roteiristas de script de plataforma do Power Automate que devem saber. Leia os artigos
Solucionar problemas de scripts e requisitos de plataforma do Office com scripts do
Office, pois grande parte dessas informações também se aplica a scripts em fluxos.
 Dica
Se você estiver apenas começando a usar scripts do Office com o Power Automate,
comece com Executar Scripts do Office com o Power Automate para saber mais
sobre as plataformas.
Evitar referências relativas

O Power Automate executa seu script na pasta de trabalho do Excel escolhida em seu
nome. A pasta de trabalho pode ser fechada quando isso acontecer. Qualquer API que
dependa do estado atual do usuário, como Workbook.getActiveWorksheet , pode se
comportar de forma diferente no Power Automate. Isso ocorre porque as APIs são
baseadas em uma posição relativa da exibição ou cursor do usuário e essa referência
não existe em um fluxo do Power Automate.
Algumas APIs de referência relativa lançam erros no Power Automate. Outros têm um
comportamento padrão que implica o estado de um usuário. Ao projetar seus scripts,
use referências absolutas para planilhas e intervalos. Isso torna o fluxo do Power
Automate consistente, mesmo que as planilhas sejam reorganizadas.
Métodos de script que falham nos fluxos do Power

Automate
Os métodos a seguir geram um erro e falham quando chamados de um script em um
fluxo do Power Automate.
ﾉ Expand table
Classe Método
Gráfico activate
Range select
Pasta de trabalho getActiveCell
Pasta de trabalho getActiveChart
Pasta de trabalho getActiveSlicer
Pasta de trabalho getSelectedRange
Pasta de trabalho getSelectedRanges
Métodos de script com um comportamento padrão nos

fluxos do Power Automate
Os métodos a seguir usam um comportamento padrão, em vez do estado atual de
qualquer usuário.
ﾉ Expand table
Classe Método Comportamento do Power Automate
Pasta de getActiveWorksheet Retorna a primeira planilha na pasta de trabalho ou a

trabalho planilha ativada atualmente pelo Worksheet.activate
método.
Planilha activate Marca a planilha como a planilha ativa para fins de

Workbook.getActiveWorksheet .
Atualizar sem suporte total no Power Automate

Os Scripts do Office não podem atualizar a maioria dos dados quando executados no
Power Automate. A maioria dos métodos de atualização, como PivotTable.refresh , não
faz nada quando chamado em um fluxo. Workbook.refreshAllDataConnections só é
atualizado quando o PowerBI é a origem. Além disso, o Power Automate não dispara
uma atualização de dados para fórmulas que usam links de pasta de trabalho.
Métodos de script que não fazem nada nos fluxos do
Power Automate
Os métodos a seguir não fazem nada em um script quando chamados por meio do
Power Automate. Eles ainda retornam com êxito e não lançam erros.
ﾉ Expand table
Classe Método
PivotTable refresh
Pasta de trabalho refreshAllPivotTables
Planilha refreshAllPivotTables
Métodos de script com um comportamento diferente no

Power Automate
Os métodos a seguir agem de forma diferente nos fluxos do Power Automate do que
quando executados pelo Excel.
ﾉ Expand table
Classe Método Comportamento do Power Automate
Pasta de refreshAllDataConnections Só atualiza as fontes do PowerBI. Para outras fontes,

trabalho o método retorna com êxito, mas não faz nada.
Selecionar pastas de trabalho com o controle

do navegador de arquivos
Ao criar a etapa Executar script de um fluxo do Power Automate, você precisa
selecionar qual pasta de trabalho faz parte do fluxo. Use o navegador de arquivos para
selecionar sua pasta de trabalho, em vez de digitar manualmente o nome da pasta de
trabalho.
Para obter mais contexto sobre a limitação do Power Automate e uma discussão sobre
possíveis soluções alternativas para a seleção dinâmica de pastas de trabalho, confira
este thread na Comunidade do Microsoft Power Automate .
Passar matrizes inteiras como parâmetros de

script
O Power Automate permite que os usuários passem matrizes para conectores como
uma variável ou como elementos únicos na matriz. O padrão é passar elementos únicos,
o que cria a matriz no fluxo. Para scripts ou outros conectores que tomam matrizes
inteiras como argumentos, você precisa selecionar o botão Alternar para inserir a
matriz inteira para passar a matriz como um objeto completo. Este botão está no canto
superior direito de cada campo de entrada de parâmetro de matriz.
Diferenças de fuso horário
Os arquivos do Excel não têm um local inerente ou um fuso horário. Sempre que um
usuário abre a pasta de trabalho, sua sessão usa o fuso horário local desse usuário para
cálculos de data. O Power Automate sempre usa UTC.
Se o script usar datas ou horários, poderá haver diferenças comportamentais quando o

script for testado localmente versus quando ele for executado pelo Power Automate. O
Power Automate permite converter, formatar e ajustar os horários. Consulte Trabalhar
com Datas e Horários dentro de seus fluxos para obter instruções sobre como usar
essas funções no Power Automate e Passar dados de e para scripts no Power Automate
para saber como fornecer essas informações de tempo para o script.
Campos de parâmetro de script ou saída

retornada não aparecendo no Power Automate
Há dois motivos para que os parâmetros ou dados retornados de um script não sejam
refletidos com precisão no construtor de fluxo do Power Automate.
A assinatura de script (os parâmetros ou valor retornado) foi alterada desde que o
conector do Excel Business (Online) foi adicionado.
A assinatura de script usa tipos sem suporte. Verifique seus tipos em relação às
restrições para o parâmetro scripts do Office e os tipos de retorno.
A assinatura de um script é armazenada com o conector do Excel Business (Online)

quando ele é criado. Remova o conector antigo e crie um novo para obter os
parâmetros mais recentes e retornar valores para a ação Executar script .
Confira também
Solucionar problemas de scripts do Office
Documentação de referência do conector do Excel Online (Business)
Melhorar o desempenho dos scripts do
Office
Artigo • 07/04/2023
A finalidade dos Scripts do Office é automatizar uma série de tarefas normalmente

executadas para economizar tempo. Um script lento pode parecer que ele não acelera o
fluxo de trabalho. Na maioria das vezes, seu script ficará perfeitamente bem e será
executado conforme o esperado. No entanto, há alguns cenários evitáveis que podem
afetar o desempenho.
O motivo mais comum para um script lento é a comunicação excessiva com a pasta de
trabalho. Isso é particularmente perceptível ao usar Excel na Web. Em determinados
momentos, seu script sincroniza seus dados locais com os da pasta de trabalho. Isso
significa que todas as operações de gravação (como workbook.addWorksheet() ) só são
aplicadas à pasta de trabalho quando essa sincronização nos bastidores acontece. Da
mesma forma, todas as operações de leitura (como myRange.getValues() ) só obtêm
dados da pasta de trabalho para o script nesses momentos. Em ambos os casos, o script
busca informações antes de agir nos dados. Por exemplo, o código a seguir registrará
com precisão o número de linhas no intervalo usado.
TypeScript
let usedRange = workbook.getActiveWorksheet().getUsedRange();

let rowCount = usedRange.getRowCount();
// The script will read the range and row count from
// the workbook before logging the information.
console.log(rowCount);
As APIs de Scripts do Office garantem que todos os dados na pasta de trabalho ou

script sejam precisos e atualizados quando necessário. Você não precisa se preocupar
com essas sincronizações para que seu script seja executado corretamente. No entanto,
uma consciência dessa comunicação script-para-nuvem pode ajudá-lo a evitar
chamadas de rede desnecessárias.
Otimizações de desempenho
Você pode aplicar técnicas simples para ajudar a reduzir a comunicação com a nuvem.
Os padrões a seguir ajudam a acelerar seus scripts.
Leia dados da pasta de trabalho uma vez em vez de repetidamente em um loop.

Remova instruções desnecessárias console.log .
Evite usar blocos de tentativa/captura.
Ler dados de pasta de trabalho fora de um loop

Qualquer método que obtenha dados da pasta de trabalho pode disparar uma chamada
de rede. Em vez de fazer repetidamente a mesma chamada, você deve salvar dados
localmente sempre que possível. Isso é especialmente verdadeiro ao lidar com loops.
Considere um script para obter a contagem de números negativos no intervalo usado

de uma planilha. O script precisa iterar em todas as células do intervalo usado. Para
fazer isso, ele precisa do intervalo, do número de linhas e do número de colunas. Você
deve armazená-los como variáveis locais antes de iniciar o loop. Caso contrário, cada
iteração do loop forçará um retorno à pasta de trabalho.
TypeScript
/**
* This script provides the count of negative numbers that are present
* in the used range of the current worksheet.
*/
// Get the working range.
let usedRange = workbook.getActiveWorksheet().getUsedRange();
// Save the values locally to avoid repeatedly asking the workbook.

let usedRangeValues = usedRange.getValues();
// Start the negative number counter.

let negativeCount = 0;
// Iterate over the entire range looking for negative numbers.

for (let i = 0; i < usedRangeValues.length; i++) {
for (let j = 0; j < usedRangeValues[i].length; j++) {
if (usedRangeValues[i][j] < 0) {
negativeCount++;
}
}
}
// Log the negative number count to the console.

console.log(negativeCount);
}
７ Observação
Como um experimento, tente substituir usedRangeValues no loop por
usedRange.getValues() . Você pode notar que o script leva consideravelmente mais
tempo para ser executado ao lidar com grandes intervalos.
Evitar o uso de try...catch blocos em loops ou ao redor

Não recomendamos usar try...catch instruções em loops ou loops ao redor. Isso é pelo
mesmo motivo pelo qual você deve evitar a leitura de dados em um loop: cada iteração
força o script a sincronizar com a pasta de trabalho para garantir que nenhum erro
tenha sido gerado. A maioria dos erros pode ser evitada verificando objetos retornados
da pasta de trabalho. Por exemplo, o script a seguir verifica se a tabela retornada pela
pasta de trabalho existe antes de tentar adicionar uma linha.
TypeScript
/**
* This script adds a row to "MyTable", if that table is present.
*/
let table = workbook.getTable("MyTable");
// Check if the table exists.

if (table) {
// Add the row.
table.addRow(-1, ["2012", "Yes", "Maybe"]);
} else {
// Report the missing table.
console.log("MyTable not found.");
}
}
Remover instruções desnecessárias console.log

O log do console é uma ferramenta vital para depurar seus scripts. No entanto, ele força
o script a sincronizar com a pasta de trabalho para garantir que as informações
registradas sejam atualizadas. Considere remover instruções de log desnecessárias
(como as usadas para testes) antes de compartilhar seu script. Normalmente, isso não
causará um problema de desempenho perceptível, a menos que a console.log()
instrução esteja em um loop.
Ajuda caso a caso

À medida que a plataforma Scripts do Office se expande para trabalhar com Power
Automate , Cartões Adaptáveis e outros recursos entre produtos, os detalhes da
comunicação script-pasta de trabalho se tornam mais complexos. Se você precisar de
ajuda para que seu script seja executado mais rapidamente, entre em contato com o
Microsoft Q&A. Certifique-se de marcar sua pergunta com "office-scripts-dev" para que
os especialistas possam encontrá-la e ajudar.
Confira também
Documentos web MDN: loops e iteração
Limites e requisitos da plataforma com
scripts do Office
Artigo • 12/01/2024
Há algumas limitações de plataforma das quais você deve estar ciente ao desenvolver
scripts do Office. Este artigo detalha o suporte do navegador e os limites de dados para
Scripts do Office para Excel.
Suporte à plataforma
Para utilizar os Scripts do Office, você precisará do seguinte.
1. Excel para Windows (versão 2210 ou superior), Excel para Mac ou Excel na
Web.
O Gravador de Ações ainda não está disponível no Canal Da Empresa

Semestral.
2. OneDrive for Business.

3. Qualquer licença comercial ou educacional do Microsoft 365 com acesso aos
aplicativos para desktop do Microsoft Office 365, como:
Office 365 Business

Office 365 Business Premium
Office 365 ProPlus
Office 365 ProPlus para dispositivos
Office 365 Enterprise E3
Office 365 Enterprise E5
Office 365 A3
Office 365 A5
4. Conectividade com a Internet com experiências conectadas habilitadas.
７ Observação
Se você atender aos requisitos e ainda não estiver vendo a guia Automatizar, é
possível que o seu administrador tenha desabilitado o recurso ou que haja outro
problema em seu ambiente. Siga as etapas em Guia Automatizar não aparecem ou
Scripts do Office não disponíveis para começar a usar os Scripts do Office.
Para usar scripts do Office no Power Automate , você deve ter uma licença comercial
do Microsoft 365.
Limites de dados
Há limites sobre a quantidade de dados do Excel que podem ser transferidos ao mesmo
tempo e quantas transações individuais do Power Automate podem ser realizadas.
Excel
Excel na Web tem as seguintes limitações ao fazer chamadas para a pasta de trabalho
por meio de um script.
As solicitações e respostas são limitadas a 5MB.

Um intervalo é limitado a cinco milhões de células.
Se você estiver encontrando erros ao lidar com conjuntos de dados grandes, tente usar
vários intervalos menores em vez de intervalos maiores. Para obter um exemplo,
consulte o exemplo Gravar um conjunto de dados grande . Você também pode usar
APIs como Range.getSpecialCells para direcionar células específicas em vez de grandes
intervalos.
Os limites do Excel que não são específicos para scripts do Office podem ser
encontrados no artigo Especificações e limites do Excel .
Power Automate
As limitações a seguir com a plataforma Power Automate são as que você
provavelmente encontrará.
Cada usuário é limitado a 1.600 chamadas para a ação Executar script por dia. Esse
limite é redefinido às 12:00 UTC.
Há um tempo limite de 120 segundos para operações síncronas do Power
Automate. Para scripts de longa duração, você deve otimizar seu script ou dividir
sua automação do Excel em várias chamadas de script.
O tamanho máximo dos parâmetros passados para a ação Executar script é de
30.000.000 bytes (28.6MB).
Limitações adicionais de uso da plataforma do Power Automate podem ser encontradas
nos artigos a seguir.
Limites e configuração no Power Automate

Problemas e limitações conhecidos para o conector do Excel Online (Business)
Power Automate restrições específicas

Há algumas diferenças importantes entre executar um script no aplicativo excel e
executar um script como parte de um fluxo do Power Automate.
Nenhuma chamada externa de um script

As chamadas de API externas falham quando um script é executado por meio do Power
Automate. Uma fetch chamada fornecerá a mensagem de erro "Erro de runtime: Linha
X: a busca não está definida". Certifique-se de marcar seus scripts para essas referências
antes de transformá-los em um fluxo.
Você terá que usar HTTP com Azure AD ou outras ações equivalentes para extrair dados
ou empurrá-los para um serviço externo.
２ Aviso
As chamadas externas feitas por meio do conector do Power Automate Excel

Online falham para ajudar a manter as políticas de prevenção de perda de dados
existentes. No entanto, scripts executados por meio do Power Automate são feitos
fora da sua organização e fora dos firewalls da sua organização. Para proteção
adicional contra usuários mal-intencionados nesse ambiente externo, o
administrador pode controlar o uso de Scripts do Office. Seu administrador pode
desabilitar o conector do Excel Online no Power Automate ou desativar scripts do
Office para Excel por meio dos controles de administrador do Office Scripts.
Diferenças de comportamento da API

Algumas APIs se comportam de forma diferente quando executadas com o Power
Automate. Outros falham devido à dependência da interface do usuário do Excel. As
listas completas são encontradas em Solucionar problemas de scripts do Office em
execução no Power Automate.
Não há suporte para pastas de trabalho iso estritas do
Open XML
A ação executar script do conector do Excel Business (Online) não dá suporte a pastas
de trabalho com a versão estrita ISO do formato de arquivo da Pasta de Trabalho do
Excel . Fluxos com esse tipo de pasta de trabalho retornam um erro "BadGateway" ao
tentar executar um script. Isso ocorre devido a restrições de coautoria. Salve as pastas
de trabalho como o formato padrão da Pasta de Trabalho do Excel para uso com o
Power Automate.
Suporte do Teams
） Importante
Ao usar o Excel com o Teams, os Scripts do Office só têm suporte no Teams na Web
(não no Teams para Windows, Mac, iOS ou Android).
Suporte de nuvem do Governo

Não há suporte para scripts do Office no GCC High ou superior. Chamadas externas de
scripts podem ser afetadas por configurações de firewall em outras nuvens do governo.
Cookies de terceiros para Excel na Web

Seu navegador precisa de cookies de terceiros habilitados para mostrar a guia
Automatizar no Excel na Web. Verifique as configurações do navegador se a guia não
está sendo exibida. Se você estiver usando uma sessão privada do navegador, talvez
seja necessário habilitar novamente essa configuração sempre.
７ Observação
Alguns navegadores se referem a essa configuração como "todos os cookies", em

vez de "cookies de terceiros".
Como ajustar as configurações de cookie em

navegadores populares
Chrome
Borda
Firefox
Safari
Acesso Condicional
As políticas de acesso condicional restringem o acesso ao SharePoint e ao OneDrive
para dispositivos não gerenciados. Se o dispositivo não for gerenciado pelo locatário,
talvez você não tenha acesso a scripts específicos ou só poderá acessá-los por meio do
navegador.
Se o script for bloqueado por políticas de Acesso Condicional, você receberá uma das
duas mensagens de erro. Essas mensagens também aparecerão no Power Automate se
o fluxo for executado de um dispositivo não gerenciado.
"Devido a políticas organizacionais, você não pode acessar esse recurso desse
dispositivo não confiável."
"Não é possível localizar esse script. Pode ter sido excluído por outro usuário." (Se
sua versão do Excel for mais antiga.)
） Importante
Os administradores devem considerar bloquear todo o acesso ao Power Automate

de dispositivos não gerenciados. Esse processo é detalhado na postagem do blog
Control Access to Power Apps and Power Automate with Azure AD Conditional
Access Policies .
Suporte à API em versões mais antigas do Excel

Algumas APIs de Scripts do Office podem não ter suporte do Excel para Windows ou
Excel para Mac, especialmente builds mais antigos. Elas incluem APIs e APIs mais
recentes para recursos somente da Web. Se um script contiver APIs sem suporte, o
Editor de Código exibirá um aviso. Se você tentar executar esse script, ele não será
executado. Em vez disso, o painel de tarefas Status de Execução de Script exibe uma
mensagem de aviso que diz: "Este script deve ser executado no momento em Excel para
a Web. Abra a pasta de trabalho no navegador e tente novamente ou entre em contato
com o proprietário do script para obter ajuda.".
Usar uma versão mais antiga do Excel para abrir pastas de trabalho com scripts
compartilhados neles não tem efeito sobre o script em si.
Confira também
Especificações e limites do Excel
Solucionar problemas de scripts do Office
Restrições de TypeScript em Scripts do
Office
Artigo • 07/04/2023
Os Scripts do Office usam a linguagem TypeScript. Na maioria das vezes, qualquer

código TypeScript ou JavaScript funcionará em Scripts do Office. No entanto, há
algumas restrições impostas pelo Editor de Código para garantir que seu script funcione
de forma consistente e conforme pretendido com sua pasta de trabalho do Excel.
Nenhum tipo 'qualquer' em Scripts do Office

Os tipos de gravação são opcionais no TypeScript, pois os tipos podem ser inferidos.
No entanto, os Scripts do Office exigem que uma variável não possa ser do tipo
nenhum . Não são permitidos scripts explícitos e implícitos any em Scripts do Office.
Esses casos são relatados como erros.
Explícita any
Você não pode declarar explicitamente uma variável como do tipo any em Scripts do
Office (ou seja, let value: any; ). O any tipo causa problemas quando processado pelo
Excel. Por exemplo, é Range necessário saber que um valor é um string , number ou
boolean . Você receberá um erro de tempo de compilação (um erro antes de executar o
script) se alguma variável for explicitamente definida como o any tipo no script.
Na captura de tela anterior, [2, 14] Explicit Any is not allowed indica que a linha nº
2, a coluna #14 define any o tipo. Isso ajuda você a localizar o erro.
Para contornar esse problema, sempre defina o tipo da variável. Se você não tiver
certeza sobre o tipo de variável, poderá usar um tipo de união . Isso pode ser útil para
variáveis que contêm Range valores, que podem ser do tipo string , number ou boolean
(o tipo de Range valores é uma união desses: string | number | boolean ).
Implícita any
Tipos de variável TypeScript podem ser definidos implicitamente . Se o compilador
TypeScript não conseguir determinar o tipo de uma variável (porque o tipo não está
definido explicitamente ou a inferência de tipo não é possível), é um erro implícito any
e você receberá um erro de tempo de compilação.
O caso mais comum em qualquer implícito any está em uma declaração variável, como
let value; . Há duas maneiras de evitar isso:
Atribua a variável a um tipo implicitamente identificável ( let value = 5; ou let

value = workbook.getWorksheet(); ).
Digite explicitamente a variável ( let value: number; )
Sem herdar classes ou interfaces do Office

Script
Classes e interfaces criadas no Script do Office não podem estender ou implementar
classes ou interfaces do Office Scripts. Em outras palavras, nada no ExcelScript
namespace pode ter subclasses ou subinterfaces.
Funções incompatíveis do TypeScript

As APIs de Scripts do Office não podem ser usadas no seguinte:
Funções geradoras
Array.sort
eval não tem suporte
A função eval do JavaScript não tem suporte por motivos de segurança.
Identificadores restritos
As palavras a seguir não podem ser usadas como identificadores em um script. São
termos reservados.
Excel
ExcelScript
console
Somente funções de seta em retornos de

chamada de matriz
Seus scripts só podem usar funções de seta ao fornecer argumentos de retorno de
chamada para métodos array . Você não pode passar qualquer tipo de identificador
ou função "tradicional" para esses métodos.
TypeScript
const myArray = [1, 2, 3, 4, 5, 6];

let filteredArray = myArray.filter((x) => {
return x % 2 === 0;
});
/*
The following code generates a compiler error in the Office Scripts Code
Editor.
filteredArray = myArray.filter(function (x) {
return x % 2 === 0;
});
*/
Não há suporte para uniões de ExcelScript

tipos e tipos definidos pelo usuário
Os Scripts do Office são convertidos no runtime de blocos de código síncronos para
assíncronos. A comunicação com a pasta de trabalho por meio de promessas está
oculta do criador do script. Essa conversão não dá suporte a tipos de união que
incluem ExcelScript tipos e tipos definidos pelo usuário. Nesse caso, o Promise é
retornado ao script, mas o compilador do Office Script não o espera e o criador do
script não pode interagir com o Promise .
O exemplo de código a seguir mostra uma união sem suporte entre ExcelScript.Table
e uma interface personalizada MyTable .
TypeScript

const selectedSheet = workbook.getActiveWorksheet();
// This union is not supported.

const tableOrMyTable: ExcelScript.Table | MyTable =
selectedSheet.getTables()[0];
// `getName` returns a promise that can't be resolved by the script.

const name = tableOrMyTable.getName();
// This logs "{}" instead of the table name.

console.log(name);
}
interface MyTable {
getName(): string
}
Construtores não dão suporte a APIs e console

instruções de Scripts do Office
console instruções e muitas APIs de Scripts do Office exigem sincronização com a pasta
de trabalho do Excel. Essas sincronizações usam await instruções na versão de runtime

compilada do script. await não há suporte em construtores . Se você precisar de
classes com construtores, evite usar APIs de Scripts do Office ou console instruções
nesses blocos de código.
O exemplo de código a seguir demonstra esse cenário. Ele gera um erro que diz failed
to load [code] [library] .
TypeScript

class MyClass {
constructor() {
// Console statements and Office Scripts APIs aren't supported in
constructors.
console.log("This won't print.");
}
}
let test = new MyClass();

}
Avisos de desempenho
O linter do Editor de Código fornece avisos se o script pode ter problemas de
desempenho. Os casos e como contornar eles estão documentados em Melhorar o
desempenho dos scripts do Office.
Chamadas de API externa

Consulte Suporte a chamadas de API externa nos Scripts do Office para obter mais
informações.
Confira também
Desfazer as alterações feitas pelos
Scripts do Office
Artigo • 07/04/2023
Não é possível desfazer alterações feitas na pasta de trabalho do Excel por um script
com o comando Desfazer do Excel. Em vez disso, você deve restaurar uma versão
anterior da pasta de trabalho do armazenamento em nuvem.
Histórico de versão
O histórico de versões do Office é uma maneira fácil de restaurar uma pasta de trabalho
mais antiga por meio da interface do usuário do Excel. O recurso funciona apenas para
arquivos armazenados no OneDrive ou no SharePoint Online.
Na pasta de trabalho do Excel na qual o script foi executado, use estas etapas para
desfazer os efeitos:
1. Acesse Históricodeversões de informações> dearquivo>.

2. Selecione uma versão salva antes de executar o script.
3. Selecione Restaurar.
Confira também
Exibir as versões anteriores de arquivos do Office
Exemplos e cenários de Scripts do Office
Artigo • 28/12/2023
Esta seção contém soluções baseadas em Scripts do Office que ajudam os usuários
finais a obter automação de tarefas diárias. Ele contém cenários realistas que os
usuários enfrentam e fornece soluções detalhadas.
As noções básicas mostram exemplos comuns que compõem scripts maiores. Eles
são categorizados com base em um recurso comum do Excel.
Cenários rápidos são exemplos que estão mais envolvidos ou resolvem um
problema específico.
Cenários entre aplicativos são exemplos que usam o Power Automate com um ou
mais Scripts do Office como partes integrais do fluxo.
Cenários do mundo real são alguns exemplos maiores emoldurados como
soluções completas e reais.
As contribuições da comunidade são exemplos de membros da comunidade de
Scripts do Office, muitas vezes de natureza leve.
） Importante
Certifique-se de atender aos pré-requisitos para scripts do Office antes de

experimentar os exemplos. Os requisitos para sua assinatura e conta do Microsoft
365 são encontrados no suporte à plataforma.
Noções básicas
ﾉ Expandir a tabela
Project Detalhes
Intervalos: trabalhar com a grade Esses exemplos mostram como trabalhar o Range objeto, que
é central para a maioria dos scripts.
Exemplos de formatação Esses exemplos mostram como aplicar diferentes estilos de

condicional formatação condicional a um intervalo.
Exemplos de validação de dados: Esses exemplos mostram como usar a validação de dados
listas suspensas, prompts e pop- para exigir condições específicas para dados de célula e
ups de aviso como o usuário é alertado para essas regras.
Exemplos de data Uma coleção de exemplos que mostram como traduzir entre
formatos de data JavaScript e Excel.
Project Detalhes
Exemplos de imagem Este exemplo adiciona uma imagem a uma pasta de trabalho
e copia uma imagem entre planilhas.
Exemplos de visibilidade de linha Uma coleção de exemplos que demonstram como mostrar,
e coluna ocultar e congelar linhas e colunas.
Exemplos de tabela Uma coleção de exemplos que mostram interações comuns

com tabelas do Excel.
Cenários rápidos
Baixe as pastas de trabalho de exemplo incluídas em cada exemplo. Isso permite ignorar
a instalação e entender o conceito principal que o exemplo demonstra.
Project Detalhes
Copiar várias tabelas do Excel Este exemplo combina dados de várias tabelas do Excel em uma
em uma única tabela única tabela que inclui todas as linhas.
Criar um sumário da pasta de Este exemplo cria uma tabela de conteúdo com links para cada
trabalho planilha.
Contagem de linhas em Este exemplo detecta se houver linhas em branco em planilhas

branco em uma planilha em que você prevê que os dados estejam presentes e, em
específica ou em todas as seguida, relatar a contagem de linhas em branco para uso em
planilhas um fluxo do Power Automate.
Gerenciar o modo de cálculo Este exemplo mostra como usar o modo de cálculo e calcular
no Excel métodos no Excel usando scripts do Office.
Mover linhas entre tabelas Este exemplo mostra como mover linhas entre tabelas salvando
filtros e processando e reaplicando os filtros.
Notificar as pessoas com Este exemplo adiciona comentários a uma célula, incluindo
comentários @mentioning um colega.
Saída de dados do Excel como Esta solução mostra como gerar dados de tabela do Excel como
JSON JSON a serem usados no Power Automate.
Remover hiperlinks de cada Este exemplo limpa todos os hiperlinks da planilha atual.
célula em uma planilha do
Excel
Definir formatação condicional Este exemplo aplica a formatação com base em valores em
para comparações entre colunas adjacentes. Ele também obtém a entrada do usuário
Project Detalhes
colunas por meio de parâmetros de script.
Usar chamadas de busca Este exemplo usa fetch para obter informações do GitHub para
externas o script.
Cenários entre aplicativos

Use o Power Automate para conectar outros aplicativos ao Excel. Tenha seus scripts
alimentando emails, formulários, mensagens do Teams e muito mais. Esses exemplos
incluem instruções passo a passo para criar cada fluxo do Power Automate.
Project Detalhes
Combinar planilhas Este exemplo usa Scripts do Office e Power Automate para extrair dados
em uma única pasta de outras pastas de trabalho em uma única pasta de trabalho.
de trabalho
Converter arquivos Este exemplo usa Scripts do Office e Power Automate para criar arquivos
CSV em pastas de .xlsx de arquivos .csv.
trabalho do Excel
Pastas de trabalho de Este exemplo usa Scripts do Office e Power Automate para fazer
referência cruzada referência cruzada e validar informações em diferentes pastas de
trabalho.
Email gráfico e Este exemplo usa scripts do Office e ações do Power Automate para criar
imagens de tabela um gráfico e enviar esse gráfico como uma imagem por email.
Registrar alterações Este exemplo usa um fluxo agendado do Power Automate para registrar
diárias no Excel e leituras diárias e relatar as alterações.
denunciá-las com um
fluxo
Executar um script Este exemplo executa um conjunto de tarefas de automação em todos os

em todos os arquivos arquivos situados em uma pasta em OneDrive for Business (também pode
do Excel em uma ser usado para uma pasta do SharePoint). Ele executa cálculos nos
pasta arquivos do Excel, adiciona formatação e insere um comentário que
@mentions um colega.
Escrever um grande Este exemplo mostra como trabalhar com um intervalo grande como
conjuntos de dados subranges menores. Isso ajuda os fluxos a lidar com limites de
transferência de dados e tempo limite de operação.
Cenários do mundo real
Os Scripts do Office podem automatizar partes de sua rotina diária. Essas tarefas diárias
geralmente existem em ecossistemas exclusivos, com pastas de trabalho do Excel que
são configuradas de maneiras específicas. Esses exemplos de cenário maiores
demonstram casos de uso do mundo real. Eles incluem os scripts do Office e as pastas
de trabalho, para que você possa ver o cenário de ponta a ponta.
Cenário Detalhes
Analisar downloads da Esse cenário apresenta um script que analisa registros de tráfego da
Web Web para determinar o país de origem de um usuário. Ele mostra as
habilidades de análise de texto, usando subfunções em scripts,
aplicando formatação condicional e trabalhando com tabelas.
Buscar e representar Esse cenário usa um Script do Office para extrair dados de uma fonte
graficamente os dados do externa (o banco de dados NOAA Tides and Currents ) e grafar as
nível de água do NOAA informações resultantes. Ele destaca as habilidades de usar fetch
para obter dados e usar gráficos.
Calculadora de notas Esse cenário apresenta um script que valida o registro de um

instrutor para as notas de sua classe. Ele mostra as habilidades de
verificação de erros, formatação de células e expressões regulares.
Agendar entrevistas no Esse cenário mostra como usar uma planilha do Excel para gerenciar
Teams os horários de reunião da entrevista e fazer um fluxo para agendar
reuniões no Teams.
Lembretes de tarefa como Esse cenário usa um Script do Office em um fluxo do Power
cartões do Teams Automate para enviar lembretes aos colegas de trabalho para
atualizar o status de um projeto. Ele destaca as habilidades de
integração do Power Automate e transferência de dados de e para
scripts.
Exemplos de contribuições e diversão da

comunidade
Damos as boas-vindas contribuições de nossa comunidade de Scripts do Office!
Sinta-se à vontade para criar uma solicitação de pull para revisão.
Project Detalhes
Jogo da Vida O blog "Ready Player Zero" de Yutao Huang na Excel Tech Community
inclui um script para modelar O Jogo da Vida de John Conway.
Botão Relógio do Este script foi contribuído por Brian Gonzalez . O cenário apresenta um
Sistema script e um botão de script que registra a hora atual.
Animação de Este roteiro foi contribuído por Leslie Black no espírito da temporada de
saudações de férias! É um script divertido que mostra uma árvore de Natal cantando no
estações Excel usando scripts do Office.
Deixe um comentário
Sinta-se à vontade para deixar um comentário, fazer uma sugestão ou registrar um
problema usando a seção Comentários na parte inferior da página de documentação da
amostra específica.
Intervalos: trabalhar com a grade em
Scripts do Office
Artigo • 05/12/2023
Os exemplos a seguir são scripts simples para você experimentar em suas próprias
pastas de trabalho. Eles formam os blocos de construção para soluções maiores.
Expanda esses scripts para estender sua solução e resolver problemas comuns.
Ler e registrar uma célula

Este exemplo lê o valor de A1 e o imprime no console.
TypeScript

// Get the value of cell A1.

let range = selectedSheet.getRange("A1");
// Print the value of A1.

console.log(range.getValue());
}
Ler a célula ativa

Esse script registra o valor da célula ativa atual. Se várias células forem selecionadas, a
célula superior esquerda será registrada.
TypeScript

// Get the current active cell in the workbook.
let cell = workbook.getActiveCell();
// Log that cell's value.

console.log(`The current cell's value is ${cell.getValue()}`);
}
Adicionar dados a um intervalo

Este script adiciona um conjunto de valores a uma nova planilha. Os valores começam
na célula A1. Os dados usados neste script são predefinidos, mas podem ser
provenientes de outros locais dentro ou fora da pasta de trabalho.
TypeScript

// The getData call could be replaced by input from Power Automate or a
fetch call.
const data = getData();
// Create a new worksheet and switch to it.

const newWorksheet = workbook.addWorksheet("DataSheet");
newWorksheet.activate();
// Get a range matching the size of the data.

const dataRange = newWorksheet.getRangeByIndexes(
0,
0,
data.length,
data[0].length);
// Set the data as the values in the range.

dataRange.setValues(data);
}
function getData(): string[][] {

return [["Abbreviation", "State/Province", "Country"],
["AL", "Alabama", "USA"],
["AK", "Alaska", "USA"],
["AZ", "Arizona", "USA"],
["AR", "Arkansas", "USA"],
["CA", "California", "USA"],
["CO", "Colorado", "USA"],
["CT", "Connecticut", "USA"],
["DE", "Delaware", "USA"],
["DC", "District of Columbia", "USA"],
["FL", "Florida", "USA"],
["GA", "Georgia", "USA"],
["HI", "Hawaii", "USA"],
["ID", "Idaho", "USA"],
["IL", "Illinois", "USA"],
["IN", "Indiana", "USA"],
["IA", "Iowa", "USA"],
["KS", "Kansas", "USA"],
["KY", "Kentucky", "USA"],
["LA", "Louisiana", "USA"],
["ME", "Maine", "USA"],
["MD", "Maryland", "USA"],
["MA", "Massachusetts", "USA"],
["MI", "Michigan", "USA"],
["MN", "Minnesota", "USA"],
["MS", "Mississippi", "USA"],
["MO", "Missouri", "USA"],
["MT", "Montana", "USA"],
["NE", "Nebraska", "USA"],
["NV", "Nevada", "USA"],
["NH", "New Hampshire", "USA"],
["NJ", "New Jersey", "USA"],
["NM", "New Mexico", "USA"],
["NY", "New York", "USA"],
["NC", "North Carolina", "USA"],
["ND", "North Dakota", "USA"],
["OH", "Ohio", "USA"],
["OK", "Oklahoma", "USA"],
["OR", "Oregon", "USA"],
["PA", "Pennsylvania", "USA"],
["RI", "Rhode Island", "USA"],
["SC", "South Carolina", "USA"],
["SD", "South Dakota", "USA"],
["TN", "Tennessee", "USA"],
["TX", "Texas", "USA"],
["UT", "Utah", "USA"],
["VT", "Vermont", "USA"],
["VA", "Virginia", "USA"],
["WA", "Washington", "USA"],
["WV", "West Virginia", "USA"],
["WI", "Wisconsin", "USA"],
["WY", "Wyoming", "USA"],
["AB", "Alberta", "CAN"],
["BC", "British Columbia", "CAN"],
["MB", "Manitoba", "CAN"],
["NB", "New Brunswick", "CAN"],
["NL", "Newfoundland and Labrador", "CAN"],
["NT", "Northwest Territory", "CAN"],
["NS", "Nova Scotia", "CAN"],
["NU", "Nunavut Territory", "CAN"],
["ON", "Ontario", "CAN"],
["PE", "Prince Edward Island", "CAN"],
["QC", "Quebec", "CAN"],
["SK", "Saskatchewan", "CAN"],
["YT", "Yukon Territory", "CAN"]];
}
Alterar uma célula adjacente

Esse script obtém células adjacentes usando referências relativas. Observe que, se a
célula ativa estiver na linha superior, parte do script falhará porque faz referência à
célula acima da selecionada no momento.
TypeScript

// Get the currently active cell in the workbook.
let activeCell = workbook.getActiveCell();
console.log(`The active cell's address is: ${activeCell.getAddress()}`);
// Get the cell to the right of the active cell and set its value and
color.
let rightCell = activeCell.getOffsetRange(0,1);
rightCell.setValue("Right cell");
console.log(`The right cell's address is: ${rightCell.getAddress()}`);
rightCell.getFormat().getFont().setColor("Magenta");
rightCell.getFormat().getFill().setColor("Cyan");
// Get the cell to the above of the active cell and set its value and
color.
// Note that this operation will fail if the active cell is in the top
row.
let aboveCell = activeCell.getOffsetRange(-1, 0);
aboveCell.setValue("Above cell");
console.log(`The above cell's address is: ${aboveCell.getAddress()}`);
aboveCell.getFormat().getFont().setColor("White");
aboveCell.getFormat().getFill().setColor("Black");
}
Alterar todas as células adjacentes

Esse script copia a formatação na célula ativa para as células vizinhas. Observe que esse
script só funciona quando a célula ativa não está em uma borda da planilha.
TypeScript

// Get the active cell.
let activeCell = workbook.getActiveCell();
// Get the cell that's one row above and one column to the left of the
active cell.
let cornerCell = activeCell.getOffsetRange(-1,-1);
// Get a range that includes all the cells surrounding the active cell.
let surroundingRange = cornerCell.getResizedRange(2, 2)
// Copy the formatting from the active cell to the new range.
surroundingRange.copyFrom(
activeCell, /* The source range. */
ExcelScript.RangeCopyType.formats /* What to copy. */
);
}
Alterar cada célula individual em um intervalo

Esse script faz loops sobre o intervalo selecionado no momento. Ela limpa a formatação
atual e define a cor de preenchimento em cada célula como uma cor aleatória.
TypeScript

// Get the currently selected range.
let range = workbook.getSelectedRange();
// Get the size boundaries of the range.

let rows = range.getRowCount();
let cols = range.getColumnCount();
// Clear any existing formatting.

range.clear(ExcelScript.ClearApplyTo.formats);
// Iterate over the range.

for (let row = 0; row < rows; row++) {
for (let col = 0; col < cols; col++) {
// Generate a random hexadecimal color code.
let colorString = `#${Math.random().toString(16).substr(-6)}`;
// Set the color of the current cell to that random hexadecimal code.
range.getCell(row, col).getFormat().getFill().setColor(colorString);
}
}
}
Obter grupos de células com base em critérios

especiais
Esse script obtém todas as células em branco no intervalo usado da planilha atual. Em
seguida, realça todas essas células com um fundo amarelo.
TypeScript

// Get the current used range.
let range = workbook.getActiveWorksheet().getUsedRange();
// Get all the blank cells.

let blankCells =
range.getSpecialCells(ExcelScript.SpecialCellType.blanks);
// Highlight the blank cells with a yellow background.

blankCells.getFormat().getFill().setColor("yellow");
}
Fórmulas
Os intervalos têm valores e fórmulas. A fórmula é a expressão a ser avaliada. O valor é o
resultado dessa expressão.
Fórmula única
Esse script define a fórmula de uma célula e exibe como o Excel armazena a fórmula e o
valor da célula separadamente.
TypeScript

// Set A1 to 2.
let a1 = selectedSheet.getRange("A1");
a1.setValue(2);
// Set B1 to the formula =(2*A1), which should equal 4.

let b1 = selectedSheet.getRange("B1");
b1.setFormula("=(2*A1)");
// Log the current results for `getFormula` and `getValue` at B1.

console.log(`B1 - Formula: ${b1.getFormula()} | Value: ${b1.getValue()}`);
}
Manipular um #SPILL! erro retornado de uma fórmula

Esse script transpõe o intervalo "A1:D2" para "A4:B7" usando a função TRANSPOSE. Se o
transpose resultar em um #SPILL erro, ele limpará o intervalo de destino e aplicará a
fórmula novamente.
TypeScript

// Use the data in A1:D2 for the sample.
let dataAddress = "A1:D2"
let inputRange = sheet.getRange(dataAddress);
// Place the transposed data starting at A4.

let targetStartCell = sheet.getRange("A4");
// Compute the target range.

let targetRange =
targetStartCell.getResizedRange(inputRange.getColumnCount() - 1,
inputRange.getRowCount() - 1);
// Call the transpose helper function.

targetStartCell.setFormula(`=TRANSPOSE(${dataAddress})`);
// Check if the range update resulted in a spill error.

let checkValue = targetStartCell.getValue() as string;
if (checkValue === '#SPILL!') {
// Clear the target range and call the transpose function again.
console.log("Target range has data that is preventing update. Clearing
target range.");
targetRange.clear();
targetStartCell.setFormula(`=TRANSPOSE(${dataAddress})`);
}
// Select the transposed range to highlight it.

targetRange.select();
}
Substituir todas as fórmulas por seus valores de resultado

Esse script substitui todas as células da planilha atual que contém uma fórmula pelo
resultado dessa fórmula. Isso significa que não haverá fórmulas depois que o script for
executado, somente valores.
TypeScript

// Get the ranges with formulas.
let usedRange = sheet.getUsedRange();
let formulaCells =
usedRange.getSpecialCells(ExcelScript.SpecialCellType.formulas);
// In each formula range: get the current value, clear the contents, and
set the value as the old one.
// This removes the formula but keeps the result.
formulaCells.getAreas().forEach((range) => {
let currentValues = range.getValues();
range.clear(ExcelScript.ClearApplyTo.contents);
range.setValues(currentValues);
});
}
Sugerir novos exemplos

Damos as boas-vindas às sugestões para novos exemplos. Se houver um cenário
comum que ajude outros desenvolvedores de script, conte-nos na seção Comentários
na parte inferior da página.
Confira também
"Noções básicas do intervalo" de Sudhi Ramamurthy no YouTube
Exemplos e cenários de Scripts do Office
Tutorial: Criar e formatar uma tabela do Excel
Exemplos de formatação condicional
Artigo • 30/12/2023
A formatação condicional no Excel aplica a formatação a células com base em condições

ou regras específicas. Esses formatos se ajustam automaticamente quando os dados são
alterados, portanto, o script não precisa ser executado várias vezes. Esta página contém
uma coleção de Scripts do Office que demonstram várias opções de formatação
condicional.
Esta pasta de trabalho de exemplo contém planilhas prontas para teste com os scripts
de exemplo.
Valor da célula
A formatação condicional de valor celular aplica um formato a cada célula que contém
um valor que atende a determinados critérios. Isso ajuda a identificar rapidamente
pontos de dados importantes.
O exemplo a seguir aplica a formatação condicional de valor celular a um intervalo.

Qualquer valor menor que 60 terá a cor de preenchimento da célula alterada e a fonte
tornada itálica.
TypeScript

// Get the range to format.
const sheet = workbook.getWorksheet("CellValue");
const ratingColumn = sheet.getRange("B2:B12");
sheet.activate();
// Add cell value conditional formatting.
const cellValueConditionalFormatting =
ratingColumn.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValu
e).getCellValue();
// Create the condition, in this case when the cell value is less than
60
let rule: ExcelScript.ConditionalCellValueRule = {
formula1: "60",
operator: ExcelScript.ConditionalCellValueOperator.lessThan
};
cellValueConditionalFormatting.setRule(rule);
// Set the format to apply when the condition is met.

let format = cellValueConditionalFormatting.getFormat();
format.getFill().setColor("yellow");
format.getFont().setItalic(true);
}
Escala de cores
A formatação condicional de escala de cores aplica um gradiente de cor em um
intervalo. As células com os valores mínimos e máximos do intervalo usam as cores
especificadas, com outras células dimensionadas proporcionalmente. Uma cor opcional
do ponto médio fornece mais contraste.
Este exemplo a seguir aplica uma escala de cores vermelha, branca e azul ao intervalo
selecionado.
TypeScript

const sheet = workbook.getWorksheet("ColorScale");
const dataRange = sheet.getRange("B2:M13");
sheet.activate();
// Create a new conditional formatting object by adding one to the

range.
const conditionalFormatting =
dataRange.addConditionalFormat(ExcelScript.ConditionalFormatType.colorScale)
;
// Set the colors for the three parts of the scale: minimum, midpoint,
and maximum.
conditionalFormatting.getColorScale().setCriteria({
minimum: {
color: "#5A8AC6", /* A pale blue. */
type:
ExcelScript.ConditionalFormatColorCriterionType.lowestValue
},
midpoint: {
color: "#FCFCFF", /* Slightly off-white. */
formula: '=50', type:
ExcelScript.ConditionalFormatColorCriterionType.percentile
},
maximum: {
color: "#F8696B", /* A pale red. */
type:
ExcelScript.ConditionalFormatColorCriterionType.highestValue
}
});
}
Barra de dados
A formatação condicional da barra de dados adiciona uma barra parcialmente
preenchida no plano de fundo de uma célula. A integridade da barra é definida pelo
valor na célula e pelo intervalo especificado pelo formato.
O exemplo a seguir cria a formatação condicional da barra de dados no intervalo

selecionado. A escala da barra de dados vai de 0 a 1200.
TypeScript

const sheet = workbook.getWorksheet("DataBar");
const dataRange = sheet.getRange("B2:D5");
sheet.activate();
// Create new conditional formatting on the range.

const format =
dataRange.addConditionalFormat(ExcelScript.ConditionalFormatType.dataBar);
const dataBarFormat = format.getDataBar();
// Set the lower bound of the data bar formatting to be 0.
const lowerBound: ExcelScript.ConditionalDataBarRule = {
type: ExcelScript.ConditionalFormatRuleType.number,
formula: "0"
};
dataBarFormat.setLowerBoundRule(lowerBound);
// Set the upper bound of the data bar formatting to be 1200.

const upperBound: ExcelScript.ConditionalDataBarRule = {
type: ExcelScript.ConditionalFormatRuleType.number,
formula: "1200"
};
dataBarFormat.setUpperBoundRule(upperBound);
}
Conjunto de ícones
A formatação condicional do conjunto de ícones adiciona ícones a cada célula em um
intervalo. Os ícones são provenientes de um conjunto especificado. Os ícones são
aplicados com base em uma matriz ordenada de critérios, com cada mapeamento de
critério em um único ícone.
O exemplo a seguir aplica o ícone "três semáforos" definir formatação condicional a um

intervalo.
TypeScript

const sheet = workbook.getWorksheet("IconSet");
const dataRange = sheet.getRange("B2:B12");
sheet.activate();
// Create icon set conditional formatting on the range.

const conditionalFormatting =
dataRange.addConditionalFormat(ExcelScript.ConditionalFormatType.iconSet);
// Use the "3 Traffic Lights (Unrimmed)" set.
conditionalFormatting.getIconSet().setStyle(ExcelScript.IconSet.threeTraffic
Lights1);
conditionalFormatting.getIconSet().setCriteria([
{ // Use the red light as the default for positive values.
formula: '=0', operator:
ExcelScript.ConditionalIconCriterionOperator.greaterThanOrEqual,
type: ExcelScript.ConditionalFormatIconRuleType.number
},
{ // The yellow light is applied to all values 6 and greater. The
replaces the red light when applicable.
},
{ // The green light is applied to all values 8 and greater. As with
the yellow light, the icon is replaced when the new criteria is met.
}
]);
}
Predefinição
A formatação condicional predefinida aplica um formato especificado a um intervalo
com base em cenários comuns, como células em branco e valores duplicados. A lista
completa de critérios predefinidos é fornecida pelo enumeração
ConditionalFormatPresetCriterion .
O exemplo a seguir fornece um preenchimento amarelo a qualquer célula em branco no

intervalo.
TypeScript

const sheet = workbook.getWorksheet("Preset");
sheet.activate();
// Add new conditional formatting to that range.

const conditionalFormat = dataRange.addConditionalFormat(
ExcelScript.ConditionalFormatType.presetCriteria);
// Set the conditional formatting to apply a yellow fill.

const presetFormat = conditionalFormat.getPreset();
presetFormat.getFormat().getFill().setColor("yellow");
// Set a rule to apply the conditional format when cells are left blank.
const blankRule: ExcelScript.ConditionalPresetCriteriaRule = {
criterion: ExcelScript.ConditionalFormatPresetCriterion.blanks
};
presetFormat.setRule(blankRule);
}
Comparação de texto
A formatação condicional de comparação de texto formata células com base no
conteúdo de texto. A formatação é aplicada quando o texto começa com, contém,
termina ou não contém a subconserção fornecida.
O exemplo a seguir marca qualquer célula no intervalo que contém o texto "revisão".
TypeScript

const sheet = workbook.getWorksheet("TextComparison");
const dataRange = sheet.getRange("B2:B6");
sheet.activate();
// Add conditional formatting based on the text in the cells.

const textConditionFormat = dataRange.addConditionalFormat(
ExcelScript.ConditionalFormatType.containsText).getTextComparison();
// Set the conditional format to provide a light red fill and make the
font bold.
textConditionFormat.getFormat().getFill().setColor("#F8696B");
textConditionFormat.getFormat().getFont().setBold(true);
// Apply the condition rule that the text contains with "review".
const textRule: ExcelScript.ConditionalTextComparisonRule = {
operator: ExcelScript.ConditionalTextOperator.contains,
text: "review"
};
textConditionFormat.setRule(textRule);
}
Parte superior/inferior
A formatação condicional superior/inferior marca os valores mais altos ou mais baixos
em um intervalo. Os altos e baixos são baseados em valores brutos ou percentuais.
O exemplo a seguir aplica a formatação condicional para mostrar os dois números mais
altos do intervalo.
TypeScript

const sheet = workbook.getWorksheet("TopBottom");
sheet.activate();
// Set the fill color to green and the font to bold for the top 2 values
in the range.
const topBottomFormat =
dataRange.addConditionalFormat(ExcelScript.ConditionalFormatType.topBottom).
getTopBottom();
topBottomFormat.getFormat().getFill().setColor("green");
topBottomFormat.getFormat().getFont().setBold(true);
topBottomFormat.setRule({
rank: 2, /* The numeric threshold. */
type: ExcelScript.ConditionalTopBottomCriterionType.topItems /* The
type of the top/bottom condition. */
});
}
Condições personalizadas
A formatação condicional personalizada permite que fórmulas complexas definam
quando a formatação é aplicada. Use isso quando as outras opções não forem
suficientes.
O exemplo a seguir define uma formatação condicional personalizada no intervalo

selecionado. Um preenchimento verde-claro e uma fonte em negrito são aplicados a
uma célula se o valor for maior que o valor na coluna anterior da linha.
TypeScript

const sheet = workbook.getWorksheet("Custom");
const dataRange = sheet.getRange("B2:H2");
sheet.activate();
// Apply a rule for positive change from the previous column.

const positiveChange =
dataRange.addConditionalFormat(ExcelScript.ConditionalFormatType.custom).get
Custom();
positiveChange.getFormat().getFill().setColor("lightgreen");
positiveChange.getFormat().getFont().setBold(true);
positiveChange.getRule().setFormula(
`=${dataRange.getCell(0,
0).getAddress()}>${dataRange.getOffsetRange(0, -1).getCell(0,
0).getAddress()}`
);
}
Validação de dados: listas suspensas,
prompts e pop-ups de aviso
Artigo • 04/10/2023
A validação de dados ajuda o usuário a garantir a consistência em uma planilha. Use

esses recursos para limitar o que pode ser inserido em uma célula e fornecer avisos ou
erros aos usuários quando essas condições não forem atendidas. Para saber mais sobre
a validação de dados no Excel, consulte Aplicar validação de dados às células .
Criar uma lista suspensa usando a validação de

dados
O exemplo a seguir cria uma lista de seleção suspensa para uma célula. Ele usa os
valores existentes do intervalo selecionado como as opções para a lista.
TypeScript

// Get the values for data validation.
const selectedRange = workbook.getSelectedRange();
const rangeValues = selectedRange.getValues();
// Convert the values into a comma-delimited string.

let dataValidationListString = "";
rangeValues.forEach((rangeValueRow) => {
rangeValueRow.forEach((value) => {
dataValidationListString += value + ",";
});
});
// Clear the old range.

selectedRange.clear(ExcelScript.ClearApplyTo.contents);
// Apply the data validation to the first cell in the selected range.
const targetCell = selectedRange.getCell(0,0);
const dataValidation = targetCell.getDataValidation();
// Set the content of the dropdown list.
dataValidation.setRule({
list: {
inCellDropDown: true,
source: dataValidationListString
}
});
}
Adicionar um prompt a um intervalo

Este exemplo cria uma nota de prompt que aparece quando um usuário insere as
células fornecidas. Isso é usado para lembrar os usuários sobre os requisitos de entrada,
sem uma aplicação estrita.
TypeScript
/**
* This script creates a text prompt that's shown in C2:C8 when a user
enters the cell.
*/
// Get the data validation object for C2:C8 in the current worksheet.
const dataValidation =
selectedSheet.getRange("C2:C8").getDataValidation();
// Clear any previous validation to avoid conflicts.

dataValidation.clear();
// Create a prompt to remind users to only enter first names in this

column.
const prompt: ExcelScript.DataValidationPrompt = {
showPrompt: true,
title: "First names only",
message: "Only enter the first name of the employee, not the full
name."
}
dataValidation.setPrompt(prompt);
}
Alerte o usuário quando dados inválidos são

inseridos
O script de exemplo a seguir impede que o usuário insira qualquer outra coisa que não
seja números positivos em um intervalo. Se eles tentarem colocar qualquer outra coisa,
uma mensagem de erro aparecerá e indicará o problema.
TypeScript
/**
* This script creates a data validation rule for the range B2:B5.
* All values in that range must be a positive number.
* Attempts to enter other values are blocked and an error message appears.
*/
// Get the range B2:B5 in the active worksheet.
const currentSheet = workbook.getActiveWorksheet();
const positiveNumberOnlyCells = currentSheet.getRange("B2:B5");
// Create a data validation rule to only allow positive numbers.

const positiveNumberValidation: ExcelScript.BasicDataValidation = {
formula1: "0",
operator: ExcelScript.DataValidationOperator.greaterThan
};
const positiveNumberOnlyRule: ExcelScript.DataValidationRule = {
wholeNumber: positiveNumberValidation
};
// Set the rule on the range.

const rangeDataValidation = positiveNumberOnlyCells.getDataValidation();
rangeDataValidation.setRule(positiveNumberOnlyRule);
// Create an alert to appear when data other than positive numbers are
entered.
const positiveNumberOnlyAlert: ExcelScript.DataValidationErrorAlert = {
message: "Positive numbers only.",
showAlert: true,
style: ExcelScript.DataValidationAlertStyle.stop,
title: "Invalid data"
};
rangeDataValidation.setErrorAlert(positiveNumberOnlyAlert);
}
Exemplos de JavaScript Date
Artigo • 11/09/2023
Esses exemplos mostram como usar o objeto JavaScript Date .
Gravar a data e a hora atuais

O exemplo a seguir obtém a data e a hora atuais e grava esses valores em duas células
na planilha ativa.
TypeScript

// Get the cells at A1 and B1.
let dateRange = workbook.getActiveWorksheet().getRange("A1");
let timeRange = workbook.getActiveWorksheet().getRange("B1");
// Get the current date and time with the JavaScript Date object.
// Add the date string to A1.

dateRange.setValue(date.toLocaleDateString());
// Add the time string to B1.

timeRange.setValue(date.toLocaleTimeString());
}
Ler uma data do Excel

Este exemplo lê uma data armazenada no Excel e a traduz em um objeto JavaScript
Date . Ele usa o número de série numérico da data como entrada para o JavaScript
Date . Esse número de série é descrito no artigo da função NOW( ).
TypeScript

// Read a date at cell A1 from Excel.
let dateRange = workbook.getActiveWorksheet().getRange("A1");

let excelDateValue = dateRange.getValue() as number;
let javaScriptDate = new Date(Math.round((excelDateValue - 25569) * 86400
* 1000));
console.log(javaScriptDate);
}
Confira também
Usar objetos JavaScript internos em Scripts do Office
Adicionar imagens a uma pasta de
trabalho
Artigo • 25/10/2023
Este exemplo mostra como trabalhar com imagens usando um Script do Office no Excel.
Cenário
As imagens ajudam com identidade visual, identidade visual e modelos. Eles ajudam a
fazer uma pasta de trabalho mais do que apenas uma tabela gigante.
O primeiro exemplo copia uma imagem de uma planilha para outra. Isso pode ser usado
para colocar o logotipo da sua empresa na mesma posição em cada planilha.
O segundo exemplo copia uma imagem de uma URL. Isso pode ser usado para copiar
fotos armazenadas por um colega em uma pasta compartilhada em uma pasta de
trabalho relacionada. Observe que esse exemplo não pode ser adaptado para trabalhar
com um arquivo de imagem local, pois não há suporte para scripts do Office.
Instalação: Exemplo de arquivo do Excel

Esta pasta de trabalho contém os dados, objetos e formatação esperados pelo script.
Código de exemplo: copiar uma imagem entre

planilhas
Adicione o script a seguir à pasta de trabalho de exemplo e experimente a amostra por
conta própria!
TypeScript
/**
* This script transfers an image from one worksheet to another.
*/
function main(workbook: ExcelScript.Workbook)
{
// Get the worksheet with the image on it.
let firstWorksheet = workbook.getWorksheet("FirstSheet");
// Get the first image from the worksheet.
// If a script added the image, you could add a name to make it easier to
find.
let image: ExcelScript.Image;
firstWorksheet.getShapes().forEach((shape, index) => {
if (shape.getType() === ExcelScript.ShapeType.image) {
image = shape.getImage();
return;
}
});
// Copy the image to another worksheet.

image.getShape().copyTo("SecondSheet");
}
Código de exemplo: adicionar uma imagem de

uma URL a uma pasta de trabalho
） Importante
Este exemplo não funcionará no Power Automate por causa da fetch chamada.
TypeScript

// Fetch the image from a URL.
const link = "https://raw.githubusercontent.com/OfficeDev/office-scripts-
docs/master/docs/images/git-octocat.png";
const response = await fetch(link);
// Store the response as an ArrayBuffer, since it is a raw image file.

const data = await response.arrayBuffer();
// Convert the image data into a base64-encoded string.

const image = convertToBase64(data);
// Add the image to a worksheet.

workbook.getWorksheet("WebSheet").addImage(image);
}
/**
* Converts an ArrayBuffer containing a .png image into a base64-encoded
string.
*/
function convertToBase64(input: ArrayBuffer) {
const uInt8Array = new Uint8Array(input);
const count = uInt8Array.length;
// Allocate the necessary space up front.

const charCodeArray = new Array(count) as string[];
// Convert every entry in the array to a character.

for (let i = count; i >= 0; i--) {
charCodeArray[i] = String.fromCharCode(uInt8Array[i]);
}
// Convert the characters to base64.

const base64 = btoa(charCodeArray.join(''));
return base64;
}
Exemplos de visibilidade de linha e
coluna
Artigo • 11/09/2023
Esses exemplos demonstram como mostrar, ocultar e congelar linhas e colunas.
Ocultar colunas
Este script oculta as colunas "D", "F" e "J".
TypeScript

const sheet = workbook.getActiveWorksheet();
// Hide columns D, F, and J.

sheet.getRange("D:D").setColumnHidden(true);
sheet.getRange("F:F").setColumnHidden(true);
sheet.getRange("J:J").setColumnHidden(true);
}
Mostrar todas as linhas e colunas

Esse script obtém o intervalo usado da planilha, verifica se há linhas e colunas ocultas e
as mostra.
TypeScript

// Get the currently selected sheet.
// Get the entire data range.

const range = selectedSheet.getUsedRange();
// If the used range is empty, end the script.

if (!range) {
console.log(`No data on this sheet.`)
return;
}
// If no columns are hidden, log message, else show columns.

if (range.getColumnHidden() == false) {
console.log(`No columns hidden`);
} else {
range.setColumnHidden(false);
}
// If no rows are hidden, log message, else, show rows.

if (range.getRowHidden() == false) {
console.log(`No rows hidden`);
} else {
range.setRowHidden(false);
}
}
Congelar células selecionadas no momento

Esse script verifica quais células estão selecionadas no momento e congela essa seleção,
de modo que essas células estejam sempre visíveis.
TypeScript

// Get the currently selected sheet.
// Get the current selected range.

const selectedRange = workbook.getSelectedRange();
// If no cells are selected, end the script.

if (!selectedRange) {
console.log(`No cells in the worksheet are selected.`);
return;
}
// Log the address of the selected range

console.log(`Selected range for the worksheet:
${selectedRange.getAddress()}`);
// Freeze the selected range.

selectedSheet.getFreezePanes().freezeAt(selectedRange);
}
Exemplos de tabela
Artigo • 21/12/2023
Esses exemplos mostram interações comuns com tabelas do Excel.
Criar uma tabela classificada

Esse exemplo cria uma tabela do intervalo usado da planilha atual e, em seguida,
classifica-a com base na primeira coluna.
TypeScript

// Create a table with the used cells.

const usedRange = selectedSheet.getUsedRange();
const newTable = selectedSheet.addTable(usedRange, true);
// Sort the table using the first column.

newTable.getSort().apply([{ key: 0, ascending: true }]);
}
Filtrar uma tabela

Esse exemplo filtra uma tabela existente usando os valores em uma das colunas.
TypeScript

// Get the table in the workbook named "StationTable".
const table = workbook.getTable("StationTable");
// Get the "Station" table column for the filter.

const stationColumn = table.getColumnByName("Station");
// Apply a filter to the table that will only show rows

// with a value of "Station-1" in the "Station" column.
stationColumn.getFilter().applyValuesFilter(["Station-1"]);
}
 Dica
Copie as informações filtradas na pasta de trabalho usando Range.copyFrom .
Adicione a linha a seguir ao final do script para criar uma nova planilha com os
dados filtrados.
TypeScript
workbook.addWorksheet().getRange("A1").copyFrom(table.getRange());
Filtrar um valor
O exemplo anterior filtra uma tabela com base em uma lista de valores incluídos. Para
excluir um valor específico da tabela, você precisa fornecer a lista de todos os outros
valores da coluna. Este exemplo usa uma função columnToSet para converter uma
coluna em um conjunto de valores exclusivos. Esse conjunto então tem o valor excluído
("Station-1") removido.
TypeScript


// Get a list of unique values in the station column.

const stationSet = columnToSet(stationColumn);

// that don't have a value of "Station-1" in the "Station" column.
stationColumn.getFilter().applyValuesFilter(stationSet.filter((value) => {
return value !== "Station-1";
}));
}
/**
* Convert a column into a set so it only contains unique values.
*/
function columnToSet(column: ExcelScript.TableColumn): string[] {
const range = column.getRangeBetweenHeaderAndTotal().getValues() as
string[][];
const columnSet: string[] = [];
range.forEach((value) => {
if (!columnSet.includes(value[0])) {
columnSet.push(value[0]);
}
});
return columnSet;
}
Remover filtros de coluna de tabela

Este exemplo remove os filtros de uma coluna de tabela, com base no local da célula
ativa. O script detecta se a célula faz parte de uma tabela, determina a coluna de tabela
e limpa todos os filtros aplicados nela.
Baixe table-with-filter.xlsx para uma pasta de trabalho pronta para uso. Adicione o script
a seguir para experimentar o exemplo por conta própria!
TypeScript

const cell = workbook.getActiveCell();
// Get the tables associated with that cell.

// Since tables can't overlap, this will be one table at most.
const currentTable = cell.getTables()[0];
// If there's no table on the selection, end the script.

if (!currentTable) {
console.log("The selection is not in a table.");
return;
}
// Get the table header above the current cell by referencing its column.
const entireColumn = cell.getEntireColumn();
const intersect = entireColumn.getIntersection(currentTable.getRange());
const headerCellValue = intersect.getCell(0, 0).getValue() as string;
// Get the TableColumn object matching that header.

const tableColumn = currentTable.getColumnByName(headerCellValue);
// Clear the filters on that table column.

tableColumn.getFilter().clear();
}
Antes de limpar o filtro de coluna (observe a célula ativa)

Depois de limpar o filtro de coluna
 Dica
Se você quiser saber mais sobre como salvar o filtro antes de limpá-lo (e se aplicar
novamente posteriormente), consulte Mover linhas entre tabelas salvando filtros,
um exemplo mais avançado.
Referenciar dinamicamente valores de tabela

Este script usa a sintaxe "@COLUMN_NAME" para definir fórmulas em uma coluna de
tabela. Os nomes de coluna na tabela podem ser alterados sem alterar esse script.
TypeScript

const table = workbook.getTable("Profits");
// Get the column names for columns 2 and 3.

// Note that these are 1-based indices.
const nameOfColumn2 = table.getColumn(2).getName();
// Set the formula of the fourth column to be the product of the values
found
// in that row's second and third columns.
const combinedColumn = table.getColumn(4).getRangeBetweenHeaderAndTotal();
combinedColumn.setFormula(`=[@[${nameOfColumn2}]]*[@[${nameOfColumn3}]]`);
}
Antes do script
Month Price Unidades Vendidas Total
Janeiro 45 5
Fevereiro 45 3
Março 45 6
Após o script
Janeiro 45 5 225
Fevereiro 45 3 135
Março 45 6 270
você também pode criar e comentários:
Combinar dados de várias tabelas do
Excel em uma única tabela
Artigo • 25/10/2023
Este exemplo combina dados de várias tabelas do Excel em uma única tabela que inclui
todas as linhas. Ele pressupõe que todas as tabelas que estão sendo usadas tenham a
mesma estrutura.
Há duas variações deste script:
1. O primeiro script combina todas as tabelas no arquivo do Excel.

2. O segundo script obtém seletivamente tabelas dentro de um conjunto de
planilhas.

Código de exemplo: combinar dados de várias

tabelas do Excel em uma única tabela
conta própria!
TypeScript

// Delete the "Combined" worksheet, if it's present.
workbook.getWorksheet('Combined')?.delete();
// Create a new worksheet named "Combined" for the combined table.

const newSheet = workbook.addWorksheet('Combined');
// Get the header values for the first table in the workbook.
// This also saves the table list before we add the new, combined table.
const tables = workbook.getTables();
const headerValues = tables[0].getHeaderRowRange().getTexts();
console.log(headerValues);
// Copy the headers on a new worksheet to an equal-sized range.

const targetRange =
newSheet.getRange('A1').getResizedRange(headerValues.length-1,
headerValues[0].length-1);
targetRange.setValues(headerValues);
// Add the data from each table in the workbook to the new table.
const combinedTable = newSheet.addTable(targetRange.getAddress(), true);
for (let table of tables) {
let dataValues = table.getRangeBetweenHeaderAndTotal().getTexts();
let rowCount = table.getRowCount();
// If the table is not empty, add its rows to the combined table.
if (rowCount > 0) {
combinedTable.addRows(-1, dataValues);
}
}
}
Código de exemplo: combinar dados de várias

tabelas do Excel em planilhas selecionadas em
uma única tabela
Baixe o arquivo de exemplotables-select-copy.xlsx e use-o com o script a seguir para
experimentá-lo sozinho!
TypeScript

// Set the worksheet names to get tables from.
const sheetNames = ['Sheet1', 'Sheet2', 'Sheet3'];
// Delete the "Combined" worksheet, if it's present.

workbook.getWorksheet('Combined')?.delete();
// Create a new worksheet named "Combined" for the combined table.

const newSheet = workbook.addWorksheet('Combined');
// Create a new table with the same headers as the other tables.
const headerValues = workbook.getWorksheet(sheetNames[0]).getTables()
[0].getHeaderRowRange().getTexts();
const targetRange =
newSheet.getRange('A1').getResizedRange(headerValues.length-1,
headerValues[0].length-1);
targetRange.setValues(headerValues);
const combinedTable = newSheet.addTable(targetRange.getAddress(), true);
// Go through each listed worksheet and get their tables.

sheetNames.forEach((sheet) => {
const tables = workbook.getWorksheet(sheet).getTables();
for (let table of tables) {
// Get the rows from the tables.
let dataValues = table.getRangeBetweenHeaderAndTotal().getTexts();
let rowCount = table.getRowCount();
// If there's data in the table, add it to the combined table.

if (rowCount > 0) {
combinedTable.addRows(-1, dataValues);
}
}
});
}
Vídeo de treinamento: combinar dados de

várias tabelas do Excel em uma única tabela
Assista Sudhi Ramamurthy percorrer este exemplo no YouTube .
Criar um sumário da pasta de trabalho
Artigo • 25/10/2023
Este exemplo mostra como criar uma tabela de conteúdo para a pasta de trabalho. Cada
entrada na tabela de conteúdo é um hiperlink para uma das planilhas da pasta de
trabalho.

Código de exemplo: criar uma tabela de

conteúdo de pasta de trabalho
conta própria!
TypeScript

// Insert a new worksheet at the beginning of the workbook.
let tocSheet = workbook.addWorksheet();
tocSheet.setPosition(0);
tocSheet.setName("Table of Contents");
// Give the worksheet a title in the sheet.

tocSheet.getRange("A1").setValue("Table of Contents");
tocSheet.getRange("A1").getFormat().getFont().setBold(true);
// Create the table of contents headers.

let tocRange = tocSheet.getRange("A2:B2")
tocRange.setValues([["#", "Name"]]);
// Get the range for the table of contents entries.
let worksheets = workbook.getWorksheets();
tocRange = tocRange.getResizedRange(worksheets.length, 0);
// Loop through all worksheets in the workbook, except the first one.
for (let i = 1; i < worksheets.length; i++) {
// Create a row for each worksheet with its index and linked name.
tocRange.getCell(i, 0).setValue(i);
tocRange.getCell(i, 1).setHyperlink({
textToDisplay: worksheets[i].getName(),
documentReference: `'${worksheets[i].getName()}'!A1`
});
};
// Activate the table of contents worksheet.

tocSheet.activate();
}
Contar linhas em branco em planilhas
Artigo • 17/11/2023
Este projeto inclui dois scripts:
Contagem de linhas em branco em uma determinada folha: atravessa o intervalo

usado em uma determinada planilha e retorna uma contagem de linhas em
branco.
Contagem de linhas em branco em todas as planilhas: atravessa o intervalo usado
em todas as planilhas e retorna uma contagem de linhas em branco.
７ Observação
Para o script, uma linha em branco é qualquer linha em que não há dados. A linha
pode ter formatação.
Esta planilha retorna a contagem de 4 linhas em branco

Esta planilha retorna a contagem de 0 linhas em branco (todas as linhas têm alguns
dados)
Código de exemplo: contar linhas em branco
em uma determinada planilha
TypeScript
function main(workbook: ExcelScript.Workbook): number

{
// Get the worksheet named "Sheet1".
const sheet = workbook.getWorksheet('Sheet1');

const range = sheet.getUsedRange(true);
// If the used range is empty, end the script.

if (!range) {
console.log(`No data on this sheet.`);
return;
}
// Log the address of the used range.

console.log(Ùsed range for the worksheet: ${range.getAddress()}`);
// Look through the values in the range for blank rows.

const values = range.getValues();
let emptyRows = 0;
for (let row of values) {
let emptyRow = true;
// Look at every cell in the row for one with a value.

for (let cell of row) {
if (cell.toString().length > 0) {
emptyRow = false
}
}
// If no cell had a value, the row is empty.

if (emptyRow) {
emptyRows++;
}
}
// Log the number of empty rows.

console.log(`Total empty rows: ${emptyRows}`);
// Return the number of empty rows for use in a Power Automate flow.
return emptyRows;
}
Código de exemplo: contagem de linhas em
branco em todas as planilhas
TypeScript
function main(workbook: ExcelScript.Workbook): number

{
// Loop through every worksheet in the workbook.
const sheets = workbook.getWorksheets();
let emptyRows = 0;
for (let sheet of sheets) {
const range = sheet.getUsedRange(true);
// If the used range is empty, skip to the next worksheet.

if (!range) {
console.log(`No data on this sheet.`);
continue;
}
// Log the address of the used range.

console.log(Ùsed range for the worksheet: ${range.getAddress()}`);
// Look through the values in the range for blank rows.

const values = range.getValues();
for (let row of values) {
let emptyRow = true;
// Look at every cell in the row for one with a value.

for (let cell of row) {
if (cell.toString().length > 0) {
emptyRow = false
}
}
// If no cell had a value, the row is empty.

if (emptyRow) {
emptyRows++;
}
}
}
// Log the number of empty rows.

console.log(`Total empty rows: ${emptyRows}`);
// Return the number of empty rows for use in a Power Automate flow.
return emptyRows;
}
Gerenciar o modo de cálculo no Excel
Artigo • 30/03/2023
Este exemplo mostra como usar o modo de cálculo e calcular métodos no Excel usando
scripts do Office. Você pode experimentar o script em qualquer arquivo do Excel.
Cenário
Pastas de trabalho com um grande número de fórmulas podem demorar um pouco
para serem recalculadas. Em vez de deixar o Excel controlar quando os cálculos
acontecem, você pode gerenciá-los como parte do script. Isso ajudará com o
desempenho em determinados cenários.
O script de exemplo define o modo de cálculo como manual. Isso significa que a pasta
de trabalho só recalculará fórmulas quando o script o informar (ou você calculará
manualmente por meio da interface do usuário ). Em seguida, o script exibe o modo
de cálculo atual e recalcula totalmente toda a pasta de trabalho.
Código de exemplo: modo de cálculo de

controle
TypeScript

// Set the calculation mode to manual.
workbook.getApplication().setCalculationMode(ExcelScript.CalculationMode.man
ual);
// Get and log the calculation mode.
const calcMode = workbook.getApplication().getCalculationMode();
console.log(calcMode);
// Manually calculate the file.
workbook.getApplication().calculate(ExcelScript.CalculationType.full);
}
Vídeo de treinamento: gerenciar o modo de

cálculo
Mover linhas entre tabelas
Artigo • 25/10/2023
Esse script faz o seguinte:
Seleciona linhas na tabela de origem em que o valor em uma coluna é igual a

algum valor ( FILTER_VALUE no script).
Move todas as linhas selecionadas para a tabela de destino em outra planilha.
Reaplica os filtros relevantes para a tabela de origem.

Código de exemplo: mover linhas usando

valores de intervalo
conta própria!
TypeScript
// You can change these names to match the data in your workbook.
const TARGET_TABLE_NAME = 'Table1';
const SOURCE_TABLE_NAME = 'Table2';
// Select what will be moved between tables.

const FILTER_COLUMN_INDEX = 1;
const FILTER_VALUE = 'Clothing';
// Get the Table objects.

let targetTable = workbook.getTable(TARGET_TABLE_NAME);
let sourceTable = workbook.getTable(SOURCE_TABLE_NAME);
// If either table is missing, report that information and stop the

script.
console.log(`Tables missing - Check to make sure both source
(${TARGET_TABLE_NAME}) and target table (${SOURCE_TABLE_NAME}) are present
before running the script. `);
return;
}
// Save the filter criteria currently on the source table.

const originalTableFilters = {};
// For each table column, collect the filter criteria on that column.
sourceTable.getColumns().forEach((column) => {
let originalColumnFilter = column.getFilter().getCriteria();
if (originalColumnFilter) {
originalTableFilters[column.getName()] = originalColumnFilter;
}
});
// Get all the data from the table.

const sourceRange = sourceTable.getRangeBetweenHeaderAndTotal();
const dataRows: (number | string | boolean)[][] =
sourceTable.getRangeBetweenHeaderAndTotal().getValues();
// Create variables to hold the rows to be moved and their addresses.

let rowsToMoveValues: (number | string | boolean)[][] = [];
let rowAddressToRemove: string[] = [];
// Get the data values from the source table.

for (let i = 0; i < dataRows.length; i++) {
if (dataRows[i][FILTER_COLUMN_INDEX] === FILTER_VALUE) {
rowsToMoveValues.push(dataRows[i]);
// Get the intersection between table address and the entire row where
we found the match. This provides the address of the range to remove.
let address =
sourceRange.getIntersection(sourceRange.getCell(i,0).getEntireRow()).getAddr
ess();
rowAddressToRemove.push(address);
}
}
// If there are no data rows to process, end the script.

if (rowsToMoveValues.length < 1) {
console.log('No rows selected from the source table match the filter
criteria.');
return;
}
console.log(Àdding ${rowsToMoveValues.length} rows to target table.`);
// Insert rows at the end of target table.

targetTable.addRows(-1, rowsToMoveValues)
// Remove the rows from the source table.

const sheet = sourceTable.getWorksheet();
// Remove all filters before removing rows.

sourceTable.getAutoFilter().clearCriteria();
// Important: Remove the rows starting at the bottom of the table.

// Otherwise, the lower rows change position before they are deleted.
console.log(`Removing ${rowAddressToRemove.length} rows from the source
table.`);
rowAddressToRemove.reverse().forEach((address) => {
sheet.getRange(address).delete(ExcelScript.DeleteShiftDirection.up);
});
// Reapply the original filters.

Object.keys(originalTableFilters).forEach((columnName) => {
sourceTable.getColumnByName(columnName).getFilter().apply(originalTableFilte
rs[columnName]);
});
}
Vídeo de treinamento: mover linhas entre

tabelas
Assista Sudhi Ramamurthy percorrer este exemplo no YouTube . Há dois scripts
mostrados na solução do vídeo. A diferença main é como as linhas são selecionadas.
Na primeira variante, as linhas são selecionadas aplicando o filtro de tabela e lendo

o intervalo visível.
No segundo, as linhas são selecionadas lendo os valores e extraindo os valores da
linha (que é o que o exemplo nesta página usa).
Notificar as pessoas com comentários
Artigo • 05/12/2023
Este exemplo mostra como adicionar comentários a uma célula, incluindo

@mentioning um colega.
Cenário de exemplo
O líder da equipe mantém o agendamento de turnos. Eles atribuem uma ID do
funcionário ao registro de turno. Se o líder da equipe quiser notificar o funcionário, ele
adicionará um comentário que @mentions o funcionário. O funcionário é enviado por
email com uma mensagem personalizada da planilha. Posteriormente, o funcionário
pode exibir a pasta de trabalho e responder ao comentário por conveniência.
Solução
1. O script extrai informações de funcionários da planilha do funcionário.
2. Em seguida, o script adiciona um comentário (incluindo o email relevante do
funcionário) à célula apropriada no registro de turno.
3. Os comentários existentes na célula são removidos antes de adicionar o novo
comentário.

Código de exemplo: adicionar comentários

conta própria!
TypeScript

// Get the list of employees.
const employees =
workbook.getWorksheet('Employees').getUsedRange().getTexts();
// Get the schedule information from the schedule table.
const scheduleSheet = workbook.getWorksheet('Schedule');
const table = scheduleSheet.getTables()[0];
const range = table.getRangeBetweenHeaderAndTotal();
const scheduleData = range.getTexts();
// Find old comments, so we can delete them later.

const oldCommentAddresses = scheduleSheet.getComments().map(oldComment =>
oldComment.getLocation().getAddress());
// Look through the schedule for a matching employee.

for (let i = 0; i < scheduleData.length; i++) {
const employeeId = scheduleData[i][3];
// Compare the employee ID in the schedule against the employee

information table.
const employeeInfo = employees.find(employeeRow => employeeRow[0] ===
employeeId);
if (employeeInfo) {
const adminNotes = scheduleData[i][4];
const commentCell = range.getCell(i, 5);
// Delete old comments, so we avoid conflicts.

if (oldCommentAddresses.find(oldCommentAddress => oldCommentAddress
=== commentCell.getAddress())) {
const comment = workbook.getCommentByCell(commentCell);
comment.delete();
}
// Add a comment using the admin notes as the text.

workbook.addComment(commentCell, {
mentions: [{
email: employeeInfo[1],
id: 0, // This ID maps this mention to the ìd=0` text in the
comment.
name: employeeInfo[2]
}],
richContent: `<at id=\"0\">${employeeInfo[2]}</at> ${adminNotes}`
}, ExcelScript.ContentType.mention);
} else {
console.log("No match for: " + employeeId);
}
}
}
Saída de dados de tabela do Excel como
JSON para uso no Power Automate
Artigo • 25/10/2023
Os dados da tabela do Excel podem ser representados como uma matriz de objetos na
forma de JSON . Cada objeto representa uma linha na tabela. Isso ajuda a extrair os
dados do Excel em um formato consistente que é visível para o usuário. Em seguida, os
dados podem ser dados a outros sistemas por meio de fluxos do Power Automate.

Uma variação desse exemplo também inclui os hiperlinks em uma das colunas de
tabela. Isso permite que níveis adicionais de dados celulares sejam exibidos no JSON.
Código de exemplo: retornar dados de tabela

como JSON
conta própria!
７ Observação
Você pode alterar a interface TableData estrutura para corresponder às colunas

da tabela. Observe que, para nomes de coluna com espaços, coloque sua chave
entre aspas, como com "Event ID" no exemplo. Para obter mais informações sobre
como trabalhar com JSON, leia Usar JSON para passar dados de e para scripts do
Office.
TypeScript
function main(workbook: ExcelScript.Workbook): TableData[] {

// Get the first table in the "PlainTable" worksheet.
// If you know the table name, use `workbook.getTable('TableName')`
instead.
const table = workbook.getWorksheet('PlainTable').getTables()[0];
// Get all the values from the table as text.

const texts = table.getRange().getTexts();
// Create an array of JSON objects that match the row structure.

let returnObjects: TableData[] = [];
if (table.getRowCount() > 0) {
returnObjects = returnObjectFromValues(texts);
}
// Log the information and return it for a Power Automate flow.

console.log(JSON.stringify(returnObjects));
return returnObjects
}
// This function converts a 2D array of values into a generic JSON object.

// In this case, we have defined the TableData object, but any similar
interface would work.
function returnObjectFromValues(values: string[][]): TableData[] {
let objectArray: TableData[] = [];
let objectKeys: string[] = [];
for (let i = 0; i < values.length; i++) {
if (i === 0) {
objectKeys = values[i]
continue;
}
let object: {[key: string]: string} = {}

for (let j = 0; j < values[i].length; j++) {
object[objectKeys[j]] = values[i][j]
}
objectArray.push(object as unknown as TableData);
}
return objectArray;
}
interface TableData {
"Event ID": string
Date: string
Location: string
Capacity: string
Speakers: string
}
Saída de exemplo da planilha "PlainTable"

JSON
[{
"Event ID": "E107",
"Date": "2020-12-10",
"Location": "Montgomery",
"Capacity": "10",
"Speakers": "Debra Berger"
}, {
"Event ID": "E108",
"Date": "2020-12-11",
"Capacity": "10",
"Speakers": "Delia Dennis"
}, {
"Event ID": "E109",
"Date": "2020-12-12",
"Capacity": "10",
"Speakers": "Diego Siciliani"
}, {
"Event ID": "E110",
"Date": "2020-12-13",
"Location": "Boise",
"Capacity": "25",
"Speakers": "Gerhart Moller"
}, {
"Event ID": "E111",
"Date": "2020-12-14",
"Location": "Salt Lake City",
"Capacity": "20",
"Speakers": "Grady Archie"
}, {
"Event ID": "E112",
"Date": "2020-12-15",
"Location": "Fremont",
"Capacity": "25",
"Speakers": "Irvin Sayers"
}, {
"Event ID": "E113",
"Date": "2020-12-16",
"Capacity": "20",
"Speakers": "Isaiah Langer"
}, {
"Event ID": "E114",
"Date": "2020-12-17",
"Capacity": "20",
"Speakers": "Johanna Lorenz"
}]
Código de exemplo: retornar dados de tabela

como JSON com texto de hiperlink
７ Observação
O script sempre extrai hiperlinks da 4ª coluna (índice 0) da tabela. Você pode

alterar essa ordem ou incluir várias colunas como dados de hiperlink modificando o
código sob o comentário // For the 4th column (0 index), extract the hyperlink
and use that instead of text.
TypeScript
function main(workbook: ExcelScript.Workbook): TableData[] {

// Get the first table in the "WithHyperLink" worksheet.
// If you know the table name, use `workbook.getTable('TableName')`
instead.
const table = workbook.getWorksheet('WithHyperLink').getTables()[0];
// Get all the values from the table as text.

const range = table.getRange();
// Create an array of JSON objects that match the row structure.

let returnObjects: TableData[] = [];
if (table.getRowCount() > 0) {
returnObjects = returnObjectFromValues(range);
}
// Log the information and return it for a Power Automate flow.

console.log(JSON.stringify(returnObjects));
return returnObjects
}
function returnObjectFromValues(range: ExcelScript.Range): TableData[] {
let values = range.getTexts();
let objectArray : TableData[] = [];
let objectKeys: string[] = [];
if (i === 0) {
objectKeys = values[i]
continue;
}
let object = {}
for (let j = 0; j < values[i].length; j++) {
// For the 4th column (0 index), extract the hyperlink and use that
instead of text.
if (j === 4) {
object[objectKeys[j]] = range.getCell(i, j).getHyperlink().address;
} else {
object[objectKeys[j]] = values[i][j];
}
}
objectArray.push(object as TableData);
}
return objectArray;
}
interface TableData {
"Event ID": string
Date: string
Location: string
Capacity: string
"Search link": string
Speakers: string
}
Saída de exemplo da planilha "WithHyperLink"

JSON
[{
"Event ID": "E107",
"Date": "2020-12-10",
"Capacity": "10",
"Search link": "https://www.google.com/search?q=Montgomery",
"Speakers": "Debra Berger"
}, {
"Event ID": "E108",
"Date": "2020-12-11",
"Capacity": "10",
"Speakers": "Delia Dennis"
}, {
"Event ID": "E109",
"Date": "2020-12-12",
"Capacity": "10",
"Speakers": "Diego Siciliani"
}, {
"Event ID": "E110",
"Date": "2020-12-13",
"Location": "Boise",
"Capacity": "25",
"Search link": "https://www.google.com/search?q=Boise",
"Speakers": "Gerhart Moller"
}, {
"Event ID": "E111",
"Date": "2020-12-14",
"Capacity": "20",
"Search link": "https://www.google.com/search?q=salt+lake+city",
"Speakers": "Grady Archie"
}, {
"Event ID": "E112",
"Date": "2020-12-15",
"Location": "Fremont",
"Capacity": "25",
"Search link": "https://www.google.com/search?q=Fremont",
"Speakers": "Irvin Sayers"
}, {
"Event ID": "E113",
"Date": "2020-12-16",
"Capacity": "20",
"Speakers": "Isaiah Langer"
}, {
"Event ID": "E114",
"Date": "2020-12-17",
"Capacity": "20",
"Speakers": "Johanna Lorenz"
}]
Usar no Power Automate

Para saber como usar esse script no Power Automate, consulte Criar um fluxo de
trabalho automatizado com o Power Automate.
Remover hiperlinks de cada célula em
uma planilha do Excel
Artigo • 25/10/2023
Este exemplo limpa todos os hiperlinks da planilha atual. Ele atravessa a planilha e, se
houver algum hiperlink associado à célula, ele limpa o hiperlink e mantém o valor da
célula como está. Também registra o tempo necessário para concluir a travessia.
７ Observação
Isso só funcionará se a contagem de células for < de 10k.

Código de exemplo: remover hiperlinks

conta própria!
TypeScript
function main(workbook: ExcelScript.Workbook, sheetName: string = 'Sheet1')

{
let sheet = workbook.getWorksheet(sheetName);
// Get the used range to operate on.

// For large ranges (over 10000 entries), consider splitting the operation
into batches for performance.
const targetRange = sheet.getUsedRange(true);
console.log(`Target Range to clear hyperlinks from:
${targetRange.getAddress()}`);
const rowCount = targetRange.getRowCount();

const colCount = targetRange.getColumnCount();
console.log(`Searching for hyperlinks in ${targetRange.getAddress()} which
contains ${(rowCount * colCount)} cells`);
// Go through each individual cell looking for a hyperlink.

// This allows us to limit the formatting changes to only the cells with
hyperlink formatting.
let clearedCount = 0;
for (let i = 0; i < rowCount; i++) {
for (let j = 0; j < colCount; j++) {
const cell = targetRange.getCell(i, j);
const hyperlink = cell.getHyperlink();
if (hyperlink) {
cell.clear(ExcelScript.ClearApplyTo.hyperlinks);
cell.getFormat().getFont().setUnderline(ExcelScript.RangeUnderlineStyle.none
);
cell.getFormat().getFont().setColor('Black');
clearedCount++;
}
}
}
console.log(`Done. Cleared hyperlinks from ${clearedCount} cells`);

}
Vídeo de treinamento: remover hiperlinks de

cada célula em uma planilha do Excel
Exemplos de tabela
Artigo • 21/12/2023
Esses exemplos mostram interações comuns com tabelas do Excel.
Criar uma tabela classificada

Esse exemplo cria uma tabela do intervalo usado da planilha atual e, em seguida,
classifica-a com base na primeira coluna.
TypeScript

// Create a table with the used cells.

const usedRange = selectedSheet.getUsedRange();
const newTable = selectedSheet.addTable(usedRange, true);
// Sort the table using the first column.

newTable.getSort().apply([{ key: 0, ascending: true }]);
}
Filtrar uma tabela

Esse exemplo filtra uma tabela existente usando os valores em uma das colunas.
TypeScript



// with a value of "Station-1" in the "Station" column.
stationColumn.getFilter().applyValuesFilter(["Station-1"]);
}
 Dica
Copie as informações filtradas na pasta de trabalho usando Range.copyFrom .
Adicione a linha a seguir ao final do script para criar uma nova planilha com os
dados filtrados.
TypeScript
workbook.addWorksheet().getRange("A1").copyFrom(table.getRange());
Filtrar um valor
O exemplo anterior filtra uma tabela com base em uma lista de valores incluídos. Para
excluir um valor específico da tabela, você precisa fornecer a lista de todos os outros
valores da coluna. Este exemplo usa uma função columnToSet para converter uma
coluna em um conjunto de valores exclusivos. Esse conjunto então tem o valor excluído
("Station-1") removido.
TypeScript


// Get a list of unique values in the station column.

const stationSet = columnToSet(stationColumn);

// that don't have a value of "Station-1" in the "Station" column.
stationColumn.getFilter().applyValuesFilter(stationSet.filter((value) => {
return value !== "Station-1";
}));
}
/**
* Convert a column into a set so it only contains unique values.
*/
function columnToSet(column: ExcelScript.TableColumn): string[] {
const range = column.getRangeBetweenHeaderAndTotal().getValues() as
string[][];
const columnSet: string[] = [];
range.forEach((value) => {
if (!columnSet.includes(value[0])) {
columnSet.push(value[0]);
}
});
return columnSet;
}
Remover filtros de coluna de tabela

Este exemplo remove os filtros de uma coluna de tabela, com base no local da célula
ativa. O script detecta se a célula faz parte de uma tabela, determina a coluna de tabela
e limpa todos os filtros aplicados nela.
Baixe table-with-filter.xlsx para uma pasta de trabalho pronta para uso. Adicione o script
a seguir para experimentar o exemplo por conta própria!
TypeScript

const cell = workbook.getActiveCell();
// Get the tables associated with that cell.

// Since tables can't overlap, this will be one table at most.
const currentTable = cell.getTables()[0];
// If there's no table on the selection, end the script.

if (!currentTable) {
console.log("The selection is not in a table.");
return;
}
// Get the table header above the current cell by referencing its column.
const entireColumn = cell.getEntireColumn();
const intersect = entireColumn.getIntersection(currentTable.getRange());
const headerCellValue = intersect.getCell(0, 0).getValue() as string;
// Get the TableColumn object matching that header.

const tableColumn = currentTable.getColumnByName(headerCellValue);
// Clear the filters on that table column.

tableColumn.getFilter().clear();
}
Antes de limpar o filtro de coluna (observe a célula ativa)

Depois de limpar o filtro de coluna
 Dica
Se você quiser saber mais sobre como salvar o filtro antes de limpá-lo (e se aplicar
novamente posteriormente), consulte Mover linhas entre tabelas salvando filtros,
um exemplo mais avançado.
Referenciar dinamicamente valores de tabela

Este script usa a sintaxe "@COLUMN_NAME" para definir fórmulas em uma coluna de
tabela. Os nomes de coluna na tabela podem ser alterados sem alterar esse script.
TypeScript

const table = workbook.getTable("Profits");
// Get the column names for columns 2 and 3.

// Note that these are 1-based indices.
// Set the formula of the fourth column to be the product of the values
found
// in that row's second and third columns.
const combinedColumn = table.getColumn(4).getRangeBetweenHeaderAndTotal();
combinedColumn.setFormula(`=[@[${nameOfColumn2}]]*[@[${nameOfColumn3}]]`);
}
Antes do script
Janeiro 45 5
Fevereiro 45 3
Março 45 6
Após o script
Janeiro 45 5 225
Fevereiro 45 3 135
Março 45 6 270
Definir formatação condicional para
comparações entre colunas
Artigo • 18/09/2023
Este exemplo mostra como aplicar a formatação condicional a um intervalo. As

condições usadas estão comparando valores com aqueles em uma coluna adjacente.
Além disso, esse exemplo usa parâmetros para obter a entrada do usuário. Isso permite
que a pessoa que executa o script selecione o intervalo, o tipo de comparação e as
cores.
Código de exemplo: definir a formatação

condicional
TypeScript
/**
* Formats a range on the current sheet based on values in an adjacent
column.
* @param rangeAddress The A1-notation range to format.
* @param compareTo The adjacent column to compare against.
* @param colorIfGreater The color of the cell if the value is greater than
the adjacent column.
* @param colorIfEqual The color of the cell if the value is equal to the
adjacent column.
* @param colorIfLess The color of the cell if the value is less than the
adjacent column.
*/
function main(
rangeAddress: string, compareTo: "Left" | "Right",
colorIfGreater: "Red" | "Green" | "Yellow" | "None",
colorIfLess: "Red" | "Green" | "Yellow" | "None",
colorIfEqual: "Red" | "Green" | "Yellow" | "None"
) {
// Get the specified range.
const range = selectedSheet.getRange(rangeAddress);
// Remove old conditional formatting.

range.clearAllConditionalFormats();
// Get the address of the first adjacent cell of the adjacent column.
let adjacentColumn: string;
if (compareTo == "Left") {
adjacentColumn = range.getColumnsBefore().getCell(0, 0).getAddress();
} else {
adjacentColumn = range.getColumnsAfter().getCell(0, 0).getAddress();
}
// Remove the worksheet name from the address to create a relative

formula.
let formula = "=$" +
adjacentColumn.substring(adjacentColumn.lastIndexOf("!") + 1);
// Set the conditional formatting based on the user's color choices.

setConditionalFormatting(
range.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getC
ellValue(),
colorIfGreater,
formula,
ExcelScript.ConditionalCellValueOperator.greaterThan);
ellValue(),
colorIfEqual,
formula,
ExcelScript.ConditionalCellValueOperator.equalTo);
ellValue(),
colorIfLess,
formula,
ExcelScript.ConditionalCellValueOperator.lessThan);
}
function setConditionalFormatting(
conditionalFormat: ExcelScript.CellValueConditionalFormat,
color: "Red" | "Green" | "Yellow" | "None",
formula: string,
operator: ExcelScript.ConditionalCellValueOperator
) {
// Pick the fill and font colors based on the preset color choices.
if (color == "Red") {
conditionalFormat.getFormat().getFont().setColor("#9C0006");
conditionalFormat.getFormat().getFill().setColor("#FFC7CE");
} else if (color == "Green") {
conditionalFormat.getFormat().getFont().setColor("#001600");
conditionalFormat.getFormat().getFill().setColor("#C6EFCE");
} else if (color == "Yellow") {
conditionalFormat.getFormat().getFont().setColor("#9C5700");
conditionalFormat.getFormat().getFill().setColor("#FFEB9C");
} else { /* None */
return;
}
// Apply the conditional formatting.

conditionalFormat.setRule({
formula1: formula,
operator: operator
});
}
Usar chamadas de busca externa em
Scripts do Office
Artigo • 30/03/2023
Este script obtém informações básicas sobre os repositórios do GitHub de um usuário.

Ele mostra como usar fetch em um cenário simples. Para obter mais informações sobre
o uso fetch ou outras chamadas externas, leia Suporte a chamadas de API externa em
Scripts do Office. Para obter informações sobre como trabalhar com objetos JSON ,
como o que é retornado pelas APIs do GitHub, leia Usar JSON para passar dados de e
para scripts do Office.
Saiba mais sobre as APIs do GitHub que estão sendo usadas na referência da API do
GitHub . Você também pode ver a saída de chamada de API bruta visitando
https://api.github.com/users/{USERNAME}/repos em um navegador da Web (certifique-
se de substituir o espaço reservado {USERNAME} pela ID do GitHub).
Código de exemplo: obter informações básicas

sobre os repositórios do GitHub do usuário
TypeScript
// Call the GitHub REST API.
// Replace the {USERNAME} placeholder with your GitHub username.
const response = await
fetch('https://api.github.com/users/{USERNAME}/repos');
const repos: Repository[] = await response.json();
// Create an array to hold the returned values.

const rows: (string | boolean | number)[][] = [];
// Convert each repository block into a row.

for (let repo of repos) {
rows.push([repo.id, repo.name, repo.license?.name, repo.license?.url]);
}
// Create a header row.
sheet.getRange('A1:D1').setValues([["ID", "Name", "License Name", "License
URL"]]);
// Add the data to the current worksheet, starting at "A2".

const range = sheet.getRange('A2').getResizedRange(rows.length - 1,
rows[0].length - 1);
range.setValues(rows);
}
// An interface matching the returned JSON for a GitHub repository.

interface Repository {
name: string,
id: string,
license?: License
}
// An interface matching the returned JSON for a GitHub repo license.

interface License {
name: string,
url: string
}
Vídeo de treinamento: como fazer chamadas

de API externas
Combinar planilhas em uma única pasta
de trabalho
Artigo • 06/12/2023
Este exemplo mostra como extrair dados de várias pastas de trabalho em uma única
pasta de trabalho centralizada. Ele usa dois scripts: um para recuperar informações de
uma pasta de trabalho e outro para criar novas planilhas com essas informações. Ele
combina os scripts em um fluxo do Power Automate que atua em uma pasta inteira do
OneDrive.
） Importante
Esse exemplo copia apenas os valores das outras pastas de trabalho. Ele não
preserva a formatação, gráficos, tabelas ou outros objetos.
Solução
1. Crie um novo arquivo do Excel no OneDrive. O nome do arquivo
"Combination.xlsx" é usado neste exemplo.
2. Crie e salve os dois scripts deste exemplo.
3. Crie uma pasta no OneDrive e adicione uma ou mais pastas de trabalho com
dados a ela. O nome da pasta "saída" é usado neste exemplo.
4. Crie um fluxo (conforme descrito na seção Fluxo do Power Automate deste artigo)
para executar estas etapas:
a. Liste todos os arquivos da pasta "saída".
b. Use o script Devolução de dados da planilha para obter os dados de cada
planilha em cada uma das pastas de trabalho.
c. Use o script Adicionar planilhas para criar uma nova planilha na pasta de
trabalho "Combination.xlsx" para cada planilha em todos os outros arquivos.
Código de exemplo: retornar dados da planilha

TypeScript
/**
* This script returns the values from the used ranges on each worksheet.
*/
function main(workbook: ExcelScript.Workbook): WorksheetData[] {
// Create an object to return the data from each worksheet.
let worksheetInformation: WorksheetData[] = [];
// Get the data from every worksheet, one at a time.

workbook.getWorksheets().forEach((sheet) => {
let values = sheet.getUsedRange()?.getValues();
worksheetInformation.push({
name: sheet.getName(),
data: values as string[][]
});
});
return worksheetInformation;
}
// An interface to pass the worksheet name and cell values through a flow.
interface WorksheetData {
name: string;
data: string[][];
}
Código de exemplo: adicionar planilhas

TypeScript
/**
* This script creates a new worksheet in the current workbook for each
WorksheetData object provided.
*/
function main(workbook: ExcelScript.Workbook, workbookName: string,
worksheetInformation: WorksheetData[]) {
// Add each new worksheet.
worksheetInformation.forEach((value) => {
let sheet = workbook.addWorksheet(`${workbookName}.${value.name}`);
// If there was any data in the worksheet, add it to a new range.

if (value.data) {
let range = sheet.getRangeByIndexes(0, 0, value.data.length,
value.data[0].length);
range.setValues(value.data);
}
});
}
// An interface to pass the worksheet name and cell values through a flow.
interface WorksheetData {
name: string;
data: string[][];
}
Fluxo do Power Automate: combinar planilhas
em uma única pasta de trabalho
1. Entre no Power Automate e crie um novo fluxo de nuvem instantânea.
2. Escolha Disparar manualmente um fluxo e selecione Criar.
3. Obtenha todas as pastas de trabalho que você deseja combinar de sua pasta.
Adicione uma ação e escolha os arquivos list do conector OneDrive for Business
na ação de pasta. Para o campo Pasta , use o seletor de arquivos para selecionar a
pasta "saída".
4. Adicione uma ação para executar o script de dados da planilha Retornar para
obter todos os dados de cada uma das pastas de trabalho. Escolha a ação executar
script do conector do Excel Online (Business). Use os valores a seguir para a ação.
Observe que quando você adicionar a Id para o arquivo, o Power Automate
encerrará a ação em um controle For each, para que a ação seja executada em
cada arquivo.

Arquivo: Id (conteúdo dinâmico de Listar arquivos na pasta)
Script: Retornar dados da planilha
5. Adicione uma ação para executar o script Adicionar planilhas no novo arquivo do
Excel que você criou. Isso adicionará os dados de todas as outras pastas de
trabalho. Após a ação de script de execução anterior e dentro do controle For
each, adicione uma ação que usa a ação executar script do conector do Excel
Online (Business). Use os valores a seguir para a ação.

Arquivo: "Combination.xlsx" (seu arquivo, conforme selecionado pelo seletor
de arquivos)
Script: Adicionar planilhas
workbookName: Nome (conteúdo dinâmico de Arquivos de lista na pasta)
worksheetInformation (consulte a nota a seguir à próxima imagem):
resultado (conteúdo dinâmico de Executar script)
７ Observação
Selecione o botão Alternar para inserir toda a matriz para adicionar o objeto
array diretamente, em vez de itens individuais para a matriz. Faça isso antes
de inserir o resultado.
6. Salve o fluxo. O designer de fluxo deve se parecer com a imagem a seguir.
7. Use o botão Testar na página do editor de fluxo ou execute o fluxo por meio da
guia Meus fluxos . Certifique-se de permitir o acesso quando solicitado.
8. O arquivo "Combination.xlsx" agora deve ter novas planilhas.
Um recurso com o mesmo nome ou identificador já existe: esse erro
provavelmente indica que a pasta de trabalho "Combination.xlsx" já tem uma
planilha com o mesmo nome. Isso acontecerá se você executar o fluxo várias vezes
com as mesmas pastas de trabalho. Crie uma pasta de trabalho sempre para
armazenar os dados combinados ou usar nomes de arquivo diferentes na pasta
"saída".
O argumento é inválido ou ausente ou tem um formato incorreto: esse erro pode
significar que o nome da planilha gerada não atende aos requisitos do Excel .
Isso é provável porque o nome é muito longo. Se os nomes da planilha tiverem
mais de 30 caracteres, substitua o código em "Adicionar planilhas" que chama
addWorksheet por algo que encurta a cadeia de caracteres. Como o nome da pasta
de trabalho em si pode ser muito longo, adicione um número de incremento ao

final do nome da planilha. Declare esse número fora do forEach loop.
TypeScript
let worksheetNumber = 1;
// Add each new worksheet.
worksheetInformation.forEach((value) => {
let worksheetName = `${workbookName}.${value.name}`;
let sheet =
workbook.addWorksheet(`${worksheetName.substr(0,30)}${worksheetNumber++
}`);
Além disso, se os nomes da pasta de trabalho tiverem mais de 30 caracteres, você

precisará encurtá-los no fluxo. Primeiro, você deve criar uma variável no fluxo para
acompanhar a contagem de pastas de trabalho. Isso evitará que nomes abreviados
idênticos sejam passados para o script. Adicione uma ação de variável Initialize
antes do fluxo (do tipo "Integer") e uma ação de variável Incrementar entre as
duas ações executar script . Em seguida, em vez de usar Name como a pasta de
trabalhoName em "Executar script 1", use a expressão
substring(items('Apply_to_each')?['Name'],0,min(length(items('Apply_to_each')?
['Name']),20)) e o conteúdo dinâmico de sua variável. Isso reduz os nomes da
pasta de trabalho para 20 caracteres e acrescenta o número da pasta de trabalho

atual à cadeia de caracteres que está sendo passada para o script.
７ Observação
Em vez de tornar o fluxo e o script mais complicados, talvez seja mais fácil
garantir que os nomes do arquivo e da planilha sejam curtos o suficiente.
Converter arquivos CSV em pastas de
trabalho do Excel
Artigo • 27/01/2024
Muitos serviços exportam dados como arquivos CSV (valor separado por vírgula). Essa
solução automatiza o processo de conversão desses arquivos CSV em pastas de
trabalho do Excel no formato de arquivo .xlsx. Ele usa um fluxo do Power Automate
para encontrar arquivos com a extensão .csv em uma pasta do OneDrive e um Script do
Office para copiar os dados do arquivo .csv em uma nova pasta de trabalho do Excel.
Solução
1. Armazene os arquivos .csv e um arquivo "Modelo" em branco .xlsx em uma pasta
do OneDrive.
2. Crie um Script do Office para analisar os dados CSV em um intervalo.
3. Crie um fluxo do Power Automate para ler os arquivos .csv e passar seu conteúdo
para o script.
Arquivos de exemplo
Baixe convert-csv-example.zip para obter o arquivo Template.xlsx e dois arquivos .csv
de exemplo. Extraia os arquivos em uma pasta no OneDrive. Este exemplo pressupõe
que a pasta seja chamada de "saída".
Adicione o script a seguir à pasta de trabalho de exemplo. Salve-o como Converter CSV
e experimente o exemplo por conta própria!
Código de exemplo: inserir valores separados

por vírgula em uma pasta de trabalho
TypeScript
/**
* Convert incoming CSV data into a range and add it to the workbook.
*/
function main(workbook: ExcelScript.Workbook, csv: string) {
let sheet = workbook.getWorksheet("Sheet1");
// Remove any Windows \r characters.

csv = csv.replace(/\r/g, "");
// Split each line into a row.
let rows = csv.split("\n");
/*
* For each row, match the comma-separated sections.
* For more information on how to use regular expressions to parse CSV
files,
* see this Stack Overflow post:
https://stackoverflow.com/a/48806378/9227753
*/
const csvMatchRegex = /(?:,|\n|^)("(?:(?:"")*[^"]*)*"|[^",\n]*|(?:\n|$))/g
rows.forEach((value, index) => {
if (value.length > 0) {
let row = value.match(csvMatchRegex);
// Check for blanks at the start of the row.

if (row[0].charAt(0) === ',') {
row.unshift("");
}
// Remove the preceding comma and surrounding quotation marks.

row.forEach((cell, index) => {
cell = cell.indexOf(",") === 0 ? cell.substring(1) : cell;
row[index] = cell.indexOf("\"") === 0 && cell.lastIndexOf("\"") ===
cell.length - 1 ? cell.substring(1, cell.length - 1) : cell;
});
// Create a 2D array with one row.

let data: string[][] = [];
data.push(row);
// Put the data in the worksheet.

let range = sheet.getRangeByIndexes(index, 0, 1, data[0].length);
range.setValues(data);
}
});
// Add any formatting or table creation that you want.

}
Power Automate flow: criar novos arquivos de

.xlsx
1. Entre no Power Automate e crie um novo fluxo de nuvem agendado.
2. Defina o fluxo como Repetir cada "1" "Dia" e selecione Criar.
3. Obtenha o arquivo do Excel de modelo. Essa é a base para todos os arquivos .csv
convertidos. No construtor de fluxos, selecione o + botão e Adicione uma ação.
Selecione a ação Obter conteúdo de arquivo do conector OneDrive for Business.
Forneça o caminho do arquivo para o arquivo "Template.xlsx".
Arquivo: /output/Template.xlsx
4. Renomeie a etapa Obter conteúdo do arquivo . Selecione o título atual, "Obter

conteúdo do arquivo", no painel de tarefas de ação. Altere o nome para "Obter
modelo do Excel".
5. Adicione uma ação que obtém todos os arquivos na pasta "saída". Escolha os
arquivos lista do conector OneDrive for Business na ação de pasta. Forneça o
caminho da pasta que contém os arquivos .csv.
Pasta: /output
6. Adicione uma condição para que o fluxo funcione apenas em arquivos .csv.
Adicione a ação de controle condição . Use os valores a seguir para a Condição.
Escolha um valor: Nome (conteúdo dinâmico de Listar arquivos na pasta).

Observe que esse conteúdo dinâmico tem vários resultados, portanto, um
para cada controle envolve a Condição.
termina com (da lista suspensa)
Escolha um valor: .csv
7. O restante do fluxo está na seção Se sim , já que só queremos agir em .csv

arquivos. Obtenha um arquivo de .csv individual adicionando uma ação que usa a
ação Obter conteúdo do arquivo do conector OneDrive for Business. Use a ID do
conteúdo dinâmico de Listar arquivos na pasta.
Arquivo: Id (conteúdo dinâmico dos arquivos list na etapa de pasta )
8. Renomeie a nova etapa Obter conteúdo do arquivo para "Obter .csv arquivo". Isso
ajuda a distinguir esse arquivo do modelo do Excel.
9. Faça o novo arquivo .xlsx, usando o modelo do Excel como o conteúdo base.
Adicione uma ação que usa a ação Criar arquivo do conector OneDrive for
Business. Use os seguintes valores.
Caminho da pasta: /output
Nome do arquivo: nome sem extensão.xlsx (escolha o Nome sem conteúdo
dinâmico de extensão nos arquivos List na pasta e digite manualmente
".xlsx" após ele)
Conteúdo do arquivo: conteúdo do arquivo (conteúdo dinâmico do modelo
Get Excel)
10. Execute o script para copiar dados na nova pasta de trabalho. Adicione a ação
executar script do conector do Excel Online (Business). Use os valores a seguir
para a ação.

Arquivo: Id (conteúdo dinâmico de Criar arquivo)
Script: Converter CSV
csv: Conteúdo do arquivo (conteúdo dinâmico do arquivo Obter .csv)
13. Você deve encontrar novos arquivos .xlsx na pasta "saída", juntamente com os
arquivos .csv originais. As novas pastas de trabalho contêm os mesmos dados que
os arquivos CSV.
Teste de script
Para testar o script sem usar o Power Automate, atribua um valor a csv antes de usá-lo.
Adicione o código a seguir como a primeira linha da main função e selecione Executar.
TypeScript
csv = `1, 2, 3
4, 5, 6
7, 8, 9`;
Arquivos separados por ponto e vírgula e outros

separadores alternativos
Algumas regiões usam ponto-e-vírgula (';') para separar valores de células em vez de
vírgulas. Nesse caso, você precisa alterar as linhas a seguir no script.
1. Substitua as vírgulas por ponto-e-vírgula na instrução de expressão regular. Isso

começa com let row = value.match .
TypeScript
let row = value.match(/(?:;|\n|^)("(?:(?:"")*[^"]*)*"|[^";\n]*|

(?:\n|$))/g);
2. Substitua a vírgula por um ponto e vírgula no marcar para a primeira célula em

branco. Isso começa com if (row[0].charAt(0) .
TypeScript
if (row[0].charAt(0) === ';') {
3. Substitua a vírgula por um ponto e vírgula na linha que remove o caractere de

separação do texto exibido. Isso começa com row[index] = cell.indexOf .
TypeScript
row[index] = cell.indexOf(";") === 0 ? cell.substr(1) : cell;
７ Observação
Se o arquivo usar guias ou qualquer outro caractere para separar os valores,

substitua o ; nas substituições acima por \t ou qualquer caractere que esteja
sendo usado.
Arquivos CSV grandes

Se o arquivo tiver centenas de milhares de células, você poderá alcançar o limite de
transferência de dados do Excel. Você precisará forçar o script a sincronizar com o Excel
periodicamente. A maneira mais fácil de fazer isso é chamar console.log depois que um
lote de linhas tiver sido processado. Adicione as seguintes linhas de código para fazer
isso acontecer.
1. Antes rows.forEach((value, index) => { de , adicione a linha a seguir.
TypeScript
let rowCount = 0;
2. Depois range.setValues(data); de , adicione o código a seguir. Observe que,

dependendo do número de colunas, talvez seja necessário reduzir 5000 para um
número menor.
TypeScript
rowCount++;
if (rowCount % 5000 === 0) {
console.log("Syncing 5000 rows.");
}
２ Aviso
Se o arquivo CSV for muito grande, você poderá ter problemas de tempo limite no
Power Automate. Você precisará dividir os dados CSV em vários arquivos antes de
convertê-los em pastas de trabalho do Excel.
Ênfases e outros caracteres unicode

Arquivos com caracteres específicos de unicódigo, como vogais acentuadas como é ,
precisam ser salvos com a codificação correta. A criação de arquivos do conector do
OneDrive do Power Automate é padrão para ANSI para arquivos .csv. Se você estiver
criando os arquivos .csv no Power Automate, precisará adicionar a marca de pedido de
byte (BOM) antes dos valores separados por vírgulas. Para UTF-8, substitua o
conteúdo do arquivo para a operação de arquivo de gravação .csv pela expressão
concat(uriComponentToString('%EF%BB%BF'), <CSV Input>) (onde <CSV Input> estão os
dados CSV originais).
Observe que esse exemplo não cria os arquivos .csv no fluxo, portanto, essa alteração
precisa acontecer na parte personalizada do fluxo. Você também pode ler e reescrever
os arquivos .csv com o BOM, se não controlar como esses arquivos são criados.
Aspas ao redor
Este exemplo remove todas as aspas ("") que cercam valores. Normalmente, eles são
adicionados a valores separados por vírgulas para evitar que vírgulas nos dados sejam
tratadas como tokens de separação. Um arquivo .csv aberto no Excel, salvo como um
arquivo .xlsx, nunca terá as aspas mostradas ao leitor. Se desejar manter as aspas e
exibi-las nas planilhas finais, substitua as linhas 27-30 do script pelo código a seguir.
TypeScript
// Remove the preceding comma.

row.forEach((cell, index) => {
row[index] = cell.indexOf(",") === 0 ? cell.substring(1) : cell;
});
A fonte deste conteúdo pode O Office Scripts é um projeto código aberto.
ser encontrada no GitHub, onde Selecione um link para fornecer
de pull. Para obter mais  Abrir um problema de documentação
guia para colaboradores.  Fornecer comentários sobre o produto
Arquivos do Excel de referência cruzada
com o Power Automate
Artigo • 06/12/2023
Essa solução mostra como comparar dados entre dois arquivos do Excel para encontrar
discrepâncias. Ele usa scripts do Office para analisar dados e Power Automate para se
comunicar entre as pastas de trabalho.
Esse exemplo passa dados entre pastas de trabalho usando objetos JSON . Para obter
mais informações sobre como trabalhar com JSON, leia Usar JSON para passar dados de
e para scripts do Office.
Cenário de exemplo
Você é um coordenador de eventos que está agendando palestrantes para as próximas
conferências. Você mantém os dados do evento em uma planilha e os registros do alto-
falante em outra. Para garantir que as duas pastas de trabalho sejam mantidas em
sincronização, use um fluxo com scripts do Office para destacar possíveis problemas.
Exemplo de arquivos do Excel

Baixe os arquivos a seguir para obter pastas de trabalho prontas para uso para o
exemplo.
1. event-data.xlsx
2. speaker-registrations.xlsx
Adicione os scripts a seguir para experimentar o exemplo por conta própria!
Código de exemplo: obter dados de evento

TypeScript
function main(workbook: ExcelScript.Workbook): string {

// Get the first table in the "Keys" worksheet.
let table = workbook.getWorksheet('Keys').getTables()[0];
// Get the rows in the event table.

let range = table.getRangeBetweenHeaderAndTotal();
let rows = range.getValues();
// Save each row as an EventData object. This lets them be passed through
Power Automate.
let records: EventData[] = [];
for (let row of rows) {
let [eventId, date, location, capacity] = row;
records.push({
eventId: eventId as string,
date: date as number,
location: location as string,
capacity: capacity as number
})
}
// Log the event data to the console and return it for a flow.
let stringResult = JSON.stringify(records);
console.log(stringResult);
return stringResult;
}
// An interface representing a row of event data.

interface EventData {
eventId: string
date: number
location: string
capacity: number
}
Código de exemplo: validar registros de alto-

falante
TypeScript
function main(workbook: ExcelScript.Workbook, keys: string): string {

// Get the first table in the "Transactions" worksheet.
let table = workbook.getWorksheet('Transactions').getTables()[0];
// Clear the existing formatting in the table.

let range = table.getRangeBetweenHeaderAndTotal();
range.clear(ExcelScript.ClearApplyTo.formats);
// Compare the data in the table to the keys passed into the script.
let keysObject = JSON.parse(keys) as EventData[];
let speakerSlotsRemaining = keysObject.map(value => value.capacity);
let overallMatch = true;
// Iterate over every row looking for differences from the other
worksheet.
let rows = range.getValues();
for (let i = 0; i < rows.length; i++) {
let row = rows[i];
let [eventId, date, location, capacity] = row;
let match = false;
// Look at each key provided for a matching Event ID.

for (let keyIndex = 0; keyIndex < keysObject.length; keyIndex++) {
let event = keysObject[keyIndex];
if (event.eventId === eventId) {
match = true;
speakerSlotsRemaining[keyIndex]--;
// If there's a match on the event ID, look for things that don't
match and highlight them.
if (event.date !== date) {
overallMatch = false;
range.getCell(i, 1).getFormat()
.getFill()
.setColor("FFFF00");
}
if (event.location !== location) {
.getFill()
}
break;
}
}
// If no matching Event ID is found, highlight the Event ID's cell.

if (!match) {
.getFill()
}
}
// Choose a message to send to the user.

let returnString = "All the data is in the right order.";
if (overallMatch === false) {
returnString = "Mismatch found. Data requires your review.";
} else if (speakerSlotsRemaining.find(remaining => remaining < 0)){
returnString = "Event potentially overbooked. Please review."
}
console.log("Returning: " + returnString);

return returnString;
}
// An interface representing a row of event data.

interface EventData {
eventId: string
date: number
location: string
capacity: number
}
Fluxo do Power Automate: verifique se há

inconsistências nas pastas de trabalho
Esse fluxo extrai as informações do evento da primeira pasta de trabalho e usa esses
dados para validar a segunda pasta de trabalho.
3. No construtor de fluxos, selecione o + botão e Adicione uma ação. Selecione a

ação executar script do conector do Excel Online (Business). Use os valores a
seguir para a ação.

Arquivo: event-data.xlsx (selecionado com o seletor de arquivo)
Script: Obter dados de evento
4. Renomeie esta etapa. Selecione o nome atual "Executar script" no painel de tarefas
e altere-o para "Obter dados de evento".
5. Adicione uma segunda ação que usa a ação executar script do conector do Excel
Online (Business). Essa ação usa os valores retornados do script Obter dados de
evento como entrada para o script de dados de evento Validar . Use os valores a

Arquivo: speaker-registration.xlsx (selecionado com o seletor de arquivo)
Script: Validar o registro de alto-falante
chaves: resultado (conteúdo dinâmico de Obter dados de evento)
6. Renomeie esta etapa também. Selecione o nome atual "Executar script 1" no painel
de tarefas e altere-o para "Validar registro de alto-falante".
7. Este exemplo usa o Outlook como o cliente de email. Para este exemplo, adicione
a Office 365 a ação Enviar e enviar e enviar email (V2) do conector do Outlook.
Você pode usar qualquer conector de email compatível com o Power Automate.
Essa ação usa os valores retornados do script de registro do alto-falante Validar
como o conteúdo do corpo do email. Use os valores a seguir para a ação.
Para: sua conta de email de teste (ou email pessoal)

Assunto: Resultados da validação de eventos
Corpo: resultado (conteúdo dinâmico do registro de alto-falante validado)
10. Você deve receber um email dizendo "Incompatibilidade encontrada. Os dados

exigem sua revisão.". Isso indica que há diferenças entre linhas em speaker-
registrations.xlsx e linhas no event-data.xlsx. Abra speaker-registrations.xlsx para
ver várias células realçadas em que há possíveis problemas com as listagens de
registro de alto-falante.
Usar Scripts do Office e Power
Automate para enviar imagens por
email de um gráfico e uma tabela
Artigo • 06/12/2023
Este exemplo usa Scripts do Office e Power Automate para criar um gráfico. Em seguida,
ele envia imagens do gráfico e sua tabela base.
Cenário de exemplo
Calcule para obter os resultados mais recentes.
Criar gráfico.
Obtenha gráfico e imagens de tabela.
Email as imagens com o Power Automate.
Dados de entrada
Gráfico de saída
Email que foi recebido por meio do fluxo do Power
Automate
Solução
Essa solução tem duas partes:
1. Um Script do Office para calcular e extrair gráfico e tabela do Excel

2. Um fluxo do Power Automate para invocar o script e enviar os resultados por
email. Para obter um exemplo sobre como fazer isso, consulte Criar um fluxo de
trabalho automatizado com o Power Automate.

Código de exemplo: calcular e extrair gráfico e

tabela do Excel
Adicione o script a seguir à pasta de trabalho de exemplo. Salve-a como Obter imagem
do gráfico e experimente a amostra por conta própria!
TypeScript
function main(workbook: ExcelScript.Workbook): ReportImages {

// Recalculate the workbook to ensure all tables and charts are updated.
// Get the data from the "InvoiceAmounts" table.

const sheet1 = workbook.getWorksheet("Sheet1");
const table = workbook.getWorksheet('InvoiceAmounts').getTables()[0];
const rows = table.getRange().getTexts();
// Get only the "Customer Name" and "Amount due" columns, then remove the
"Total" row.
const selectColumns = rows.map((row) => {
return [row[2], row[5]];
});
table.setShowTotals(true);
selectColumns.splice(selectColumns.length - 1, 1);
console.log(selectColumns);
// Delete the "ChartSheet" worksheet if it's present, then recreate it.

workbook.getWorksheet('ChartSheet')?.delete();
const chartSheet = workbook.addWorksheet('ChartSheet');
// Add the selected data to the new worksheet.

const targetRange =
chartSheet.getRange('A1').getResizedRange(selectColumns.length - 1,
selectColumns[0].length - 1);
targetRange.setValues(selectColumns);
// Insert the chart on sheet 'ChartSheet' at cell "D1".

const chart = chartSheet.addChart(ExcelScript.ChartType.columnClustered,
targetRange);
chart.setPosition('D1');
// Get images of the chart and table, then return them for a Power
Automate flow.
const chartImage = chart.getImage();
const tableImage = table.getRange().getImage();
return { chartImage, tableImage };
}
// The interface for table and chart images.
interface ReportImages {
chartImage: string
tableImage: string
}
Power Automate flow: Email as imagens do

gráfico e da tabela
Esse fluxo executa o script e envia emails às imagens retornadas.
1. Crie um novo fluxo de nuvem instantânea.
3. Este exemplo requer recursos do Power Automate que não têm suporte no novo
designer de fluxo (adicionando HTML a um email). Alterne para o designer antigo
com o alternância no canto superior direito da tela.
4. Adicione uma nova etapa que usa o conector do Excel Online (Business) com a
ação Executar script . Use os valores a seguir para a ação.

Arquivo: email-chart-table.xlsx (selecionado com o seletor de arquivo)
Script: Obter imagem do gráfico
5. Este exemplo usa o Outlook como o cliente de email. Você pode usar qualquer
suporte do Power Automate do conector de email, mas o restante das etapas
pressupõe que você escolheu o Outlook. Adicione uma nova etapa que usa o
conector Office 365 Outlook e a ação Enviar e enviar email (V2). Use os valores a
Para: sua conta de email de teste (ou email pessoal)

Assunto: Examine os dados do relatório
Para o campo Corpo , selecione "Exibição de Código" ( </> ) e insira o
seguinte:
HTML
Please review the following report data: 

 
Chart: 
 
<img src="data:image/png;base64,@{outputs('Run_script')?
['body/result/chartImage']}"/>
 
Data: 
 
<img src="data:image/png;base64,@{outputs('Run_script')?
['body/result/tableImage']}"/>
 

6. Salve o fluxo e experimente-o. Use o botão Testar na página do editor de fluxo ou
execute o fluxo por meio da guia Meus fluxos . Certifique-se de permitir o acesso
quando solicitado.
Vídeo de treinamento: extrair e enviar imagens

de email do gráfico e da tabela
Registrar alterações diárias no Excel e
denunciá-las com um fluxo do Power
Automate
Artigo • 07/12/2023
Power Automate e Office Scripts combinam para lidar com tarefas repetitivas para você.
Neste exemplo, você tem a tarefa de gravar uma única leitura numérica em uma pasta
de trabalho todos os dias e relatar a alteração desde ontem. Você criará um fluxo para
obter essa leitura, fazer logon na pasta de trabalho e relatar a alteração por meio de um
email.

Código de exemplo: registrar e relatar leituras

diárias
Adicione o script a seguir à pasta de trabalho de exemplo. Salve-o como Registro de
valor diário e experimente a amostra por conta própria!
TypeScript
function main(workbook: ExcelScript.Workbook, newData: string): string {

// Get the table by its name.
const table = workbook.getTable("ReadingTable");
// Read the current last entry in the Reading column.

const readingColumn = table.getColumnByName("Reading");
const readingColumnValues = readingColumn.getRange().getValues();
const previousValue = readingColumnValues[readingColumnValues.length - 1]
[0] as number;
// Add a row with the date, new value, and a formula calculating the
difference.
const currentDate = new Date(Date.now()).toLocaleDateString();
const newRow = [currentDate, newData, "=[@Reading]-
OFFSET([@Reading],-1,0)"];
table.addRow(-1, newRow,);
// Return the difference between the newData and the previous entry.
const difference = Number.parseFloat(newData) - previousValue;
console.log(difference);
return difference;
}
Fluxo de exemplo: relatar alterações diárias

Siga estas etapas para criar um fluxo do Power Automate para o exemplo.
1. Crie um novo fluxo de nuvem agendado.
2. Agende o fluxo para repetir a cada 1 dia.
3. Selecione Criar.
4. Em um fluxo real, você adicionará uma etapa que obtém seus dados. Os dados
podem vir de outra pasta de trabalho, um cartão adaptável do Teams ou qualquer
outra fonte. Para testar o exemplo, faça um número de teste. Adicione uma ação e
escolha a ação Inicializar variável . Dê-lhe os valores a seguir.
a. Nome: Entrada
b. Tipo: Inteiro
c. Valor: 190000
5. Adicione uma ação e escolha a ação executar script do conector do Excel Online
(Business). Use os valores a seguir para a ação.
a. Localização: OneDrive for Business
b. Biblioteca de Documentos: OneDrive
c. Arquivo: daily-readings.xlsx (Escolhido por meio do navegador de arquivos)
d. Script: Registrar valor diário
e. newData: Entrada (conteúdo dinâmico)
6. O script retorna a diferença de leitura diária como conteúdo dinâmico chamado

"resultado". Para o exemplo, você pode enviar as informações por email para si
mesmo. Adicione uma ação e escolha a ação Enviar um email (V2) do conector do
Outlook (ou qualquer cliente de email que você preferir). Use os valores a seguir
para concluir a ação.
a. Para: Seu endereço de email
b. Assunto: alteração diária de leitura
c. Corpo: resultado de "Diferença de ontem:" (conteúdo dinâmico do Excel)
7. Salve o fluxo e experimente-o. Use o botão Testar na página do editor de fluxo.

Certifique-se de permitir o acesso quando solicitado.
Executar um script em todos os arquivos
do Excel em uma pasta
Artigo • 06/12/2023
Este projeto executa um conjunto de tarefas de automação em todos os arquivos

situados em uma pasta no OneDrive for Business. Ele também pode ser usado em uma
pasta do SharePoint. Ele executa cálculos nos arquivos do Excel, adiciona formatação e
insere um comentário que @mentions um colega.
Exemplo de arquivos do Excel

Baixe highlight-alert-excel-files.zip para todas as pastas de trabalho que você
precisará para este exemplo. Extraia esses arquivos para uma pasta intitulada Vendas.
Adicione o script a seguir à coleção de scripts para experimentar o exemplo por conta
própria!
Código de exemplo: adicionar formatação e

inserir comentário
Este é o script que é executado em cada pasta de trabalho individual. Adicione-o à pasta
de trabalho de exemplo. Salve-o como Revisar script e experimente o exemplo por
conta própria!
TypeScript

// Get the table named "Table1" in the workbook.
const table1 = workbook.getTable("Table1");
// If the table is empty, end the script.

const rowCount = table1.getRowCount();
if (rowCount === 0) {
return;
}
// Force the workbook to be completely recalculated.

// Get the "Amount Due" column from the table.

const amountDueColumn = table1.getColumnByName('Amount Due');
const amountDueValues =
amountDueColumn.getRangeBetweenHeaderAndTotal().getValues();
// Find the highest amount that's due.
let highestValue = amountDueValues[0][0];
let row = 0;
for (let i = 1; i < amountDueValues.length; i++) {
if (amountDueValues[i][0] > highestValue) {
highestValue = amountDueValues[i][0];
row = i;
}
}
let highestAmountDue = table1.getColumn("Amount

due").getRangeBetweenHeaderAndTotal().getRow(row);
// Set the fill color to yellow for the cell with the highest value in the
"Amount Due" column.
highestAmountDue.getFormat().getFill().setColor("FFFF00");
// Insert an @mention comment in the cell.

workbook.addComment(highestAmountDue, {
mentions: [{
email: "AdeleV@M365x904181.OnMicrosoft.com",
id: 0,
name: "Adele Vance"
}],
richContent: "<at id=\"0\">Adele Vance</at> Please review this amount"
}, ExcelScript.ContentType.mention);
}
Fluxo do Power Automate: execute o script em

cada pasta de trabalho na pasta
Esse fluxo executa o script em cada pasta de trabalho na pasta "Vendas".
3. No construtor de fluxos, selecione o + botão e Adicione uma ação. Use os

arquivos list do conector OneDrive for Business em ação de pasta. Use os valores
a seguir para a ação.
Pasta: /Sales (selecionado pelo seletor de arquivos)

4. Verifique se somente as pastas de trabalho estão selecionadas. Adicione uma nova
ação de controle de condição . Use os valores a seguir para a condição.
Escolha um valor: Nome (conteúdo dinâmico de Listar arquivos na pasta)

termina com: (da lista suspensa)
Escolha um valor: .xlsx
5. No branch True , adicione uma nova ação. Selecione a ação executar script do
conector do Excel Online (Business). Use os valores a seguir para a ação.

Arquivo: Id (conteúdo dinâmico de Listar arquivos na pasta)
Script: Revisar script
7. Experimente! Use o botão Testar na página do editor de fluxo ou execute o fluxo
por meio da guia Meus fluxos . Certifique-se de permitir o acesso quando
solicitado.
Vídeo de treinamento: executar um script em

todos os arquivos do Excel em uma pasta
Escrever um grande conjuntos de dados
Artigo • 07/12/2023
A Range.setValues() API coloca os dados em um intervalo. Essa API tem limitações

dependendo de vários fatores, como tamanho de dados e configurações de rede. Isso
significa que, se você tentar gravar uma quantidade maciça de informações em uma
pasta de trabalho como uma única operação, precisará gravar os dados em lotes
menores para atualizar de forma confiável um grande intervalo.
A primeira parte do exemplo mostra como escrever um grande conjunto de dados no

Excel. A segunda parte expande o exemplo para fazer parte de um fluxo do Power
Automate. Isso será necessário se o script demorar mais tempo para ser executado do
que o tempo limite de ação do Power Automate.
Para noções básicas de desempenho em Scripts do Office, leia Melhorar o desempenho

dos scripts do Office.
Exemplo 1: gravar um conjunto de dados

grande em lotes
Este script grava linhas de um intervalo em partes menores. Ele seleciona 1000 células
para gravar por vez. Execute o script em uma planilha em branco para ver os lotes de
atualização em ação. A saída do console fornece mais informações sobre o que está
acontecendo.
７ Observação
Você pode alterar o número de linhas totais que estão sendo escritas alterando o
valor de SAMPLE_ROWS . Você pode alterar o número de células a serem gravadas
como uma única ação alterando o valor de CELLS_IN_BATCH .
TypeScript

const SAMPLE_ROWS = 100000;
const CELLS_IN_BATCH = 10000;

console.log(`Generating data...`)
let data: (string | number | boolean)[][] = [];
// Generate six columns of random data per row.
for (let i = 0; i < SAMPLE_ROWS; i++) {
data.push([i, ...[getRandomString(5), getRandomString(20),
getRandomString(10), Math.random()], "Sample data"]);
}
console.log(`Calling update range function...`);

const updated = updateRangeInBatches(sheet.getRange("B2"), data,
CELLS_IN_BATCH);
if (!updated) {
console.log(Ùpdate did not take place or complete. Check and run
again.`);
}
}
function updateRangeInBatches(
startCell: ExcelScript.Range,
values: (string | boolean | number)[][],
cellsInBatch: number
): boolean {
const startTime = new Date().getTime();

console.log(`Cells per batch setting: ${cellsInBatch}`);
// Determine the total number of cells to write.

const totalCells = values.length * values[0].length;
console.log(`Total cells to update in the target range: ${totalCells}`);
if (totalCells <= cellsInBatch) {
console.log(`No need to batch -- updating directly`);
updateTargetRange(startCell, values);
return true;
}
// Determine how many rows to write at once.

const rowsPerBatch = Math.floor(cellsInBatch / values[0].length);
console.log("Rows per batch: " + rowsPerBatch);
let rowCount = 0;
let totalRowsUpdated = 0;
let batchCount = 0;
// Write each batch of rows.

rowCount++;
if (rowCount === rowsPerBatch) {
batchCount++;
console.log(`Calling update next batch function. Batch#:
${batchCount}`);
updateNextBatch(startCell, values, rowsPerBatch, totalRowsUpdated);
// Write a completion percentage to help the user understand the

progress.
rowCount = 0;
totalRowsUpdated += rowsPerBatch;
console.log(`${((totalRowsUpdated / values.length) * 100).toFixed(1)}%
Done`);
}
}
console.log(Ùpdating remaining rows -- last batch: ${rowCount}`)

if (rowCount > 0) {
updateNextBatch(startCell, values, rowCount, totalRowsUpdated);
}
let endTime = new Date().getTime();

console.log(`Completed ${totalCells} cells update. It took: ${((endTime -
startTime) / 1000).toFixed(6)} seconds to complete. ${((((endTime -
startTime) / 1000)) / cellsInBatch).toFixed(8)} seconds per ${cellsInBatch}
cells-batch.`);
return true;
}
/**
* A helper function that computes the target range and updates.
*/
function updateNextBatch(
startingCell: ExcelScript.Range,
data: (string | boolean | number)[][],
rowsPerBatch: number,
totalRowsUpdated: number
) {
const newStartCell = startingCell.getOffsetRange(totalRowsUpdated, 0);
const targetRange = newStartCell.getResizedRange(rowsPerBatch - 1,
data[0].length - 1);
console.log(Ùpdating batch at range ${targetRange.getAddress()}`);
const dataToUpdate = data.slice(totalRowsUpdated, totalRowsUpdated +
rowsPerBatch);
try {
targetRange.setValues(dataToUpdate);
} catch (e) {
throw Èrror while updating the batch range: ${JSON.stringify(e)}`;
}
return;
}
/**
* A helper function that computes the target range given the target range's
starting cell
* and selected range and updates the values.
*/
function updateTargetRange(
targetCell: ExcelScript.Range,
values: (string | boolean | number)[][]
) {
const targetRange = targetCell.getResizedRange(values.length - 1,
values[0].length - 1);
console.log(Ùpdating the range: ${targetRange.getAddress()}`);
try {
targetRange.setValues(values);
} catch (e) {
throw Èrror while updating the whole range: ${JSON.stringify(e)}`;
}
return;
}
// Credit: https://www.codegrepper.com/code-
examples/javascript/random+text+generator+javascript
function getRandomString(length: number): string {
var randomChars =
'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
var result = '';
for (var i = 0; i < length; i++) {
result += randomChars.charAt(Math.floor(Math.random() *
randomChars.length));
}
return result;
}
Vídeo de treinamento: gravar um grande conjunto de

dados
Exemplo 2: gravar dados em lotes de um fluxo

do Power Automate
Para este exemplo, você precisará concluir as etapas a seguir.
1. Crie uma pasta de trabalho no OneDrive chamada SampleData.xlsx.

2. Crie uma segunda pasta de trabalho no OneDrive chamada TargetWorkbook.xlsx.
3. Abra SampleData.xlsx.
4. Adicione dados de exemplo. Você pode usar o script na seção Gravar um conjunto
de dados grande em lotes para gerar esses dados.
5. Crie e salve os dois scripts a seguir.
6. Siga as etapas em Fluxo do Power Automate: ler e gravar dados em um loop para
criar o fluxo.
Código de exemplo: ler parte de uma pasta de trabalho

TypeScript
function main(
startRow: number,
batchSize: number
): string[][] {
// This sample only reads the first worksheet in the workbook.
const sheet = workbook.getWorksheets()[0];
// Get the boundaries of the range.

// Note that we're assuming usedRange is too big to read or write as a
single range.
const usedRange = sheet.getUsedRange();
const lastColumnIndex = usedRange.getLastColumn().getColumnIndex();
const lastRowindex = usedRange.getLastRow().getRowIndex();
// If we're starting past the last row, exit the script.

if (startRow > lastRowindex) {
return [[]];
}
// Get the next batch or the rest of the rows, whichever is smaller.
const rowCountToRead = Math.min(batchSize, (lastRowindex - startRow + 1));
const rangeToRead = sheet.getRangeByIndexes(startRow, 0, rowCountToRead,
lastColumnIndex + 1);
return rangeToRead.getValues() as string[][];
}
Código de exemplo: ler linhas selecionadas

TypeScript
function main(
data: string[][],
currentRow: number,
batchSize: number
): boolean {
// Get the first worksheet.
const sheet = workbook.getWorksheets()[0];
// Set the given data.

if (data && data.length > 0) {
sheet.getRangeByIndexes(currentRow, 0, data.length,
data[0].length).setValues(data);
}
// If the script wrote less data than the batch size, signal the end of
the flow.
return batchSize > data.length;
}
Fluxo do Power Automate: ler e gravar dados em um loop
3. Crie uma variável para acompanhar a linha atual que está sendo lida e escrita. No
construtor de fluxos, selecione o + botão e Adicione uma ação. Selecione a ação
Inicializar variável e dê-lhe os valores a seguir.
Nome: currentRow
Tipo: Inteiro
Valor: 0
4. Adicione uma ação para definir o número de linhas a serem lidas em um único
lote. Dependendo do número de colunas, isso pode precisar ser menor para evitar
os limites de transferência de dados. Faça uma nova ação de variável Initialize
com os valores a seguir.
Nome: batchSize
Tipo: Inteiro
Valor: 10000
5. Adicione um controle Fazer até o controle. O fluxo lerá partes dos dados até que
todos eles sejam copiados. Você usará o valor de -1 para indicar que o fim dos
dados foi atingido. Dê ao controle os valores a seguir.
Escolha um valor: currentRow (conteúdo dinâmico)

é igual a (da lista suspensa)
Escolha um valor: -1
6. As etapas restantes são adicionadas dentro do controle Fazer . Em seguida, chame

o script para ler os dados. Adicione a ação executar script do conector do Excel
Online (Business). Renomeie-o para Ler dados. Use os valores a seguir para a
ação.

Arquivo: "SampleData.xlsx" (conforme selecionado pelo seletor de arquivos)
Script: ler linhas selecionadas
startRow: currentRow (conteúdo dinâmico)
batchSize: batchSize (conteúdo dinâmico)
7. Chame o script para gravar os dados. Adicione uma segunda ação executar script .
Renomeie-o para Gravar dados. Use os valores a seguir para a ação.

Arquivo: "TargetWorkbook.xlsx" (conforme selecionado pelo seletor de
arquivos)
Script: gravar dados no local da linha
dados: resultado (conteúdo dinâmico dos dados de leitura)
Pressione a entrada do Switch para a matriz inteira primeiro.
startRow: currentRow (conteúdo dinâmico)
batchSize: batchSize (conteúdo dinâmico)
8. Atualize a linha atual para refletir que um lote de dados foi lido e gravado.
Adicione uma ação de variável Increment com os valores a seguir.
Nome: currentRow
Valor: batchSize (conteúdo dinâmico)
9. Adicione um controle Condição ao marcar se os scripts tiverem lido tudo. O script

"Gravar dados no local da linha" retorna true quando ele grava menos linhas do
que o tamanho do lote permite. Isso significa que ele está no final do conjunto de
dados. Crie a ação de controle condição com os valores a seguir.
Escolha um valor: resultado (conteúdo dinâmico dos dados de gravação)

é igual a (da lista suspensa)
Escolha um valor: true (expressão)
10. Na seção True do controle Condição , defina a variável currentRow como -1.
Adicione uma ação definir variável com os valores a seguir.
Nome: currentRow
Valor: -1
13. O arquivo "TargetWorkbook.xlsx" agora deve ter os dados de "SampleData.xlsx".

Cenário de exemplo de Scripts do
Office: analisar downloads da Web
Artigo • 25/10/2023
Nesse cenário, você tem a tarefa de analisar relatórios de download do site da sua
empresa. O objetivo desta análise é determinar se o tráfego da Web vem do Estados
Unidos ou de outros lugares do mundo.
Seus colegas carregam os dados brutos em sua pasta de trabalho. O conjunto de dados
de cada semana tem sua própria planilha. Há também a planilha Resumo com uma
tabela e um gráfico que mostra tendências semana a semana.
Você desenvolverá um script que analisa dados de downloads semanais na planilha

ativa. Ele analisará o endereço IP associado a cada download e determinará se ele veio
ou não dos EUA. A resposta será inserida na planilha como um valor booliano ("TRUE"
ou "FALSE") e a formatação condicional será aplicada a essas células. Os resultados do
local do endereço IP serão totalizados na planilha e copiados para a tabela de resumo.
Habilidades de script abordadas

Análise de texto
Subfunções em scripts
Formatação condicional
Tabelas
Instruções de instalação
1. Baixe a pasta de trabalho de exemplo para o OneDrive.
2. Abra a pasta de trabalho no Excel.
3. Na guia Automatizar, selecioneNovo Script e cole o script a seguir no editor.
TypeScript

/* Get the Summary worksheet and table.
* End the script early if either object is not in the workbook.
*/
let summaryWorksheet = workbook.getWorksheet("Summary");
if (!summaryWorksheet) {
console.log("The script expects a worksheet named \"Summary\".
Please download the correct template and try again.");
return;
}
let summaryTable = summaryWorksheet.getTable("Table1");
if (!summaryTable) {
console.log("The script expects a summary table named \"Table1\".
Please download the correct template and try again.");
return;
}

let currentWorksheet = workbook.getActiveWorksheet();
if (currentWorksheet.getName().toLocaleLowerCase().indexOf("week")
!== 0) {
console.log("Please switch worksheet to one of the weekly data
sheets and try again.")
return;
}
// Get the values of the active range of the active worksheet.

let logRange = currentWorksheet.getUsedRange();
if (logRange.getColumnCount() !== 8) {
console.log(`Verify that you are on the correct worksheet. Either
the week's data has been already processed or the content is incorrect.
The following columns are expected: ${[
"Time Stamp", "IP Address", "kilobytes", "user agent code",
"milliseconds", "Request", "Results", "Referrer"
]}`);
return;
}
// Get the range that will contain TRUE/FALSE if the IP address is
from the United States (US).
let isUSColumn = logRange
.getLastColumn()
.getOffsetRange(0, 1);
// Get the values of all the US IP addresses.

let ipRange = workbook.getWorksheet("USIPAddresses").getUsedRange();
let ipRangeValues = ipRange.getValues() as number[][];
let logRangeValues = logRange.getValues() as string[][];
// Remove the first row.
let topRow = logRangeValues.shift();
console.log(Ànalyzing ${logRangeValues.length} entries.`);
// Create a new array to contain the boolean representing if this is

a US IP address.
let newCol: (boolean | string)[][] = [];
// Go through each row in worksheet and add Boolean.

for (let i = 0; i < logRangeValues.length; i++) {
let curRowIP = logRangeValues[i][1];
if (findIP(ipRangeValues, ipAddressToInteger(curRowIP)) > 0) {
newCol.push([true]);
} else {
newCol.push([false]);
}
}
// Remove the empty column header and add proper heading.

newCol = [["Is US IP"], ...newCol];
// Write the result to the spreadsheet.

console.log(Àdding column to indicate whether IP belongs to US
region or not at address: ${isUSColumn.getAddress()}`);
console.log(newCol.length);
console.log(newCol);
isUSColumn.setValues(newCol);
// Call the local function to add summary data to the worksheet.

addSummaryData();
// Call the local function to apply conditional formatting.

applyConditionalFormatting(isUSColumn);
// Autofit columns.
currentWorksheet.getUsedRange().getFormat().autofitColumns();
// Get the calculated summary data.

let summaryRangeValues =
currentWorksheet.getRange("J2:M2").getValues();
// Add the corresponding row to the summary table.

summaryTable.addRow(null, summaryRangeValues[0]);
console.log("Complete.");
return;
/**
* A function to add summary data on the worksheet.
*/
function addSummaryData() {
// Add a summary row and table.
let summaryHeader = [["Year", "Week", "US", "Other"]];
let countTrueFormula =
"=COUNTIF(" + isUSColumn.getAddress() + ', "=TRUE")/' +
(newCol.length - 1);
let countFalseFormula =
"=COUNTIF(" + isUSColumn.getAddress() + ', "=FALSE")/' +
(newCol.length - 1);
let summaryContent = [
[
'=TEXT(A2,"YYYY")',
'=TEXTJOIN(" ", FALSE, "Wk", WEEKNUM(A2))',
countTrueFormula,
countFalseFormula
]
];
let summaryHeaderRow = currentWorksheet.getRange("J1:M1");
let summaryContentRow = currentWorksheet.getRange("J2:M2");
console.log("2");
summaryHeaderRow.setValues(summaryHeader);
console.log("3");
summaryContentRow.setValues(summaryContent);
console.log("4");
let formats = [[".000", ".000"]];

summaryContentRow
.getOffsetRange(0, 2)
.getResizedRange(0, -2).setNumberFormats(formats);
}
}
/**
* Apply conditional formatting based on TRUE/FALSE values of the Is US
IP column.
*/
function applyConditionalFormatting(isUSColumn: ExcelScript.Range) {
// Add conditional formatting to the new column.
let conditionalFormatTrue = isUSColumn.addConditionalFormat(
ExcelScript.ConditionalFormatType.cellValue
);
let conditionalFormatFalse = isUSColumn.addConditionalFormat(
ExcelScript.ConditionalFormatType.cellValue
);
// Set TRUE to light blue and FALSE to light orange.
conditionalFormatTrue.getCellValue().getFormat().getFill().setColor("#8
FA8DB");
conditionalFormatTrue.getCellValue().setRule({
formula1: "=TRUE",
operator: ExcelScript.ConditionalCellValueOperator.equalTo
});
conditionalFormatFalse.getCellValue().getFormat().getFill().setColor("#
F8CCAD");
conditionalFormatFalse.getCellValue().setRule({
formula1: "=FALSE",
operator: ExcelScript.ConditionalCellValueOperator.equalTo
});
}
/**
* Translate an IP address into an integer.
* @param ipAddress: IP address to verify.
*/
function ipAddressToInteger(ipAddress: string): number {
// Split the IP address into octets.
let octets = ipAddress.split(".");
// Create a number for each octet and do the math to create the
integer value of the IP address.
let fullNum =
// Define an arbitrary number for the last octet.
111 +
parseInt(octets[2]) * 256 +
parseInt(octets[1]) * 65536 +
parseInt(octets[0]) * 16777216;
return fullNum;
}
/**
* Return the row number where the ip address is found.
* @param ipLookupTable IP look-up table.
* @param n IP address to number value.
*/
function findIP(ipLookupTable: number[][], n: number): number {
for (let i = 0; i < ipLookupTable.length; i++) {
if (ipLookupTable[i][0] <= n && ipLookupTable[i][1] >= n) {
return i;
}
}
return -1;
}
4. Renomeie o script para Analisar Downloads da Web e salve-o.
Executando o script
Navegue até qualquer uma das planilhas week** e execute o script Analisar Downloads
da Web . O script aplicará a formatação condicional e a rotulagem de local na planilha
atual. Ele também atualizará a planilha Resumo .
Antes de executar o script

Depois de executar o script
Office: buscar e grafar dados em nível
de água da NOAA
Artigo • 30/03/2023
Neste cenário, você precisa plotar o nível da água na estação de Seattle da

Administração Nacional Oceânica e Atmosférica . Você usará dados externos para
preencher uma planilha e criar um gráfico.
Você desenvolverá um script que usa o fetch comando para consultar o banco de
dados NOAA Tides and Currents . Isso fará com que o nível da água seja registrado em
um determinado período de tempo. As informações serão retornadas como JSON ,
portanto, parte do script traduzirá isso em valores de intervalo. Depois que os dados
estiverem na planilha, eles serão usados para fazer um gráfico.
Para obter mais informações sobre como trabalhar com JSON, leia Usar JSON para
passar dados de e para scripts do Office.

Chamadas de API externa ( fetch )
Análise JSON
Gráficos
TypeScript
/**
* Gets data from the National Oceanic and Atmospheric Administration's
Tides and Currents database.
* That data is used to make a chart.
*/
// Get the current sheet.
let currentSheet = workbook.getActiveWorksheet();
// Create selection of parameters for the fetch URL.
// More information on the NOAA APIs is found here:
// https://api.tidesandcurrents.noaa.gov/api/prod/
const option = "water_level";
const startDate = "20201225"; /* yyyymmdd date format */
const endDate = "20201227";
const station = "9447130"; /* Seattle */
// Construct the URL for the fetch call.

const strQuery =
`https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?
product=${option}&begin_date=${startDate}&end_date=${endDate}&datum=MLL
W&station=${station}&units=english&time_zone=gmt&application=NOS.COOPS.
TAC.WL&format=json`;
console.log(strQuery);
// Resolve the Promises returned by the fetch operation.

const response = await fetch(strQuery);
const rawJson: string = await response.json();
// Translate the raw JSON into a usable state.

const stringifiedJson = JSON.stringify(rawJson);
// Note that we're only taking the data part of the JSON and
excluding the metadata.
const noaaData: NOAAData[] = JSON.parse(stringifiedJson).data;
// Create table headers and format them to stand out.

let headers = [["Time", "Level"]];
let headerRange = currentSheet.getRange("A1:B1");
headerRange.setValues(headers);
headerRange.getFormat().getFill().setColor("#4472C4");
headerRange.getFormat().getFont().setColor("white");
// Insert all the data in rows from JSON.

let noaaDataCount = noaaData.length;
let dataToEnter = [[], []]
for (let i = 0; i < noaaDataCount; i++) {
let currentDataPiece = noaaData[i];
dataToEnter[i] = [currentDataPiece.t, currentDataPiece.v];
}
let dataRange = currentSheet.getRange("A2:B" + String(noaaDataCount +

1)); /* +1 to account for the title row */
dataRange.setValues(dataToEnter);
// Format the "Time" column for timestamps.

dataRange.getColumn(0).setNumberFormatLocal("[$-en-US]mm/dd/yyyy
hh:mm AM/PM;@");
// Create and format a chart with the level data.

let chart =
currentSheet.addChart(ExcelScript.ChartType.xyscatterSmooth,
dataRange);
chart.getTitle().setText("Water Level - Seattle");
chart.setTop(0);
chart.setLeft(300);
chart.setWidth(500);
chart.setHeight(300);
chart.getAxes().getValueAxis().setShowDisplayUnitLabel(false);
chart.getAxes().getCategoryAxis().setTextOrientation(60);
chart.getLegend().setVisible(false);
// Add a comment with the data attribution.

currentSheet.addComment(
"A1",
`This data was taken from the National Oceanic and Atmospheric
Administration's Tides and Currents database on ${new
Date(Date.now())}.`
);
/**
* An interface to wrap the parts of the JSON we need.
* These properties must match the names used in the JSON.
*/
interface NOAAData {
t: string; // Time
v: number; // Level
}
}
3. Renomeie o script como Gráfico de Nível de Água da NOAA e salve-o.
Executando o script
Em qualquer planilha, execute o script do Gráfico de Nível de Água da NOAA . O script
busca os dados de nível da água de 25 de dezembro de 2020 a 27 de dezembro de
2020. As const variáveis no início do script podem ser alteradas para usar datas
diferentes ou obter informações diferentes da estação. A API do CO-OPS para
Recuperação de Dados descreve como obter todos esses dados.

Office: calculadora de grau
Artigo • 25/10/2023
Nesse cenário, você é um instrutor que contabiliza as notas de fim de ano de cada
aluno. Você está inserindo as pontuações para suas atribuições e testes à medida que
você vai. Agora, é hora de determinar o destino dos alunos.
Você desenvolverá um script que totaliza as notas para cada categoria de ponto. Em
seguida, ele atribuirá uma nota de letra a cada aluno com base no total. Para ajudar a
garantir a precisão, você adicionará algumas verificações para ver se as pontuações
individuais são muito baixas ou altas. Se a pontuação de um aluno for menor que zero
ou mais do que o valor de ponto possível, o script sinalizará a célula com um
preenchimento vermelho e não totalizará os pontos desse aluno. Essa será uma
indicação clara de quais registros você precisa marcar duas vezes. Você também
adicionará uma formatação básica às notas para que você possa exibir rapidamente a
parte superior e inferior da classe.

Formatação de célula
Verificação de erros
Expressões regulares
Formatação condicional
TypeScript

// Get the worksheet and validate the data.
let studentsRange = workbook.getActiveWorksheet().getUsedRange();
if (studentsRange.getColumnCount() !== 6) {
throw new Error(`The required columns are not present. Expected
column headers: "Student ID | Assignment score | Mid-term | Final |
Total | Grade"`);
}
let studentData = studentsRange.getValues();
// Clear the total and grade columns.

studentsRange.getColumn(4).getCell(1,
0).getAbsoluteResizedRange(studentData.length - 1, 2).clear();
// Clear all conditional formatting.
workbook.getActiveWorksheet().getUsedRange().clearAllConditionalFormats
();
// Use regular expressions to read the max score from the assignment,
mid-term, and final scores columns.
let maxScores: string[] = [];
const assignmentMaxMatches = (studentData[0][1] as
string).match(/\d+/);
const midtermMaxMatches = (studentData[0][2] as string).match(/\d+/);
const finalMaxMatches = (studentData[0][3] as string).match(/\d+/);
// Check the matches happened before proceeding.

if (!(assignmentMaxMatches && midtermMaxMatches && finalMaxMatches))
{
throw new Error(`The scores are not present in the column headers.
Expected format: "Assignments (n)|Mid-term (n)|Final (n)"`);
}
// Use the first (and only) match from the regular expressions as the
max scores.
maxScores = [assignmentMaxMatches[0], midtermMaxMatches[0],
finalMaxMatches[0]];
// Set conditional formatting for each of the assignment, mid-term,

and final scores columns.
maxScores.forEach((score, i) => {
let range = studentsRange.getColumn(i + 1).getCell(0,
0).getRowsBelow(studentData.length - 1);
setCellValueConditionalFormatting(
score,
range,
"#9C0006",
"#FFC7CE",
ExcelScript.ConditionalCellValueOperator.greaterThan
)
});
// Store the current range information to avoid calling the workbook

in the loop.
let studentsRangeFormulas =
studentsRange.getColumn(4).getFormulasR1C1();
let studentsRangeValues = studentsRange.getColumn(5).getValues();
/* Iterate over each of the student rows and compute the total score
and letter grade.
* Note that iterator starts at index 1 to skip first (header) row.
*/
for (let i = 1; i < studentData.length; i++) {
// If any of the scores are invalid, skip processing it.
if (studentData[i][1] > maxScores[0] ||
studentData[i][2] > maxScores[1] ||
studentData[i][3] > maxScores[2]) {
continue;
}
const total = (studentData[i][1] as number) + (studentData[i][2] as
number) + (studentData[i][3] as number);
let grade: string;
switch (true) {
case total < 60:
grade = "F";
break;
case total < 70:
grade = "D";
break;
case total < 80:
grade = "C";
break;
case total < 90:
grade = "B";
break;
default:
grade = "A";
break;
}
// Set total score formula.

studentsRangeFormulas[i][0] = '=RC[-2]+RC[-1]';
// Set grade cell.
studentsRangeValues[i][0] = grade;
}
// Set the formulas and values outside the loop.

studentsRange.getColumn(4).setFormulasR1C1(studentsRangeFormulas);
studentsRange.getColumn(5).setValues(studentsRangeValues);
// Put a conditional formatting on the grade column.

let totalRange = studentsRange.getColumn(5).getCell(0,
0).getRowsBelow(studentData.length - 1);
"A",
totalRange,
"#001600",
"#C6EFCE",
ExcelScript.ConditionalCellValueOperator.equalTo
);
["D", "F"].forEach((grade) => {
grade,
totalRange,
"#443300",
"#FFEE22",
ExcelScript.ConditionalCellValueOperator.equalTo
);
})
// Center the grade column.
studentsRange.getColumn(5).getFormat().setHorizontalAlignment(ExcelScri
pt.HorizontalAlignment.center);
}
/**
* Helper function to apply conditional formatting.
* @param value Cell value to use in conditional formatting formula1.
* @param range Target range.
* @param fontColor Font color to use.
* @param fillColor Fill color to use.
* @param operator Operator to use in conditional formatting.
*/
function setCellValueConditionalFormatting(
value: string,
range: ExcelScript.Range,
fontColor: string,
fillColor: string,
operator: ExcelScript.ConditionalCellValueOperator) {
// Determine the formula1 based on the type of value parameter.
let formula1: string;
if (isNaN(Number(value))) {
// For cell value equalTo rule, use this format: formula1:
"=\"A\"",
formula1 = `=\"${value}\"`;
} else {
// For number input (greater-than or less-than rules), just append
'='.
formula1 = `=${value}`;
}
// Apply conditional formatting.

let conditionalFormatting: ExcelScript.ConditionalFormat;
conditionalFormatting =
range.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue)
;
conditionalFormatting.getCellValue().getFormat().getFont().setColor(fon
tColor);
conditionalFormatting.getCellValue().getFormat().getFill().setColor(fil
lColor);
conditionalFormatting.getCellValue().setRule({ formula1, operator });
}
4. Renomeie o script como Calculadora de Notas e salve-o.

Executar o script
Execute o script calculadora de grau na única planilha. O script totaliza as notas e
atribui a cada aluno uma nota de letra. Se as notas individuais tiverem mais pontos do
que a atribuição ou o teste vale, a nota ofensiva será marcada como vermelha e o total
não será calculado. Além disso, todas as notas 'A' são realçadas em verde, enquanto as
notas 'D' e 'F' são realçadas em amarelo.
Antes de executar o script

Office: agendar entrevistas no Teams
Artigo • 07/12/2023
Nesse cenário, você é um recrutador de RH agendando reuniões de entrevista com

candidatos no Teams. Você gerencia a agenda de entrevistas de candidatos em um
arquivo do Excel. Você precisará enviar o convite da reunião do Teams para o candidato
e os entrevistadores. Em seguida, você precisa atualizar o arquivo do Excel com a
confirmação de que as reuniões do Teams foram enviadas.
A solução tem três etapas que são combinadas em um único fluxo do Power Automate.
1. Um script extrai dados de uma tabela e retorna uma matriz de objetos como
dados JSON .
2. Em seguida, os dados são enviados para a ação de reunião Do Teams Create a
Teams para enviar convites.
3. Os mesmos dados JSON são enviados para outro script para atualizar o status do
convite.
Para obter mais informações sobre como trabalhar com JSON, leia Usar JSON para
passar dados de e para scripts do Office.

Fluxos do Power Automate
Integração do Teams
Análise de tabela
Baixar a pasta de trabalho


3. Altere pelo menos um dos endereços de email para seus próprios para que você
receba um convite.
Criar os scripts
1. Na guia Automatizar, selecioneNovo Script e cole o script a seguir no editor. Isso
extrairá dados de tabela para agendar convites.
TypeScript
function main(workbook: ExcelScript.Workbook): InterviewInvite[] {

const MEETING_DURATION =
workbook.getWorksheet("Constants").getRange("B1").getValue() as number;
const MESSAGE_TEMPLATE =
workbook.getWorksheet("Constants").getRange("B2").getValue() as string;
// Get the interview candidate information.

const sheet = workbook.getWorksheet("Interviews");
const table = sheet.getTables()[0];
const dataRows = table.getRangeBetweenHeaderAndTotal().getValues();
// Convert the table rows into InterviewInvite objects for the flow.
let invites: InterviewInvite[] = [];
dataRows.forEach((row) => {
const inviteSent = row[1] as boolean;
if (!inviteSent) {
const startTime = new Date(Math.round(((row[6] as number) - 25569) *
86400 * 1000));
const finishTime = new Date(startTime.getTime() + MEETING_DURATION *
60 * 1000);
const candidateName = row[2] as string;
const interviewerName = row[4] as string;
invites.push({
ID: row[0] as string,
Candidate: candidateName,
CandidateEmail: row[3] as string,
Interviewer: row[4] as string,
InterviewerEmail: row[5] as string,
StartTime: startTime.toISOString(),
FinishTime: finishTime.toISOString(),
Message: generateInviteMessage(MESSAGE_TEMPLATE, candidateName,
interviewerName)
});
}
});
console.log(JSON.stringify(invites));
return invites;
}
function generateInviteMessage(
messageTemplate: string,
candidate: string,
interviewer: string) : string {
return messageTemplate.replace("_Candidate_",
candidate).replace("_Interviewer_", interviewer);
}
// The interview invite information.

interface InterviewInvite {
ID: string
Candidate: string
CandidateEmail: string
Interviewer: string
InterviewerEmail: string
StartTime: string
FinishTime: string
Message: string
}
1. Nomeie o script Agendar Entrevistas para o fluxo.
2. Crie outro novo script com o código a seguir. Isso marcará as linhas como
convidadas.
TypeScript
function main(workbook: ExcelScript.Workbook, invites: InterviewInvite[]) {

const table = workbook.getWorksheet("Interviews").getTables()[0];
// Get the ID and Invite Sent columns from the table.

const idColumn = table.getColumnByName("ID");
const idRange = idColumn.getRangeBetweenHeaderAndTotal().getValues();
const inviteSentColumn = table.getColumnByName("Invite Sent?");
const dataRowCount = idRange.length;
// Find matching IDs to mark the correct row.

for (let row = 0; row < dataRowCount; row++){
let inviteSent = invites.find((invite) => {
return invite.ID == idRange[row][0] as string;
});
if (inviteSent) {
inviteSentColumn.getRangeBetweenHeaderAndTotal().getCell(row,
0).setValue(true);
console.log(Ìnvite for ${inviteSent.Candidate} has been sent.`);
}
}
}
// The interview invite information.

interface InterviewInvite {
ID: string
Candidate: string
CandidateEmail: string
Interviewer: string
InterviewerEmail: string
StartTime: string
FinishTime: string
Message: string
}
1. Nomeie o segundo script Record Sent Invites para o fluxo.
Criar o fluxo do Power Automate

Esse fluxo executa os scripts de agendamento de entrevista, envia as reuniões do Teams
e registra a atividade de volta na pasta de trabalho.
3. No construtor de fluxos, selecione o + botão e Adicione uma ação. Use a ação

executar script do conector do Excel Online (Business). Conclua a ação com os
valores a seguir.

Arquivo: hr-interviews.xlsx (Escolhido por meio do navegador de arquivos)
Script: Agendar entrevistas
4. Adicione uma ação que usa a ação criar uma reunião do Microsoft Teams
connector. À medida que você seleciona conteúdo dinâmico no conector do Excel,
um Para cada bloco será gerado para o fluxo. Conclua o conector com os valores a
seguir.
Assunto: Entrevista com Contoso

Mensagem: Mensagem (conteúdo dinâmico de Executar script)
Fuso horário: Horário Padrão do Pacífico
Hora de início: StartTime (conteúdo dinâmico de Executar script)
Hora de término: FinishTime (conteúdo dinâmico de Executar script)
ID do calendário: Calendário
Participantes obrigatórios: CandidateEmail ; InterviewerEmail (conteúdo
dinâmico de Executar script – observe o ';' separando os valores)
5. No mesmo Para cada bloco, adicione outra ação Executar script . Use os seguintes
valores.

Arquivo: hr-interviews.xlsx (Escolhido por meio do navegador de arquivos)
Script: Gravar convites enviados
convites: resultado (conteúdo dinâmico de Executar script)
Pressione a entrada do Switch para a matriz inteira primeiro.

Vídeo de treinamento: enviar uma reunião do

Teams de dados do Excel
Assista Sudhi Ramamurthy percorrer uma versão deste exemplo no YouTube . Sua
versão usa um script mais robusto que lida com a alteração de colunas e tempos de
reunião obsoletos.
Office: lembretes de tarefa
automatizados
Artigo • 06/12/2023
Nesse cenário, você está gerenciando um projeto. Você usa uma planilha do Excel para
acompanhar o status de seus funcionários todos os meses. Muitas vezes você precisa
lembrar as pessoas para preencher suas status, então você decidiu automatizar esse
processo de lembrete.
Você criará um fluxo do Power Automate para enviar mensagens a pessoas com campos
de status ausentes e aplicar suas respostas à planilha. Para fazer isso, você desenvolverá
um par de scripts para lidar com o trabalho com a pasta de trabalho. O primeiro script
obtém uma lista de pessoas com status em branco e o segundo script adiciona uma
cadeia de caracteres status à linha direita. Você também usará cartões adaptáveis do
Teams para que os funcionários insiram seus status diretamente da notificação.

Criar fluxos no Power Automate
Passar dados para scripts
Retornar dados de scripts
Cartões Adaptáveis do Teams
Tabelas
Pré-requisitos
Esse cenário usa o Power Automate e o Microsoft Teams . Você precisará de ambos
associados à conta que você usa para desenvolver scripts do Office. Para acesso gratuito
a uma assinatura do Microsoft Developer para saber mais sobre e trabalhar com esses
aplicativos, considere ingressar no Programa de Desenvolvedor do Microsoft 365.
Baixar a pasta de trabalho

Criar os scripts
1. Primeiro, precisamos de um script para obter todos os funcionários com status
relatórios ausentes da planilha. Na guia Automatizar, selecioneNovo Script e cole
o script a seguir no editor.
TypeScript
/**
* This script looks for missing status reports in a project management
table.
*
* @returns An array of Employee objects (containing their names and
emails).
*/
function main(workbook: ExcelScript.Workbook): Employee[] {
// Get the first worksheet and the first table on that worksheet.
let sheet = workbook.getFirstWorksheet()
let table = sheet.getTables()[0];
// Give the column indices names matching their expected content.

const NAME_INDEX = 0;
const EMAIL_INDEX = 1;
const STATUS_REPORT_INDEX = 2;
// Get the data for the whole table.

let bodyRangeValues =
table.getRangeBetweenHeaderAndTotal().getValues();
// Create the array of Employee objects to return.

let people: Employee[] = [];
// Loop through the table and check each row for completion.
for (let i = 0; i < bodyRangeValues.length; i++) {
let row = bodyRangeValues[i];
if (row[STATUS_REPORT_INDEX] === "") {
// Save the email to return.
people.push({ name: row[NAME_INDEX].toString(), email:
row[EMAIL_INDEX].toString() });
}
}
// Log the array to verify we're getting the right rows.

console.log(people);
// Return the array of Employees.

return people;
}
/**
* An interface representing an employee.
* An array of Employees will be returned from the script
* for the Power Automate flow.
*/
interface Employee {
name: string;
email: string;
}
2. Salve o script com o nome Obter Pessoas.
3. Em seguida, precisamos de um segundo script para processar os boletins status e

colocar as novas informações na planilha. No painel de tarefas Editor de Código,
selecione Novo Script e cole o script a seguir no editor.
TypeScript
/**
* This script applies the results of a Teams Adaptive Card about
* a status update to a project management table.
*
* @param senderEmail - The email address of the employee updating
their status.
* @param statusReportResponse - The employee's status report.
*/
function main(workbook: ExcelScript.Workbook,
senderEmail: string,
statusReportResponse: string) {
// Get the first worksheet and the first table in that worksheet.
let sheet = workbook.getFirstWorksheet();
let table = sheet.getTables()[0];
// Give the column indices names matching their expected content.

const NAME_INDEX = 0;
const EMAIL_INDEX = 1;
const STATUS_REPORT_INDEX = 2;
// Get the range and data for the whole table.

let bodyRange = table.getRangeBetweenHeaderAndTotal();
let tableRowCount = bodyRange.getRowCount();
let bodyRangeValues = bodyRange.getValues();
// Create a flag to denote success.

let statusAdded = false;
// Loop through the table and check each row for a matching email
address.
for (let i = 0; i < tableRowCount && !statusAdded; i++) {
let row = bodyRangeValues[i];
// Check if the row's email address matches.

if (row[EMAIL_INDEX] === senderEmail) {
// Add the Teams Adaptive Card response to the table.
bodyRange.getCell(i, STATUS_REPORT_INDEX).setValues([
[statusReportResponse]
]);
statusAdded = true;
}
}
// If successful, log the status update.

if (statusAdded) {
console.log(
`Successfully added status report for ${senderEmail} containing:
${statusReportResponse}`
);
}
}
4. Salve o script com o nome Salvar Status.
Criar o fluxo do Power Automate

1. Abra a guia Criar Automate do Power .
 Dica
Se você ainda não criou um fluxo antes, marcar nosso tutorial Comece a usar
scripts com o Power Automate para aprender o básico.
3. Escolha Disparar manualmente um fluxo nas opções e selecione Criar.
4. O fluxo precisa chamar o script Obter Pessoas para obter todos os funcionários
com campos de status vazios. No construtor de fluxos, selecione o + botão e
Adicione uma ação. Selecione a ação executar script do conector do Excel Online
(Business). Forneça as seguintes entradas para a etapa de fluxo:

Arquivo: task-reminders.xlsx (Escolhido por meio do navegador de arquivos)
Script: Obter Pessoas
5. Em seguida, o fluxo precisa processar cada funcionário na matriz retornada pelo
script. Adicione o cartão adaptável post do conector do Microsoft Teamse
aguarde uma ação de resposta.
6. O envio de um Cartão Adaptável requer que o JSON do cartão seja fornecido

como a Mensagem. Você pode usar o cartão adaptável Designer para criar
cartões personalizados. Para este exemplo, use o JSON a seguir.
JSON
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.0",
"body": [
{
"type": "TextBlock",
"size": "Medium",
"weight": "Bolder",
"text": "Update your Status Report"
},
{
"type": "Image",
"altText": "",
"url": "https://i.imgur.com/f5RcuF3.png"
},
{
"type": "TextBlock",
"text": "This is a reminder to update your status report for this
month's review. You can do so right here in this card, or by adding it
directly to the spreadsheet.",
"wrap": true
},
{
"type": "Input.Text",
"placeholder": "My status report for this month is...",
"id": "response",
"isMultiline": true
}
],
"actions": [
{
"type": "Action.Submit",
"title": "Submit",
"id": "submit"
}
]
}
7. Para o campo Destinatário , adicione email do conteúdo dinâmico (a seleção terá

o logotipo do Excel por ele). A adição de email faz com que a etapa de fluxo seja
cercada por um Para cada bloco. Isso significa que a matriz será iterada pelo
Power Automate.
8. Preencha os campos restantes da seguinte maneira:
Postar como: Bot de fluxo

Post in: Chat com o bot Flow
Mensagem de atualização: obrigado por enviar seu relatório de status. Sua
resposta foi adicionada com êxito à planilha.
9. No Para cada bloco, seguindo o post adaptável cartão e aguarde uma ação de
resposta, adicione uma nova ação. Selecione a ação executar script do conector
do Excel Online (Business). Forneça as seguintes entradas para a etapa de fluxo:

Arquivo: task-reminders.xlsx (Escolhido por meio do navegador de arquivos)
Script: Salvar Status
senderEmail: email (conteúdo dinâmico do Excel)
statusReportResponse: resposta (conteúdo dinâmico do Teams)
Executando o fluxo
Para testar o fluxo, verifique se todas as linhas de tabela com status em branco usam um
endereço de email vinculado a uma conta do Teams (você provavelmente deve usar seu
próprio endereço de email durante o teste). Use o botão Testar na página do editor de
fluxo ou execute o fluxo por meio da guia Meus fluxos . Certifique-se de permitir o
acesso quando solicitado.
Você deve receber um Cartão Adaptável do Power Automate por meio do Teams.
Depois de preencher o campo status no cartão, o fluxo continuará e atualizará a planilha
com o status fornecido.
Antes de executar o fluxo
Recebendo o cartão adaptável
Depois de executar o fluxo

Office: botão Desatar relógio
Artigo • 25/10/2023
A ideia de cenário e o script usados neste exemplo foram contribuídos pelo membro da
comunidade do Office Scripts , Brian Gonzalez .
Nesse cenário, você criará uma folha de tempo para um funcionário que permite que
eles registrem seus horários de início e término com um botão. Com base no que foi
gravado anteriormente, selecionar o botão iniciará seu dia (relógio) ou terminará seu dia
(relógio).
TypeScript
/**
* This script records either the start or end time of a shift,
* depending on what is filled out in the table.
* It is intended to be used with a Script Button.
*/
// Get the first table in the timesheet.
const timeSheet = workbook.getWorksheet("MyTimeSheet");
const timeTable = timeSheet.getTables()[0];
// Get the appropriate table columns.

const clockInColumn = timeTable.getColumnByName("Clock In");
const clockOutColumn = timeTable.getColumnByName("Clock Out");
const durationColumn = timeTable.getColumnByName("Duration");
// Get the last rows for the Clock In and Clock Out columns.
let clockInLastRow =
clockInColumn.getRangeBetweenHeaderAndTotal().getLastRow();
let clockOutLastRow =
clockOutColumn.getRangeBetweenHeaderAndTotal().getLastRow();
// Get the current date to use as the start or end time.

let date: Date = new Date();
// Add the current time to a column based on the state of the table.
if (clockInLastRow.getValue() as string === "") {
// If the Clock In column has an empty value in the table, add a
start time.
clockInLastRow.setValue(date.toLocaleString());
} else if (clockOutLastRow.getValue() as string === "") {
// If the Clock Out column has an empty value in the table,
// add an end time and calculate the shift duration.
clockOutLastRow.setValue(date.toLocaleString());
const clockInTime = new Date(clockInLastRow.getValue() as string);
const clockOutTime = new Date(clockOutLastRow.getValue() as
string);
const clockDuration = Math.abs((clockOutTime.getTime() -
clockInTime.getTime()));
let durationString = getDurationMessage(clockDuration);
durationColumn.getRangeBetweenHeaderAndTotal().getLastRow().setValue(du
rationString);
} else {
// If both columns are full, add a new row, then add a start time.
timeTable.addRow()
clockInLastRow.getOffsetRange(1,
0).setValue(date.toLocaleString());
}
}
/**
* A function to write a time duration as a string.
*/
function getDurationMessage(delta: number) {
// Adapted from here:
// https://stackoverflow.com/questions/13903897/javascript-return-
number-of-days-hours-minutes-seconds-between-two-dates
delta = delta / 1000;

let durationString = "";
let days = Math.floor(delta / 86400);

delta -= days * 86400;
let hours = Math.floor(delta / 3600) % 24;

delta -= hours * 3600;
let minutes = Math.floor(delta / 60) % 60;
if (days >= 1) {
durationString += days;
durationString += (days > 1 ? " days" : " day");
if (hours >= 1 && minutes >= 1) {

durationString += ", ";
}
else if (hours >= 1 || minutes > 1) {
durationString += " and ";
}
}
if (hours >= 1) {
durationString += hours;
durationString += (hours > 1 ? " hours" : " hour");
if (minutes >= 1) {
durationString += " and ";
}
}
if (minutes >= 1) {
durationString += minutes;
durationString += (minutes > 1 ? " minutes" : " minute");
}
return durationString;
}
4. Renomeie o script como "Relógio de perfuração".
5. Salve o script.
6. Na pasta de trabalho, selecione célula E2.
7. Adicione um botão script. Acesse o menu Mais opções (...) na página Detalhes do
script e selecione Adicionar botão.
8. Salve a pasta de trabalho.
Executar o script
Selecione o botão Socar o relógio para executar o script. Ele registra o tempo atual em
"Clock In" ou "Clock Out", dependendo do que foi inserido anteriormente.
７ Observação
A duração só será registrada se for maior que um minuto. Edite manualmente o
tempo "Clock In" para testar durações maiores.
Saudações de estação
Artigo • 25/10/2023
Este roteiro foi contribuído por Leslie Black no espírito da temporada de férias! É um
script divertido que mostra uma árvore cantando no Excel usando scripts do Office.
Desfrutar!
Assista ao script de saudações do Seasons em ação no canal do YouTube "Blog de TI do

Les" .

Código de exemplo: árvore feliz

conta própria!
TypeScript
/* Original version by Leslie Black. */

let happyTree = workbook.getWorksheet('HappyTree');
happyTree.activate();
setOuterEdgeYellow(workbook) //yellow
setOuterEdgeRed(workbook) //red
setFlashingStarAndSmileRed(workbook) //red
setFlashingStarAndSmileYellow(workbook) //yellow
setFlashingStarAndSmileRed(workbook) //red
setFlashingStarAndSmileYellow(workbook) //yellow
blink(workbook)
unblink(workbook)
console.log('Routine finished');
function blink(workbook: ExcelScript.Workbook) {

let selectedSheet = workbook.getWorksheet('HappyTree');
// Set the eyes to brown.
selectedSheet.getRanges("N16:Q17, G16: J17")
.getFormat()
.getFill()
.setColor("C65911");
}
function unblink(workbook: ExcelScript.Workbook) {

// Set the eyes back to white (except the pupils).
selectedSheet.getRanges("N16:N17, O16:Q16, G16:H17, I16:J16, P17:Q17,
J17")
.getFormat()
.getFill()
.setColor("FFFFFF");
}
function setFlashingStarAndSmileRed(workbook: ExcelScript.Workbook) {
// Set the star to red.
selectedSheet.getRanges("L2:L6, K3:K5, M3:M5, N4, J4")
.getFormat()
.getFill()
.setColor("FF0000");
// Set the smile points to black.
selectedSheet.getRanges("I26, O26")
.getFormat()
.getFill()
.setColor("000000");
}
function setFlashingStarAndSmileYellow(workbook: ExcelScript.Workbook) {

// Set the start to yellow.
selectedSheet.getRanges("L2:L6, K3:K5, M3:M5, N4, J4")
.getFormat()
.getFill()
// Clear the smile points.
selectedSheet.getRanges("O26, I26")
.getFormat()
.getFill().clear();
}
}
function setOuterEdgeYellow(workbook: ExcelScript.Workbook) {

let sheet = workbook.getWorksheet('HappyTree');
// Set the outer edge to yellow.
sheet.getRanges("Q11, G11, R12, F12, S13, E13, T14, D14, C15, U15,
T16:T17, D16:D17, C18, U18, T19, D19, L2:L6, C21, U21, C23, U23, C25, U25,
C27, U27, C29, U29, T30, D30, K3:K5, M3: M5, S31, E31, R32, F32, Q33, G33,
P34, H34, O35, I35, N36:N37, J36:J37, K37:M37, N4, J4, K7, M7, N8, J8, O9,
I9, P10, H10")
.getFormat()
.getFill()
}
function setOuterEdgeRed(workbook: ExcelScript.Workbook) {

let sheet = workbook.getWorksheet('HappyTree');
// Set the outer edge to red.
sheet.getRanges("Q11, G11, R12, F12, S13, E13, T14, D14, C15, U15,
T16:T17, D16:D17, C18, U18, T19, D19, L2:L6, C21, U21, C23, U23, C25, U25,
C27, U27, C29, U29, T30, D30, K3:K5, M3: M5, S31, E31, R32, F32, Q33, G33,
P34, H34, O35, I35, N36:N37, J36:J37, K37:M37, N4, J4, K7, M7, N8, J8, O9,
I9, P10, H10")
.getFormat()
.getFill()
.setColor("FF0000");
}
Diferenças entre scripts do Office e
macros VBA
Artigo • 16/04/2023
Scripts do Office e macros VBA têm muito em comum. Ambos permitem que os
usuários automatizem soluções por meio de um gravador de ação fácil de usar e
permitam edições dessas gravações. Ambas as estruturas são projetadas para capacitar
pessoas que podem não se considerar programadoras para criar pequenos programas
no Excel.
A diferença fundamental é que as macros VBA são desenvolvidas para soluções de área
de trabalho e os Scripts do Office são projetados para soluções seguras, entre
plataformas e baseadas em nuvem.
Este artigo descreve as main diferenças entre macros VBA (bem como VBA em geral) e
Scripts do Office. Como os Scripts do Office só estão disponíveis para o Excel, esse é o
único host que está sendo discutido aqui.
Plataforma e ecossistema
A tabela a seguir mostra quais recursos têm suporte para quais plataformas e produtos.
Excel Excel para Excel Excel Outros Power
Online Windows para para produtos do Automate
Mac iOS Office
Scripts do Office Sim Sim Sim Não Não Sim
Gravador de Ação Sim Sim Sim Não Não Não

de Scripts do Office
Macros VBA Não Sim Sim Não Sim Não
Suplementos do Sim Sim Sim Sim Sim Não

Office
Suplementos COM Não Sim Sim Não Sim Não
O VBA foi projetado para ser centrado na área de trabalho. O VBA pode interagir com a
área de trabalho de um usuário para se conectar com tecnologias semelhantes, como
COM e OLE. No entanto, o VBA não tem uma maneira conveniente de chamar para a
Internet. Os Scripts do Office usam um runtime universal para JavaScript. Isso fornece
comportamento e acessibilidade consistentes, independentemente do computador ser
usado para executar o script. Eles também podem fazer chamadas para um conjunto
limitado de serviços Web.
Os usuários exigem uma licença corporativa ou educacional para usar ou criar scripts do
Office. Para obter a lista completa de licenças com suporte, consulte Suporte à
plataforma. O VBA é integrado às versões da área de trabalho do Excel e não requer
licenciamento especial.
Segurança
As macros VBA têm a mesma autorização de segurança que o Excel. Isso lhes dá acesso
total à sua área de trabalho. Os Scripts do Office só têm acesso à pasta de trabalho, não
ao computador que hospeda a pasta de trabalho. Além disso, nenhum token de
autenticação JavaScript pode ser compartilhado com scripts. Isso significa que o script
não tem os tokens do usuário conectado nem há recursos de API para entrar em um
serviço externo, portanto, eles não podem usar tokens existentes para fazer chamadas
externas em nome do usuário.
Os administradores têm três opções para macros VBA: permitir todas as macros no
locatário, não permitir macros no locatário ou permitir apenas macros com certificados
assinados. Essa falta de granularidade torna difícil isolar um único ator ruim.
Atualmente, os Scripts do Office podem estar desativados para um locatário inteiro,
ativado para um locatário inteiro ou ativado para um grupo de usuários em um
locatário. Os administradores também têm controle sobre quem pode compartilhar
scripts com outras pessoas e quem pode usar scripts no Power Automate.
Cobertura
Atualmente, o VBA oferece uma cobertura mais completa dos recursos do Excel,
especialmente aqueles disponíveis no cliente da área de trabalho. Os Scripts do Office
abrangem quase todos os cenários para Excel na Web. Além disso, à medida que novos
recursos estreiam na Web, os Scripts do Office darão suporte a eles para as APIs Do
Gravador de Ações e JavaScript.
Os Scripts do Office não dão suporte a eventos no nível do Excel. Os scripts só são
executados quando um usuário os inicia manualmente ou quando um fluxo do Power
Automate chama o script.
Power Automate
O VBA não tem um conector do Power Automate. Todos os cenários de VBA com
suporte envolvem um usuário que atende à execução da macro.
Os Scripts do Office podem ser executados por meio do Power Automate. Sua pasta de
trabalho pode ser atualizada por meio de fluxos agendados ou controlados por eventos,
permitindo automatizar fluxos de trabalho sem sequer abrir o Excel. Experimente os
scripts de chamada de um tutorial manual de fluxo do Power Automate para começar a
aprender sobre o Power Automate. Você também pode marcar o exemplo de lembretes
de tarefas automatizados para ver scripts do Office conectados ao Teams por meio do
Power Automate em um cenário real.
Confira também
Diferenças entre os scripts do Office e os suplementos do Office
Referência do VBA do Excel
Diferenças entre os scripts do Office e
os suplementos do Office
Artigo • 31/03/2023
Entenda as diferenças entre scripts do Office e suplementos do Office para saber

quando usar cada um deles. Os Scripts do Office são projetados para serem feitos
rapidamente por qualquer pessoa que queira melhorar seu fluxo de trabalho. Os
suplementos do Office se integram à interface do usuário do Office para uma
experiência mais interativa por meio de botões de faixa de opções e painéis de tarefas.
Os suplementos do Office também podem expandir funções internas do Excel
fornecendo funções personalizadas.
Os Scripts do Office são executados até a conclusão com uma seleção de botão manual
ou como uma etapa no Power Automate , enquanto os Suplementos do Office
continuam em execução dependendo de como eles estão configurados. Por exemplo,
você pode configurar um Suplemento do Office para continuar em execução mesmo
quando o painel de tarefas for fechado. Isso significa que os Suplementos do Office
mantêm o estado durante uma sessão, enquanto os Scripts do Office não mantêm um
estado interno entre execuções. Se a solução que você está criando exigir um estado
mantido, você deverá visitar a documentação de Suplementos do Office para saber mais
sobre suplementos do Office.
O restante deste artigo descreve as diferenças de main entre suplementos do Office e

scripts do Office.
Suporte à plataforma
A tabela a seguir mostra quais recursos têm suporte para quais plataformas e produtos.
Excel Excel para Excel Excel Outros Power

Online Windows para para produtos do Automate
Mac iOS Office
Scripts do Office Sim Sim Sim Não Não Sim
Gravador de Ação Sim Sim Sim Não Não Não

de Scripts do Office
Macros VBA Não Sim Sim Não Sim Não
Suplementos do Sim Sim Sim Sim Sim Não

Office
Suplementos COM Não Sim Sim Não Sim Não
APIs
Embora as APIs JavaScript do Office para Suplementos do Office e as APIs de Scripts do
Office compartilhem algumas funcionalidades, elas são plataformas diferentes. As APIs
de Scripts do Office são um subconjunto otimizado e síncrono do modelo de API
JavaScript do Excel. A principal diferença é o uso do load / sync paradigma com
suplementos. Além disso, os suplementos oferecem APIs para eventos e um conjunto
mais amplo de funcionalidade fora do Excel, conhecido como APIs comuns.
Os suplementos do Office oferecem maior conectividade com serviços Web externos e

bibliotecas. Os Scripts do Office são limitados a chamadas externas específicas.
Eventos
Os Scripts do Office não dão suporte a eventos no nível da pasta de trabalho. Os scripts
são disparados por usuários que selecionam o botão Executar para um script ou por
meio do Power Automate. Cada script executa o código em uma única main função e
termina.
Controles UX e interface do usuário

Os Scripts do Office só podem interagir com a pasta de trabalho, não com o painel de
tarefas. Se você precisar de autenticação, janelas de diálogo ou controles adicionais de
UX e interface do usuário, você precisará criar um Suplemento do Office em vez de um
Script do Office.
Confira também
Diferenças entre scripts do Office e macros VBA
Criar um suplemento do painel de tarefas do Excel
Quando usar Power Query ou Scripts do
Office
Artigo • 31/03/2023
Power Query e Scripts do Office são soluções de automação poderosas para o Excel.
Ambas as soluções permitem que os usuários do Excel limpo e transformem dados em
pastas de trabalho. Um único Power Query ou Script do Office pode ser atualizado e
executado novamente em novos dados para produzir resultados consistentes, o que
economiza tempo e permite que você trabalhe com as informações resultantes mais
rapidamente.
Este artigo fornece uma visão geral de quando você pode favorecer uma plataforma em
relação à outra. Em geral, Power Query é bom para extrair e transformar dados de
grandes fontes de dados externas e scripts do Office são bons para soluções rápidas
centradas no Excel e integrações do Power Automate.
Grandes fontes de dados e recuperação de

dados: Power Query
Recomendamos Power Query ao lidar com fontes de dados de plataformas com
suporte.
Power Query tem conexões de dados internas com centenas de fontes. Power Query é
especialmente projetado para tarefas de recuperação, transformação e combinação de
dados. Quando você precisa de dados de uma dessas fontes, Power Query oferece uma
maneira sem código de trazer esses dados para o Excel na forma necessária.
Essas conexões Power Query são projetadas para conjuntos de dados grandes. Eles não
têm os mesmos limites de transferência que o Power Automate ou Excel na Web.
Os Scripts do Office oferecem uma solução leve para fontes de dados menores ou
fontes de dados não cobertas por conectores Power Query. Isso inclui o uso fetch ou
APIs REST ou a obtenção de informações de fontes de dados ad hoc, como uma cartão
adaptável do Teams.
Formatação, visualizações e controle

programático: Scripts do Office
Recomendamos scripts do Office quando suas necessidades vão além da importação e
transformação de dados.
Quase tudo o que você pode fazer manualmente por meio da interface do usuário do
Excel é possível com scripts do Office. Eles são ótimos para aplicar formatação
consistente a pastas de trabalho. Scripts criam gráficos, tabelas dinâmicas, formas,
imagens e outras visualizações de planilha. Os scripts também fornecem controle
preciso sobre as posições, tamanhos, cores e outros atributos dessas visualizações.
A inclusão do código TypeScript fornece um alto grau de personalização. A lógica de

controle programático como if...else instruções torna seu script robusto. Isso permite
que você faça coisas como ler dados condicionalmente sem depender de fórmulas
complexas do Excel ou examinar a pasta de trabalho para obter alterações inesperadas
antes de alterar a pasta de trabalho.
A formatação pode ser aplicada com Power Query por meio de modelos do Excel. No
entanto, os modelos são atualizados no nível individual ou da organização, enquanto os
Scripts do Office oferecem controle de acesso mais granular.
Power Automate integrations

Os Scripts do Office oferecem mais opções para integração do Power Automate. Os
scripts são adaptados às suas soluções. Você define a entrada e a saída do script para
que ele funcione com qualquer outro conector ou dados no fluxo. A captura de tela a
seguir mostra um exemplo de fluxo do Power Automate que passa dados de um Cartão
Adaptável do Teams para um Script do Office.
Power Query é usado no conector do Power Automate SQL Server. A ação
Transformar dados usando Power Query permite criar uma consulta no Power Automate.
Embora esta seja uma ferramenta poderosa para uso com SQL Server, ela limita Power
Query a essa fonte de entrada, conforme mostrado na captura de tela de fluxo a seguir.
Dependências da plataforma
Atualmente, os Scripts do Office estão disponíveis para Excel para Windows, para Mac e
na Web. A experiência de Power Query completa está atualmente disponível apenas
para Excel para Windows. Ambos podem ser usados por meio do Power Automate, o
que permite que o fluxo funcione com pastas de trabalho do Excel armazenadas no
OneDrive.
Confira também
Portal Power Query
Power Query com o Excel

Office Dev Scripts

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Office Dev Scripts

Enviado por

Direitos autorais:

Formatos disponíveis

Dê a sua opinião sobre a experiência de download do PDF.

Documentação de scripts do Office

Integre-se com o Power Automate

Converter arquivos CSV em pastas de trabalho do Excel

Definir formatação condicional para comparações entre colunas

Mais scripts de exemplo

Como compartilhar scripts

Quando usar Scripts do Office

Mais informações sobre o Gravador de Ações podem ser encontradas no artigo

Compartilhar Scripts do Office

Saiba mais sobre como os scripts são armazenados no seu OneDrive em

Agendar scripts para serem executados

Conectar Scripts do Office com o Power

Este tutorial ensina os conceitos básicos de gravação, edição e escrita de um Script do

Este tutorial é destinado a pessoas com conhecimento básico ou de nível

Adicione dados e grave um script básico

1. Crie uma nova pasta de trabalho do Excel.

2. Copie os seguintes dados de vendas de frutas e cole-os na planilha, começando na

Fruta 2018 2019

Laranjas 1000 1200

Limões 800 900

Limões-galego 600 500

Toranjas 900 700

4. Selecione o botão Gravar Ações.

5. Selecione as células A2:C2 (a linha "Laranjas") e defina a cor de preenchimento

6. Interrompa a gravação selecionando o botão Parar.

Edite um script existente

1. No painel, agora aberto, Detalhes, selecione o botão Editar.

2. Você deve ver algo semelhante a este código:

function main(workbook: ExcelScript.Workbook) {

Criar uma tabela

1. Adicione a seguinte linha no final do script (antes do encerramento } ):

let table = selectedSheet.addTable("A1:C5", true);

table.getSort().apply([{ key: 0, ascending: true }]);

Seu script deve ter esta aparência:

function main(workbook: ExcelScript.Workbook) {

As tabelas possuem um objeto TableSort , acessado por meio do método

3. Execute o script. Você deve visualizar uma tabela como esta:

Se você executar novamente o script, receberá um erro. Isso ocorre porque

Ler uma célula

2. Copie os seguintes dados e cole-os na nova planilha, começando na célula A1.

Data Conta Descrição Débito Crédito

10/10/2019 Verificando Vinícola Coho -20.05

11/10/2019 Crédito A Companhia Telefônica 99.95

13/10/2019 Crédito Vinícola Coho 154.43

15/10/2019 Verificando Depósito externo 1000

20/10/2019 Crédito Vinícola Coho – Reembolso -35.45

25/10/2019 Verificando Ideal para sua empresa de produtos -85.64

01/11/2019 Verificando Depósito externo 1000

3. Acesse a guia Automatizar e selecioneNovo Script.

Substitua o conteúdo do script pelo código a seguir:

function main(workbook: ExcelScript.Workbook) {

// Format the range to display numerical dollar amounts.

// Fit the width of all the used columns to the data.

// Get the value of cell D2.

7. Você deverá ver [Array[1]] no console. Isso não é um número porque os

8. Quando uma matriz bidimensional é registrada no console, ela agrupa os valores

9. Expanda o segundo nível da matriz selecionando o triângulo azul recém-revelado.

Modificar o valor de uma célula

Estamos lançando o valor retornado de range.getValue() para um number

2. O valor da célula D2 agora deverá ser positivo.

Modificar os valores de uma coluna

function main(workbook: ExcelScript.Workbook) {

// Format the range to display numerical dollar amounts.