Skip to content
Office Oxide

Go-Bibliothek für Office — Schnellstart

Das Go-Paket github.com/yfedoseev/office_oxide/go umhüllt das C-FFI von office_oxide via cgo und gibt dir idiomatische Go-Typen für Lesen, Konvertieren und Bearbeiten von DOCX / XLSX / PPTX / DOC / XLS / PPT.

Installation

go get github.com/yfedoseev/office_oxide/go@latest

Die Bindung braucht die C-Bibliothek office_oxide zur Linkzeit. Zwei Wege, sie bereitzustellen.

Option 1 — Einzeiler-Installer (empfohlen):

go run github.com/yfedoseev/office_oxide/go/cmd/install@latest

Der Installer lädt das passende Prebuild von liboffice_oxide (und den Header) für dein OS/Arch und legt es dort ab, wo cgo es findet. Nach einem Upgrade neu starten, um das neue ABI mitzunehmen.

Option 2 — cgo-Flags selbst setzen, wenn du die Library aus dem Rust-Source gebaut hast (cargo build --release --lib) oder sie in einem System-Prefix liegt:

export CGO_CFLAGS="-I/usr/local/include"
export CGO_LDFLAGS="-L/usr/local/lib -loffice_oxide"

Ein Dokument lesen

package main

import (
    "fmt"
    "log"

    officeoxide "github.com/yfedoseev/office_oxide/go"
)

func main() {
    doc, err := officeoxide.Open("report.docx")
    if err != nil {
        log.Fatal(err)
    }
    defer doc.Close()

    text, err := doc.PlainText()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(text)
}

Einzelaufruf-Helfer:

text, err := officeoxide.ExtractText("report.docx")

Kern-API

doc, err := officeoxide.Open("file.xlsx")
if err != nil { log.Fatal(err) }
defer doc.Close()

format, _ := doc.Format()      // "xlsx"
text, _   := doc.PlainText()
md, _     := doc.ToMarkdown()
html, _   := doc.ToHTML()
irJSON, _ := doc.ToIRJSON()

err = doc.SaveAs("file.docx")

Document umhüllt ein C-Handle; ein Finalizer gibt es frei, wenn du Close vergisst, aber bevorzuge stets defer doc.Close() für deterministisches Cleanup.

Aus Bytes öffnen (gut für Streaming / Serverless):

data, _ := os.ReadFile("report.pptx")
doc, err := officeoxide.OpenFromBytes(data, "pptx")

format muss "docx", "xlsx", "pptx", "doc", "xls" oder "ppt" sein.

Bearbeiten

Editierbare Handles bewahren beim Speichern alle unveränderten OPC-Teile (Bilder, Diagramme, Custom-XML). Nur DOCX, XLSX und PPTX.

ed, err := officeoxide.OpenEditable("template.docx")
if err != nil { log.Fatal(err) }
defer ed.Close()

n, _ := ed.ReplaceText("{{name}}", "Alice")
fmt.Printf("%d Ersetzungen\n", n)

err = ed.Save("out.docx")

Text in DOCX / PPTX ersetzen

ed, _ := officeoxide.OpenEditable("slides.pptx")
defer ed.Close()

ed.ReplaceText("Q3", "Q4")
ed.ReplaceText("2024", "2025")

buf, _ := ed.SaveToBytes()   // []byte für Upload / Stream
_ = os.WriteFile("slides_q4.pptx", buf, 0o644)

XLSX-Zellen setzen

ed, _ := officeoxide.OpenEditable("budget.xlsx")
defer ed.Close()

ed.SetCell(0, "A1", officeoxide.NewStringCell("Total"))
ed.SetCell(0, "B1", officeoxide.NewNumberCell(42.5))
ed.SetCell(0, "C1", officeoxide.NewBoolCell(true))
ed.SetCell(0, "D1", officeoxide.NewEmptyCell())

ed.Save("budget.xlsx")

Nimm NewStringCell, NewNumberCell, NewBoolCell oder NewEmptyCell — der Konstruktor wählt die richtige Variante für den FFI-Aufruf.

Formatunabhängige IR

doc.ToIRJSON() gibt JSON zurück, das dem Rust-Schema DocumentIR entspricht. Unmarshal-en in das gewünschte Layout:

import "encoding/json"

irJSON, _ := doc.ToIRJSON()

var ir struct {
    Sections []struct {
        Title    *string           `json:"title"`
        Elements []json.RawMessage `json:"elements"`
    } `json:"sections"`
}
_ = json.Unmarshal([]byte(irJSON), &ir)
fmt.Printf("%d Abschnitte\n", len(ir.Sections))

Format ohne Öffnen erkennen

fmt := officeoxide.DetectFormat("mystery.bin")  // "" falls nicht unterstützt

Altformate

Öffnen wie OOXML; SaveAs konvertiert transparent über die IR:

doc, _ := officeoxide.Open("old.xls")
defer doc.Close()
_ = doc.SaveAs("modern.xlsx")

Fehler

Jeder fehlbare Aufruf liefert ein *officeoxide.Error mit typisiertem Code und der ursprünglichen Operation:

if _, err := officeoxide.Open("missing.docx"); err != nil {
    var e *officeoxide.Error
    if errors.As(err, &e) {
        fmt.Printf("code=%d op=%s\n", e.Code, e.Op)
    }
}

Ein geschlossenes Handle zu nutzen liefert officeoxide.ErrClosed.

Code Name Bedeutung
0 OK Erfolg
1 INVALID_ARG nil / leer / falsche Format-String
2 IO Dateisystem-Fehler
3 PARSE beschädigtes Dokument
4 EXTRACTION Parsing OK, aber Rendering scheiterte
5 INTERNAL Bug — bitte Issue eröffnen
6 UNSUPPORTED Erweiterung/Feature nicht unterstützt

Fehlersuche

Symptom Lösung
could not determine kind of name for C.office_document_open Headers sind für cgo nicht sichtbar. Installer ausführen oder CGO_CFLAGS setzen.
Linker: cannot find -loffice_oxide CGO_LDFLAGS="-L/path/to/lib -loffice_oxide" setzen oder Installer ausführen.
Laufzeit: cannot open shared object file Lib-Verzeichnis in LD_LIBRARY_PATH (Linux), DYLD_LIBRARY_PATH (macOS) ergänzen oder DLL neben die EXE legen (Windows).
unsupported format bei .doc/.xls Erweiterung muss klein geschrieben sein, oder OpenFromBytes(data, "doc") verwenden.
Cross-Compilation scheitert cgo braucht eine zur Zielplattform passende C-Toolchain. zig cc oder CC=aarch64-linux-gnu-gcc.

Siehe auch