NSAttributedString — چیست، قالب‌بندی متن و ویژگی‌ها در iOS

NSAttributedString چیست؟

NSAttributedString — یک کلاس اساسی iOS/macOS برای کار با متن قالب‌بندی شده است. این کلاس قابلیت‌های NSString را گسترش می‌دهد و به رشته ویژگی‌هایی اضافه می‌کند — یک فرهنگ لغت از جفت‌های کلید-مقدار، جایی که کلید یک ثابت NSAttributedStringKey است (مثلاً .font، .foregroundColor) و مقدار شیء مربوطه (UIFont, UIColor). هر کاراکتر در رشته می‌تواند مجموعه ویژگی‌های خاص خود را داشته باشد که امکان قالب‌بندی ترکیبی در یک رشته را فراهم می‌کند.

معماری NSAttributedString بر اساس مفهوم محدوده‌های ویژگی (attribute runs) است. اگر ویژگی .font = UIFont.boldSystemFont(ofSize: 16) را برای محدوده کاراکترهای 0..5 تنظیم کنید، همه کاراکترهای این محدوده با فونت پررنگ نمایش داده می‌شوند. سایر کاراکترها می‌توانند فونت دیگری داشته باشند یا اصلاً ویژگی نداشته باشند. هنگام نمایش رشته دارای ویژگی، سیستم UIKit ویژگی‌های محدوده‌های مختلف را ترکیب کرده و متن را به صورت یکپارچه رندر می‌کند.

NSAttributedString تغییرناپذیر است — پس از ایجاد، ویژگی‌ها و محتوای آن قابل تغییر نیستند. برای تغییر، زیرکلاس NSMutableAttributedString وجود دارد که متدهایی برای افزودن، حذف و تغییر ویژگی‌ها در هر محدوده‌ای ارائه می‌دهد. این تفاوت برای چندنخی مهم است: NSAttributedString تغییرناپذیر thread-safe است، اما NSMutableAttributedString خیر.

ویژگی‌های اصلی قالب‌بندی متن

NSAttributedString حدود 40 ویژگی استاندارد تعریف شده در NSAttributedStringKey را پشتیبانی می‌کند. هر ویژگی بر جنبه خاصی از ظاهر متن تأثیر می‌گذارد: فونت، رنگ، موقعیت، زیرخط، سایه، فاصله بین کاراکترها، سبک پاراگراف و پیوندها. برای تنظیم یک ویژگی از ثابت NSAttributedStringKey استفاده می‌شود و یک شیء از نوع مربوطه به آن اختصاص داده می‌شود.

NSParagraphStyle — قالب‌بندی پاراگراف

NSMutableParagraphStyle — شیءای که ویژگی‌های بصری پاراگراف را مدیریت می‌کند: ترازبندی (.alignment: .left, .center, .right, .justified)، فاصله بین خطوط (.lineSpacing)، فاصله بین پاراگراف‌ها (.paragraphSpacing)، تورفتگی خط اول (.firstLineHeadIndent)، تورفتگی چپ و راست (.headIndent, .tailIndent) و جهت نوشتار (.baseWritingDirection). ParagraphStyle به محدوده‌ای اعمال می‌شود که شامل کاراکترهای خط جدید است، اگر قالب‌بندی یکسان برای کل پاراگراف مورد نیاز باشد.

چگونه NSAttributedString در کد ایجاد کنیم

ایجاد NSAttributedString از طریق مقداردهنده اولیه‌ای انجام می‌شود که یک رشته و یک فرهنگ لغت از ویژگی‌ها را می‌پذیرد. ویژگی‌ها به کل رشته اعمال می‌شوند. برای قالب‌بندی ترکیبی (ویژگی‌های مختلف در بخش‌های مختلف رشته) از NSMutableAttributedString با افزودن بعدی ویژگی‌ها به محدوده‌های خاص استفاده می‌شود. Objective-C از فرهنگ لغت NSAttributedStringKey: UIFont استفاده می‌کند، در حالی که Swift از فرهنگ لغت 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)

ایجاد با NSMutableParagraphStyle

مثال قالب‌بندی پاراگراف را از طریق NSMutableParagraphStyle نشان می‌دهد. ترازبندی مرکز، فاصله بین خطوط 8 پوینت، فاصله بعد از پاراگراف 12 پوینت تنظیم می‌شود. ParagraphStyle به فرهنگ لغت ویژگی‌ها تحت کلید .paragraphStyle اضافه می‌شود. NSAttributedString paragraphStyle ارسالی را کپی می‌کند، بنابراین پس از ایجاد رشته می‌توان آن را بدون تأثیر بر رشته از قبل ایجاد شده تغییر داد.

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 و تغییر ویژگی‌ها

