Услуга SFDocuments.Calc

Споделената библиотека SFDocuments предлага набор от методи и свойства за улесняване управлението и боравенето с документи на LibreOffice.

Услугата SFDocuments.Calc е подклас на услугата SFDocuments.Document. Всички методи и свойства, дефинирани за услугата Document, са достъпни и през екземпляр на услугата Calc.

Услугата Calc е предназначена основно за:

• боравене с листове в документ на Calc (копиране, вмъкване, преместване и т.н.)

• обмен на данни между структури от данни на Basic и диапазони на Calc

• копиране и импортиране на големи количества данни.

Тази страница от помощта описва методи и свойства, приложими само за документи на Calc.

Извикване на услугата

Преди да използвате услугата Calc, библиотеката ScriptForge трябва да бъде заредена или импортирана:

• Макросите на Basic изискват зареждане на библиотеката ScriptForge чрез следния оператор:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Скриптовете на Python изискват импортиране от модула scriptforge:
from scriptforge import CreateScriptService

Услугата Calc е тясно свързана с услугата UI на библиотеката ScriptForge. Следват няколко примера за обръщения към услугата Calc.

Долният програмен фрагмент създава екземпляр на услугата Calc, който съответства на текущо активния документ на Calc.

    Set oDoc = CreateScriptService("Calc")
  

Друг начин да се създаде екземпляр на услугата Calc, е да се използва услугата UI. В следващия пример се създава нов документ на Calc и oDoc е екземпляр на услугата Calc:

    Dim ui As Object, oDoc As Object
    Set ui = CreateScriptService("UI")
    Set oDoc = ui.CreateDocument("Calc")
  

Или чрез метода OpenDocument на услугата UI:

    Set oDoc = ui.OpenDocument("C:\Documents\MyFile.ods")
  

Екземпляр на услугата Calc може да се създаде и като се зададе име на прозорец за метода CreateScriptService:

    Dim oDoc As Object
    Set oDoc = CreateScriptService("SFDocuments.Calc", "MyFile.ods")
  

В горния пример "MyFile.ods" е името на отворен прозорец с документ. Ако този аргумент не е подаден, се взема предвид текущият прозорец.

Обръщение към услугата Calc може да се осъществи и чрез документа, сочен от ThisComponent. Това е особено полезно при изпълнение на макрос от развойната среда на Basic.

    Dim oDoc As Object
    Set oDoc = CreateScriptService("Calc", ThisComponent)
  

Препоръчва се ресурсите да бъдат освободени след употреба:

    Set oDoc = oDoc.Dispose()
  

Ако обаче документът бъде затворен с метода CloseDocument, освобождаването на ресурсите с гореописаната команда става излишно.

    myDoc = CreateScriptService("Calc")
  

    ui = CreateScriptService("UI")
    myDoc = ui.CreateDocument("Calc")
  

    myDoc = ui.OpenDocument(r"C:\Documents\MyFile.ods")
  

    myDoc = CreateScriptService("SFDocuments.Calc", "MyFile.ods")
    myDoc.Dispose()
  

    bas = CreateScriptService("Basic")
    myDoc = CreateScriptService("Calc", bas.ThisComponent)
  

Използването на префикса "SFDocuments." при извикването на услугата не е задължително.

Определения

Много методи изискват като аргумент "Sheet" (лист) или "Range" (диапазон). Единичните клетки се смятат за частен случай на диапазон – Range.

И двете могат да бъдат изразени като низ или като референция (= обект) според ситуацията:

• В рамките на конкретен екземпляр на Calc листовете и диапазоните се подават като низове от рода на "Лист1" и "D2:F6".

• Освен това, свойствата .Sheet и .Range връщат референция, която може да се използва като аргумент на метод, извикван от друг екземпляр на услугата Calc.

Примерът по-долу копира данни от документа A (отворен само за четене и скрит) към документа B.

    Dim oDocA As Object, oDocB As Object
    Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)
    Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")
    oDocB.CopyToRange(oDocA.Range("SheetX.D4:F8"), "D2:F6") 'CopyToRange(source, target)
  

    docA = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
    docB = ui.OpenDocument(r"C:\Documents\FileB.ods")
    docB.CopyToRange(docA.Range("SheetX.D4:F8"), "D2:F6")
  

SheetName

Или името на листа като низ, или обект, получен чрез свойството .Sheet.

Съкращението "~" (тилда) представя текущия лист.

RangeName

Или низ, обозначаващ съвкупност от съседни клетки в лист на текущия екземпляр, или обект, получен чрез свойството .Range.

Съкращението "~" (тилда) представя текущата селекция или първия избран диапазон, ако са избрани няколко диапазона.

Съкращението "*" представя всички използвани клетки.

Името на листа не е задължително, когато се дефинира диапазон. Ако не е подадено име на лист, се използва текущият лист. Ограждащи кавички и знаци $ се допускат, но се игнорират.

Когато се задава SheetName (име на лист) като низ, ограждането на името на листа с единични кавички е задължително, ако то съдържа интервали " " или точки ".".

Долните примери илюстрират в кои случаи е задължителна употребата на единични кавички:

      ' Единичните кавички не са задължителни.
      oDoc.clearAll("SheetA.A1:B10")
      oDoc.clearAll("'SheetA'.A1:B10")
      ' Единичните кавички са задължителни.
      oDoc.clearAll("'Sheet.A'.A1:B10")
    

С изключение на свойството CurrentSelection услугата Calc работи само с единични диапазони от клетки.

Свойства

Свойствата, общи за всички видове документи, са неявно приложими и за документи на Calc. За повече информация прочетете помощната страница за услугата Document.

Свойствата, налични специално за документи на Calc, са:

Посетете уебсайта с документацията на LibreOffice API, за да научите повече за UNO обектите XCellRange, XSheetCellCursor и XSpreadsheet.

Методи

A1Style

Връща адрес на диапазон като низ на базата на координати в лист, т.е. номера на редове и колони.

Ако е подадена само една двойка координати, се връща адрес на единична клетка. Допълнителни аргументи могат да указват долния десен ъгъл на правоъгълен диапазон.

svc.A1Style(row1: int, column1: int, row2: int = 0; column2: int = 0; sheetname: str = "~"): str

row1, column1: указват номера на реда и номера на колоната на горната лява клетка в разглеждания диапазон. Номерата на редове и колони започват от 1.

row2, column2: указват номера на ред и номера на колона на долната дясна клетка в разглеждания диапазон. Ако тези аргументи не са подадени, или ако са подадени стойности, по-малки от row1 и column1, се връща адресът на единичната клетка, представена от row1 и column1.

sheetname: името на листа, което да бъде добавено към връщания адрес на диапазон. Листът трябва да съществува. Подразбираната стойност е "~", съответстваща на текущия активен лист.

В примерите на Basic и Python по-долу се приема, че текущо активният лист е "Sheet1".

    Set oDoc = CreateScriptService("Calc")
    addr1 = oDoc.A1Style(1, 1) ' '$Sheet1'.$A$1
    addr2 = oDoc.A1Style(2, 2, 3, 6) ' '$Sheet1'.$B$2:$F$3
    addr3 = oDoc.A1Style(2, 2, 0, 6) ' '$Sheet1'.$B$2
    addr4 = oDoc.A1Style(3, 4, 3, 8, "Sheet2") ' '$Sheet2'.$D$3:$H$3
    addr5 = oDoc.A1Style(5, 1, SheetName := "Sheet3") ' '$Sheet3'.$A$5
  

    doc = CreateScriptService("Calc")
    addr1 = doc.A1Style(1, 1) # '$Sheet1'.$A$1
    addr2 = doc.A1Style(2, 2, 3, 6) # '$Sheet1'.$B$2:$F$3
    addr3 = doc.A1Style(2, 2, 0, 6) # '$Sheet1'.$B$2
    addr4 = doc.A1Style(3, 4, 3, 8, "Sheet2") # '$Sheet2'.$D$3:$H$3
    addr5 = doc.A1Style(5, 1, sheetname="Sheet3") # '$Sheet3'.$A$5
  

Методът A1Style може да бъде комбиниран с всяко от многото свойства и методи на услугата Calc, което изисква диапазон като аргумент, например GetValue, GetFormula, ClearAll и т.н.

Activate

