NSAttributedString — ano ito, pag-format ng teksto at mga attribute sa iOS

Ano ang NSAttributedString?

NSAttributedString — ay isang pangunahing klase ng iOS/macOS para sa pagtatrabaho sa naka-format na teksto. Pinalalawak nito ang mga kakayahan ng NSString sa pamamagitan ng pagdaragdag ng mga attribute sa string — isang diksyunaryo ng mga pares ng key-value, kung saan ang key ay isang NSAttributedStringKey constant (hal., .font, .foregroundColor), at ang value ay ang kaukulang bagay (UIFont, UIColor). Ang bawat character sa string ay maaaring magkaroon ng sarili nitong set ng mga attribute, na nagpapahintulot sa pinaghalong pag-format sa isang string.

Ang arkitektura ng NSAttributedString ay batay sa konsepto ng mga range ng attribute (attribute runs). Kung itatakda mo ang attribute na .font = UIFont.boldSystemFont(ofSize: 16) para sa range ng mga character na 0..5, lahat ng character sa range na ito ay magpapakita sa bold na font. Ang natitirang mga character ay maaaring magkaroon ng ibang font o walang attribute. Kapag nagpapakita ng string na may attribute, pinagsasama ng UIKit system ang mga katangian mula sa iba't ibang range at ni-render ang teksto nang pare-pareho.

Ang NSAttributedString ay hindi nababago — pagkatapos ng paggawa, ang mga attribute at nilalaman nito ay hindi mababago. Para sa pagbabago, mayroong subclass na NSMutableAttributedString na nagbibigay ng mga pamamaraan para sa pagdaragdag, pagtanggal, at pagbabago ng mga attribute sa anumang range. Ang pagkakaibang ito ay mahalaga para sa multi-threading: ang hindi nababagong NSAttributedString ay thread-safe, habang ang NSMutableAttributedString ay hindi.

Mga pangunahing attribute ng pag-format ng teksto

NSAttributedString ay sumusuporta sa humigit-kumulang 40 karaniwang attribute na tinukoy sa NSAttributedStringKey. Ang bawat attribute ay nakakaapekto sa isang partikular na aspeto ng hitsura ng teksto: font, kulay, posisyon, salungguhit, anino, spacing sa pagitan ng mga character, istilo ng talata, at hyperlink. Para mag-set ng attribute, ginagamit ang constant na NSAttributedStringKey, at itinatalaga dito ang isang bagay ng kaukulang uri.

NSParagraphStyle — pag-format ng talata

NSMutableParagraphStyle — bagay na namamahala sa mga visual na katangian ng talata: alignment (.alignment: .left, .center, .right, .justified), line spacing (.lineSpacing), distansya sa pagitan ng mga talata (.paragraphSpacing), indentation ng unang linya (.firstLineHeadIndent), kaliwa at kanang indentation (.headIndent, .tailIndent) at direksyon ng teksto (.baseWritingDirection). Ang ParagraphStyle ay inilalapat sa range na may kasamang mga bagong linya na character, kung kinakailangan ang parehong pag-format para sa buong talata.

Paano gumawa ng NSAttributedString sa code

Paggawa ng NSAttributedString ay ginagawa sa pamamagitan ng initializer na tumatanggap ng string at diksyunaryo ng mga attribute. Ang mga attribute ay inilalapat sa buong string. Para sa pinaghalong pag-format (iba't ibang attribute sa iba't ibang bahagi ng string) ginagamit ang NSMutableAttributedString na may kasunod na pagdaragdag ng mga attribute sa mga tiyak na range. Ang Objective-C ay gumagamit ng diksyunaryo na NSAttributedStringKey: UIFont, habang ang Swift ay gumagamit ng type-safe na diksyunaryo na [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)

Paggawa gamit ang NSMutableParagraphStyle

Ipinapakita ng halimbawa ang pag-format ng talata sa pamamagitan ng NSMutableParagraphStyle. Itinatakda ang center alignment, line spacing na 8 puntos, distansya pagkatapos ng talata na 12 puntos. Ang ParagraphStyle ay idinaragdag sa diksyunaryo ng mga attribute sa ilalim ng key na .paragraphStyle. NSAttributedString ay kinokopya ang ibinigay na paragraphStyle, kaya pagkatapos gawin ang string, maaari itong baguhin nang hindi naaapektuhan ang nagawa nang string.

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 at pagbabago ng mga attribute

