Spis treści
Indeks 🔎︎

# 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:

- Otwieranie, zamykanie i zapisywanie dokumentów

- Dostęp do standardowych lub niestandardowych właściwości dokumentów

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:

• 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

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)
            # (...)

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()

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.

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()

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.

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")

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.

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")

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')

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.

Tematy pokrewne

Usługa ScriptForge.Dictionary

Usługa ScriptForge.UI

Usługa SFWidgets.Menu