NSAttributedString — mi ez, szövegformázás és attribútumok iOS-ben

Mi az NSAttributedString?

NSAttributedString — egy alapvető iOS/macOS osztály a formázott szöveggel való munkához. Kibővíti az NSString képességeit azáltal, hogy attribútumokat ad a sztringhez — egy kulcs-érték párokból álló szótárt, ahol a kulcs egy NSAttributedStringKey konstans (pl. .font, .foregroundColor), az érték pedig a megfelelő objektum (UIFont, UIColor). A sztring minden karaktere rendelkezhet saját attribútumkészlettel, ami lehetővé teszi a vegyes formázást egyetlen sztringen belül.

Az NSAttributedString architektúrája az attribútumtartományok (attribute runs) koncepcióján alapul. Ha a .font = UIFont.boldSystemFont(ofSize: 16) attribútumot állítja be a 0..5 karaktertartományra, akkor ezen tartomány összes karaktere félkövér betűtípussal jelenik meg. A többi karakter lehet más betűtípusú, vagy egyáltalán nem rendelkezhet attribútummal. Attribútumokkal ellátott sztring megjelenítésekor az UIKit rendszer kombinálja a különböző tartományok jellemzőit, és egységesen rendereli a szöveget.

Az NSAttributedString megváltoztathatatlan — létrehozás után attribútumai és tartalma nem módosítható. Módosításhoz létezik az NSMutableAttributedString alosztály, amely metódusokat biztosít attribútumok hozzáadásához, eltávolításához és módosításához bármely tartományban. Ez a különbség fontos a több szálas feldolgozás szempontjából: a megváltoztathatatlan NSAttributedString thread-safe, míg az NSMutableAttributedString nem.

A szövegformázás fő attribútumai

NSAttributedString körülbelül 40, az NSAttributedStringKey-ben meghatározott szabványos attribútumot támogat. Minden attribútum a szöveg megjelenésének egy adott aspektusát befolyásolja: betűtípus, szín, pozíció, aláhúzás, árnyék, karakterköz, bekezdésstílus és hiperhivatkozások. Attribútum beállításához az NSAttributedStringKey konstanst használjuk, és egy megfelelő típusú objektumot rendelünk hozzá.

NSParagraphStyle — bekezdésformázás

NSMutableParagraphStyle — objektum, amely a bekezdés vizuális jellemzőit kezeli: igazítás (.alignment: .left, .center, .right, .justified), sorköz (.lineSpacing), bekezdések közötti távolság (.paragraphSpacing), első sor behúzása (.firstLineHeadIndent), bal és jobb behúzás (.headIndent, .tailIndent) és szövegirány (.baseWritingDirection). A ParagraphStyle arra a tartományra alkalmazandó, amely új sor karaktereket tartalmaz, ha azonos formázás szükséges a teljes bekezdéshez.

Hogyan hozzunk létre NSAttributedString-et kódban

Létrehozás Az NSAttributedString egy inicializálón keresztül történik, amely egy sztringet és egy attribútumszótárt fogad. Az attribútumok a teljes sztringre alkalmazandók. Vegyes formázáshoz (különböző attribútumok a sztring különböző részein) NSMutableAttributedString-t használunk az attribútumok későbbi hozzáadásával meghatározott tartományokhoz. Az Objective-C az NSAttributedStringKey: UIFont szótárt használja, míg a Swift a típusbiztos [NSAttributedString.Key: Any] szótárt.

let plainText = "Hello, Swift!"

// Create with uniform attributes for the entire string
let attributes: [NSAttributedString.Key: Any] = [
    NSAttributedString.Key.font:
        UIFont.systemFont(ofSize: 18),
    NSAttributedString.Key.foregroundColor:
        UIColor.darkText,
    NSAttributedString.Key.kern: 1.5
]

let attributedString =
    NSAttributedString(string: plainText,
                        attributes: attributes)

Létrehozás NSMutableParagraphStyle-lel

A példa a bekezdésformázást mutatja be NSMutableParagraphStyle segítségével. Középre igazítás, 8 pontos sorköz, 12 pontos távolság a bekezdés után. A ParagraphStyle a .paragraphStyle kulcs alatt kerül az attribútumszótárba. NSAttributedString másolatot készít a kapott paragraphStyle-ról, így a sztring létrehozása után az módosítható anélkül, hogy a már létrehozott sztringre hatással lenne.

let paragraphStyle = NSMutableParagraphStyle()
paragraphStyle.alignment = NSTextAlignment.center
paragraphStyle.lineSpacing = 8.0
paragraphStyle.paragraphSpacing = 12.0
paragraphStyle.firstLineHeadIndent = 20.0

let attributed = NSAttributedString(
    string: "Centered paragraph with spacing",
    attributes: [NSAttributedString.Key.paragraphStyle: paragraphStyle])

NSMutableAttributedString és attribútumok módosítása

NSMutableAttributedString — az NSAttributedString egy alosztálya, amely lehetővé teszi a tartalom és attribútumok módosítását a létrehozás után. Fő metódusok: addAttribute(_:value:range:) egy attribútum hozzáadásához egy tartományhoz; addAttributes(_:range:) több attribútum hozzáadásához; setAttributes(_:range:) az összes attribútum cseréjéhez egy tartományban; removeAttribute(_:range:) attribútum eltávolításához; replaceCharacters(in:with:) szöveg cseréjéhez.

