Sumário
Índice 🔎︎

# Ler e Escrever Valores em Células

Macros no LibreOffice Calc frequentemente precisam ler e escrever valores de/para células em planilhas. Esta página de ajuda descreve as várias abordagens para acessar planilhas e células para ler ou alterar seus valores.

Todos os exemplos apresentados nesta página podem ser implementados em Basic e Python.

## Acessando uma única célula

O exemplo abaixo insere o valor numérico 123 na célula "A1" da planilha atual.

        Dim oSheet as Object
        Dim oCell as Object
        oSheet = ThisComponent.CurrentController.getActiveSheet()
        oCell = oSheet.getCellRangeByName("A1")
        oCell.setValue(123)

O mesmo pode ser feito em Python:

        doc = XSCRIPTCONTEXT.getDocument()
        sheet = doc.getCurrentController().getActiveSheet()
        cell = sheet.getCellRangeByName("A1")
        cell.setValue(123)

Note que nos exemplos anteriores a célula é acessada usando seu endereço "A1". Também é possível acessar células usando índices como se a planilha fosse uma matriz onde colunas e linhas são indexadas por valores inteiros iniciando em zero.

Isso pode ser feito usando o método getCellByPosition(colIndex, rowIndex), o qual requer um índice de coluna e um índice de linha. O exemplo abaixo em Basic muda o valor textual na célula "C1" (coluna 2, linha 0).

        oSheet = ThisComponent.CurrentController.getActiveSheet()
        oCell = oSheet.getCellByPosition(2, 0)
        oCell.setString("Hello")

Este exemplo pode ser implementado em Python da seguinte forma:

        doc = XSCRIPTCONTEXT.getDocument()
        sheet = doc.getCurrentController().getActiveSheet()
        cell = sheet.getCellByPosition(2, 0)
        cell.setString("Hello")

A principal diferença entre scripts em Python e Basic é a maneira como o objeto referente à planilha é acessado, o que é feito por meio da variável de contexto XSCRIPTCONTEXT. Após isso, todos os métodos e propriedades são idênticos em Basic e em Python.

## Valores, Strings e Fórmulas

Células podem ter três tipos de valores: números, strings e fórmulas. Cada tipo conta com métodos para definição e leitura de valores:

Tipo | Get Method | Set Method
--- | --- | ---
Numérico | getValue() | setValue(newValue)
Texto | getString() | setString(newString)
Fórmula | getFormula() | setFormula(newFormula)

Datas e valores monetários são considerados como valores numéricos no Calc.

O exemplo a seguir insere valores numéricos nas células "A1" e "A2" e insere uma fórmula na célula "A3" que retorna a multiplicação desses valores.

        oSheet = ThisComponent.CurrentController.getActiveSheet()
        oCell = oSheet.getCellRangeByName("A1")
        oCell.setValue(10)
        oCell = oSheet.getCellRangeByName("A2")
        oCell.setValue(20)
        oCell = oSheet.getCellRangeByName("A3")
        oCell.setFormula("=A1*A2")

## Acessando células em planilhas diferentes

Os exemplos anteriores usaram apenas a planilha ativa para realizar operações. É possível acessar células em diferentes planilhas usando seus índices ou nomes.

O exemplo abaixo insere um valor numérico na célula "A1" da planilha chamada "Sheet2".

        oSheet = ThisComponent.Sheets.getByName("Sheet2")
        oCell = oSheet.getCellRangeByName("A1")
        oCell.setValue(123)

Este exemplo pode ser implementado em Python da seguinte forma:

        doc = XSCRIPTCONTEXT.getDocument()
        sheet = doc.Sheets["Sheet2"]
        cell = sheet.getCellRangeByName("A1")
        cell.setValue(123)

Planilhas também podem ser acessadas usando índices iniciando em zero considerando a ordem em que elas aparecem no arquivo Calc.

Em Basic, em vez de usar o método getByName, use o método Sheets(sheetIndex) conforme mostrado a seguir:

        oSheet = ThisComponent.Sheets(0)

Isso pode ser feito de forma similar em Python:

        sheet = doc.Sheets[0]

## Usando a biblioteca ScriptForge

O serviço Calc da biblioteca ScriptForge pode ser usado para obter e definir valores de células da seguinte forma:

        ' Carrega a biblioteca ScriptForge
        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        ' Obtém acesso ao documento Calc atual
        oDoc = CreateScriptService("Calc")
        ' Define os valores das células A1 e A2
        oDoc.setValue("A1", "Hello")
        oDoc.setValue("A2", 123)

O método setValue pode ser usado para definir tanto valores numéricos como valores textuais. Para definir uma fórmula, utilize o método setFormula.

Com o serviço Calc, a obtenção e definição de valores podem ser feitas usando uma única linha de código. O exemplo abaixo lê o valor da célula "A1" e mostra o valor em uma caixa de mensagem.

        Dim val as Variant, oDoc as Object
        oDoc = CreateScriptService("Calc")
        val = oDoc.getValue("A1")
        MsgBox val

A biblioteca ScriptForge também torna mais simples o acesso a células em planilhas diferentes, conforme demonstra o exemplo abaixo:

        Dim val1, val2
        ' Lê a célula "A1" da planilha "Sheet1"
        val1 = oDoc.getValue("Sheet1.A1")
        ' Lê a célula "B3" da planilha "Sheet2"
        val2 = oDoc.getValue("Sheet2.B3")
        ' Insere o resultado na célula "A1" da planilha "Report"
        Dim result : result = val1 * val2
        oDoc.setValue("Report.A1", result)

Os exemplos acima também podem ser implementados em Python:

        from scriptforge import CreateScriptService
        doc = CreateScriptService("Calc")
        doc.setValue("A1", "Hello")

        doc = CreateScriptService("Calc")
        bas = CreateScriptService("Basic")
        val = doc.getValue("A1")
        bas.MsgBox(val)

        first_val = doc.getValue("Sheet1.A1")
        second_val = doc.getValue("Sheet2.B3")
        result = first_val * second_val
        doc.setValue("Report.A1", result)

Tópicos relacionados

A Biblioteca ScriptForge

Serviço SFDocuments.Calc

Programando com scripts Python