Conteúdo

# Ler e escrever valores em intervalos

As macros no LibreOffice Calc precisam frequentemente de ler e escrever valores de/para folhas de cálculo. Esta página de ajuda descreve as várias formas de aceder a folhas de cálculo e intervalos para ler ou escrever os seus valores.

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

## Aceder a uma única célula

O exemplo abaixo insere o valor numérico 123 na célula «A1» da folha 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 com Python:

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

Note-se que, nos exemplos anteriores, o acesso à célula é feito através do nome do intervalo «A1». Também é possível aceder às células utilizando índices, como se a folha fosse uma matriz em que as colunas e as linhas são indexadas a partir do zero.

Isto pode ser feito utilizando o método getCellByPosition(colIndex, rowIndex), que recebe um índice de coluna e um índice de linha. O exemplo abaixo em Basic altera o valor do texto na célula «C1» (coluna 2, linha 0).

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

Este exemplo também 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 os scripts em Python e em Basic reside na forma de aceder ao objeto da folha através da variável de contexto XSCRIPTCONTEXT. Para além disso, todos os métodos e propriedades são idênticos em Basic e em Python.

## Valores, cadeias de caracteres e fórmulas

As células do Calc podem conter três tipos de valores: numéricos, cadeias de caracteres e fórmulas. Cada tipo tem os seus próprios métodos set e get:

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

As datas e os valores monetários são considerados valores numéricos no Calc.

O exemplo seguinte insere valores numéricos nas células «A1» e «A2» e insere uma fórmula na célula «A3» que calcula o produto 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")

## Aceder a intervalos em folhas diferentes

Os exemplos anteriores utilizaram apenas a folha ativa para realizar operações. É possível aceder a intervalos de células em folhas diferentes através dos seus índices ou nomes.

O exemplo abaixo insere um valor numérico na célula «A1» da folha denominada «Sheet2».

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

Este exemplo também pode ser implementado em Python da seguinte forma:

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

Também é possível aceder às folhas utilizando índices com base zero, indicando qual a folha, tendo em conta a ordem em que aparecem no ficheiro do Calc.

No Basic, em vez de utilizar o método getByName, utilize Sheets(sheetIndex), conforme mostrado a seguir:

        oSheet = ThisComponent.Sheets(0)

Isto pode ser feito de forma semelhante em Python:

        sheet = doc.Sheets[0]

## Utilização da biblioteca ScriptForge

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

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

O método setValue pode ser utilizado para definir valores numéricos e de texto. Para definir uma fórmula de célula, utilize o método setFormula.

Com o serviço Calc, é possível obter e definir valores de células com uma única linha de código. O exemplo abaixo obtém o valor da célula «A1» e apresenta-o numa caixa de mensagem.

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

A biblioteca ScriptForge também facilita o acesso a intervalos em diferentes folhas, como se pode ver no exemplo abaixo:

        Dim val1, val2
        ' Obtém a célula "A1" da folha denominada "Sheet1"
        val1 = oDoc.getValue("Sheet1.A1")
        ' Obtém a célula "B3" da folha denominada "Sheet2"
        val2 = oDoc.getValue("Sheet2.B3")
        ' Coloca o resultado na célula «A1» da folha «Relatório»
        Dim result : result = val1 * val2
        oDoc.setValue("Report.A1", result)

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

        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

Programação com scripts Python