Ако аргументът sheetname е подаден, даденият лист се активира и става текущо избран. Ако аргументът отсъства, се активира прозорецът на документа.

svc.Activate(sheetname: str = ""): bool

sheetname: името на листа, който да бъде активиран в документа. Подразбираната стойност е празен низ, което означава, че ще бъде активиран прозорецът на документа, без да се променя активният лист.

Примерът по-долу активира листа с име "Sheet4" в текущо активния документ.

    Dim ui as Variant, oDoc as Object
    Set ui = CreateScriptService("UI")
    Set oDoc = ui.GetDocument(ui.ActiveWindow)
    oDoc.Activate("Sheet4")
  

    ui = CreateScriptService("UI")
    myDoc = ui.GetDocument(ui.ActiveWindow)
    myDoc.Activate("Sheet4")
  

Активирането на лист има смисъл само ако се извършва върху документ на Calc. За да се уверите, че е налице документ на Calc, можете да използвате свойството isCalc на обекта документ, което връща True, ако той е документ на Calc, и False в противен случай.

Charts

Връща списъка с имената на всички обекти диаграми в даден лист или единичен екземпляр на услугата Chart.

• Ако е зададен само sheetname, се връща индексиран от нула масив, съдържащ имената на всички диаграми.

• Ако е подаден chartname, се връща единичен обект, съответстващ на желаната диаграма. Указаната диаграма трябва да съществува.

svc.Charts(sheetname: str, chartname: str = ""): obj

sheetname: името на листа, от който трябва да се извлече списъкът с диаграми или в който се намира зададената диаграма.

chartname: зададеното от потребителя име на обекта диаграма, който да бъде върнат. Ако диаграмата няма име, дефинирано от потребителя, може да се използва вътрешното име на обекта. Ако този аргумент отсъства, се връща списъкът с имената на диаграмите в текущия лист.

Използвайте страничната лента Навигатор, за да проверите имената, присвоени на диаграмите, в категорията OLE обекти.

Следващият пример показва броя обекти диаграми в "Sheet1":

    Dim arrNames as Object
    arrNames = oDoc.Charts("Sheet1")
    MsgBox "There are " & UBound(arrNames) + 1 & " charts in Sheet1"
  

Следващият пример осъществява достъп до диаграмата с име "MyChart" в листа "Sheet1" и отпечатва типа ѝ.

    Dim oChart as Object
    oChart = oDoc.Charts("Sheet1", "MyChart")
    MsgBox oChart.ChartType
  

    bas = CreateScriptService("Basic")
    chart_names = doc.Charts("Sheet1")
    bas.MsgBox(f"There are {len(chart_names)} charts in Sheet1")
  

    chart = doc.Charts("Sheet1", "MyChart")
    bas.MsgBox(chart.ChartType)
  

ClearAll

Изчиства цялото съдържание и форматите от дадения диапазон.

Може да се зададе филтрираща формула, за да се определи кои клетки да бъдат засегнати.

svc.ClearAll(range: str, opt filterformula: str, opt filterscope: str)

range: диапазонът, който да бъде изчистен, като низ.

filterformula: формула на Calc, която да бъде приложена върху дадения диапазон, за да се определи кои клетки да бъдат засегнати. Зададената формула трябва да връща True или False. Ако този аргумент не е подаден, се обработват всички клетки в диапазона.

filterscope: определя как filterformula се разширява до зададения диапазон. Този аргумент е задължителен, ако е зададен filterformula. Приемат се следните стойности:

• "CELL": формулата, зададена в аргумента filterformula, се разширява по веднъж за всяка клетка в range.

• "ROW": формулата, зададена в аргумента filterformula, се разширява по веднъж за всеки ред в range.

• "COLUMN": формулата, зададена в аргумента filterformula, се разширява по веднъж за всяка колона в range.

    ' Изчиства всички клетки в диапазона ЛистX.A1:J10
    oDoc.ClearAll("ЛистX.A1:J10")
    ' Изчиства всички клетки в диапазона ЛистX.A1:J10, чиято стойност е по-голяма от 100.
    oDoc.ClearAll("ЛистX.A1:J10", "=ЛистX.A1>100", "CELL")
    ' Изчиства всички редове в диапазона ЛистX.A1:J10, чиято сума е по-голяма от 500.
    oDoc.ClearAll("ЛистX.A1:J10", "=SUM(ЛистX.A1:J1)>100", "ROW")
    ' Изчиства всички колони в диапазона ЛистX.A1:J10, чиято сума е по-голяма от 500.
    oDoc.ClearAll("ЛистX.A1:J10", "=SUM(ЛистX.A1:A10)>100", "COLUMN")
  

    myDoc.ClearAll("ЛистX.A1:F10")
    myDoc.ClearAll("ЛистX.A1:J10", "=ЛистX.A1>100", "CELL")
    myDoc.ClearAll("ЛистX.A1:J10", "=SUM(ЛистX.A1:J1)>100", "ROW")
    myDoc.ClearAll("ЛистX.A1:J10", "=SUM(ЛистX.A1:A10)>100", "COLUMN")
  

ClearFormats

Изчиства форматите и стиловете в дадения диапазон.

Може да се зададе филтрираща формула, за да се определи кои клетки да бъдат засегнати.

svc.ClearFormats(range: str, opt filterformula: str, opt filterscope: str)

range: диапазонът, чиито формати и стилове трябва да се изчистят, като низ.

      oDoc.ClearFormats("SheetX.*")
  

    myDoc.ClearFormats("SheetX.*")
  

Refer to the ClearAll method documentation for examples on how to use the arguments filterformula and filterscope.

ClearValues

Изчиства стойностите и формулите в дадения диапазон.

Може да се зададе филтрираща формула, за да се определи кои клетки да бъдат засегнати.

svc.ClearValues(range: str, opt filterformula: str, opt filterscope: str)

range: диапазонът, чиито стойности и формули трябва да се изчистят, като низ.

      oDoc.ClearValues("SheetX.A1:F10")
  

    myDoc.ClearValues("SheetX.A1:F10")
  

Refer to the ClearAll method documentation for examples on how to use the arguments filterformula and filterscope.

CompactLeft

Изтрива колоните на зададен диапазон, които съответстват на филтър, изразен като формула на Calc. Филтърът се прилага върху всяка колона, за да се реши дали да бъде изтрита.

Изтритата колона може да бъде ограничена от височината на указания диапазон или да се простира до височината на целия лист, при което се изтриват цели колони.

Този метод връща низ с адреса на уплътнения диапазон. Ако всички колони са изтрити, се връща празен низ.

Ако е избран диапазон от клетки, извикването на този метод няма да повлияе върху селекцията.

svc.CompactLeft(range: str, wholecolumn: bool = False, opt filterformula: str): str

range: диапазонът, от който ще бъдат изтрити колони, като низ.

wholecolumn: ако тази настройка има стойност True, целите колони ще бъдат изтрити от листа. Подразбираната стойност е False, която означава, че изтриваните колони ще бъдат ограничени до височината на зададения диапазон range.

filterformula: филтърът, който да бъде приложен върху всяка колона, за да се определи дали да бъде изтрита. Филтърът е изразен като формула на Calc, която трябва да се приложи върху първата колона. Когато формулата върне True за някоя колона, тази колона ще бъде изтрита. Подразбираният филтър изтрива всички празни колони.

Например, да кажем, че е избран диапазонът A1:J200 (височина = 200), така че подразбираната формула е =(COUNTBLANK(A1:A200)=200). Това означава, че ако всичките 200 клетки в първата колона (колона A) са празни, колоната се изтрива. Обърнете внимание, че формулата е построена само спрямо първата колона. Методът CompactLeft ще я обобщи вътрешно за всички останали колони.

