Векторні документи
HokusaiPDF — це окремий продукт для векторних PDF-документів. На відміну від растрового кодувальника pdf(), він малює текст, фігури й градієнти як вміст PDF: текст лишається виділюваним і придатним до пошуку, фігури лишаються чіткими за будь-якого масштабу, а зображення на сторінці вбудовуються як растри, підготовлені звичайними конвеєрами Hokusai. Потрібна Pango 1.44 або новіша; продукту Hokusai вона не потрібна.
// Package.swift: додайте продукт до цілі, що створює PDF.product(name: "HokusaiPDF", package: "hokusai")Модель
Section titled “Модель”VectorPage — це незмінне значення: кожен метод повертає нову сторінку з ще одним елементом, намальованим поверх попередніх. Нічого не відтворюється, доки не записано VectorDocument, а хибні значення відхиляються під час додавання елемента.
| Складник | API |
|---|---|
| Сторінка | VectorPage(size:) з .a4(_), .letter(_) (типово книжкова) або .points(width:height:) (1…14 400). Початок координат — лівий верхній кут, одиниці — пункти (1/72 дюйма). |
| Тло | .background(_ paint: VectorPaint): .color(Color) або .linearGradient(from:to:angle:). |
| Прямокутник | .rectangle(_ frame:fill:stroke:cornerRadius:); потрібні заливка, обведення або обоє. |
| Лінія | .line(from:to:stroke:) з VectorStroke(color:width:) (ширина 0…1000, більша за нуль). |
| Зображення | .image(_ pipeline:frame:fit:opacity:); fit — .contain, .cover або .fill. |
| Текст | .text(_ content:at:width:style:); TextContent звичайний або з розміткою Pango. |
| Стиль | VectorTextStyle(family:size:weight:italic:color:alignment:wrap:lineSpacing:); насиченість від .thin до .black; вирівнювання .leading, .center, .trailing, .justified; перенос .word, .character, .wordThenCharacter. |
| Документ | VectorDocument(pages:metadata:) або VectorDocument(_ page:metadata:); data() і write(to:). |
let navy = Color(red: 0.1, green: 0.14, blue: 0.3)let teal = Color(red: 0.15, green: 0.5, blue: 0.55)let photo = try Hokusai(url: URL(fileURLWithPath: "scene.png"))
let cover = try VectorPage(size: .a4()) .background(.linearGradient(from: navy, to: teal)) .image(photo, frame: VectorRect(x: 40, y: 40, width: 515, height: 322), fit: .cover) .text("Pharos Point", at: VectorPoint(x: 40, y: 390), width: 515, style: VectorTextStyle(family: "sans", size: 34, weight: .bold, color: .white)) .text("Selectable, searchable text on a vector page.", at: VectorPoint(x: 40, y: 440), width: 515, style: VectorTextStyle(size: 14, color: Color(red: 0.85, green: 0.9, blue: 0.95)))
let summary = try VectorPage(size: .a4()) .rectangle(VectorRect(x: 40, y: 40, width: 515, height: 60), fill: .color(navy), cornerRadius: 8) .text("Summary", at: VectorPoint(x: 56, y: 58), style: VectorTextStyle(size: 22, weight: .bold, color: .white)) .line(from: VectorPoint(x: 40, y: 130), to: VectorPoint(x: 555, y: 130), stroke: VectorStroke(color: teal, width: 2)) .text(.markup("The light is visible for <b>24 nautical miles</b> and flashes every <span foreground=\"#267f8c\">ten seconds</span>."), at: VectorPoint(x: 40, y: 150), width: 515, style: VectorTextStyle(size: 13, lineSpacing: 1.3))
let document = VectorDocument(pages: [cover, summary], metadata: PDFDocumentMetadata(title: "Pharos Point", author: "Docs"))let info = try await document.write(to: URL(fileURLWithPath: "report.pdf"))print("vector document →", info.pageCount, "pages,", info.byteCount, "bytes")
сторінка 1 із 2PDF · 595 × 842 · 335 KB
Друга сторінка (заокруглений темно-синій заголовок, лінія й абзац із розміткою) міститься в тому самому PDF; як попередній перегляд показано лише першу. Документ записав 2 сторінки на 343 455 байтів. Виділіть заголовок у будь-якому переглядачі PDF, щоб переконатися, що це текст.
Пам’ять, файли й скасування
Section titled “Пам’ять, файли й скасування”Запис малює сторінки по одній: зображення сторінки обчислюються безпосередньо перед її малюванням і вивільняються після, тож пам’ять містить растри однієї сторінки, а не всіх. write(to:) змушує Cairo писати у тимчасовий файл поруч із призначенням, який атомарно замінює призначення лише тоді, коли документ завершено; збій чи скасування лишає наявний файл як був. Малювання й файловий вивід виконуються поза кооперативним виконавцем Swift, а скасування завдання, що викликає операцію, зупиняє роботу з CancellationError. Батьківські каталоги не створюються.
Помилки
Section titled “Помилки”func attempt(_ name: String, _ run: () async throws -> String) async { do { print(name, "→", try await run()) } catch { print(name, "→ throws", error) }}let photo = try Hokusai(url: URL(fileURLWithPath: "scene.png")).resize(width: 400)
await attempt("custom size 20000 pt") { _ = try VectorPage(size: .points(width: 20000, height: 100)); return "accepted" }await attempt("empty rectangle") { _ = try VectorPage().rectangle(VectorRect(x: 0, y: 0, width: 0, height: 10), fill: .color(.white)); return "accepted" }await attempt("rectangle without fill or stroke") { _ = try VectorPage().rectangle(VectorRect(x: 0, y: 0, width: 10, height: 10)); return "accepted" }await attempt("document without pages") { _ = try await VectorDocument(pages: []).data(); return "written" }await attempt("invalid markup") { let page = try VectorPage().text(.markup("<b>unclosed"), at: VectorPoint(x: 10, y: 10)) _ = try await VectorDocument(page).data(); return "written"}await attempt("raster pdf, dpi 0") { _ = try photo.pdf(pageSize: .image(dpi: 0)); return "accepted" }| Ситуація | Результат |
|---|---|
Власний розмір сторінки поза 1…14 400 пунктів |
invalidOption(name: "page width", …"from 1 to 14400 points"), під час створення сторінки |
| Прямокутник без площі | invalidOption(name: "rectangle", …), під час додавання |
| Прямокутник без заливки й обведення | invalidOption: «give a fill, a stroke, or both» |
| Хибна розмітка Pango | invalidOption(name: "text", …"the Pango markup is not valid"), під час додавання тексту |
| Документ без сторінок | invalidInput: «a document needs at least one page» |
| Конвеєр зображення, що завершується помилкою | помилка цього конвеєра з data() / write(to:) |
| Cairo не може створити PDF | encode |