Usługa SFDocuments.Document

Biblioteka SFDocuments udostępnia metody i właściwości ułatwiające zarządzanie dokumentami LibreOffice i manipulowanie nimi.

Metody mające zastosowanie do wszystkich typów dokumentów (dokumenty tekstowe, arkusze, prezentacje itp.) udostępnia usługa SFDocuments.Document. Oto kilka przykładów:

warning

Właściwości, metody lub argumenty oznaczone (*) NIE mają zastosowania do dokumentów Base.


Metody i właściwości specyficzne dla niektórych komponentów LibreOffice są przechowywane w oddzielnych usługach, takich jak SFDocuments.SF_Calc i SFDocuments.SF_Base.

Chociaż język Basic nie oferuje dziedziczenia pomiędzy klasami obiektów, te ostatnie usługi można uznać za podklasy usługi SFDocuments.Document. Takie podklasy mogą odwoływać się do właściwości i metod opisanych poniżej.

Wywoływanie usługi

Przed użyciem usługi Document należy załadować lub zaimportować bibliotekę ScriptForge:

note

• Podstawowe makra wymagają załadowania biblioteki ScriptForge przy użyciu następującej instrukcji:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Skrypty Pythona wymagają importu z modułu scriptforge:
from scriptforge import CreateScriptService


Poniżej znajdują się trzy warianty wywołania usługi Document.

W języku Basic

Używając metody getDocument z usługi ScriptForge.UI:


    Dim ui As Object, oDoc As Object
    Set ui = CreateScriptService("UI")
    Set oDoc = ui.GetDocument("Untitled 1")
  

Alternatywnie możesz użyć metod CreateDocument i OpenDocument z usługi UI.


    Set oDocA = ui.CreateDocument("Calc")
    Set oDocB = ui.OpenDocument("C:\Documents\MyFile.odt")
  

Używanie nazwy okna, jeśli dokument jest już otwarty.


    Dim oDoc As Object
    Set oDoc = CreateScriptService("SFDocuments.Document", "Untitled 1") 'Default = ActiveWindow
  

Korzystanie z dokumentu, do którego odwołuje się ThisComponent. Jest to szczególnie przydatne podczas uruchamiania makra z poziomu IDE Basic.


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

Z makra wywołanego zdarzeniem w dokumencie.


    Sub RunEvent(ByRef poEvent As Object)
        Dim oDoc As Object
        Set oDoc = CreateScriptService("SFDocuments.DocumentEvent", poEvent)
        ' (...)
    End Sub
  
note

Usługa Document jest ściśle powiązana z usługami UI i FileSystem.


Za wyjątkiem sytuacji, gdy dokument został zamknięty przez program metodą CloseDocument (jest to wówczas zbędne), zaleca się po wykorzystaniu zwolnić zasoby:


    Set oDoc = oDoc.Dispose()
  
W języku Python

    from scriptforge import CreateScriptService
    ui = CreateScriptService("UI")
    doc = ui.GetDocument("Untitled 1")
    # (...)
    doc.Dispose()
  

    docA = ui.CreateDocument("Calc")
    docB = ui.OpenDocument("C:\Documents\MyFile.odt")
  

    doc = CreateScriptService("SFDocuments.Document", "Untitled 1")
  

    bas = CreateScriptService("Basic")
    doc = CreateScriptService("Document", bas.ThisComponent)
  

    def RunEvent(event)
        doc = CreateScriptService("SFDocuments.DocumentEvent", Event)
        # (...)
  
tip

Użycie prefiksu "SFDocuments." podczas wywoływania usługi jest opcjonalne.


Właściwości

Nazwa

Tylko do odczytu

Typ

Opis

CustomProperties (*)

Nie

Dictionary service

Zwraca instancję obiektu ScriptForge.Dictionary. Po aktualizacji można go ponownie przekazać do właściwości w celu aktualizacji dokumentu.
Poszczególnymi elementami słownika mogą być ciągi znaków, liczby, daty (Basic) lub elementy com.sun.star.util.Duration.

