Згенерований текст
Hokusai відтворює текст через libvips і Pango. Hokusai.text(_:layout:style:) повертає звичайний незмінний конвеєр (прозоре зображення тексту), який можна перетворювати, накладати чи кодувати окремо; drawText — скорочення для накладання цього конвеєра на наявний. Для відтворення тексту потрібна libvips, зібрана з Pango (Hokusai.capabilities().textRendering), а збірка без неї повідомляє HokusaiError.unsupported із завершальної операції, а не з виклику.
Компонування
Section titled “Компонування”TextLayout задає розмір текстового блока:
.natural(типово): такого розміру, якого потребує текст; рядки розриваються лише на переносах..width(_:wrap:): переносить рядки за шириною в пікселях за розміру шрифту й DPI стилю.wrap—.word(типово),.character,.wordCharacter(розрив між словами та всередині надто довгого слова) або.none..fit(width:height:): найбільша роздільність, за якої текст вміщується в блок.dpiстилю не використовується, аlineHeightмає лишатися1.
let style = TextStyle(fontSize: 40, color: Color(red: 0.1, green: 0.14, blue: 0.3))let sentence: TextContent = "The lighthouse keeper wound the clock every evening."
// natural: as large as the text needs; lines break only at newlines.let natural = try Hokusai.text(sentence, style: style)// width: wrap lines to a pixel width.let wrapped = try Hokusai.text(sentence, layout: .width(420), style: style)// width with .character breaks anywhere, `.none` never breaks and clips at the width.let clipped = try Hokusai.text(sentence, layout: .width(420, wrap: .none), style: style)// fit: the largest size that fits the box (the style's dpi is not used).let fitted = try Hokusai.text(sentence, layout: .fit(width: 420, height: 120), style: style)
for (name, text) in [("natural", natural), ("wrapped", wrapped), ("clipped", clipped), ("fitted", fitted)] { try await text.png().write(to: URL(fileURLWithPath: "\(name).png"))}
.naturalPNG · 954 × 38 · 8 KB 
.width(420)PNG · 393 × 120 · 11 KB 
.width(420, wrap: .none)PNG · 954 × 38 · 8 KB 
.fit(420 × 120)PNG · 393 × 120 · 11 KB
Виміряні розміри наведено в кожному підписі. Зверніть увагу, що .width(420) дав зображення завширшки 393 пікселі, бо рядки розірвалися до досягнення межі, а wrap: .none у цій збірці поводився як .natural (954 × 38), тож не покладайтеся на нього для обрізання тексту; обрізайте через extract, якщо потрібно.
Типографіка: TextStyle
Section titled “Типографіка: TextStyle”| Властивість | Тип | За замовчуванням | Межі |
|---|---|---|---|
font |
String |
"sans" |
Родина й стиль Pango без розміру, напр. "Helvetica Bold"; не шлях до файлу. |
fontFile |
URL? |
nil |
Локальний файл TTF чи OTF, доступний для font на цей рендер. Потребує libvips із fontconfig; файл, який libvips не може завантажити, — лише попередження, і використовується названий font. |
fontSize |
Int |
24 |
1…2000 пунктів за dpi. |
color |
Color |
чорний | |
alignment |
TextAlignment |
.left |
.left, .center, .right. |
justify |
Bool |
false |
Розтягує перенесені рядки на повну ширину. |
lineHeight |
Double |
1 |
0.5…5, кратне природній висоті рядка шрифту. |
dpi |
Int |
72 |
1…2400; ігнорується в .fit. |
stroke |
TextStroke? |
nil |
Обведення: color, width у (0, 64]. |
shadow |
TextShadow? |
nil |
offsetX/offsetY у межах ±10 000, blur 0…64 (типово 1.2), color (його непрозорість — це непрозорість тіні). |
rotation |
Double |
0 |
Градуси за годинниковою стрілкою; скінченне. |
let base = TextStyle(font: "sans Bold", fontSize: 72, color: Color(red: 0.1, green: 0.14, blue: 0.3))
var stroked = basestroked.color = .whitestroked.stroke = TextStroke(color: Color(red: 0.1, green: 0.14, blue: 0.3), width: 4)
var shadowed = baseshadowed.shadow = TextShadow(offsetX: 4, offsetY: 4, blur: 3)
var rotated = baserotated.rotation = -12
let variants: [(String, TextStyle)] = [("plain", base), ("stroke", stroked), ("shadow", shadowed), ("rotated", rotated)]for (name, style) in variants { try await Hokusai.text("Hokusai", style: style).png().write(to: URL(fileURLWithPath: "\(name).png"))}
// Alignment and line height apply to multi-line text.var centred = TextStyle(fontSize: 36, color: Color(red: 0.1, green: 0.14, blue: 0.3))centred.alignment = .centercentred.lineHeight = 1.4try await Hokusai.text("Hokusai\nSwift image processing", style: centred).png() .write(to: URL(fileURLWithPath: "centred.png"))
звичайнийPNG · 270 × 55 · 4 KB 
обведенняPNG · 278 × 63 · 9 KB 
тіньPNG · 290 × 75 · 12 KB 
обертання −12PNG · 276 × 110 · 11 KB 
по центру, lineHeight 1.4PNG · 367 × 86 · 7 KB
Шрифти надходять із хоста: установіть потрібні застосунку й вказуйте ім’я встановленої родини. Постачайте шрифти разом із застосунком і завантажуйте через fontFile, коли хост неможливо контролювати.
Розмітка
Section titled “Розмітка”TextContent — це .plain(String) або .markup(String); рядковий літерал є звичайним. Звичайний текст завжди екранується, тож будь-який рядок користувача безпечно відтворювати. .markup — це розмітка Pango (не HTML і не CSS) для змішаних шрифтів, розмірів і кольорів; хибна розмітка викликає помилку під час відтворення тексту.
// Pango markup mixes fonts, sizes and colours in one text. (Plain text is always escaped.)let markup = """<span size="xx-large" weight="bold">Sale</span> <span foreground="#c83030">−30%</span><i>this week only</i> · <span font_family="monospace">code HOKUSAI</span>"""try await Hokusai.text(.markup(markup), style: TextStyle(fontSize: 36, color: Color(red: 0.1, green: 0.14, blue: 0.3))) .png().write(to: URL(fileURLWithPath: "markup.png"))
// Characters that look like markup are safe in plain text.try await Hokusai.text(.plain("a < b & c"), style: TextStyle(fontSize: 36, color: Color(red: 0.1, green: 0.14, blue: 0.3))) .png().write(to: URL(fileURLWithPath: "plain-escaped.png"))
розміткаPNG · 515 × 104 · 12 KB 
звичайний, екранованийPNG · 142 × 27 · 2 KB
Малювання на зображенні
Section titled “Малювання на зображенні”drawText(_:placement:layout:style:) накладає відтворений текст за тими самими правилами розміщення, обрізання й змішування, що й будь-який інший шар (Композиція). placement — це .at(x:y:) або .gravity(_:offsetX:offsetY:).
let photo = try Hokusai(url: URL(fileURLWithPath: "scene.png")).resize(width: 640)
var style = TextStyle(font: "sans Bold", fontSize: 40, color: .white)style.shadow = TextShadow(offsetX: 2, offsetY: 2, blur: 2, color: Color(red: 0, green: 0, blue: 0, opacity: 0.7))
try await photo .drawText("Pharos Point", placement: .gravity(.southWest, offsetX: 24, offsetY: 20), style: style) .webp(quality: 88) .write(to: URL(fileURLWithPath: "caption.webp"))
drawTextWEBP · 640 × 400 · 15 KB
Помилки
Section titled “Помилки”func attempt(_ name: String, _ build: () throws -> Hokusai) async { do { let output = try await build().png().data() print(name, "→", output.info.width, "×", output.info.height) } catch { print(name, "→ throws", error) }}
let style = TextStyle(fontSize: 24)await attempt("hello") { try Hokusai.text("Hello", style: style) }await attempt("empty text") { try Hokusai.text("", style: style) }await attempt("font file as family") { try Hokusai.text("Hi", style: TextStyle(font: "/fonts/Inter.ttf")) }await attempt("fontSize 3000") { try Hokusai.text("Hi", style: TextStyle(fontSize: 3000)) }await attempt("fit with lineHeight") { var tall = TextStyle(); tall.lineHeight = 2 return try Hokusai.text("Hi", layout: .fit(width: 200, height: 100), style: tall)}await attempt("invalid markup") { try Hokusai.text(.markup("<b>unclosed"), style: style) }| Виклик | Результат |
|---|---|
Hokusai.text("Hello", style: TextStyle(fontSize: 24)) |
зображення 52 × 19 |
| порожній текст | invalidOption(name: "text", …"must not be empty") |
font, що є шляхом (/fonts/Inter.ttf) |
invalidOption(name: "font", …"is a family name; pass a font file as fontFile") |
fontSize: 3000 |
invalidOption: «must be from 1 through 2000» |
.fit з lineHeight, відмінним від 1 |
invalidOption: «must be 1 with a fit layout» |
| хибна розмітка | invalidInput: «the text is not valid Pango markup» |