NSMutableAttributedString — ay isang subclass ng NSAttributedString na nagpapahintulot sa pagbabago ng nilalaman at mga attribute pagkatapos ng paggawa. Mga pangunahing pamamaraan: addAttribute(_:value:range:) para magdagdag ng isang attribute sa isang range; addAttributes(_:range:) para magdagdag ng maraming attribute; setAttributes(_:range:) para palitan ang lahat ng attribute sa isang range; removeAttribute(_:range:) para alisin ang isang attribute; replaceCharacters(in:with:) para palitan ang teksto.

addAttribute at addAttributes ay nagdaragdag ng mga attribute sa mga umiiral na, nang hindi inaalis ang mga nakatakda na. Kung sa range ay mayroon nang attribute na may parehong key, ang value nito ay papalitan. setAttributes ay ganap na pinapalitan ang diksyunaryo ng mga attribute para sa range — lahat ng naunang nakatakdang attribute ay aalisin. Ito ay mahalaga sa sunud-sunod na pag-format ng isang string: ang addAttributes ay mas ligtas dahil hindi nito nirerestore ang mga nakatakda nang font at kulay.

Mga Range (NSRange) ay tinukoy sa pamamagitan ng istrukturang NSRange(location: 0, length: 5). location — panimulang index (0-based), length — bilang ng mga character. Kung ang range ay lumampas sa hangganan ng string, ang NSMutableAttributedString ay bumubuo ng exception na NSRangeException. Para sa ligtas na pagtatrabaho sa mga range, ginagamit ang mga pamamaraan ng NSRange mula sa Foundation, tulad ng NSIntersectionRange at 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)

Halimbawa ng pagpapakita ng string na may attribute sa UILabel

Ang pinakakaraniwang paraan ng pagpapakita ng NSAttributedString — pagtatalaga nito sa property na attributedText ng UILabel. Hindi tulad ng property na text, ang attributedText ay gumagamit ng mga attribute para sa rendering, na sumusuporta sa pinaghalong pag-format. Mahalaga: kung nakatakda ang attributedText, binabalewala ng UILabel ang mga property na font, textColor, textAlignment — lahat ng visual na katangian ay kinuha mula sa mga attribute ng 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

Pagpapakita sa UITextView na may mga interactive na link

UITextView ay sumusuporta sa mga interactive na link sa NSAttributedString. Ang attribute na .link na may NSURL ay ginagawang clickable ang teksto. Para sa paghawak ng mga click, ginagamit ang delegate na UITextViewDelegate na may pamamaraang textView(_:shouldInteractWith:in:interaction:). Sinusuportahan din ng UITextView ang pagpili ng teksto at paggamit ng UIMenuController para sa mga karaniwang operasyon (kopya, paghahanap).

Conversion ng NSAttributedString sa HTML at RTF

NSAttributedString ay sumusuporta sa conversion mula sa HTML at RTF sa pamamagitan ng NSAttributedString.DocumentType. Para mag-load ng HTML, ginagamit ang initializer na may mga parameter na documentAttributes: NSAttributedString(data: htmlData, options: [.documentType: .html], documentAttributes: nil). Katulad para sa RTF: .rtf o .rtfd. Ang mekanismong ito ay kapaki-pakinabang para sa pagpapakita ng HTML na nilalaman nang walang WebView.

Para sa pag-export sa HTML, ginagamit ang pamamaraang data(from:documentAttributes:) na may range at uri ng dokumento. HTML export: try attributedString.data(from: fullRange, documentAttributes: [.documentType: .html]). Ang nakuhang data ay maaaring i-save sa file, ipadala sa server, o ipakita sa WebView. Sa pag-export, ang mga font, kulay, alignment, listahan ay pinapanatili — lahat ng attribute ng pag-format ay kino-convert sa mga CSS style.

Ang suporta para sa RTF ay partikular na nauugnay para sa mga macOS application, kung saan ang RTF ay ang karaniwang format ng rich text. Sinusuportahan din ng iOS ang pagbasa at pagsulat ng RTF, ngunit hindi ito ginagamit bilang pangunahing format. Ang pagkakaiba sa pagitan ng RTF at RTFD: ang RTFD ay may kasamang nested na mga mapagkukunan (mga larawan) na naka-pack sa isang direktoryo. NSAttributedString ay maaaring magproseso ng parehong format sa pamamagitan ng isang pinag-isang interface.

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)