Description (*)

Nie

String

Daje dostęp do właściwości Description dokumentu (znanej również jako „Komentarze”)

DocumentProperties (*)

Tak

Dictionary service

Zwraca obiekt ScriptForge.Dictionary zawierający wszystkie wpisy. Uwzględniono statystyki dokumentów. Należy pamiętać, że są one specyficzne dla typu dokumentu. Na przykład dokument programu Calc zawiera wpis „CellCount”. Inne dokumenty tego nie robią.

DocumentType

Tak

String

Wartość ciągu z typem dokumentu ("Base", "Calc", "Writer", etc)

ExportFilters

Tak

String array

Zwraca listę z nazwami filtrów eksportu mającymi zastosowanie do bieżącego dokumentu jako tablicę ciągów znaków liczoną od zera. Zwracane są również filtry używane do importu/eksportu.

ImportFilters

Tak

String array

Zwraca listę z nazwami filtrów importu mającymi zastosowanie do bieżącego dokumentu jako tablicę ciągów znaków liczoną od zera. Zwracane są również filtry używane do importu/eksportu.

IsBase
IsCalc
IsDraw
IsImpress
IsMath
IsWriter

Tak

Boolean

Dokładnie jedna z tych właściwości jest True dla danego dokumentu.

Keywords (*)

Nie

String

Daje dostęp do właściwości Keywords dokumentu. Przedstawiana jako lista słów kluczowych rozdzielonych przecinkami

Readonly (*)

Tak

Boolean

True, jeśli dokument faktycznie jest w trybie tylko do odczytu

Subject (*)

Nie

String

Daje dostęp do właściwości Subject dokumentu.

Title (*)

Nie

String

Daje dostęp do właściwości Title dokumentu.

XComponent

Tak

Obiekt UNO

Obiekt UNO com.sun.star.lang.XComponent lub com.sun.star.comp.dba.ODatabaseDocument reprezentujący dokument


Przykład:

W języku Basic

Poniższy przykład drukuje wszystkie właściwości dokumentu. Należy pamiętać, że obiekt oDoc zwrócony przez metodę UI.OpenDocument jest obiektem SFDocuments.Document.


    Dim ui as Variant : Set ui = CreateScriptService("UI")
    Dim oDoc as Object
    Set oDoc = ui.OpenDocument("C:\Documents\MyFile.ods")
    Dim propDict as Object
    Set propDict = oDoc.DocumentProperties
    Dim keys as Variant : propKeys = propDict.Keys
    Dim k as String, strProp as String
    For Each k In propKeys
        strProp = strProp & k & ": " & propDict.Item(k) & CHR$(10)
    Next k
    MsgBox strProp
    oDoc.CloseDocument()
  
W języku Python

Aby uzyskać dostęp do właściwości dokumentu w skrypcie Pythona, użytkownik musi uzyskać do nich bezpośredni dostęp, używając ich nazw, jak pokazano poniżej:


    doc = ui.GetDocument(r"C:\Documents\MyFile.ods")
    msg = doc.Title + '\n' + doc.Description + '\n' + doc.Keywords
    bas = CreateScriptService("Basic")
    bas.MsgBox(msg)
    doc.CloseDocument()
  

Lista metod w usłudze Document

Activate
CloseDocument
CreateMenu
ExportAsPDF

PrintOut
RemoveMenu
RunCommand
Save

SaveAs
SaveCopyAs
SetPrinter


Activate

Zwraca True, jeśli dokument mógł zostać aktywowany. W przeciwnym razie nie nastąpi żadna zmiana w rzeczywistym interfejsie użytkownika. Jest to odpowiednik metody Activate usługi UI.

Ta metoda jest przydatna, gdy trzeba ustawić fokus na dokumencie, który jest zminimalizowany lub ukryty.

