NSTextAttachment: Was es ist und wie man ein Bild in Text auf iOS einfügt
NSTextAttachment ist eine Klasse aus dem UIKit-Framework, die das Einbetten von Bildern und anderen Medienobjekten in formatierten Text über NSAttributedString ermöglicht. Es arbeitet auf der Ebene von TextKit und Core Text und gibt Entwicklern Kontrolle über Größe, Position und Verhalten von Anhängen innerhalb des Textflusses. Laut Apple Documentation (2025) unterstützt NSTextAttachment Bilder, PDF und benutzerdefinierte View-Container und integriert sich mit UITextView und UILabel. Das Verständnis dieser API ist für die Erstellung von Rich Text in iOS-Anwendungen erforderlich — von Chats und Editoren bis hin zu Nachrichtenfeeds mit Symbolen in Bildunterschriften.
Wichtige Punkte
- NSTextAttachment ist eine UIKit-Klasse zum Einbetten von Medien in formatierten iOS-Text.
- Ein Bild wird über NSAttributedString mit dem Schlüssel NSAttachmentAttributeName hinzugefügt.
- Die Eigenschaft bounds steuert die Größe und den vertikalen Versatz des Anhangs.
- NSTextAttachment unterstützt Bilder, PDF und benutzerdefinierte Dateien über einen Datencontainer.
- Die API integriert sich mit UITextView, UILabel und TextKit für flexibles Textlayout.
Was ist NSTextAttachment?
NSTextAttachment ist eine Klasse aus dem UIKit-Framework, die das Einbetten von Medienobjekten direkt in den Textinhalt von NSAttributedString ermöglicht. Im Gegensatz zu einem separaten UIImageView, der neben dem Text platziert wird, macht NSTextAttachment das Bild zum Teil des Textflusses: Das Bild wird mit Zeilen umgebrochen, nimmt an der Ausrichtung teil und belegt Platz wie ein normales Zeichen.
Die Klasse ist Teil der TextKit-Architektur, die die Textdarstellung auf iOS und macOS verwaltet. TextKit zerlegt Text in Glyphen, berücksichtigt Kerning, Ligaturen und Zeilenabstände — und NSTextAttachment fügt sich in diese Pipeline als spezielles Zeichen ein, das nicht als Buchstabe, sondern als grafisches Objekt gerendert wird.
Jede Instanz von NSTextAttachment enthält contents (Dateidaten), fileType (UTI-Inhaltstyp) und bounds (ein Rechteck in Points, das Größe und Position definiert). Laut Apple Human Interface Guidelines entspricht bounds standardmäßig der Bildgröße, kann aber für eine präzise Anpassung an die Schriftart geändert werden.
Verwenden Sie NSTextAttachment anstelle eines separaten UIImageView, wenn sich das Bild als Teil des Textes verhalten soll — in Chats, Nachrichtenfeeds, Texteditoren und Formularen mit Symbolen in Eingabefeldern.
Wie man ein Bild über NSTextAttachment in Text einfügt
Der grundlegende Arbeitsablauf mit NSTextAttachment besteht aus drei Schritten: Instanz erstellen, Bild festlegen und an NSAttributedString anhängen. Sehen wir uns den Prozess anhand von Swift an.
swift
let attachment = NSTextAttachment()
attachment.image = UIImage(named: "icon-star")
let attachmentString = NSAttributedString(attachment: attachment)
let text = NSMutableAttributedString(string: "Rating: ")
text.append(attachmentString)
let label = UILabel()
label.attributedText = textNach dem Aufruf von NSAttributedString(attachment:) wird das NSTextAttachment-Objekt in das Attribut NSAttachmentAttributeName umgewandelt, das an ein spezielles Objektersetzungszeichen (Code 0xFFFC) angehängt wird. Dieses Zeichen wird nicht als Buchstabe angezeigt — stattdessen wird das Bild aus der image-Eigenschaft an seiner Stelle gezeichnet.
Wenn das Bild in der Mitte einer Textzeile platziert werden soll (z. B. ein Symbol nach einem Wort), fügen Sie einfach den attachmentString an der gewünschten Position in NSMutableAttributedString ein. TextKit berücksichtigt automatisch die Zeilenhöhe und richtet das Bild an der Grundlinie aus.
Wichtig: Die Eigenschaft image ist nur unter iOS verfügbar (seit iOS 7). Unter macOS verwenden Sie die Eigenschaft contents mit NSImage. Aus Gründen der Abwärtskompatibilität sollten Sie es immer vorziehen, image direkt festzulegen, anstatt sich auf den Datencontainer zu verlassen.
Konfiguration von bounds und Anhangposition
Standardmäßig zeigt NSTextAttachment das Bild in seiner ursprünglichen Größe in Points an. In der Praxis ist fast immer eine Anpassung der Größe und vertikalen Position erforderlich — dies erfolgt über die bounds-Eigenschaft.
Die CGRect-bounds-Struktur enthält origin (Versatz in X und Y) und size (Breite und Höhe). Der Y-Versatz ist besonders wichtig: Ein negativer Wert verschiebt das Bild unter die Grundlinie, ein positiver Wert hebt es an. Ein typisches Szenario ist die Ausrichtung eines Symbols in der Mitte einer Textzeile.
swift
let attachment = NSTextAttachment()
attachment.image = UIImage(named: "icon-star")
let font = UIFont.systemFont(ofSize: 16)
let fontCapHeight = font.capHeight
let imageSize = CGSize(width: 18, height: 18)
attachment.bounds = CGRect(
x: 0,
y: (fontCapHeight - imageSize.height) / 2,
width: imageSize.width,
height: imageSize.height
)Die Ausrichtungsberechnung verwendet die capHeight der Schriftart — die Höhe eines Großbuchstabens, nicht die vollständige Zeilenhöhe. Dadurch wird sichergestellt, dass das Symbol visuell mit der Oberkante des Textes übereinstimmt, anstatt zwischen Grundlinie und Oberlänge zu schweben. Die Bildgröße im Beispiel beträgt 18×18 pt, was typisch für Symbole in UI-Text ist.
Wenn das Bild größer als die Textzeile sein soll (z. B. eine Foto-Vorschau in einem Chat), erhöht TextKit automatisch den Zeilenabstand für die aktuelle Zeile. In diesem Fall sollte bounds auf die natürliche Größe und der Y-Versatz auf Null gesetzt werden.
PDF und benutzerdefinierte Anhänge
NSTextAttachment unterstützt nicht nur PNG und JPEG, sondern auch PDF-Dokumente sowie beliebige Dateien über die contents-Eigenschaft. Dies macht es zu einem universellen Werkzeug für Rich Text in iOS-Anwendungen.
Beim Festlegen eines PDF-Bildes in attachment.image rendert das System automatisch die erste Seite des Dokuments. Für eine präzise Darstellung verwenden Sie die Daten jedoch direkt über den Initialisierer mit Daten und UTI-Typ:
swift
guard let pdfData = Bundle.main.url(forResource: "document",
withExtension: "pdf") else { return }
let fileData = Data(contentsOf: pdfData)
let attachment = NSTextAttachment(data: fileData,
ofType: "com.adobe.pdf")
attachment.bounds = CGRect(x: 0, y: -4,
width: 24, height: 24)
let pdfString = NSAttributedString(attachment: attachment)Der Parameter ofType akzeptiert einen UTI-String (Uniform Type Identifier). Zu den Standardtypen gehören: public.image (beliebiges Bild), public.jpeg, public.png, com.adobe.pdf. Bei Angabe der korrekten UTI wählt das System die geeignete Rendermethode — für PDF ist dies CGPDFDocument, für Bilder CGImageSource.
Für benutzerdefinierte Dateitypen (z. B. Vektorgrafiken im SVG-Format) benötigen Sie eine Unterklasse von NSTextAttachment, die die Methode image(forBounds:textContainer:characterIndex:) überschreibt. Wenn die Standarddarstellung nicht geeignet ist, geben Sie nil zurück und implementieren Sie das Zeichnen über Core Graphics in der draw-Methode.
NSTextAttachment in UITextView und Delegierung
NSTextAttachment funktioniert sowohl in UILabel als auch in UITextView korrekt. UITextView bietet jedoch mehr Möglichkeiten: Interaktion mit Anhängen (Tippen auf ein Symbol), Bearbeiten von Text zusammen mit Bildern und Unterstützung für NSAttachmentBehavior.
Zur Behandlung von Taps auf NSTextAttachment in UITextView verwenden Sie das UITextViewDelegate-Protokoll und die Methode textView(_:shouldInteractWith:in:interaction:). Diese Methode wird aufgerufen, wenn der Benutzer auf einen Anhang tippt, und ermöglicht die Navigation zu einem Bildschirm, das Öffnen eines Popups oder das Abspielen einer Animation.
swift
func textView(_ textView: UITextView,
shouldInteractWith attachment: NSTextAttachment,
in characterRange: NSRange,
interaction: UITextItemInteraction) -> Bool {
if interaction == .preview {
return false
}
// Detailscreen öffnen
showImageDetail(attachment.image)
return false
}Die Methode unterscheidet Interaktionstypen über den interaction-Parameter: .preview (3D Touch / Haptic Touch), .default (normaler Tap) und .presentActions (Kontextmenü). Für jeden Typ können Sie ein eigenes Verhalten definieren oder es durch Rückgabe von false deaktivieren.
Beim Bearbeiten von UITextView mit NSTextAttachment ist wichtig zu beachten: Das Löschen des Ersatzzeichens (0xFFFC) löscht auch den Anhang. Der Benutzer sieht das Bild als einzelnes Element — es wird als Ganzes ausgewählt, nicht Pixel für Pixel. Für Drag-and-Drop-Unterstützung von Anhängen unter iOS 15+ verwenden Sie NSTextAttachmentViewProvider.
Häufige Fehler bei der Arbeit mit NSTextAttachment
Der erste häufige Fehler ist das Ignorieren von bounds. Entwickler verlassen sich oft auf die ursprüngliche Bildgröße, was zu riesigen Symbolen im Text oder umgekehrt zu kaum sichtbaren Bildern führt. Setzen Sie bounds immer explizit unter Berücksichtigung der Schriftart und des Kontexts.
Der zweite Fehler ist ein falscher Y-Versatz. Ein positiver Wert in bounds.origin.y verschiebt das Bild nach unten (im Koordinatensystem von UIKit zeigt die Y-Achse nach unten — das erscheint unintuitiv, aber so funktioniert Core Graphics). Für die Zentrierung innerhalb einer Zeile verwenden Sie die Formel mit der capHeight der Schriftart, wie in Abschnitt 3 gezeigt.
Das dritte Problem ist der Bildverlust bei Änderung von traitCollection. Wenn der Benutzer den Dunkelmodus oder Dynamic Type umschaltet, kann sich die Schriftgröße ändern, aber bounds bleiben gleich. Die Lösung besteht darin, bounds dynamisch in der layoutSubviews-Methode oder über KVO auf font zu berechnen.
Der vierte häufige Fehler ist die Verwendung von NSTextAttachment in UILabel mit numberOfLines > 1. Im mehrzeiligen Modus mit begrenzter Breite bricht TextKit Zeilen zusammen mit dem Bild korrekt um. Das Problem tritt auf, wenn die Höhe des Anhangs die Zeilenhöhe überschreitet — benachbarte Zeilen überlappen sich. Die Lösung besteht darin, den lineSpacing über NSMutableParagraphStyle zu erhöhen.
Häufig gestellte Fragen
Wie unterscheidet sich NSTextAttachment von UIImageView im Text?
NSTextAttachment macht das Bild zum Teil des Textflusses: Es wird mit dem Text umbrochen, ausgerichtet und skaliert. UIImageView ist an die Koordinaten der Superview gebunden und nimmt nicht am Textlayout teil.
Kann ich NSTextAttachment zu UILabel hinzufügen?
Ja, wenn Sie die Eigenschaft attributedText anstelle von text setzen. UILabel zeigt NSTextAttachment korrekt an, unterstützt jedoch keine Interaktivität. Für Taps auf den Anhang verwenden Sie UITextView.
Wie ändere ich die Bildgröße nach dem Erstellen des Anhangs?
Ändern Sie die bounds-Eigenschaft der vorhandenen NSTextAttachment-Instanz. Der Text wird automatisch mit den neuen Größen neu gerendert, ohne dass ein neues NSAttributedString erstellt werden muss.
Unterstützt NSTextAttachment animierte Bilder?
NSTextAttachment unterstützt statische Bilder. Für GIF und animierte Formate ist eine benutzerdefinierte Implementierung über NSTextAttachmentViewProvider unter iOS 15+ oder über CADisplayLink erforderlich.
Wie füge ich NSTextAttachment programmatisch zu Text hinzu?
Erstellen Sie eine NSTextAttachment-Instanz, legen Sie Bild oder Daten fest, setzen Sie bounds, wickeln Sie es in NSAttributedString(attachment:) ein und fügen Sie es mit der Methode insert(_:at:) in NSMutableAttributedString ein.
Zusammenfassung
- NSTextAttachment ist eine UIKit-Klasse zum Einbetten von Bildern, PDF und anderen Medien in formatierten Text.
- Ein Bild wird über NSAttributedString(attachment:) hinzugefügt und wird Teil des Textflusses.
- Die bounds-Eigenschaft steuert Größe und Position: Setzen Sie sie immer explizit unter Berücksichtigung der Schriftart.
- Um ein Symbol innerhalb einer Zeile zu zentrieren, verwenden Sie die Formel mit der capHeight der aktuellen Schriftart.
- PDF-Anhänge werden über den Initialisierer mit data und dem korrekten UTI-Typ unterstützt.
- Zur Behandlung von Taps auf Anhänge verwenden Sie UITextViewDelegate und die shouldInteractWith-Methode.
- Bei Änderung von Dynamic Type berechnen Sie bounds dynamisch neu, um Zeilenüberlappungen zu vermeiden.
Wir entwickeln eine mobile Applikation schlüsselfertig
IT Sectr entwickelt seit 2017 iOS- und Android-Apps für Startups und Unternehmen. Wir beraten Sie und schlagen die beste Lösung vor.
Lesen Sie auch