Pular para conteúdo

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:

['Col 1', 'Col 2', 'Col 3']

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