Pular para conteú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.

Ações

Cada seção abaixo descreve a ação, parâmetros, chaves de retorno (variáveis de estado) e notas.

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.
Retornar:

nenhum (ação que modifica a planilha).

excel.convert_to_xlsx

Converte um arquivo (ex.: .xls) para .xlsx. Requer Excel instalado no host.

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 no assets.
  • excel_visible (opcional) — exibe o Excel durante a conversão.
Retornar:

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.create_new

Cria uma nova pasta de trabalho em branco.

Parâmetros:

nenhum.

Retornar:
  • workbook — novo Workbook.
  • worksheet — planilha ativa criada.

Nota: use excel.save para gravar em disco.

excel.create_sheet

Cria uma nova planilha na pasta de trabalho.

Parâmetros:
  • workbook — Workbook.
  • sheet_name — nome da nova planilha.
Retornar:
  • workbook — Workbook atualizado.
  • worksheet — a nova Worksheet criada.

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.
Retornar:
  • template — objeto que pode ser passado para excel.set_template.

excel.delete_rows

Remove linhas de start até end (inclusive). Se end não informado, apenas start é removido.

Parâmetros:
  • worksheet, start, end (opcional).
Retornar:

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.
Retornar:

nenhum. Erros da macro podem ser propagados.

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).
Retornar:
  • first_col, first_row, last_col, last_row, values — onde values é uma matriz de linhas/colunas (ex.: values[0][1]).
Exceções:
  • InvalidRange em caso de intervalo inválido (implementação interna pode variar).

excel.get_dimensions

Retorna o intervalo que contém dados na planilha.

Parâmetros:
  • worksheet — Worksheet.
Retornar:
  • 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.last_line

Retorna o número da última linha utilizada.

Parâmetros:
  • worksheet — Worksheet.
Retornar:
  • last_line — inteiro com o número da última linha.

excel.list_sheets

Retorna os nomes das planilhas e a planilha ativa.

Parâmetros:
  • workbook — objeto Workbook.
Retornar:
  • sheets — lista de nomes de planilhas.
  • active_sheet — nome da planilha ativa.

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.
Retornar:
  • workbook — objeto openpyxl Workbook.
  • worksheet — planilha ativa (Worksheet).
Exceções:
  • 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.rename_sheet

Renomeia a planilha fornecida.

Parâmetros:
  • worksheet — Worksheet a renomear.
  • new_name — novo nome.
Retornar:
  • worksheet — Worksheet atualizada.

excel.save

Salva a pasta de trabalho em disco.

Parâmetros:
  • workbook — Workbook.
  • filepath — caminho (incluindo nome) onde salvar.
Retornar:

nenhum.

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.
Retornar:
  • workbook — Workbook (mesmo objeto recebido).
  • worksheet — Worksheet selecionada.

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).
Retornar:

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).
Retornar:

nenhum.

Exceções:

WrongVarType se range não for um intervalo válido.

excel.set_template

Aplica um template (criado por excel.create_style_template) a um intervalo.

Parâmetros:
  • worksheet, range, template.
Retornar:

nenhum.

excel.update_cell

Atualiza o valor de uma célula.

Parâmetros:
  • worksheet — Worksheet.
  • value — valor a inserir.
  • cell — referência Excel (ex.: A1).
Retornar:
  • mesmo formato de excel.get_cell (chaves: first_col, first_row, last_col, last_row, values).