NSMutableAttributedString — زیرکلاسی از NSAttributedString است که امکان تغییر محتوا و ویژگی‌ها را پس از ایجاد فراهم می‌کند. متدهای اصلی: addAttribute(_:value:range:) برای افزودن یک ویژگی به یک محدوده؛ addAttributes(_:range:) برای افزودن چندین ویژگی؛ setAttributes(_:range:) برای جایگزینی همه ویژگی‌ها در یک محدوده؛ removeAttribute(_:range:) برای حذف یک ویژگی؛ replaceCharacters(in:with:) برای جایگزینی متن.

addAttribute و addAttributes ویژگی‌ها را به ویژگی‌های موجود اضافه می‌کنند، بدون حذف موارد از پیش تعیین شده. اگر در محدوده قبلاً ویژگی با همان کلید وجود داشته باشد، مقدار آن جایگزین می‌شود. setAttributes فرهنگ لغت ویژگی‌ها را برای محدوده به طور کامل جایگزین می‌کند — همه ویژگی‌های قبلاً تنظیم شده حذف می‌شوند. این نکته در قالب‌بندی متوالی یک رشته مهم است: addAttributes ایمن‌تر است زیرا فونت‌ها و رنگ‌های از قبل تنظیم شده را بازنشانی نمی‌کند.

محدوده‌ها (NSRange) با ساختار NSRange(location: 0, length: 5) تعریف می‌شوند. location — شاخص شروع (مبتنی بر 0)، length — تعداد کاراکترها. اگر محدوده از مرزهای رشته خارج شود، NSMutableAttributedString استثنای NSRangeException ایجاد می‌کند. برای کار ایمن با محدوده‌ها از متدهای NSRange از Foundation مانند NSIntersectionRange و 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)

نمایش رشته دارای ویژگی در UILabel

رایج‌ترین روش نمایش NSAttributedString — اختصاص آن به ویژگی attributedText UILabel است. برخلاف ویژگی text، attributedText از ویژگی‌ها برای رندر استفاده می‌کند و از قالب‌بندی ترکیبی پشتیبانی می‌کند. مهم: اگر attributedText تنظیم شده باشد، UILabel ویژگی‌های font، textColor، textAlignment را نادیده می‌گیرد — همه ویژگی‌های بصری از ویژگی‌های 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

نمایش در UITextView با پیوندهای تعاملی

UITextView از پیوندهای تعاملی در NSAttributedString پشتیبانی می‌کند. ویژگی .link با NSURL متن را قابل کلیک می‌کند. برای مدیریت کلیک‌ها از delegate UITextViewDelegate با متد textView(_:shouldInteractWith:in:interaction:) استفاده می‌شود. UITextView همچنین از انتخاب متن و استفاده از UIMenuController برای عملیات استاندارد (کپی، جستجو) پشتیبانی می‌کند.

تبدیل NSAttributedString به HTML و RTF

NSAttributedString از تبدیل از HTML و RTF از طریق NSAttributedString.DocumentType پشتیبانی می‌کند. برای بارگذاری HTML از مقداردهنده اولیه با پارامترهای documentAttributes استفاده می‌شود: NSAttributedString(data: htmlData, options: [.documentType: .html], documentAttributes: nil). به طور مشابه برای RTF: .rtf یا .rtfd. این مکانیزم برای نمایش محتوای HTML بدون WebView مفید است.

برای خروجی به HTML از متد data(from:documentAttributes:) با محدوده و نوع سند استفاده می‌شود. خروجی HTML: try attributedString.data(from: fullRange, documentAttributes: [.documentType: .html]). داده‌های به‌دست آمده را می‌توان در فایل ذخیره کرد، به سرور ارسال کرد یا در WebView نمایش داد. در هنگام خروجی، فونت‌ها، رنگ‌ها، ترازبندی، لیست‌ها حفظ می‌شوند — همه ویژگی‌های قالب‌بندی به استایل‌های CSS تبدیل می‌شوند.

پشتیبانی از RTF به ویژه برای برنامه‌های macOS که RTF فرمت استاندارد متن غنی است، مرتبط است. iOS نیز خواندن و نوشتن RTF را پشتیبانی می‌کند، اما از آن به عنوان فرمت اصلی استفاده نمی‌کند. تفاوت بین RTF و RTFD: RTFD شامل منابع تو در تو (تصاویر) بسته‌بندی شده در یک دایرکتوری است. NSAttributedString می‌تواند هر دو فرمت را از طریق یک رابط واحد پردازش کند.

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)