Функциите на Calc, използвани в аргумента filterformula, трябва да са изразени с английските си имена. Посетете уикистраницата List of Calc Functions за пълен списък с функциите на Calc на английски.

    ' Изтриваме всички празни колони в диапазона G1:L10 от Лист1.
    newrange = oDoc.CompactLeft("Лист1.G1:L10")
    ' Примерът по-долу е подобен, но целите колони се изтриват от листа.
    newrange = oDoc.CompactLeft("Лист1.G1:L10", WholeColumn := True)
    ' Изтрива всички колони, в които първият ред е отбелязан с "X".
    newrange = oDoc.CompactLeft("Лист1.G1:L10", FilterFormula := "=(G1=""X"")")
    ' Изтрива всички колони, за които сумата на стойностите в колоната е нечетна.
    newrange = oDoc.CompactLeft("Лист1.G1:L10", FilterFormula := "=(MOD(SUM(G1:G10);2)=1)")
  

    newrange = myDoc.CompactLeft("Лист1.G1:L10")
    newrange = myDoc.CompactLeft("Лист1.G1:L10", wholecolumn = True)
    newrange = myDoc.CompactLeft("Лист1.G1:L10", filterformula = '=(G1="X")')
    newrange = myDoc.CompactLeft("Лист1.G1:L10", filterformula = '=(MOD(SUM(G1:G10);2)=1)')
  

CompactUp

Изтрива редовете на зададен диапазон, които съответстват на филтър, изразен като формула на Calc. Филтърът се прилага върху всеки ред, за да се реши дали да бъде изтрит.

Изтриваните редове може да бъдат ограничени от ширината на указания диапазон или да се простират до ширината на целия лист, при което се изтриват цели редове.

Този метод връща низ с адреса на уплътнения диапазон. Ако всички редове са изтрити, се връща празен низ.

Ако е избран диапазон от клетки, извикването на този метод няма да повлияе върху селекцията.

svc.CompactUp(range: str, wholerow: bool = False, opt filterformula: str): str

range: диапазонът, от който ще бъдат изтрити редове, като низ.

wholerow: ако тази настройка има стойност True, целите редове ще бъдат изтрити от листа. Подразбираната стойност е False, която означава, че изтриваните редове ще бъдат ограничени до ширината на зададения диапазон range.

filterformula: филтърът, който да бъде приложен върху всеки ред, за да се определи дали да бъде изтрит. Филтърът е изразен като формула на Calc, която трябва да се приложи върху първия ред. Когато формулата върне True за някой ред, този ред ще бъде изтрит. Подразбираният филтър изтрива всички празни редове.

Например, да кажем, че е избран диапазонът A1:J200 (ширина = 10), така че подразбираната формула е =(COUNTBLANK(A1:J1)=10). Това означава, че ако всичките 10 клетки в първия ред (ред 1) са празни, редът се изтрива. Обърнете внимание, че формулата е построена само спрямо първия ред. Методът CompactUp ще я обобщи вътрешно за всички останали редове.

Функциите на Calc във формулата, зададена с аргумента filterformula, трябва да са изразени с английските си имена. Посетете уикистраницата List of Calc Functions за пълен списък с функциите на Calc на английски.

    ' Изтриваме всички празни редове в диапазона G1:L10 от Лист1.
    newrange = oDoc.CompactUp("Лист1.G1:L10")
    ' Примерът по-долу е подобен, но целите редове се изтриват от листа.
    newrange = oDoc.CompactUp("Лист1.G1:L10", WholeRow := True)
    ' Изтрива всички редове, в които първата колона е отбелязана с "X".
    newrange = oDoc.CompactUp("Лист1.G1:L10", FilterFormula := "=(G1=""X"")")
    ' Изтрива всички редове, за които сумата на стойностите в реда е нечетна.
    newrange = oDoc.CompactUp("Лист1.G1:L10", FilterFormula := "=(MOD(SUM(G1:L1);2)=1)")
  

    newrange = myDoc.CompactUp("Лист1.G1:L10")
    newrange = myDoc.CompactUp("Лист1.G1:L10", wholerow = True)
    newrange = myDoc.CompactUp("Лист1.G1:L10", filterformula = '=(G1="X")')
    newrange = myDoc.CompactUp("Лист1.G1:L10", filterformula = '=(MOD(SUM(G1:L1);2)=1)')
  

CopySheet

Копира указан лист преди съществуващ лист или в края на списъка с листове. Копираният лист трябва да е в някой отворен документ на Calc. Връща True при успех.

svc.CopySheet(sheetname: any, newname: str, [beforesheet: any]): bool

sheetname: името на листа, който да бъде копиран, като низ, или референция към обекта му.

newname: името на листа, който да бъде вмъкнат. Името не трябва да е вече използвано в документа.

beforesheet: името (низ) или индексът (число, броено от 1) на листа, преди който да бъде вмъкнат копираният лист. Този аргумент е незадължителен и подразбираното поведение е копираният лист да се добави на последна позиция.

Следващият пример създава копие на листа "SheetX" и го вмъква като последен лист в текущия документ. Името на копирания лист е "SheetY".

    Dim oDoc as Object
    ' Получава обекта Document на текущия прозорец.
    Set oDoc = CreateScriptService("Calc")
    oDoc.CopySheet("SheetX", "SheetY")
  

Долният пример копира "SheetX" от "FileA.ods" и го поставя на последната позиция във "FileB.ods" с името "SheetY":

      Dim oDocA As Object : Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)
      Dim oDocB As Object : Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")
      oDocB.CopySheet(oDocA.Sheet("SheetX"), "SheetY")
  

    myDoc.CopySheet("SheetX", "SheetY")
  

    docA = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
    docB = ui.OpenDocument(r"C:\Documents\FileB.ods")
    docB.CopySheet(docA.Sheet("SheetX"), "SheetY")
  

За да копирате листове между отворени документи, използвайте CopySheet. За да копирате листове от документи, които са затворени, използвайте CopySheetFromFile.

CopySheetFromFile

Копира указан лист от затворен документ на Calc и го поставя преди съществуващ лист или в края на списъка с листове на файла, сочен от обект Document.

Ако файлът не съществува, възниква грешка. Ако не е валиден файл на Calc, се вмъква празен лист. Ако листът източник не съществува във входния файл, в горния край на новопоставения лист се вмъква съобщение за грешка.

svc.CopySheetFromFile(filename: str, sheetname: str, newname: str, [beforesheet: any]): bool

filename: посочва кой файл да бъде отворен. Трябва да следва нотацията, зададена с SF_FileSystem.FileNaming. Файлът не трябва да е защитен с парола.

sheetname: името на листа, който да бъде копиран, като низ.

newname: името на копирания лист, който да бъде вмъкнат в документа. Името не трябва да е вече използвано в документа.

beforesheet: името (низ) или индексът (число, броено от 1) на листа, преди който да бъде вмъкнат копираният лист. Този аргумент е незадължителен и подразбираното поведение е копираният лист да се добави на последна позиция.

Следващият пример копира "SheetX" от "myFile.ods" и го поставя в документа, сочен от "oDoc", под името "SheetY", на първа позиция.

    oDoc.CopySheetFromFile("C:\Documents\myFile.ods", "SheetX", "SheetY", 1)
  

    myDoc.CopySheetFromFile(r"C:\Documents\myFile.ods", "SheetX", "SheetY", 1)
  

CopyToCell

Копира указан диапазон източник (стойности, формули и формати) към диапазон или клетка местоназначение. Този метод възпроизвежда поведението на операция „копиране и поставяне“ от диапазон към единична клетка.

Връща низ, представящ променения диапазон от клетки. Размерът на променената област изцяло се определя от размера на областта източник.

Диапазонът източник може да принадлежи на друг отворен документ.

svc.CopyToCell(sourcerange: any, destinationcell: str): str

sourcerange: диапазонът източник като низ, когато принадлежи на същия документ, или като референция, когато е част от друг отворен документ на Calc.

destinationcell: клетката местоназначение, където ще бъде поставен копираният диапазон от клетки, като низ. Ако е подаден диапазон, се взема предвид само горната му лява клетка.

Следва пример, в който източникът и местоназначението са в един и същ файл:

      oDoc.CopyToCell("SheetX.A1:F10", "SheetY.C5")
  

Долният пример показва как да копирате диапазон от друг отворен документ на Calc.

    Dim ui as Variant : ui = CreateScriptService("UI")
    Dim oDocSource As Object, oDocDestination As Object
    ' Отваряме документа източник във фонов режим (скрито)
    Set oDocSource = ui.OpenDocument("C:\SourceFile.ods", Hidden := True, ReadOnly := True)
    Set oDocDestination = CreateScriptService("Calc")
    oDocDestination.CopyToCell(oDocSource.Range("Sheet1.C2:C4"), "SheetT.A5")
    ' Не забравяйте да затворите документа източник, защото той е отворен като „скрит“.
    oDocSource.CloseDocument()
  

    docSource = ui.OpenDocument(r"C:\Documents\SourceFile.ods", hidden = True, readonly = True)
    docDestination = CreateScriptService("Calc")
    docDestination.CopyToCell(docSource.Range("Sheet1.C2:C4"), "SheetT.A5")
    docSource.CloseDocument()
  