Składnia:

svc.Activate(): bool

Przykład:

Poniższy przykład uwzględnia, że plik „My_File.ods” jest już otwarty, ale nieaktywny.

W języku Basic

    Dim oDoc As Object
    Set oDoc = CreateScriptService("Document", "MyFile.ods")
    oDoc.Activate()
  
W języku Python

    doc = CreateScriptService("Document", "MyFile.ods")
    doc.Activate()
  
tip

Pamiętaj, że możesz wywołać usługę Document, przekazując do CreateScriptService „Document” lub „SFDocuments.Document”


CloseDocument

Zamyka dokument. Jeśli dokument jest już zamknięty, niezależnie od sposobu zamknięcia, ta metoda nie ma żadnego efektu i zwraca wartość False.

Metoda zwróci również False, jeśli użytkownik odmówi jego zamknięcia.

Zwraca wartość True, jeśli dokument został pomyślnie zamknięty.

Składnia:

svc.CloseDocument(saveask: bool = True): bool

Parametry:

saveask: jeśli True (domyślnie), użytkownik jest proszony o potwierdzenie, czy zmiany powinny zostać zapisane na dysku. Argument ten jest ignorowany, jeśli dokument nie został zmodyfikowany.

Przykład:

W języku Basic

    If oDoc.CloseDocument(True) Then
        ' ...
    End If
  
W języku Python

    if doc.CloseDocument(True):
        # ...
  

CreateMenu

Tworzy nową pozycję menu na pasku menu danego okna dokumentu.

Ta metoda zwraca instancję usługi SFWidgets.Menu.

note

Utworzone menu jest dostępne tylko podczas bieżącej sesji LibreOffice i nie jest zapisywane ani w dokumencie, ani w globalnych ustawieniach aplikacji. Dlatego zamknięcie okna dokumentu spowoduje zniknięcie menu. Pojawi się ponownie dopiero, gdy makro tworzące menu zostanie ponownie wykonane.


Składnia:

svc.CreateMenu(menuheader: str, [before: any], submenuchar: str = ">"): svc

Parametry:

menuheader: nazwa najwyższego poziomu nowego menu.

before: nazwa (jako ciąg znaków) lub pozycja (jako liczba całkowita rozpoczynająca się od 1) istniejącego menu, przed którym zostanie umieszczone nowe menu. Jeżeli dla tego argumentu nie zostanie zdefiniowana żadna wartość, menu zostanie utworzone na ostatniej pozycji paska menu.

submenuchar: separator używany do tworzenia drzew menu podczas wywoływania metod jako AddItem z usługi Menu. Wartość domyślna to „>”.

Przykład:

W języku Basic

    Dim oDoc as Object, oMenu as Object
    Set oDoc = CreateScriptService("Document")
    Set oMenu = oDoc.CreateMenu("Moje menu")
    With oMenu
        ' Dodaj pozycje do menu
        .AddItem("Item A")
        .AddItem("Item B")
        ' ...
        ' Po utworzeniu menu można zwolnić instancję usługi
        .Dispose()
    End With
  
W języku Python

    doc = CreateScriptService("Document")
    menu = doc.CreateMenu("Moje menu")
    menu.AddItem("Item A")
    menu.AddItem("Item B")
    # ...
    menu.Dispose()
  
tip

Odwiedź stronę pomocy SFWidgets.Menu, aby dowiedzieć się więcej o tworzeniu/usuwaniu menu w oknach dokumentów LibreOffice.


ExportAsPDF

Eksportuje dokument bezpośrednio jako plik PDF do określonej lokalizacji. Zwraca True, jeśli plik PDF został pomyślnie utworzony.

Opcje eksportu można ustawić ręcznie w oknie dialogowym Plik - Eksportuj jako - Eksportuj jako PDF lub wywołując metody GetPDFExportOptions i SetPDFExportOptions z usługi Session.

