Zarządzanie dokumentami

Zarządzanie dokumentami

Document jest punktem wejścia dla każdej operacji zarządzania dokumentami opisanej tutaj: otwierania i zapisywania plików, eksportu do HTML, dodawania opcjonalnych warstw treści, tworzenia Tagged PDF oraz odczytu lub zapisu danych AcroForm. Page i Form są dostępne poprzez Document.Page(n) i Document.Form().

Otwieranie i zapisywanie dokumentów

pdf.Open wczytuje plik PDF z podanej ścieżki; pdf.OpenWithPassword robi to samo dla plików zabezpieczonych hasłem. Document.Save zapisuje wynik w nowej ścieżce pliku.

doc, err := pdf.Open("input.pdf")
if err != nil {
	panic(err)
}

_, err = pdf.OpenWithPassword("locked.pdf", "userpassword")
if err != nil {
	panic(err)
}

err = doc.Save("output.pdf")

Eksportowanie do HTML

Document.SaveHTML i Document.WriteHTML konwertują dokument do HTML. HTMLSaveOptions.Mode wybiera reprezentację: HTMLModeText (widoczny stylowany tekst na tle rastrowym bez glifów), HTMLModeNative (grafika strony jako jedna warstwa SVG w linii), lub HTMLModeFlow (przepływowy HTML z nagłówkami i akapitami w kolejności czytania). Nieustawienie Mode skutkuje domyślnym, wiernym wynikiem: pełnostronicowym rastrem z przezroczystą warstwą tekstu do zaznaczania.

doc, _ := pdf.Open("input.pdf")

// Faithful mode (default)
doc.SaveHTML("out.html")

// Visible-text mode
doc.SaveHTML("out.html", pdf.HTMLSaveOptions{Mode: pdf.HTMLModeText})

// Multi-file output: external resources plus one HTML file per page
doc.SaveHTML("site/doc.html", pdf.HTMLSaveOptions{
    Mode: pdf.HTMLModeNative, ResourceDir: "assets", SplitPages: true,
})

// Page subset, custom raster DPI and title
doc.SaveHTML("part.html", pdf.HTMLSaveOptions{Pages: []int{1, 3}, DPI: 96, Title: "Report"})

Zarządzanie opcjonalnymi warstwami treści

Document.AddLayer(name) tworzy nową Opcjonalną Grupę Zawartości i zwraca *Layer; Document.Layers() wymienia wszystkie istniejące warstwy. Page.BeginLayer / Page.EndLayer oznaczają zawartość strony jako należącą do warstwy, a Layer.SetVisible(false) ukrywa tę zawartość.

doc := pdf.NewDocumentFromFormat(pdf.PageFormatA4)
layer := doc.AddLayer("Watermark")

page, _ := doc.Page(1)
page.BeginLayer(layer)
page.AddText("DRAFT", pdf.TextStyle{Font: pdf.FontHelveticaBold, Size: 48},
    pdf.Rectangle{LLX: 150, LLY: 400, URX: 450, URY: 460})
page.EndLayer()

layer.SetVisible(false)
doc.Save("layered.pdf")

Tworzenie oznakowanych (dostępnych) plików PDF

Document.TaggedContent() zwraca fasadę *TaggedContent, która posiada logiczne drzewo struktury dokumentu i ustawia metadane katalogu wymagane przez PDF/UA. Page.TagContent otacza wywołanie rysowania w zaznaczonej zawartości i zwraca *StructElement dla tego węzła.

doc := pdf.NewDocumentFromFormat(pdf.PageFormatA4)
tc := doc.TaggedContent()
tc.SetTitle("Quarterly Report")
tc.SetLanguage("en-US")
page, _ := doc.Page(1)

page.TagContent(tc.Root(), pdf.StructH1, func() error {
    return page.AddText("Quarterly Report", pdf.TextStyle{Font: pdf.FontHelveticaBold, Size: 24},
        pdf.Rectangle{LLX: 50, LLY: 760, URX: 545, URY: 800})
})
fig, _ := page.TagContent(tc.Root(), pdf.StructFigure, func() error {
    return page.AddImage("chart.png", pdf.Rectangle{LLX: 50, LLY: 540, URX: 300, URY: 680})
})
fig.SetAlt("Bar chart of Q3 sales by region") // required for figures