За да симулирате копиране и поставяне от диапазон в единична клетка, използвайте CopyToCell. За да симулирате копиране и поставяне от диапазон в по-голям диапазон (със същите клетки, размножени неколкократно), използвайте CopyToRange.

CopyToRange

Копира надолу и/или надясно указан диапазон източник (стойности, формули и формати) в диапазон местоназначение. Този метод имитира поведението на операция „копиране и поставяне“ от диапазон източник към по-голям диапазон местоназначение.

• Ако височината (или ширината) на областта местоназначение е > 1 ред (или колона), височината (или ширината) на източника трябва да е <= височината (или ширината) на местоназначението. В противен случай не става нищо.

• Ако височината (или ширината) на местоназначението е = 1, то се разширява надолу (или надясно) до височината (или ширината) на диапазона източник.

Методът връща низ, представящ променения диапазон от клетки.

Диапазонът източник може да принадлежи на друг отворен документ.

svc.CopyToRange(sourcerange: any, destinationrange: str): str

sourcerange: диапазонът източник като низ, когато принадлежи на същия документ, или като референция, когато е част от друг отворен документ на Calc.

destinationrange: местоназначението на копирания диапазон от клетки, като низ.

Копиране в рамките на същия документ:

    oDoc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
    ' Връща низ за диапазон: "$SheetY.$C$5:$J$14"
  

Копиране от един файл в друг:

    Dim oDocA As Object : Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)
    Dim oDocB As Object : Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")
    oDocB.CopyToRange(oDocA.Range("SheetX.A1:F10"), "SheetY.C5:J5")
  

    doc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")
  

    docA = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)
    docB = ui.OpenDocument(r"C:\Documents\FileB.ods")
    docB.CopyToRange(docA.Range("SheetX.A1:F10"), "SheetY.C5:J5")
  

CreateChart

Създава нов обект диаграма, показващ данните в указания диапазон. Върнатият обект диаграма може да бъде управляван впоследствие чрез услугата Chart.

svc.CreateChart(chartname: str, sheetname: str, range: str, columnheader: bool = False, rowheader: bool = False): obj

chartname: дефинираното от потребителя име за създаваната диаграма. Името трябва да е уникално в рамките на листа.

sheetname: името на листа, в който да бъде разположена диаграмата.

range: диапазонът, който да се използва като източник на данни за диаграмата. Може да сочи към всеки лист от документа на Calc.

columnheader: когато е True, най-горният ред на диапазона се използва като надписи за оста на категориите или легендата (подразбира се False).

rowheader: когато е True, най-лявата колона на диапазона се използва като надписи за оста на категориите или легендата (подразбира се False).

Примерите по-долу на Basic и Python създават диаграма с данните от диапазона "A1:B5" на листа "Sheet1" и я разполагат в "Sheet2".

    Set oChart = oDoc.CreateChart("MyChart", "Sheet2", "Sheet1.A1:B5", RowHeader := True)
    oChart.ChartType = "Donut"
  

    chart = doc.CreateChart("MyChart", "Sheet2", "Sheet1.A1:B5", rowheader=True)
    chart.ChartType = "Donut"
  

Вижте помощната страница за услугата Chart на ScriptForge, за да научите повече за боравенето с обекти диаграми. Могат да се променят свойства като типа на диаграмата, заглавията на диаграмата и на осите и позицията на диаграмата.

CreatePivotTable

Създава нова обобщена таблица със свойства, определени от подадените към метода аргументи.

За обобщената таблица трябва да бъде зададено име. Ако в листа цел вече има обобщена таблица със същото име, тя ще бъде заместена без предупреждение.

Този метод връща низ, съдържащ диапазона, в който е разположена новата обобщена таблица.

svc.CreatePivotTable(pivottablename: str, sourcerange: str, targetcell: str, datafields: str[0..*], rowfields: str[0..*], columnfields: str[0..*], filterbutton: bool = true, rowtotals: bool = true, columntotals: bool = true): str

pivottablename: дефинираното от потребителя име на новата обобщена таблица.

sourcerange: диапазонът, съдържащ началните данни, като низ. Приема се, че първата колона съдържа имената на полетата, използвани в обобщената таблица.

targetcell: горната лява клетка, от която да бъде разположена новата обобщена таблица. Ако е зададен диапазон, се взема предвид само горната му лява клетка.

datafields: може да бъде единичен низ или масив с низове, които дефинират имената на полетата и функциите, които да бъдат приложени. Когато е зададен масив, той трябва да следва синтаксиса Array("ИмеНаПоле[;Функция]", ...).

Разрешените функции са: Sum, Count, Average, Max, Min, Product, CountNums, StDev, StDevP, Var, VarP и Median. Имената на функциите трябва да бъдат на английски. Когато всички стойности са числови, се подразбира функцията Sum, в противен случай – функцията Count.

rowfields: единичен низ или масив с имената на полета, които да бъдат използвани за редовете на обобщената таблица.

columnfields: единичен низ или масив с имената на полета, които да бъдат използвани за колоните на обобщената таблица.

filterbutton: определя дали над обобщената таблица да се показва бутон за филтриране (подразбира се True).

rowtotals: указва дали към обобщената таблица да се добави отделна колона за суми на редовете (подразбира се True).

columntotals: указва дали към обобщената таблица да се добави отделен ред за суми на колоните (подразбира се True).

    Dim vData As Variant, oDoc As Object, ui As Object, sTable As String, sPivot As String
    Set ui = CreateScriptService("UI")
    Set oDoc = ui.CreateDocument("Calc")
    vData = Array(Array("Стока", "Град", "Екип", "2002", "2003", "2004"), _
        Array("Книги", "Пловдив", "Иван", 14788, 30222, 23490), _
        Array("Бонбони", "Пловдив", "Иван", 26388, 15641, 32849), _
        Array("Химикалки", "Пловдив", "Иван", 16569, 32675, 25396), _
        Array("Книги", "Пловдив", "Петя", 21961, 21242, 29009), _
        Array("Бонбони", "Пловдив", "Петя", 26142, 22407, 32841))
    sTable = oDoc.SetArray("A1", vData)
    sPivot = oDoc.CreatePivotTable("PT1", sTable, "H1", _
        Array("2002", "2003;count", "2004;average"), _ ' Три полета с данни
        "Стока", _ ' Едно поле за редове
        Array("Град", "Екип"), False) ' Две полета за колони
  

    ui = CreateScriptService("UI")
    doc = ui.CreateDocument("Calc")
    vData = [["Стока", "Град", "Екип", "2002", "2003", "2004"],
             ["Книги", "Пловдив", "Иван", 14788, 30222, 23490],
             ["Бонбони", "Пловдив", "Иван", 26388, 15641, 32849],
             ["Химикалки", "Пловдив", "Иван", 16569, 32675, 25396)],
             ["Книги", "Пловдив", "Петя", 21961, 21242, 29009],
             ["Бонбони", "Пловдив", "Петя", 26142, 22407, 32841]]
    sTable = doc.SetArray("A1", vData)
    sPivot = doc.CreatePivotTable("PT1", sTable, "H1",
                                  ["2002", "2003;count", "2004;average"],
                                  "Стока",
                                  ["Град", "Екип"], False)
  

За да научите повече за обобщените таблици в LibreOffice Calc, прочетете помощната страница Обобщени таблици.

DAvg, DCount, DMax, DMin and DSum

Apply the functions Average, Count, Max, Min and Sum, respectively, to all the cells containing numeric values on a given range, excluding values from filtered and hidden rows and hidden columns, the same as for the status bar functions.

svc.DAvg(range: str): float

svc.DCount(range: str): float

svc.DMax(range: str): float

svc.DMin(range: str): float

svc.DSum(range: str): float

range: диапазонът, върху който ще бъде приложена функцията, като низ.

Примерът по-долу прилага функцията Sum върху диапазона "A1:A1000" на текущо избрания лист:

      result = oDoc.DSum("~.A1:A1000")
  

    result = myDoc.DSum("~.A1:A1000")
  