Składnia:

svc.ExportAsPDF(filename: str, overwrite: bool = False, opt pages: str, opt password: str, opt watermark: str): bool

Parametry:

filename: pełna ścieżka i nazwa pliku PDF, który ma zostać utworzony. Musi być zgodny z notacją SF_FileSystem.FileNaming.

overwrite: określa, czy plik docelowy może zostać nadpisany (domyślnie = False). Jeśli parametr overwrite jest ustawiony na False, a plik docelowy już istnieje, wystąpi błąd.

pages: ciąg znaków określający, które strony zostaną wyeksportowane. W tym argumencie zastosowano tę samą notację, co w oknie dialogowym Plik - Eksportuj jako - Eksportuj jako PDF.

password: określa hasło umożliwiające otwarcie pliku PDF.

watermark: tekst, który będzie używany jako znak wodny w pliku PDF, który będzie rysowany na każdej stronie wynikowego pliku PDF.

Przykład:

W języku Basic

Poniższy przykład eksportuje bieżący dokument jako plik PDF, definiuje hasło i zastępuje plik docelowy, jeśli już istnieje.


    oDoc.ExportAsPDF("C:\User\Documents\myFile.pdf", Password := "1234", Overwrite := True)
  

Poniższy fragment kodu pobiera aktualne opcje eksportu PDF i używa ich do utworzenia pliku PDF.


    Dim exportSettings as Object, oSession as Object
    oSession = CreateScriptService("Session")
    exportSettings = oSession.GetPDFExportOptions()
    ' Ustawia opcję True na opcję eksportowania komentarzy jako notatek PDF
    exportSettings.ReplaceItem("ExportNotes", True)
    oSession.SetPDFExportOptions(exportSettings)
    oDoc.ExportAsPDF("C:\User\Documents\myFile.pdf")
  
W języku Python

    doc.ExportAsPDF(r"C:\User\Documents\myFile.pdf", password = "1234", overwrite = True)
  

    session = CreateScriptService("Session")
    exportSettings = oSession.GetPDFExportOptions()
    exportSettings.ReplaceItem("ExportNotes", True)
    session.SetPDFExportOptions(exportSettings)
    doc.ExportAsPDF(r"C:\User\Documents\myFile.pdf")
  

PrintOut

Metoda ta wysyła zawartość dokumentu do drukarki domyślnej lub do drukarki zdefiniowanej metodą SetPrinter.

Zwraca True, jeśli dokument został pomyślnie wydrukowany.

Składnia:

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

Parametry:

pages: strony do wydrukowania jako ciąg znaków, jak w interfejsie użytkownika. Przykład: „1-4;10;15-18”. Wartość domyślna to wszystkie strony.

copies: liczba kopii. Wartość domyślna to 1.

Przykład:

W języku Basic

    If oDoc.PrintOut("1-4;10;15-18", Copies := 2) Then
        ' ...
    End If
  
W języku Python

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

RemoveMenu

Usuwa menu najwyższego poziomu z paska menu danego okna dokumentu.

Zwraca wartość True, jeśli można usunąć określone menu. Jeśli określone menu nie istnieje, metoda zwraca False.

note

Tej metody można użyć do usunięcia dowolnej pozycji menu z okna dokumentu, łącznie z menu domyślnymi. Żadna z tych zmian na pasku menu nie jest jednak zapisywana w dokumencie ani w ustawieniach aplikacji. Aby przywrócić domyślne ustawienia paska menu, po prostu zamknij i otwórz ponownie okno dokumentu.


Składnia:

svc.RemoveMenu(menuheader: str): bool

Parametry:

menuheader: nazwa najwyższego poziomu menu, które ma zostać usunięte.

Przykład:

W języku Basic

    Dim oDoc as Object
    Set oDoc = CreateScriptService("Document")
    oDoc.RemoveMenu("Moje menu")
  