Az addAttribute és addAttributes attribútumokat ad a meglévőkhöz, anélkül hogy eltávolítaná a már beállítottakat. Ha a tartományban már létezik attribútum ugyanazzal a kulccsal, annak értéke lecserélődik. A setAttributes teljesen lecseréli az attribútumszótárt a tartomány számára — az összes korábban beállított attribútum eltávolításra kerül. Ez fontos egy sztring szekvenciális formázásakor: az addAttributes biztonságosabb, mert nem állítja vissza a már beállított betűtípusokat és színeket.

Tartományok (NSRange) meghatározása az NSRange(location: 0, length: 5) struktúrával történik. location — kezdő index (0-alapú), length — karakterek száma. Ha a tartomány túllépi a sztring határait, az NSMutableAttributedString NSRangeException kivételt generál. A tartományokkal való biztonságos munkához a Foundation NSRange metódusai használatosak, mint például NSIntersectionRange és NSUnionRange.

let attributed = NSMutableAttributedString(
    string: "Bold and red text here")

// Apply bold font to first 9 characters
let boldRange = NSRange(location: 0, length: 9)
attributed.addAttribute(
    NSAttributedString.Key.font,
    value: UIFont.boldSystemFont(ofSize: 16),
    range: boldRange)

// Apply red color to characters 13-16 ("text")
let redRange = NSRange(location: 13, length: 4)
attributed.addAttribute(
    NSAttributedString.Key.foregroundColor,
    value: UIColor.red,
    range: redRange)

// Apply underline to the entire string
let fullRange = NSRange(location: 0,
                       length: attributed.length)
attributed.addAttribute(
    NSAttributedString.Key.underlineStyle,
    value: NSUnderlineStyle.single.rawValue,
    range: fullRange)

Példa attribútumokkal ellátott sztring megjelenítésére UILabel-ben

A leggyakoribb módszer az NSAttributedString megjelenítésére — hozzárendelése a UILabel attributedText tulajdonságához. A text tulajdonságtól eltérően az attributedText attribútumokat használ a rendereléshez, támogatva a vegyes formázást. Fontos: ha az attributedText be van állítva, a UILabel figyelmen kívül hagyja a font, textColor, textAlignment tulajdonságokat — az összes vizuális jellemző az NSAttributedString attribútumaiból származik.

let label = UILabel()
label.numberOfLines = 0

let fullText = NSMutableAttributedString(
    string: "Price: $24.99 per month")

// Format "Price:" label with bold font
let priceLabelRange = NSRange(
    location: 0, length: 6)
fullText.addAttribute(
    NSAttributedString.Key.font,
    value: UIFont.boldSystemFont(ofSize: 16),
    range: priceLabelRange)

// Format "$24.99" with green color
let amountRange = NSRange(
    location: 7, length: 6)
fullText.addAttribute(
    NSAttributedString.Key.foregroundColor,
    value: UIColor.systemGreen(),
    range: amountRange)
fullText.addAttribute(
    NSAttributedString.Key.font,
    value: UIFont.boldSystemFont(ofSize: 22),
    range: amountRange)

// Apply gray color to "per month" text
let periodRange = NSRange(
    location: 14, length: 9)
fullText.addAttribute(
    NSAttributedString.Key.foregroundColor,
    value: UIColor.secondaryLabel,
    range: periodRange)

label.attributedText = fullText

Megjelenítés UITextView-ben interaktív hivatkozásokkal

UITextView támogatja az interaktív hivatkozásokat az NSAttributedString-ben. A .link attribútum NSURL-lel kattinthatóvá teszi a szöveget. A kattintások kezeléséhez a UITextViewDelegate delegáltat használjuk a textView(_:shouldInteractWith:in:interaction:) metódussal. A UITextView támogatja továbbá a szöveg kijelölését és a UIMenuController használatát szabványos műveletekhez (másolás, keresés).

NSAttributedString konvertálása HTML-be és RTF-be

NSAttributedString támogatja a konvertálást HTML-ből és RTF-ből az NSAttributedString.DocumentType segítségével. HTML betöltéséhez a documentAttributes paraméterekkel rendelkező inicializálót használjuk: NSAttributedString(data: htmlData, options: [.documentType: .html], documentAttributes: nil). Hasonlóan RTF esetén: .rtf vagy .rtfd. Ez a mechanizmus hasznos HTML-tartalom megjelenítéséhez WebView nélkül.

HTML-be történő exportáláshoz a data(from:documentAttributes:) metódust használjuk tartománnyal és dokumentumtípussal. HTML export: try attributedString.data(from: fullRange, documentAttributes: [.documentType: .html]). A kapott adatok menthetők fájlba, elküldhetők a szerverre vagy megjeleníthetők WebView-ban. Exportáláskor a betűtípusok, színek, igazítás, listák megmaradnak — az összes formázási attribútum CSS-stílusokká konvertálódik.

Az RTF támogatás különösen releváns macOS alkalmazásokhoz, ahol az RTF a dúsított szöveg szabványos formátuma. Az iOS is támogatja az RTF olvasását és írását, de nem használja elsődleges formátumként. Az RTF és RTFD közötti különbség: az RTFD beágyazott erőforrásokat (képeket) tartalmaz egy könyvtárba csomagolva. NSAttributedString mindkét formátumot képes feldolgozni egységes interfészen keresztül.

let htmlString = "<p><b>Bold<\/b> and <i>italic<\/i><\/p>"
guard let htmlData = htmlString.data(
    using: String.Encoding.utf8) else { return }

let options: [NSAttributedString.DocumentReadingOptionKey: Any] = [
    NSAttributedString.DocumentReadingOptionKey.documentType:
        NSAttributedString.DocumentType.html
]

let attributedFromHTML =
    try? NSAttributedString(
        data: htmlData,
        options: options,
        documentAttributes: nil)