Клетките в зададения диапазон, които съдържат текст, ще бъдат игнорирани от всички тези функции. Например методът DCount няма да брои клетките с текст, а само тези с числа.

ExportRangeToFile

Експортира указания диапазон като изображение или PDF файл.

Този метод връща True, ако файлът местоназначение е създаден успешно.

Скритите редове и колони в зададения диапазон не се експортират във файла местоназначение.

svc.ExportRangeToFile(range: str, filename: str, imagetype: str = "pdf", overwrite: bool = False): bool

range: име на лист или диапазон от клетки, който да бъде експортиран, като низ.

filename: името на файла, който да бъде записан. То трябва да следва нотацията, зададена с SF_FileSystem.FileNaming.

imagetype: определя типа на файла местоназначение. Възможни стойности са "jpeg", "pdf" (подразбира се) и "png".

overwrite: когато е True, файлът местоназначение може да бъде презаписан (подразбира се False).

    ' Експортира целия лист като PDF файл.
    oDoc.ExportRangeToFile("SheetX", "C:\Temp\image.pdf")
    ' Експортира диапазона като PNG файл и презаписва файла местоназначение, ако той съществува.
    oDoc.ExportRangeToFile("SheetX.A1:D10", "C:\Temp\image.png", "png", Overwrite := True)
  

    doc.ExportRangeToFile("SheetX", r"C:\Temp\image.pdf")
    doc.ExportRangeToFile("SheetX.A1:D10", r"C:\Temp\image.png", "png", overwrite = True)
  

Forms

В зависимост от подадените параметри, този метод връща:

• индексиран от нула масив (или кортеж в Python) с имената на всички формуляри, съдържащи се в даден лист (ако отсъства аргументът form)

• екземпляр на услугата SFDocuments.Form, представящ зададения като аргумент формуляр.

svc.Forms(sheetname: str): str[0..*]

svc.Forms(sheetname: str, form: str = ''): svc

svc.Forms(sheetname: str, form: int): svc

sheetname: името на листа, от който ще бъде извлечен формулярът, като низ.

form: името или индексът на формуляр, съхраняван в посочения лист. Ако този аргумент отсъства, методът ще върне списък с имената на всички формуляри, налични в листа.

В следващите примери първият ред получава имената на всички формуляри, съхранявани в "Sheet1", а вторият извлича обекта Form на формуляра с име "Form_A", който се съхранява в "Sheet1".

    Set FormNames = oDoc.Forms("Sheet1")
    Set FormA = oDoc.Forms("Sheet1", "Form_A")
  

    form_names = doc.Forms("Sheet1")
    form_A = doc.Forms("Sheet1", "Form_A")
  

GetColumnName

Преобразува номер на колона между 1 и 1024 в съответните букви (колона A, B, …, AMJ). Ако даденият номер на колона е извън допустимия диапазон, се връща низ с нулева дължина.

svc.GetColumnName(columnnumber: int): str

columnnumber: номерът на колона като целочислена стойност в интервала 1 – 1024.

Показва прозорец за съобщение с името на третата колона, което по подразбиране е "C".

    MsgBox oDoc.GetColumnName(3)
  

    bas = CreateScriptService("Basic")
    bas.MsgBox(myDoc.GetColumnName(3))
  

Максималният брой колони, разрешен в лист на Calc, е 1024.

GetFormula

Получаване на формулата или формулите в дадения диапазон от клетки като единичен низ, едномерен или двумерен масив от низове.

Имената на функциите на Calc във върнатите формули са на английски. Посетете уикистраницата List of Calc Functions за пълен списък с функциите на Calc на английски.

svc.GetFormula(range: str): any

range: диапазонът, от който да бъдат извлечени формулите, като низ.

Следващият пример връща масив с размери 3 на 2 с формулите в диапазона "A1:B3" (3 реда на 2 колони):

    arrFormula = oDoc.GetFormula("~.A1:B3")
  

    arrFormula = myDoc.GetFormula("~.A1:B3")
  

GetValue

Получаване на стойността или стойностите, съхранявани в дадения диапазон, като единична стойност, едномерен масив или двумерен масив. Всички стойности са или числа от тип double, или низове.

svc.GetValue(range: str): any

range: диапазонът, от който да бъдат извлечени стойностите, като низ.

      arrValues = oDoc.GetValue("~.B1:C100")
  

    arrValues = myDoc.GetValue("~.B1:C100")
  

Ако някоя клетка съдържа дата, се връща числото, съответстващо на датата. За преобразуване на числови стойности в дати в скриптове на Basic използвайте вградената функция вградената функция CDate. В скриптове на Python използвайте функцията CDate от услугата Basic.

ImportFromCSVFile

Импортира съдържанието на текстов файл във формат CSV и го разполага върху дадена клетка местоназначение.

Преди да се вмъкне съдържанието на CSV файла, областта местоназначение се изчиства от всякакво съдържание и формати. Размерът на променената област се определя изцяло от съдържанието на входния файл.

Методът връща низ, представящ променения диапазон от клетки.

svc.ImportFromCSVFile(filename: str, destinationcell: str, [filteroptions: str]): str

filename: името на файла, който да бъде отворен. То трябва да следва нотацията, зададена с SF_FileSystem.FileNaming.

destinationcell: клетката местоназначение за вмъкване на импортираните данни, като низ. Ако вместо това е подаден диапазон, се взема предвид само горната му лява клетка.

filteroptions: аргументите за входния филтър за CSV. Подразбираният филтър прави следните предположения:

• Кодирането на входния файл е UTF8.

• Разделителят на полета е запетая, точка и запетая или знак за табулация.