W języku Python

    doc = CreateScriptService("Document")
    doc.RemoveMenu("Moje menu")
  
tip

Odwiedź stronę pomocy SFWidgets.Menu, aby dowiedzieć się więcej o tworzeniu/usuwaniu menu w oknach dokumentów LibreOffice.


RunCommand

Uruchamia polecenie UNO w oknie dokumentu skojarzonym z instancją usługi. Kilka typowych poleceń to: Save, SaveAs, ExportToPDF, Undo, Copy, Paste itp.

Sam dokument nie musi być aktywny, aby móc uruchamiać polecenia.

Polecenia można uruchamiać z argumentami lub bez nich. Argumenty nie są sprawdzane przed uruchomieniem polecenia. Jeśli polecenie lub jego argumenty są nieprawidłowe, nic się nie stanie.

tip

Pełną listę poleceń UNO, które można uruchomić w LibreOffice, można znaleźć na stronie Wiki Development/DispatchCommands.


Składnia:

svc.RunCommand(command: str, [args: any])

Parametry:

command: ciąg znaków zawierający nazwę polecenia UNO, w którym rozróżniana jest wielkość liter. Dodanie przedrostka ".uno:" do polecenia jest opcjonalne. Samo polecenie nie jest sprawdzane pod kątem poprawności. Jeśli po wywołaniu polecenia nic się nie dzieje, prawdopodobnie polecenie jest nieprawidłowe.

args: dla każdego argumentu, który ma być przekazany do polecenia, określ parę zawierającą nazwę i wartość argumentu.

Przykład:

W języku Basic

Poniższy przykład uruchamia polecenie SelectData w pliku Calc o nazwie „MyFile.ods”, co powoduje wybranie obszaru danych na podstawie aktualnie wybranej komórki. Należy pamiętać, że to polecenie nie wymaga żadnych argumentów.


    Set oDoc = CreateScriptService("Document", "MyFile.ods")
    oDoc.RunCommand("SelectData")
  

Poniżej znajduje się przykład uruchamiający polecenie UNO ReplaceAll i przekazujący wartości dla swoich argumentów SearchString i ReplaceString. Uruchomienie tego polecenia spowoduje zastąpienie wszystkich wystąpień ciągu „abc” przez „ABC” w bieżącym arkuszu.


    ' Argumenty przekazywane do polecenia:
    ' SearchString  = "abc"
    ' ReplaceString = "ABC"
    oDoc.RunCommand(".uno:ReplaceAll", "SearchString", "abc", "ReplaceString", "ABC")
  

Pamiętaj, że wywołanie polecenia ReplaceAll bez argumentów spowoduje otwarcie okna dialogowego Znajdź i zamień.

W języku Python

    doc = CreateScriptService("Document", "MyFile.ods")
    doc.RunCommand("SelectData")
  

    doc.RunCommand(".uno:ReplaceAll", "SearchString", "abc", "ReplaceString", "ABC")
  

W języku Python możliwe jest także wywołanie RunCommand przy użyciu argumentów słów kluczowych:


    doc.RunCommand(".uno:ReplaceAll", SearchString = "abc", ReplaceString = "ABC")
  
tip

Każdy komponent LibreOffice ma dostępny własny zestaw poleceń. Jednym z łatwych sposobów nauki poleceń jest przejście do Narzędzia - Dostosuj - Klawiatura. Kiedy najedziesz myszką na funkcję na liście Function, pojawi się podpowiedź z odpowiednim poleceniem UNO.


Save

Przechowuje dokument w lokalizacji pliku, z której został załadowany. Metoda jest ignorowana, jeżeli dokument nie był modyfikowany.

Zwraca wartość False, jeśli nie można zapisać dokumentu. Jeśli plik jest otwarty w trybie tylko do odczytu lub jeśli jest to nowy plik, który nie został jeszcze zapisany, pojawia się błąd.

