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