• Разделителят за низове е двойна кавичка (").

• Включват се всички редове.

• Низовете в кавички се форматират като текст.

• Разпознават се специални числа.

• Всички колони се приемат за текстови, освен ако се разпознаят като валидни числа.

• Езикът е английски/САЩ, което означава десетичен разделител "." и разделител на хилядите ",".

    oDoc.ImportFromCSVFile("C:\Temp\myCSVFile.csv", "SheetY.C5")
  

    myDoc.ImportFromCSVFile(r"C:\Temp\myCSVFile.csv", "SheetY.C5")
  

За да научите повече за настройките на филтъра за CSV, вижте помощната страница „Настройки на филтъра за CSV“.

ImportFromDatabase

Импортира от база от данни съдържанието на таблица, заявка или резултатен набор, т.е. резултат от команда SELECT на SQL, и го вмъква върху клетка местоназначение.

Преди да се вмъкне импортираното съдържание, областта местоназначение се изчиства от всякакво съдържание и формати. Размерът на променената област се определя изцяло от съдържанието на таблицата или заявката.

Методът връща True, когато импортирането е успешно.

svc.ImportFromDatabase(filename: str = "", registrationname: str = "", destinationcell: str = "", sqlcommand: str = "", directsql: bool): bool

filename: името на файла, който да бъде отворен. То трябва да следва нотацията, зададена с SF_FileSystem.FileNaming.

registrationname: името, чрез което базата от данни да бъде намерена в регистъра на бази от данни. Този аргумент се игнорира, ако е подаден filename.

destinationcell: местоназначението на импортираните данни като низ. Ако е подаден диапазон, се взема предвид само горната му лява клетка.

sqlcommand: име на таблица или заявка (без ограждащи кавички или квадратни скоби) или оператор SELECT на SQL, в който имената на таблици и полета може да са оградени с квадратни скоби или кавички за по-добра четливост.

directsql: когато е True, командата на SQL се изпраща към СУБД без предварителен анализ. Подразбира се False. Аргументът се игнорира за таблици. За заявки прилаганата настройка е тази, която е била зададена при създаване на заявката.

    oDoc.ImportFromDatabase("C:\Temp\myDbFile.odb", , "SheetY.C5", "SELECT * FROM [Employees] ORDER BY [LastName]")
  

    myDoc.ImportFromDatabase(r"C:\Temp\myDbFile.odb", , "SheetY.C5", "SELECT * FROM [Employees] ORDER BY [LastName]")
  

InsertSheet

Вмъква нов празен лист преди съществуващ лист или в края на списъка с листове.

svc.InsertSheet(sheetname: str, [beforesheet: any]): bool

sheetname: името на новия лист.

beforesheet: името (низ) или индексът (число, броено от 1) на листа, преди който да бъде вмъкнат новият лист. Този аргумент е незадължителен и подразбираното поведение е листът да се вмъкне на последна позиция.

Следният пример вмъква нов празен лист с име "SheetX" преди "SheetY":

    oDoc.InsertSheet("SheetX", "SheetY")
  

    myDoc.InsertSheet("SheetX", "SheetY")
  

MoveRange

Премества указан диапазон източник към диапазон местоназначение. Методът връща низ, представящ променения диапазон от клетки. Размерите на променената област се определят изцяло от размера на областта източник.

svc.MoveRange(source: str, destination: str): str

source: диапазонът от клетки – източник, като низ.

destination: клетката местоназначение, като низ. Ако е подаден диапазон, за местоназначение се взема горната му лява клетка.

    oDoc.MoveRange("SheetX.A1:F10", "SheetY.C5")
  

    myDoc.MoveRange("SheetX.A1:F10", "SheetY.C5")
  

MoveSheet

Премества съществуващ лист и го поставя преди указан лист или в края на списъка с листове.

svc.MoveSheet(sheetname: str, [beforesheet: any]): bool

sheetname: името на листа, който да бъде преместен. Листът трябва да съществува, иначе възниква изключение.

beforesheet: името (низ) или индексът (число, броено от 1) на листа, преди който да бъде поставен оригиналният лист. Този аргумент е незадължителен и подразбираното поведение е листът да се премести на последна позиция.

Примерът по-долу премества съществуващия лист "SheetX" и го поставя преди "SheetY":

    oDoc.MoveSheet("SheetX", "SheetY")
  

    myDoc.MoveSheet("SheetX", "SheetY")
  

Offset

Връща нов диапазон (като низ), отместен с определен брой редове и колони от даден диапазон.

Този метод се държи по същия начин като едноименната функция Offset на Calc.

svc.Offset(reference: str, rows: int = 0, columns: int = 0, [height: int], [width: int]): str

reference: диапазонът, като низ, който методът ще използва като отправна точка за операцията отместване.

rows: броят колони, с които началният диапазон да бъде отместен нагоре (отрицателна стойност) или надолу (положителна стойност). Използвайте 0 (подразбира се), за да го оставите на същия ред.

columns: броят колони, с които началният диапазон да бъде отместен наляво (отрицателна стойност) или надясно (положителна стойност). Използвайте 0 (подразбира се), за да го оставите на същата колона.

height: височината на областта, която започва от новата позиция на диапазона. Пропуснете този аргумент, ако не е необходимо преоразмеряване по вертикала.

width: ширината на областта, която започва от новата позиция на диапазона. Пропуснете този аргумент, ако не е необходимо преоразмеряване по хоризонтала.

Аргументите rows и columns не трябва да водят до нулев или отрицателен начален ред или колона.

Аргументите height и width не трябва да водят до нулев или отрицателен брой редове или колони.

    oDoc.Offset("A1", 2, 2)
    'SheetX.$C$3 (A1, преместена с два реда надолу и две колони надясно)
    oDoc.Offset("A1", 2, 2, 5, 6)
    'SheetX.$C$3:$H$7 (A1, преместена с два реда и две колони и с размери 5 реда и 6 колони)
  

    myDoc.Offset("A1", 2, 2)
    myDoc.Offset("A1", 2, 2, 5, 6)
  

OpenRangeSelector

Отваря немодален диалог за избиране на диапазон в документа и връща низ, съдържащ избрания диапазон.

Този метод отваря същия диалог, който се използва от LibreOffice при натискане на бутона „Свиване“. Например в диалога Инструменти - Удовлетворяване на условие има бутон „Свиване“ вдясно от полето Клетка с формула.

Този метод не променя текущата селекция.

svc.OpenRangeSelector(opt title: str, opt selection: str, singlecell: bool = False, closeafterselect: bool = True): str

title: заглавието на диалога като низ.

selection: незадължителен диапазон, който е избран отначало при показване на диалога.

singlecell: когато е True (подразбира се), може да се избира само единична клетка. Когато е False, е разрешено избирането на диапазон.

closeafterselect: ако е True (подразбира се), диалогът се затваря незабавно след като е направен избор. Ако е False, потребителят може да промени селекцията колкото пъти е необходимо и после ръчно да затвори диалога.

    Dim sRange as String
    sRange = oDoc.OpenRangeSelector(Title := "Select a range")
  

    sRange = myDoc.OpenRangeSelector(title = "Select a range")
  

Printf

Връща входния низ, след като замести знаците маркери в него със стойностите им в даден диапазон.

Този метод не променя текущата селекция.

Можете да използвате този метод, за да извлечете бързо определени части от име на диапазон, например името на листа или първата колона и ред, и да съставите от тях нов адрес на диапазон.

svc.Printf(inputstr: str, range: str, tokencharacter: str = "%"): str

inputstr: низът с маркерите, които ще бъдат заменени със съответните стойности в range.

range: име на диапазон (RangeName), от който да бъдат извлечени стойностите. Ако то съдържа име на лист, листът трябва да съществува.

tokencharacter: знак, използван за означаване на маркерите. По подразбиране знакът за маркер е "%". Приемат се следните маркери:

• %S – името на листа, съдържащ диапазона, включително единични кавички, когато са необходими.

• %R1 – номерът на реда на горната лява клетка от диапазона.

• %C1 – буквата на колоната на горната лява клетка от диапазона.

• %R2 – номерът на реда на долната дясна клетка от диапазона.

• %C2 – буквата на колоната на долната дясна клетка от диапазона.

Примерът по-долу извлича всички елементи от RangeName, дефиниран в sRange, и ги използва за съставяне на съобщение.

    Dim sRange as String, sInputStr as String
    sRange = "Sheet1.A1:E10"
    sInputStr = "Sheet name: %S" & Chr(10) & _
                "First row: %R1" & Chr(10) & _
                "First column %C1" & Chr(10) & _
                "Last row %R2" & Chr(10) & _
                "Last column %C2"
    MsgBox oDoc.Printf(sInputStr, sRange)
  

Методът Printf може да бъде комбиниран със SetFormula, за да се зададат формули в множество клетки. Да вземем например таблица с числови стойности в диапазона "A1:E10", от която трябва да се създадат формули, сумиращи стойностите от всеки ред, и резултатите да се разположат в диапазона "F1:F10":

    Dim sFormula as String, sRange as String
    sRange = "A1:E10"
    ' Обърнете внимание на употребата на знака "$".
    sFormula = "=SUM($%C1%R1:$%C2%R1)"
    oDoc.SetFormula("F1:F10", oDoc.Printf(sFormula, sRange))
  

    sRange = "Sheet1.A1:E10"
    sInputStr = "Sheet name: %S\n" \
                "First row: %R1\n" \
                "First column %C1\n" \
                "Last row %R2\n" \
                "Last column %C2"
    bas = CreateScriptService("Basic")
    bas.MsgBox(myDoc.Printf(sInputStr, sRange))
  

    sRange = "A1:E10
    sFormula = "=SUM($%C1%R1:$%C2%R1)"
    myDoc.SetFormula("F1:F10", myDoc.Printf(sFormula, sRange))
  

PrintOut

Този метод изпраща съдържанието на дадения лист към подразбирания принтер или към принтера, зададен чрез метода SetPrinter на услугата Document.

Връща True, ако листът е бил успешно отпечатан.

svc.PrintOut(opt sheetname: str, pages: str = "", copies: num = 1): bool

sheetname: листът, който да се отпечата, подразбира се активният лист.

pages страниците, които да бъдат отпечатани, като низ, както в потребителския интерфейс. Пример: "1-4;10;15-18". Подразбират се всички страници.

copies: броят копия. Подразбира се 1.

    If oDoc.PrintOut("SheetX", "1-4;10;15-18", Copies := 2) Then
        ' ...
    End If
  

    if doc.PrintOut('SheetX', copies=3, pages='45-88'):
        # ...
  

RemoveDuplicates

Removes duplicate rows from a specified range. The comparison to determine if a given row is a duplicate is done based on a subset of columns in the range.

This method returns a string containing the resulting range.

The removal of duplicate rows is done starting at the first row in the range moving downwards, meaning that if two or more rows are duplicates then only the first one is kept.

svc.RemoveDuplicates(range: str, opt columns: int[0..*], header: bool = False, casesensitive: bool = False, mode: str = "COMPACT"): str

range: The range from which duplicates will be removed, as a string.

columns: An array containing column numbers indicating which columns will be considered to determine if a row is a duplicate or not. If this argument is left blank, then only the first column is used. Items in this array must be in the interval between 1 and the range width.

header: Specifies whether the first row is a header row (Default = False).

casesensitive: Specifies whether string comparisons are case-sensitive (Default = False).

mode: Specifies what to do with duplicate rows. If mode = "CLEAR" then duplicates are simply removed from the sheet leaving the cells blank. If mode = "COMPACT" then duplicates are removed and empty rows are compacted up (Default = "COMPACT").

    ' Removes duplicate rows where values in column A are duplicate
    ' Note that all optional arguments use their default value
    oDoc.RemoveDuplicates("A1:B10")
    ' Removes duplicate rows considering that the first row contains headers
    ' Columns A and B are used to determine if a row is a duplicate
    ' Cells containing duplicate values are left blank
    oDoc.RemoveDuplicates("A1:D10", columns := Array(1, 2), header := True, mode := "CLEAR")
  

    myDoc.RemoveDuplicates("A1:B10")
    myDoc.RemoveDuplicates("A1:D10", columns = (1, 2), header = True, mode = "CLEAR")
  

RemoveSheet

Премахва съществуващ лист от документа.

svc.RemoveSheet(sheetname: str): bool

sheetname: името на листа за премахване.

    oDoc.RemoveSheet("SheetY")
  

    myDoc.RemoveSheet("SheetY")
  

RenameSheet

Преименува дадения лист и връща True при успех.

svc.RenameSheet(sheetname: str, newname: str): bool

sheetname: името на листа, който да се преименува.

newname: новото име на листа. То не трябва да е вече съществуващо.

Този пример преименува активния лист на "SheetY":

    oDoc.RenameSheet("~", "SheetY")
  

    mydoc.RenameSheet("~", "SheetY")
  

SetArray

Съхранява дадената стойност, започвайки от указана целева клетка. Променената област започва от целевата клетка или горния ляв ъгъл на подадения диапазон и се простира до размера на входния аргумент value. Векторите винаги се разполагат вертикално.

Методът връща низ, представящ променената област като диапазон от клетки.

svc.SetArray(targetcell: str, value: any): str

targetcell: клетката или диапазонът, където да е началото на съхранената стойност, като низ.

value: скалар, вектор или масив (в Python – едно- или двумерни списъци и кортежи) с новите стойности, които да се съхранят, започвайки от целевата клетка или от горния ляв ъгъл на диапазона, ако targetcell е диапазон. Новите стойности трябва да са низове, числа или дати. Други типове ще предизвикат изпразването на съответните клетки.

В следващия пример с вградената функция DimArray се създава масив, който после се съхранява върху клетката "A1":

    Dim arrData as Variant
    arrData = DimArray(2, 1)
    arrData(0, 0) = 1 : arrData(1, 0) = 2 : arrData(2, 0) = 3
    arrData(0, 1) = "One" : arrData(1, 1) = "Two" : arrData(2, 1) = "Three"
    oDoc.SetArray("Sheet1.A1", arrData)
  

В този пример с метода RangeInit на услугата ScriptForge се създава масив със стойности, който после се съхранява от клетката "A1" надолу.

    'Запълваме първата колона със стойности от 1 до 1000.
    oDoc.SetArray("Sheet1.A1", SF_Array.RangeInit(1, 1000))
  

    arrData = ((1, "One"), (2, "Two"), (3, "Three"))
    myDoc.SetArray("Sheet1.A1", arrData)
  

    myDoc.SetArray("Sheet1.A1", tuple(i + 1 for i in range(1000)))
  

За да разтоварите пълното съдържание на масив в лист, използвайте SetArray. За да разтоварите съдържанието на масив само в рамките на целевия диапазон от клетки, използвайте SetValue.

SetCellStyle

Прилага указания стил за клетки върху дадения целеви диапазон. Променя се целият диапазон, а останалата част от листа остава незасегната. Ако стилът за клетки не съществува, възниква грешка.

Методът връща низ, представящ променената област като диапазон от клетки.

svc.SetCellStyle(targetrange: str, style: str, opt filterformula: str, opt filterscope: str): str

targetrange: диапазонът, върху който ще бъде приложен стилът, като низ.

style: името на стила за клетки, който да бъде приложен.

    oDoc.SetCellStyle("A1:J1", "Heading 1")
    oDoc.SetCellStyle("A2:J100", "Neutral")
  

    myDoc.SetCellStyle("A1:J1", "Heading 1")
    myDoc.SetCellStyle("A2:J100", "Neutral")
  

Refer to the ClearAll method documentation for examples on how to use the arguments filterformula and filterscope.

SetFormula

Вмъква дадената формула или масив от формули в указания диапазон. Размерът на променената област е равен на размера на диапазона.

Методът връща низ, представящ променената област като диапазон от клетки.

svc.SetFormula(targetrange: str, formula: any): str

targetrange: диапазонът, в който да бъдат вмъкнати формулите, като низ.

formula: низ, вектор или масив от низове с новите формули за всички клетки от целевия диапазон.

Цялата област се обновява, а останалата част от листа остава непроменена.

Ако дадената формула е низ, уникалната формула се поставя из целия диапазон с коригиране на относителните обръщения.

Ако размерът на formula е по-малък от този на targetrange, оставащите клетки се изпразват.

Ако размерът на formula е по-голям от този на targetrange, формулите се копират само частично, докато се запълни размерът на targetrange.

Векторите винаги се разполагат вертикално, освен ако targetrange има височина от точно 1 ред.

Функциите на Calc, използвани в аргумента formula, трябва да са изразени с английските си имена. Посетете уикистраницата List of Calc Functions за пълен списък с функциите на Calc на английски.

    oDoc.SetFormula("A1", "=A2")
    'Хоризонтален вектор, частично празен
    oDoc.SetFormula("A1:F1", Array("=A2", "=B2", "=C2+10"))
    'D2 съдържа формулата "=H2".
    oDoc.SetFormula("A1:D2", "=E1")
  

    myDoc.SetFormula("A1", "=A2")
    myDoc.SetFormula("A1:F1", ("=A2", "=B2", "=C2+10"))
    myDoc.SetFormula("A1:D2", "=E1")
  

SetValue

Съхранява дадената стойност в указания диапазон. Размерът на променената област е равен на размера на целевия диапазон.

Методът връща низ, представящ променената област като диапазон от клетки.

svc.SetValue(targetrange: str, value: any): str

targetrange: диапазонът, в който да бъде съхранена дадената стойност, като низ.

value: скалар, вектор или масив с новите стойности за всички клетки на диапазона. Новите стойности трябва да са низове, числа или дати. Други типове ще предизвикат изпразването на съответните клетки.

Целият диапазон се обновява, а останалата част от листа остава непроменена. Ако размерът на value е по-малък от този на targetrange, оставащите клетки се изпразват.

Ако размерът на value е по-голям от този на targetrange, value се копира само частично, докато се запълни размерът на targetrange.

Векторите се разполагат вертикално, освен ако targetrange има височина от точно 1 ред.

    oDoc.SetValue("A1", 2)
    'По-долу масивът Value е по-малък от TargetRange (оставащите клетки се изпразват).
    oDoc.SetValue("A1:F1", Array(1, 2, 3))
    'По-долу Value и TargetRange имат еднакъв размер.
    oDoc.SetValue("A1:D2", SF_Array.AppendRow(Array(1, 2, 3, 4), Array(5, 6, 7, 8)))
  

Ако искате да запълните единичен ред със стойности, можете да използвате функцията Offset. В долния пример приемаме, че arrData е едномерен масив:

    Dim firstCell As String : firstCell = "A1"
    Dim lenArray As Integer : lenArray = UBound(arrData) - LBound(arrData) + 1
    Dim newRange As String : newRange = oDoc.Offset(firstCell, width = lenArray)
    oDoc.SetValue(newRange, arrData)
  

    myDoc.SetValue("A1", 2)
    myDoc.SetValue("A1:F1", (1, 2, 3))
    myDoc.SetValue("A1:D2", ((1, 2, 3, 4), (5, 6, 7, 8)))
  

    firstCell = "A1"
    newRange = doc.Offset(firstCell, width = len(arrData))
    doc.SetValue(newRange, arrData)
  

ShiftDown

Премества даден диапазон от клетки надолу, като вмъква празни редове. Текущата селекция остава непроменена.

В зависимост от стойността на аргумента wholerow вмъкнатите редове могат да се простират или до ширината на указания диапазон, или през всички колони.

Този метод връща низ, представящ новото местоположение на началния диапазон.

Ако изместеният диапазон пресича границите на листа, не се случва нищо.

svc.ShiftDown(range: str, wholerow: bool = False, opt rows: int): str

range: диапазонът, над който ще бъдат вмъкнати редове, като низ.

wholerow: ако е False (подразбира се), ширината на вмъкнатите редове ще бъде същата като на указания диапазон range. В противен случай вмъкнатите редове ще се простират през всички колони в листа.

rows: броят редове, които да бъдат вмъкнати. Подразбираната стойност е височината на оригиналния диапазон range. Броят редове трябва да е положително число.

    ' Премества диапазона "A3:D3" с един ред надолу; засяга само колоните от A до D.
    oDoc.ShiftDown("A3:D3")
    ' Вмъкнатият ред се простира през всички колони в листа.
    oDoc.ShiftDown("A3:D3", WholeRow := True)
    ' Премества диапазона "A3:D3" надолу с пет реда.
    oDoc.ShiftDown("A3:D3", Rows := 5)
    ' Премества диапазона "A3:D10" надолу с два реда и показва новото местоположение на оригиналния диапазон.
    Dim sNewRange as String
    sNewRange = oDoc.ShiftDown("A3:D10", Rows := 2)
    MsgBox sNewRange   ' $Sheet1.$A$5:$D$12
  

    myDoc.ShiftDown("A3:D3")
    myDoc.ShiftDown("A3:D3", wholerow = True)
    myDoc.ShiftDown("A3:D3", rows = 5)
    sNewRange = myDoc.ShiftDown("A3:D10", rows = 2)
    bas = CreateScriptService("Basic")
    bas.MsgBox(sNewRange)
  

ShiftLeft

Изтрива най-левите колони от даден диапазон и премества наляво всички клетки вдясно от засегнатите. Текущата селекция остава непроменена.

В зависимост от стойността на аргумента wholecolumn изтритите колони могат да се простират или до височината на указания диапазон, или през всички редове.

Този метод връща низ низ, представящ местоположението на оставащата част от началния диапазон. Ако са изтрити всички клетки от оригиналния диапазон, се връща празен низ.

svc.ShiftLeft(range: str, wholecolumn: bool = False, opt columns: int): str

range: диапазонът, от който ще бъдат изтрити клетки, като низ.

wholecolumn: ако е False (подразбира се), височината на изтритите колони ще бъде същата като на указания диапазон range. В противен случай изтритите колони ще се простират през всички редове в листа.

columns: броят колони, които да бъдат изтрити от указания диапазон range. Подразбира се ширината на оригиналния диапазон range, която е и максималната стойност на този аргумент.

    ' Изтрива диапазона "B3:B6"; премества наляво всички клетки отдясно.
    oDoc.ShiftLeft("B3:B6")
    ' Изтрива първата колона в диапазона "A3:D6".
    oDoc.ShiftLeft("A3:D6", Columns := 1)
    ' Изтритите колони (от A до D) се простират през всички редове в листа.
    oDoc.ShiftLeft("A3:D6", WholeColumn := True)
  

    myDoc.ShiftLeft("B3:B6")
    myDoc.ShiftLeft("A3:D6", Columns = 1)
    myDoc.ShiftLeft("A3:D6", WholeColumn = True)
  

ShiftUp

Изтрива най-горните редове от даден диапазон и премества нагоре всички клетки под засегнатите. Текущата селекция остава непроменена.

В зависимост от стойността на аргумента wholerow изтритите редове могат да се простират или до ширината на указания диапазон, или през всички колони.

Този метод връща низ низ, представящ местоположението на оставащата част от началния диапазон. Ако са изтрити всички клетки от оригиналния диапазон, се връща празен низ.

svc.ShiftUp(range: str, wholerow: bool = False, opt rows: int): str

range: диапазонът, от който ще бъдат изтрити клетки, като низ.

wholerow: ако е False (подразбира се), ширината на изтритите редове ще бъде същата като на указания диапазон range. В противен случай изтритите редове ще се простират през всички колони в листа.

rows: броят редове, които да бъдат изтрити от указания диапазон range. Подразбира се височината на оригиналния диапазон range, която е и максималната стойност на този аргумент.

    ' Изтрива диапазона "A3:D3"; премества всички клетки под него с един ред нагоре.
    oDoc.ShiftUp("A3:D3")
    ' Изтрива първия ред в диапазона "A3:D6".
    oDoc.ShiftUp("A3:D6", Rows := 1)
    ' Изтритите редове се простират през всички колони в листа.
    oDoc.ShiftUp("A3:D6", WholeRow := True)
  

    myDoc.ShiftUp("A3:D3")
    myDoc.ShiftUp("A3:D6", rows = 1)
    myDoc.ShiftUp("A3:D6", wholerow = True)
  

ShiftRight

Премества даден диапазон от клетки надясно, като вмъква празни колони. Текущата селекция остава непроменена.

В зависимост от стойността на аргумента wholecolumn вмъкнатите колони могат да се простират или до височината на указания диапазон, или през всички редове.

Този метод връща низ, представящ новото местоположение на началния диапазон.

Ако изместеният диапазон пресича границите на листа, не се случва нищо.

svc.ShiftRight(range: str, wholecolumn: bool = False, opt columns: int): str

range: диапазонът, вляво от който ще се вмъкват празни колони, като низ.

wholecolumn: ако е False (подразбира се), височината на вмъкнатите колони ще бъде същата като на указания диапазон range. В противен случай вмъкнатите колони ще се простират през всички редове в листа.

columns: броят колони, които да бъдат вмъкнати. Подразбираната стойност е ширината на оригиналния диапазон range.

    ' Премества диапазона "A3:A6" надясно с една колона; засяга само редовете 3 – 6.
    oDoc.ShiftRight("A3:A6")
    ' Премества диапазона "A3:A6" надясно с пет колони.
    oDoc.ShiftRight("A3:A6", Columns := 5)
    ' Вмъкнатата колона се простира през всички редове в листа.
    oDoc.ShiftRight("A3:A6", WholeColumn := True)
  

    myDoc.ShiftRight("A3:A6")
    myDoc.ShiftRight("A3:A6", columns = 5)
    myDoc.ShiftRight("A3:A6", wholecolumn = True)
  

SortRange

Sort the given range on any number of columns/rows. The sorting order may vary by column/row. If the number of sort keys is > 3 then the range is sorted several times, by groups of 3 keys, starting from the last key. It returns a string representing the modified range of cells. The size of the modified area is fully determined by the size of the source area.

svc.SortRange(range: str, sortkeys: any, sortorder: any = "ASC", destinationcell: str = "", containsheader: bool = False, casesensitive: bool = False, sortcolumns: bool = False): str

range: диапазонът, който да бъде сортиран, като низ.

sortkeys: A scalar (if 1 column/row) or an array of column/row numbers starting from 1.

sortorder: A scalar or an array of strings containing the values "ASC" (ascending), "DESC" (descending). Each item is paired with the corresponding item in sortkeys. If the sortorder array is shorter than sortkeys, the remaining keys are sorted in ascending order.

destinationcell: клетката местоназначение за сортирания диапазон от клетки, като низ. Ако е подаден диапазон, се взема предвид само горната му лява клетка. По подразбиране се презаписва диапазонът източник.

containsheader: когато е True, първият ред/колона не се сортира.

casesensitive: само за сравняване на низове. Подразбира се False.

sortcolumns: когато е True, колоните се сортират от ляво надясно. Подразбира се False: редовете се сортират от горе надолу.

    'Сортираме диапазона по колоните A (възходящ ред) и C (низходящ ред).
    oDoc.SortRange("A2:J200", Array(1, 3), Array("ASC", "DESC"), CaseSensitive := True)
  

    myDoc.SortRange("A2:J200", (1, 3), ("ASC", "DESC"), casesensitive = True)
  

В ScriptForge всички подпрограми или идентификатори на Basic с префикс „_“ са запазени за вътрешна употреба. Те не са предназначени за използване в макроси на Basic.