Oprettelse af Python-scripts med ScriptForge

Forskelle mellem Basic og Python

Biblioteket ScriptForge er tilgængeligt for både Basic og Python. De fleste tjenester, metoder og egenskaber fungerer på samme måde i begge programmeringssprog. På grund af forskelle i, hvordan hvert sprog virker, skal ScriptForge-brugere være bevidst om nogle programmets karakteristika ved brug af Python:

Metoder og egenskabsnavne: I Python kan alle metoder og egenskaber bruges skrevet med småt, med stort begyndelsesbogstav af hvert ord i SammensatteOrd ("KamelFormat"), eller stort bogstav af nye ord i sammensatteOrd ("kamelFormat").
Argumenter: Alle nøgleords-argumenter overført til metoder er skrevet med små bogstaver.
Datoer: Alle dato-objekter videregives og returneres som datetime.datetime hjemmehørende Python-objekter.
Matrixer: En-dimensionelle matrixer videregives og returneres som tupler (er et uforanderligt objekt). To-dimensionelle matrixer videregives og returneres som tupler af tupler.
Ingen: Python's nøgleord None (Ingen)er ligeværdigt med Basic's Null (Nul), Empty (Tom) eller Nothing (Intet).
UNO-objekter: Alle UNO-strukturer udveksles mellem Basic og Python uden nogle ændringer.
Fejlsøgning: Nårsomhelst der sker en fejl i Python-scripts, der bruger ScriptForge, viser fejlbeskeden, der gives af Pythons kørselsstak, den kodelinje, der udløste fejlen. I Basic viser fejlbeskeder ikke denne oplysning.

Besøg Hjælp til LibreOfficeDev Python-scripter og se flere oplysninger om Python-scriptarbejde med LibreOfficeDev.

Redigering af Python-scripts i IDE'er

Mens du redigerer Python-scripts kan du få indskrivningstips ‒ relateret til ScriptForge-tjenesters offentlige metoder og egenskaber ‒ fra IDE'er som understøtter denne funktion. Visuelt mens du redigerer et brugerscript:

Når musemarkøren holdes over en objektinstans, en metode eller en egenskab, vises dens detaljerede beskrivelse.
Et "." efter en objektinstans viser et rullegardin-felt med alle de tilgængelige grænseflader.
Parentes efter et metodenavn starter kode-fuldførelse ved at vise metodens argumenter.

Skrivetips vises når metoder og egenskaber redigeres med korrekte store og små bogstaver.

Kørsel af Python-scripts under LibreOfficeDev

Afhængigt af hvad du har tænkt at opnå, kan du vælge en af følgende måder at udføre Python-scripts i LibreOfficeDev:

Udfør scripts i den aktuelle LibreOfficeDev-proces: Python-scripts udføres inde fra LibreOfficeDev-processen ved at bruge menuen Funktioner ▸ Makroer ▸ Udfør makro eller APSO-udvidelsen til at kalde brugerscripts gemt i mappen til Python-scripts. Du kan også bruge APSO Python-skallen til at udføre Python-scripts interaktivt.
Udfør scripts separat fra LibreOfficeDev-processen: Python-scripts udføres fra en ekstern proces, som forbinder til en kørende LibreOfficeDev-proces med brug af et rør (en pipe) eller en sokkel (en socket).

Hvis du planlægger at udføre scripts inde fra LibreOfficeDev-processen, anbefales det at installere APSO-udvidelsen (Alternativ Python-scriptorganisator). Hvis du derimod vil udvikle Python-scripts udenfor LibreOfficeDev, kan du vælge dit foretrukne Python-IDE.

Udførelse af scripts inde fra LibreOfficeDev-processen

Brug af APSO-udvidelsen

Den letteste måde at komme i gang med at bruge Python-scipts i LibreOfficeDev er ved at installere APSO-udvidelsen. Efter installation af den, åbn en hvilken som helst LibreOfficeDev-komponent og gå til Funktioner ▸ Makroer ▸ Administrér Python-scripts.

I hovedvinduet for APSO går du til Menu ▸ Python-skal.

Alternativt kan du åbne APSO med standardgenvejen Alt + Skift + F11.