Sam dokument nie musi być aktywny, aby uruchomić tę metodę.

Składnia:

svc.Save(): bool

Przykład:

W języku Basic

    If Not oDoc.Save() Then
        ' ...
    End If
  
W języku Python

    if not doc.Save():
        # ...
  

SaveAs

Przechowuje dokument w podanej lokalizacji pliku. Nowa lokalizacja staje się nową nazwą pliku, do którego zostaną zastosowane proste wywołania metody Save.

Zwraca wartość False, jeśli nie można zapisać dokumentu. W przypadku odrzucenia nadpisywania miejsca docelowego lub gdy miejsce docelowe ma ustawiony atrybut tylko do odczytu, pojawia się błąd.

Sam dokument nie musi być aktywny, aby uruchomić tę metodę.

Składnia:

svc.SaveAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool

Parametry:

filename: ciąg zawierający nazwę pliku, który ma zostać użyty. Musi być zgodny z notacją SF_FileSystem.FileNaming.

overwrite: jeśli True, plik docelowy może zostać nadpisany (domyślnie = False).

password (*): ciąg znaków inny niż spacja chroniący dokument.

filtername (*): nazwa filtra, który ma zostać użyty przy zapisaniu dokumentu. Jeśli ten argument zostanie przekazany, filtr musi istnieć.

filteroptions (*): opcjonalny ciąg opcji skojarzony z filtrem.

Przykład:

W języku Basic

    oDoc.SaveAs("C:\Documents\NewCopy.odt", overwrite := True)
  
W języku Python

    doc.SaveAs(r"C:\Documents\NewCopy.odt", overwrite = True)
  

SaveCopyAs

Przechowuje kopię lub eksportuje dokument do podanej lokalizacji pliku. Rzeczywista lokalizacja pozostaje niezmieniona.

Zwraca wartość False, jeśli nie można zapisać dokumentu. W przypadku odrzucenia nadpisywania miejsca docelowego lub gdy miejsce docelowe ma ustawiony atrybut tylko do odczytu, pojawia się błąd.

Sam dokument nie musi być aktywny, aby uruchomić tę metodę.

Składnia:

svc.SaveCopyAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool

Parametry:

filename: ciąg zawierający nazwę pliku, który ma zostać użyty. Musi być zgodny z notacją SF_FileSystem.FileNaming.

overwrite: jeśli True, plik docelowy może zostać nadpisany (domyślnie = False).

password (*): ciąg znaków inny niż spacja chroniący dokument.

filtername (*): nazwa filtra, który ma zostać użyty przy zapisaniu dokumentu. Jeśli ten argument zostanie przekazany, filtr musi istnieć.

filteroptions (*): opcjonalny ciąg opcji skojarzony z filtrem.

Przykład:

W języku Basic

    oDoc.SaveCopyAs("C:\Documents\Copy2.odt", Overwrite := True)
  
W języku Python

    doc.SaveCopyAs(r"C:\Documents\Copy2.odt", overwrite = True)
  

SetPrinter

Określa opcje drukarki dla dokumentu.

Zwraca True, gdy się powiedzie.

Składnia:

svc.SetPrinter(opt printer: str, opt orientation: str, paperformat: str): bool

Parametry:

printer: nazwa kolejki drukarki, do której chcesz drukować. W przypadku nieobecności ustawiana jest drukarka domyślna.

orientation: albo PORTRAIT, albo LANDSCAPE. W przypadku braku pozostawione bez zmian w odniesieniu do ustawień drukarki.

paperformat: określa format papieru jako wartość ciągu, która może wynosić A3, A4, A5, LETTER, LEGAL lub TABLOID. Pozostawiony bez zmian w przypadku nieobecności.

Przykład:

W języku Basic

    oDoc.SetPrinter(Orientation := "PORTRAIT")
  
W języku Python

    doc.SetPrinter(paperformat='TABLOID')
  
warning

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.