doc.Save("accessible.pdf")

Grupowanie elementów również zagnieżdża się pod korzeniem drzewa:

doc := pdf.NewDocumentFromFormat(pdf.PageFormatA4)
tc := doc.TaggedContent()
page, _ := doc.Page(1)

tbl := tc.Root().AddChild(pdf.StructTable)
row := tbl.AddChild(pdf.StructTR)
cell := row.AddChild(pdf.StructTD)
page.TagContent(cell, pdf.StructP, func() error { return nil })

Eksportowanie i importowanie danych formularza jako JSON

Form.ExportJSON serializuje każdy typ pola i wartość do JSON ({"name": {"type": "text", "value": "Jane"}, ...}); Form.ImportJSON nakłada ładunek JSON na formularz i zwraca liczbę pól, które zaktualizował. JSONExportOptions.Indent pretty-prints output.

doc, _ := pdf.Open("filled.pdf")
data, _ := doc.Form().ExportJSON(pdf.JSONExportOptions{Indent: true})

// Fill a template from a JSON payload; discard the applied-field count.
template, _ := pdf.Open("template.pdf")
_, _ = template.Form().ImportJSON(data)

Wskazówki i najlepsze praktyki

• Wybierz HTMLModeNative dla stron z dużą ilością wektorów, HTMLModeFlow dla czytania w trybie reflow/na urządzeniach mobilnych oraz domyślne, wierne ustawienie (bez ustawionego Mode), gdy najważniejsza jest wierność wizualna.
• Wywołaj Layer.SetVisible(false) przed Save, aby domyślnie ukrywać warstwy znaków wodnych lub adnotacji, jednocześnie umożliwiając adresowanie treści za pomocą obiektu Layer.
• Ustaw TaggedContent.SetTitle i SetLanguage przed wywołaniem Page.TagContent, ponieważ walidacja PDF/UA sprawdza metadane na poziomie katalogu, które te metody zapisują.
• Wywołaj StructElement.SetAlt na każdym węźle StructFigure — obrazy bez alternatywnego tekstu nie przejdą walidacji PDF/UA.
• Użyj JSONExportOptions.Indent do porównywania stanu wyeksportowanego formularza w formie czytelnej dla człowieka; pomiń go w przypadku zwartych ładunków maszynowych.

Częste problemy

FAQ

Który tryb eksportu HTML powinienem użyć?

HTMLModeText dla najmniejszego, w pełni wybieralnego wyjścia; HTMLModeNative, gdy jakość wektorowa (krzywe, natywne pociągnięcia) ma większe znaczenie niż rozmiar pliku; HTMLModeFlow dla przepływalnego, przyjaznego urządzeniom mobilnym układu czytania. Pozostaw Mode nieustawione, aby zachować domyślne renderowanie rastrowe z przezroczystym tekstem.

Czy mogę wyeksportować tylko wybrane strony do HTML?

Tak. Ustaw HTMLSaveOptions.Pages na wycinek numerów stron liczonych od 1, np. pdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []int{1, 3}}}}.

Jak ukryć warstwę domyślnie, ale umożliwić przeglądarce włączenie jej ponownie?

Wywołaj Layer.SetVisible(false) przed zapisaniem. Warstwa pozostaje adresowalną grupą opcjonalnej zawartości; Layer.IsVisible() zgłasza jej aktualny stan.

Czy eksport formularza JSON zawiera typy pól?

Tak. Każde wyeksportowane pole jest obiektem JSON z kluczami type i value, np. {"subscribe": {"type": "checkbox", "value": true}}.

Czy muszę wywoływać TagContent dla każdego elementu, czy mogę bezpośrednio zagnieżdżać grupy?

Oba. Page.TagContent opakowuje wywołanie rysowania i dodaje element struktury liścia. Aby grupować elementy (tabele, listy), wywołaj StructElement.AddChild na korzeniu drzewa lub elemencie nadrzędnym, aby najpierw zbudować zagnieżdżenie, a następnie oznacz zawartość liścia poniżej.

API Reference Podsumowanie

Zobacz także

• Aspose.PDF — Enterprise Documentation