Ações do Excel
Ações do Excel são ações para interagir com arquivos do Excel.
Ações
excel.append
Anexe novas linhas ao final da planilha.
Parâmetros:
worksheet - planilha a ser usada para obtenção de células.
line_values (opcional) - array com cada índice sendo uma coluna diferente, exemplo:
grid_values (opcional) - uma grade onde cada linha representará uma linha e cada elemento de linha representará uma coluna, exemplo:
[
['Linha 1 - Col1', 'Linha 1 - Col2', 'Linha 1 - Col3'],
['Linha 2 - Col1', 'Linha 2 - Col2', 'Linha 2 - Col3']
]
Retorna:
Esta ação não tem retorno.
Exceções:
Esta ação não retorna nenhuma exceção
excel.convert_to_xlsx
Converta qualquer tipo de arquivo que o Excel possa abrir (por exemplo: XLS, CSV), para arquivo XLSX. O arquivo convertido será salvo no mesmo caminho e com o mesmo nome, com extensão .xlsx.
Importante: Para utilizar esta ação, o software Excel deve estar instalado na máquina e todas as janelas do Excel devem estar fechadas.
Parâmetros:
filepath - Caminho para o arquivo que será convertido.
Retorna:
Esta ação não tem retorno.
Exceções:
Esta ação não retorna nenhuma exceção
excel.create_new
Crie uma planilha completamente nova.
Importante: para salvar esta planilha em uma pasta, deve-se chamar a ação excel.save.
Parâmetros:
Esta ação não tem parâmetros.
Retorna:
workbook - Pasta de trabalho a ser usada com outras ações do Excel
worksheet - planilha ativa do arquivo
Ações do Excel
As ações do Excel expostas ao robô permitem abrir, ler, editar e salvar arquivos Excel.
Observação importante: apenas métodos anotados com @decorators.robotaction
são ações de usuário e estão documentados aqui. Os retornos das ações são mapeados para variáveis de estado — ou seja, se a ação retorna {'workbook': workbook}
você acessa esse valor no fluxo com $workbook
.
Métodos expostos
Cada seção abaixo descreve a ação, parâmetros, chaves de retorno (variáveis de estado) e notas.
excel.open
Abre um arquivo Excel e (opcionalmente) tenta atualizar valores calculados abrindo o Excel localmente antes de carregar.
Parâmetros:
- filepath
— caminho do arquivo nos assets.
- use_formula
(opcional, default False) — se True retorna fórmulas em vez de valores calculados.
- auto_update
(opcional, default True) — se True tenta abrir o Excel para atualizar células com fórmulas antes de carregar.
- excel_visible
(opcional, default False) — se True exibe a aplicação Excel ao atualizar.
Retorno (variáveis de estado):
- workbook
— objeto openpyxl Workbook.
- worksheet
— planilha ativa (Worksheet).
Exceções / notas:
- FileNotFoundException
se o arquivo não existir no assets.
- InvalidExcelFile
quando o arquivo está em formato incompatível (ex.: .xls) ou corrompido; use excel.convert_to_xlsx
quando aplicável.
Exemplo de uso:
# chamar a ação (no fluxo do robô)
# excel.open('planilha.xlsx')
# depois acesse $workbook e $worksheet
excel.create_new
Cria uma nova pasta de trabalho em branco.
Parâmetros: nenhum.
Retorno:
- workbook
— novo Workbook.
- worksheet
— planilha ativa criada.
Nota: use excel.save
para gravar em disco.
excel.list_sheets
Retorna os nomes das planilhas e a planilha ativa.
Parâmetros:
- workbook
— objeto Workbook.
Retorno:
- sheets
— lista de nomes de planilhas.
- active_sheet
— nome da planilha ativa.
excel.create_sheet
Cria uma nova planilha na pasta de trabalho.
Parâmetros:
- workbook
— Workbook.
- sheet_name
— nome da nova planilha.
Retorno:
- workbook
— Workbook atualizado.
- worksheet
— a nova Worksheet criada.
excel.rename_sheet
Renomeia a planilha fornecida.
Parâmetros:
- worksheet
— Worksheet a renomear.
- new_name
— novo nome.
Retorno:
- worksheet
— Worksheet atualizada.
excel.select_sheet
Seleciona uma planilha da pasta de trabalho.
Parâmetros:
- workbook
— Workbook.
- sheet_name
(opcional) — nome da planilha; se omitido retorna a planilha ativa.
Retorno:
- workbook
— Workbook (mesmo objeto recebido).
- worksheet
— Worksheet selecionada.
excel.get_cell
Retorna o conteúdo de uma célula ou intervalo.
Parâmetros:
- worksheet
— Worksheet.
- range
— string no formato Excel (ex.: A1
ou A1:C3
).
Retorno:
- first_col
, first_row
, last_col
, last_row
, values
— onde values
é uma matriz de linhas/colunas (ex.: values[0][1]
).
Exceção:
- InvalidRange
em caso de intervalo inválido (implementação interna pode variar).
excel.update_cell
Atualiza o valor de uma célula.
Parâmetros:
- worksheet
— Worksheet.
- value
— valor a inserir.
- cell
— referência Excel (ex.: A1
).
Retorno:
- mesmo formato de excel.get_cell
(chaves: first_col
, first_row
, last_col
, last_row
, values
).
excel.append
Anexa uma linha ou múltiplas linhas ao final da planilha.
Parâmetros:
- worksheet
— Worksheet.
- line_values
(opcional) — lista representando uma linha.
- grid_values
(opcional) — lista de listas para anexar várias linhas.
Retorno: nenhum (ação que modifica a planilha).
excel.save
Salva a pasta de trabalho em disco.
Parâmetros:
- workbook
— Workbook.
- filepath
— caminho (incluindo nome) onde salvar.
Retorno: nenhum.
excel.last_line
Retorna o número da última linha utilizada.
Parâmetros:
- worksheet
— Worksheet.
Retorno:
- last_line
— inteiro com o número da última linha.
excel.get_dimensions
Retorna o intervalo que contém dados na planilha.
Parâmetros:
- worksheet
— Worksheet.
Retorno:
- range
— intervalo no padrão Excel (ex.: A1:F150
).
- first_cell
— referência da primeira célula.
- last_cell
— referência da última célula.
excel.convert_to_xlsx
Converte um arquivo (ex.: .xls) para .xlsx. Requer Excel instalado no host.
Parâmetros:
- filepath
— caminho no assets.
- excel_visible
(opcional) — exibe o Excel durante a conversão.
Retorno: nenhum (arquivo convertido é criado ao lado do original com extensão .xlsx
).
Nota: se o Excel não estiver instalado a ação loga um erro e não converte.
excel.delete_rows
Remove linhas de start
até end
(inclusive). Se end
não informado, apenas start
é removido.
Parâmetros:
- worksheet
, start
, end
(opcional).
Retorno: nenhum.
excel.execute_macro
Executa uma macro via COM (requer Excel instalado).
Parâmetros:
- file_path
— arquivo com a macro.
- macro
— identificador/nome da macro.
- save_after_execution
(opcional, default True) — salva após execução.
Retorno: nenhum. Erros da macro podem ser propagados.
excel.create_style_template
Cria um template de estilo reutilizável.
Parâmetros:
- font_name, font_size, bold, italic, underline, font_color, background_color, border_style, border_color
.
Retorno:
- template
— objeto que pode ser passado para excel.set_template
.
excel.set_template
Aplica um template
(criado por excel.create_style_template
) a um intervalo.
Parâmetros:
- worksheet
, range
, template
.
Retorno: nenhum.
excel.set_table_format
Aplica estilos em cabeçalho, linhas ímpares e pares de um intervalo.
Parâmetros:
- worksheet
, range
, header_style
, odd_line_style
, even_line_style
(opcional).
Retorno: nenhum.
Exceção: WrongVarType
se range
não for um intervalo válido.
excel.set_style
Aplica estilo (campos individuais) a células ou intervalo.
Parâmetros:
- worksheet
, range
e propriedades de estilo (font_name
, font_size
, bold
, italic
, underline
, font_color
, background_color
, border_style
, border_color
).
Retorno: nenhum.
Se desejar, posso adicionar pequenos exemplos de uso práticos para cada ação (trechos curtos com chamadas e como ler as variáveis de estado), ou aplicar pequenas melhorias seguras no código excel.py
(ex.: tratamento de erros e limpeza de imports).
Esta ação não retorna nenhuma exceção