NSTextAttachment: wat is het en hoe voeg je een afbeelding toe aan tekst in iOS
NSTextAttachment is een klasse uit het UIKit-framework waarmee afbeeldingen en andere media-objecten in opgemaakte tekst kunnen worden ingebed via NSAttributedString. Het werkt op het niveau van TextKit en Core Text, en geeft ontwikkelaars controle over de grootte, positie en het gedrag van bijlagen in de tekststroom. Volgens Apple Documentation (2025) ondersteunt NSTextAttachment afbeeldingen, PDF en aangepaste weergavecontainers, en integreert het met UITextView en UILabel. Inzicht in deze API is essentieel voor het maken van Rich Text in iOS-apps, van chats en editors tot nieuwsfeeds met pictogrammen in bijschriften.
Belangrijkste punten
- NSTextAttachment — UIKit-klasse voor het inbedden van media in opgemaakte iOS-tekst.
- Afbeelding wordt toegevoegd via NSAttributedString met de sleutel NSAttachmentAttributeName.
- De eigenschap bounds bepaalt de grootte en verticale verschuiving van de bijlage.
- NSTextAttachment ondersteunt afbeeldingen, PDF en aangepaste bestanden via een datacontainer.
- API integreert met UITextView, UILabel en TextKit voor flexibele tekstlay-out.
Wat is NSTextAttachment?
NSTextAttachment is een klasse uit het UIKit-framework waarmee media-objecten rechtstreeks in de tekstinhoud van NSAttributedString kunnen worden ingebed. In tegenstelling tot een aparte UIImageView naast de tekst, maakt NSTextAttachment de afbeelding onderdeel van de tekststroom: de afbeelding beweegt mee met de regels, neemt deel aan uitlijning en neemt ruimte in als een gewoon teken.
De klasse maakt deel uit van de TextKit-architectuur die het renderen van tekst op iOS en macOS beheert. TextKit splitst tekst in glyphs, houdt rekening met kerning, ligaturen en interlinie, en NSTextAttachment wordt in deze pijplijn ingebed als een speciaal teken dat niet als letter maar als grafisch object wordt weergegeven.
Elke NSTextAttachment-instantie bevat de eigenschappen contents (bestandsgegevens), fileType (UTI-type van de inhoud) en bounds (rechthoek in points die de grootte en positie bepaalt). Volgens de Apple Human Interface Guidelines is bounds standaard gelijk aan de afbeeldingsgrootte, maar kan worden aangepast voor een exacte pasvorm op het lettertype.
Gebruik NSTextAttachment in plaats van een aparte UIImageView wanneer de afbeelding zich als onderdeel van de tekst moet gedragen, in chats, nieuwsfeeds, tekstverwerkers en formulieren met pictogrammen in invoervelden.
Een afbeelding toevoegen aan tekst via NSTextAttachment
Het basisscenario voor werken met NSTextAttachment bestaat uit drie stappen: een instantie maken, de afbeelding instellen en deze aan NSAttributedString koppelen. Laten we het proces bekijken met een Swift-voorbeeld.
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 = textNa het aanroepen van NSAttributedString(attachment:) wordt het NSTextAttachment-object omgezet in het attribuut NSAttachmentAttributeName, dat wordt gekoppeld aan een speciaal vervangend teken (object replacement character, code 0xFFFC). Dit teken wordt niet weergegeven als een letter; in plaats daarvan wordt de afbeelding uit de eigenschap image getekend.
Als de afbeelding in het midden van een tekstregel moet worden geplaatst (bijvoorbeeld een pictogram na een woord), voeg dan eenvoudig de attachmentString in op de gewenste positie in NSMutableAttributedString. TextKit houdt automatisch rekening met de regelafstand en lijnt de afbeelding uit op de basislijn.
Belangrijk: de eigenschap image is alleen beschikbaar op iOS (vanaf iOS 7). Gebruik op macOS de eigenschap contents met NSImage. Stel voor achterwaartse compatibiliteit altijd image rechtstreeks in, vertrouw niet op de datacontainer.
Bounds en positie van de bijlage configureren
Standaard geeft NSTextAttachment de afbeelding weer op de oorspronkelijke grootte in points. In de praktijk is bijna altijd aanpassing van de grootte en verticale positie nodig, hiervoor wordt de eigenschap bounds gebruikt.
De CGRect bounds-structuur bevat origin (verschuiving op X en Y) en size (breedte en hoogte). De verschuiving op Y is bijzonder belangrijk: een negatieve waarde plaatst de afbeelding onder de basislijn, een positieve waarde erboven. Een typisch scenario is het centreren van een pictogram in een tekstregel.
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
)De uitlijning wordt berekend met capHeight van het lettertype, de hoogte van een hoofdletter, niet de volledige regelafstand. Dit garandeert dat het pictogram visueel overeenkomt met de bovenrand van de tekst en niet bungelt tussen baseline en ascender. De afbeeldingsgrootte in het voorbeeld is 18×18 pt, typisch voor pictogrammen in UI-tekst.
Als de afbeelding groter moet zijn dan de tekstregel (bijvoorbeeld een fotovoorbeeld in een chat), vergroot TextKit automatisch de regelafstand voor de huidige regel. In dit geval wordt bounds ingesteld op natuurlijke grootte en is de Y-verschuiving nul.
PDF en aangepaste bijlagen
NSTextAttachment ondersteunt niet alleen PNG en JPEG, maar ook PDF-documenten en willekeurige bestanden via de eigenschap contents. Dit maakt het een universeel hulpmiddel voor Rich Text in iOS-apps.
Bij het instellen van een PDF-afbeelding in attachment.image rendert het systeem automatisch de eerste pagina van het document. Gebruik voor nauwkeurige weergave de gegevens rechtstreeks via de initialisator met data en UTI-type:
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)De parameter ofType accepteert een UTI-string (Uniform Type Identifier). Standaardtypen: public.image (elke afbeelding), public.jpeg, public.png, com.adobe.pdf. Bij het opgeven van de juiste UTI kiest het systeem de juiste rendermethode: voor PDF is dat CGPDFDocument, voor afbeeldingen CGImageSource.
Voor aangepaste bestandstypen (bijvoorbeeld vectorafbeeldingen in SVG-formaat) is een subklasse van NSTextAttachment nodig die de methode image(forBounds:textContainer:characterIndex:) overschrijft. Als standaardweergave niet geschikt is, retourneer dan nil en implementeer het tekenen via Core Graphics in de methode draw.
NSTextAttachment in UITextView en delegatie
NSTextAttachment werkt correct zowel in UILabel als in UITextView. UITextView biedt echter meer mogelijkheden: interactie met bijlagen (tikken op pictogram), het bewerken van tekst samen met afbeeldingen en ondersteuning voor NSAttachmentBehavior.
Voor het afhandelen van een tik op NSTextAttachment in UITextView wordt de delegate UITextViewDelegate gebruikt met de methode textView(_:shouldInteractWith:in:interaction:). Deze methode wordt aangeroepen wanneer de gebruiker op de bijlage tikt en maakt het mogelijk om naar een scherm te navigeren, een pop-up te openen of een animatie af te spelen.
swift
func textView(_ textView: UITextView,
shouldInteractWith attachment: NSTextAttachment,
in characterRange: NSRange,
interaction: UITextItemInteraction) -> Bool {
if interaction == .preview {
return false
}
// Detailscherm openen
showImageDetail(attachment.image)
return false
}De methode onderscheidt interactietypen via de parameter interaction: .preview (3D Touch / Haptic Touch), .default (normale tik) en .presentActions (contextmenu). Voor elk type kunt u eigen gedrag instellen of het verbieden door false te retourneren.
Bij het bewerken van UITextView met NSTextAttachment is het belangrijk te onthouden: het verwijderen van het vervangende teken (0xFFFC) verwijdert ook de bijlage. De gebruiker ziet de afbeelding als één geheel, deze wordt in zijn geheel geselecteerd, niet pixel voor pixel. Gebruik NSTextAttachmentViewProvider voor slepen van bijlagen in iOS 15+.
Veelgemaakte fouten bij NSTextAttachment
De eerste veelgemaakte fout is het negeren van bounds. Ontwikkelaars vertrouwen vaak op de oorspronkelijke afbeeldingsgrootte, wat leidt tot enorme pictogrammen in de tekst of, omgekeerd, tot amper zichtbare afbeeldingen. Stel bounds altijd expliciet in, rekening houdend met het lettertype en de context.
De tweede fout is onjuiste Y-verschuiving. Een positieve waarde in bounds.origin.y plaatst de afbeelding lager (in het UIKit-coördinatensysteem wijst de Y-as naar beneden, dit lijkt onlogisch maar zo werkt Core Graphics). Gebruik voor uitlijning in het midden van de regel de formule met capHeight van het lettertype, zoals getoond in sectie 3.
Het derde probleem is verlies van afbeelding bij wijziging van traitCollection. Wanneer de gebruiker Dark Mode of Dynamic Type inschakelt, kan de lettergrootte veranderen terwijl bounds hetzelfde blijft. Oplossing: bereken bounds dynamisch in de methode layoutSubviews of via KVO op font.
De vierde veelgemaakte fout is gebruik van NSTextAttachment in UILabel met numberOfLines > 1. In meerregelige modus met beperkte breedte verplaatst TextKit de regels correct samen met de afbeelding. Het probleem ontstaat wanneer de hoogte van de bijlage de regelafstand overschrijdt, aangrenzende regels overlappen elkaar dan. Oplossing: verhoog lineSpacing via NSMutableParagraphStyle.
Veelgestelde vragen
Wat is het verschil tussen NSTextAttachment en UIImageView in tekst?
NSTextAttachment maakt de afbeelding onderdeel van de tekststroom: het beweegt mee, wordt uitgelijnd en geschaald met de tekst. UIImageView is gebonden aan de coördinaten van de superview en neemt niet deel aan de tekstlay-out.
Kan NSTextAttachment worden toegevoegd aan UILabel?
Ja, als u de eigenschap attributedText instelt in plaats van text. UILabel geeft NSTextAttachment correct weer, maar ondersteunt geen interactiviteit. Gebruik UITextView voor tikken op de bijlage.
Hoe verander ik de afbeeldingsgrootte na het maken van een attachment?
Wijzig de eigenschap bounds van de bestaande NSTextAttachment-instantie. De tekst wordt automatisch opnieuw weergegeven met de nieuwe afmetingen, zonder dat een nieuwe NSAttributedString nodig is.
Ondersteunt NSTextAttachment geanimeerde afbeeldingen?
NSTextAttachment ondersteunt statische afbeeldingen. Voor GIF en geanimeerde formaten is een aangepaste implementatie nodig via NSTextAttachmentViewProvider in iOS 15+ of via CADisplayLink.
Hoe voeg ik NSTextAttachment programmatisch toe aan tekst?
Maak een NSTextAttachment-instantie, stel image of data in, configureer bounds, wikkel in NSAttributedString(attachment:) en voeg in via insert(_:at:) in NSMutableAttributedString.
Samenvatting
- NSTextAttachment — UIKit-klasse voor het inbedden van afbeeldingen, PDF's en andere media in opgemaakte tekst.
- Afbeelding wordt toegevoegd via NSAttributedString(attachment:) en wordt onderdeel van de tekststroom.
- De eigenschap bounds bepaalt grootte en positie: stel deze altijd expliciet in, rekening houdend met het lettertype.
- Gebruik voor het centreren van een pictogram in een regel de formule met capHeight van het huidige lettertype.
- PDF-bijlagen worden ondersteund via de initialisator met data en het juiste UTI-type.
- Gebruik UITextViewDelegate en de methode shouldInteractWith voor het afhandelen van tikken op bijlagen.
- Herbereken bounds dynamisch bij Dynamic Type-wijzigingen om overlappende regels te voorkomen.
We ontwikkelen een mobiele applicatie turnkey
IT Sectr creëert sinds 2017 iOS- en Android-applicaties voor startups en bedrijven. We adviseren u en stellen de beste oplossing voor.
Lees ook