NSAttributedString — apa itu, format teks dan atribut di iOS

Apa itu NSAttributedString?

NSAttributedString — adalah kelas fundamental iOS/macOS untuk bekerja dengan teks terformat. Ia memperluas kemampuan NSString dengan menambahkan atribut ke string — kamus pasangan kunci-nilai, di mana kuncinya adalah konstanta NSAttributedStringKey (misalnya, .font, .foregroundColor), dan nilainya adalah objek yang sesuai (UIFont, UIColor). Setiap karakter dalam string dapat memiliki kumpulan atributnya sendiri, memungkinkan pemformatan campuran dalam satu string.

Arsitektur NSAttributedString didasarkan pada konsep rentang atribut (attribute runs). Jika Anda mengatur atribut .font = UIFont.boldSystemFont(ofSize: 16) untuk rentang karakter 0..5, semua karakter dalam rentang ini akan ditampilkan dengan font tebal. Karakter lainnya dapat memiliki font berbeda atau tidak memiliki atribut sama sekali. Saat menampilkan string ber atribut, sistem UIKit menggabungkan karakteristik dari berbagai rentang dan merender teks secara seragam.

NSAttributedString bersifat tidak dapat diubah — setelah dibuat, atribut dan kontennya tidak dapat diubah. Untuk modifikasi, ada subkelas NSMutableAttributedString yang menyediakan metode untuk menambah, menghapus, dan mengubah atribut dalam rentang apa pun. Perbedaan ini penting untuk multi-threading: NSAttributedString yang tidak dapat diubah bersifat thread-safe, sedangkan NSMutableAttributedString tidak.

Atribut utama pemformatan teks

NSAttributedString mendukung sekitar 40 atribut standar yang didefinisikan dalam NSAttributedStringKey. Setiap atribut memengaruhi aspek tertentu dari tampilan teks: font, warna, posisi, garis bawah, bayangan, spasi antar karakter, gaya paragraf, dan hyperlink. Untuk mengatur atribut, digunakan konstanta NSAttributedStringKey, dan diberikan objek dari tipe yang sesuai.

NSParagraphStyle — pemformatan paragraf

NSMutableParagraphStyle — objek yang mengelola karakteristik visual paragraf: perataan (.alignment: .left, .center, .right, .justified), spasi antar baris (.lineSpacing), jarak antar paragraf (.paragraphSpacing), indentasi baris pertama (.firstLineHeadIndent), indentasi kiri dan kanan (.headIndent, .tailIndent) serta arah teks (.baseWritingDirection). ParagraphStyle diterapkan pada rentang yang mencakup karakter baris baru, jika pemformatan yang sama diperlukan untuk seluruh paragraf.

Cara membuat NSAttributedString dalam kode

Pembuatan NSAttributedString dilakukan melalui inisialisator yang menerima string dan kamus atribut. Atribut diterapkan ke seluruh string. Untuk pemformatan campuran (atribut berbeda di bagian string yang berbeda) digunakan NSMutableAttributedString dengan penambahan atribut selanjutnya ke rentang tertentu. Objective-C menggunakan kamus NSAttributedStringKey: UIFont, sedangkan Swift menggunakan kamus type-safe [NSAttributedString.Key: Any].

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)

Membuat dengan NSMutableParagraphStyle

Contoh menunjukkan pemformatan paragraf melalui NSMutableParagraphStyle. Perataan tengah, spasi antar baris 8 poin, jarak setelah paragraf 12 poin diatur. ParagraphStyle ditambahkan ke kamus atribut di bawah kunci .paragraphStyle. NSAttributedString menyalin paragraphStyle yang diberikan, sehingga setelah string dibuat, ia dapat diubah tanpa mempengaruhi string yang sudah dibuat.

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 dan mengubah atribut

NSMutableAttributedString — adalah subkelas dari NSAttributedString yang memungkinkan perubahan konten dan atribut setelah dibuat. Metode utama: addAttribute(_:value:range:) untuk menambahkan satu atribut ke rentang; addAttributes(_:range:) untuk menambahkan beberapa atribut; setAttributes(_:range:) untuk mengganti semua atribut dalam rentang; removeAttribute(_:range:) untuk menghapus atribut; replaceCharacters(in:with:) untuk mengganti teks.

addAttribute dan addAttributes menambahkan atribut ke yang sudah ada, tanpa menghapus yang sudah diatur. Jika dalam rentang sudah ada atribut dengan kunci yang sama, nilainya akan diganti. setAttributes sepenuhnya mengganti kamus atribut untuk rentang — semua atribut yang sebelumnya diatur akan dihapus. Ini penting saat memformat satu string secara berurutan: addAttributes lebih aman karena tidak mereset font dan warna yang sudah diatur.

Rentang (NSRange) didefinisikan dengan struktur NSRange(location: 0, length: 5). location — indeks awal (berbasis 0), length — jumlah karakter. Jika rentang melampaui batas string, NSMutableAttributedString menghasilkan pengecualian NSRangeException. Untuk bekerja dengan aman dengan rentang, gunakan metode NSRange dari Foundation, seperti NSIntersectionRange dan 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)

Contoh menampilkan string ber atribut di UILabel

Cara paling umum menampilkan NSAttributedString — menetapkannya ke properti attributedText UILabel. Berbeda dengan properti text, attributedText menggunakan atribut untuk rendering, mendukung pemformatan campuran. Penting: jika attributedText diatur, UILabel mengabaikan properti font, textColor, textAlignment — semua karakteristik visual diambil dari atribut NSAttributedString.

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

Menampilkan di UITextView dengan tautan interaktif

UITextView mendukung tautan interaktif dalam NSAttributedString. Atribut .link dengan NSURL membuat teks dapat diklik. Untuk menangani klik, gunakan delegasi UITextViewDelegate dengan metode textView(_:shouldInteractWith:in:interaction:). UITextView juga mendukung pemilihan teks dan penggunaan UIMenuController untuk operasi standar (salin, cari).

Konversi NSAttributedString ke HTML dan RTF

NSAttributedString mendukung konversi dari HTML dan RTF melalui NSAttributedString.DocumentType. Untuk memuat HTML, gunakan inisialisator dengan parameter documentAttributes: NSAttributedString(data: htmlData, options: [.documentType: .html], documentAttributes: nil). Demikian pula untuk RTF: .rtf atau .rtfd. Mekanisme ini berguna untuk menampilkan konten HTML tanpa WebView.

Untuk ekspor ke HTML, gunakan metode data(from:documentAttributes:) dengan rentang dan tipe dokumen. Ekspor HTML: try attributedString.data(from: fullRange, documentAttributes: [.documentType: .html]). Data yang diperoleh dapat disimpan ke file, dikirim ke server, atau ditampilkan di WebView. Saat mengekspor, font, warna, perataan, daftar dipertahankan — semua atribut pemformatan dikonversi ke gaya CSS.

Dukungan untuk RTF sangat relevan untuk aplikasi macOS, di mana RTF adalah format standar teks kaya. iOS juga mendukung pembacaan dan penulisan RTF, tetapi tidak menggunakannya sebagai format utama. Perbedaan antara RTF dan RTFD: RTFD menyertakan sumber daya bersarang (gambar) yang dikemas dalam direktori. NSAttributedString dapat memproses kedua format melalui antarmuka terpadu.

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)