Nu kan du begynde at taste Pyton-kommandoer, og skallen vil vil udskrive det tilsvarende output efter at hver kodelinjer er udført.

For at begynde at bruge ScriptForge-biblioteket, må du importere CreateScriptService-metoden. Med denne har du tilgang til de tjenester, som biblioteket tilbyder. Eksemplet herunder bruger Basic-tjenesten til at vise et beskedfelt.


        from scriptforge import CreateScriptService
        bas = CreateScriptService("Basic")
        bas.MsgBox("Hello!")

For at udføre eksemplet ovenfor, skriv hver linje ind i Python-skallen, én efter én, hvor du trykker Enter-tasten hver gang du har tastet en kodelinje.

Nu kan du begynde at udføre Python-kommandoer med en hvilken som helst af ScriptForge-tjenesterne. For eksempel bruger kodestykket herunder tjenesten UI (User Interface = brugerflade) til at oprette et tomt Writer-dokument.


        ui = CreateScriptService("UI")
        doc = ui.CreateDocument("Writer")

Oprettelse af Python-scriptfiler

Du kan oprette dine egne Pythonfiler og redigere dem med din foretrukne teksteditor. Senere kan du kalde dem fra en hvilken som helst LibreOfficeDev-komponent.

Det første skridt er at finde ud af, hvor dine brugerscripts er gemt. Se hjælpesiden Administration og placering af Python-scripts.

Nu kan du oprette en tekstfil i din Python-brugerscriptmappe, for eksempel mit_script.py, og begynde at skrive dine scipts.

Det næste er et simpel eksempel, som henter en numerisk værdi fra en Calc-celle og forøger den med 1. Bare skriv følgende kode i mit_script.py-filen.


    from scriptforge import CreateScriptService
    doc = CreateScriptService("Calc")
    
    def increment_cell(args=None):
        value = doc.GetValue("A1")
        value += 1
        doc.SetValue("A1", value)
    
    g_exportedScripts = (increment_cell, )

Dette eksempel opretter funktionen increment_cell. Bemærk at g_exportedScripts er en tupel, som fortæller, hvilke funktioner der vil blive vist i LibreOfficeDev som bruger-scripts.

Sådan udfører du dette script fra et Calc-dokument:

Opret eller åbn en Calc-fil.
Skriv en numerisk værdi i celle "A1" i den aktuelle ark.
Gå til Funktioner ▸ Makroer ▸ Udfør makro.
Vælg Mine makroer ▸ mit_script i biblioteksvælgeren. Vælg så increment_cell-funktionen under listen Makronavn.
Klik på Udfør. Bemærk at værdien i celle "A1" blev forøget med 1.

Du kan også bruge APSO til at udføre Python-scripts på en lignende måde:

Åbn først APSO ved at gå til Funktioner ▸ Makroer ▸ Administrér Python-scripts.
I makrolisten navigerer du til Mine makroer ▸ mit_script ▸ increment_cell.
Klik på Udfør.

Udførsel af scripts separat fra LibreOfficeDev-processen

Bestemme installations-stien

Det første skridt for at udføre scripts fra et separat proces er at finde den mappe, hvor LibreOfficeDev er installeret. Der findes flere måder at gøre dette, men ScriptForge giver en hurtig måde at identificere din installationssti. For at gøre det, åbn APSO's Python-skal og skriv:


      from scriptforge import CreateScriptService
      fs = CreateScriptService("FileSystem")
      fs.FileNaming = "SYS"
      inst_dir = fs.InstallFolder
      print(inst_dir)

Outputtet fra koden ovenfor er basiskataloget, hvor LibreOfficeDev er installeret. Nu skal du tilføje "program"-undermappen til stien for basiskataloget. Det giver den basismappe, hvorfra du vil udføre Python-scripts i en separat proces.

Lad os for eksempel sige, at du får /usr/lib/libreoffice/ som resultatet af at udføre Python-koden ovenfor. Så skal du se på /usr/lib/libreoffice/program som stien til at udføre dine Python-scripts.

Start LibreOfficeDev med pipe- eller socket-indstillinger (rør eller sokkel).

