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 غير القابل للتغيير آمن للخيوط، بينما 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 قاموس [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 تجعل النص قابلًا للنقر. لمعالجة النقرات، يتم استخدام المفوض 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)