For at udføre Python-scripts fra en separat proces, er du nødt til at starte LibreOfficeDev med nogle få ekstra indstillinger, som angiver rør-navnet (pipe) eller værtsnavnet (host) og porten, som den eksterne proces vil bruge til at kommunikere med LibreOfficeDev-komponent-processen.

Åbn dit operativsystems kommandoprompt, gå til programmappen for dit LibreOfficeDev-installationsbibliotek og skriv enten:

On Linux or macOS:

libreoffice --accept='pipe,name=aPipeName;urp;'

På Windows:

soffice.exe --accept='socket,host=localhost,port=2021;urp;'

as a Flatpak:

flatpak run org.libreOffice.LibreOffice accept='socket,host=localhost,port=2021;urp;'

Begge kommandoerne ovenfor vil starte LibreOfficeDev med en åben kommunikationskanal, sådan at andre processer kan udveksle meddelelser med den.

Bemærk at det forrige eksempel åbner LibreOfficeDev startcenter. Hvis du ønsker at åbne en specifik komponent, for eksempel Writer, kan du tilføje flaget --writer til kommandoen som vist nedenfor.

./soffice --writer --accept='socket,host=localhost,port=2021;urp;'

Læg mærke til parametrene name, eller host og port, som i dette eksempel er henholdsvis aPipeName, eller localhost og 2021.

Udføre en ekstern Python-skal

Start Python-skallen fra program-mappen i installationsstien for LibreOfficeDev. Følg trinnene ovenfor for at lære, hvordan du finder installationsstien.

On Linux or macOS:

$ cd /usr/lib/libreoffice/program

$ python

På Windows:

$ cd C:\\Program Files\\LibreOffice\\program\

$ python.exe

Dette vil åbne Python-skallen, og nu kan du begynde at skrive kommandoer, som vil blive udført af LibreOfficeDev. Men før du gør dette, må du opsætte pipe- eller socket-forbindelsen (rør eller sokkel). ScriptForge-sætningen nedenfor skal udføres før det allerførste kald til CreateScriptService().

Udfør enten:


   from scriptforge import ScriptForge, CreateScriptService
   ScriptForge(pipe='aPipeName')


    from scriptforge import ScriptForge, CreateScriptService
    ScriptForge(hostname='localhost', port=2021)

Læs afsnittet Sætte PYTHONPATH nedenfor i tilfælde af fejl ved import af scriptforge.py eller uno.py.

Den anden koldelinje ovenfor definerer pipe- eller host- og port-indstillingerne (rør eller vært og port), sådan at Python-skallen kan kommunikere med en kørende LibreOfficeDev-proces, der er åbnet med de samme pipe- eller socket-indstillinger.

Nu kan du udføre andre Python-kommandoer, og de vil kunne kommunikere med LibreOfficeDev-processen. For eksempel:


    ui = CreateScriptService("UI")
    bas = CreateScriptService("Basic")
    doc = ui.OpenDocument("~/Documents/myFile.ods")
    bas.MsgBox(doc.DocumentType)

Sætte PYTHONPATH

Afhængigt af konfigurationen af dit operativsystem, kan det være nødvendigt at du sætter miljøvariablen PYTHONPATH for at kunne importere scriptforge.py-biblioteket, som igen kræver import af uno.py-biblioteket.

Brug filsøgningsværtøjet i dit operativsystem til at finde kataloget, hvor begge disse filer er placeret.

For eksempel, på en standard Ubuntu-installation kan disse to filer være placeret i:

scriptforge.py: Placeret i /usr/lib/libreoffice/program
uno.py: Placeret i /usr/lib/python3/dist-packages

I dette tilfælde, sæt miljøvariablen PYTHONPATH som følger før du starter Python-fortolkeren:

export PYTHONPATH=/usr/lib/libreoffice/program:/usr/lib/python3/dist-packages

Placeringen af disse filer kan være forskellig for hvert operativsystem og LibreOfficeDev-installationsmetode.

Biblioteket ScriptForge

Hjælp til LibreOfficeDev Pythonscripts

Start af LibreOfficeDev-software med parametere