NSAttributedString — یہ کیا ہے، ٹیکسٹ فارمیٹنگ اور iOS میں خصوصیات

NSAttributedString کیا ہے؟

NSAttributedString فارمیٹ شدہ ٹیکسٹ کے ساتھ کام کرنے کے لیے ایک بنیادی iOS/macOS کلاس ہے۔ یہ سٹرنگ میں خصوصیات (کلید-قدر کے جوڑوں کی ایک ڈکشنری جہاں کلید ایک NSAttributedStringKey مستقل (مثلاً، .font، .foregroundColor) ہے اور قدر متعلقہ آبجیکٹ (UIFont، UIColor) ہے) شامل کرکے NSString کو بڑھاتا ہے۔ سٹرنگ کا ہر حرف اپنی خصوصیات کا سیٹ رکھ سکتا ہے، جو ایک ہی سٹرنگ کے اندر مخلوط فارمیٹنگ کو قابل بناتا ہے۔

NSAttributedString کا فن تعمیر خصوصیت کے رنز (attribute runs) کے تصور پر مبنی ہے۔ اگر آپ حروف کی رینج 0..5 کے لیے .font خصوصیت کو UIFont.boldSystemFont(ofSize: 16) پر سیٹ کرتے ہیں، تو اس رینج کے تمام حروف بولڈ میں ظاہر ہوں گے۔ دوسرے حروف کا مختلف فونٹ ہو سکتا ہے یا کوئی خصوصیت نہیں ہو سکتی۔ خصوصیات والی سٹرنگ رینڈر کرتے وقت، UIKit سسٹم مختلف رینجز کی خصوصیات کو ضم کرتا ہے اور ٹیکسٹ کو یکساں طور پر رینڈر کرتا ہے۔

NSAttributedString ناقابل تغیر ہے — تخلیق کے بعد، اس کی خصوصیات اور مواد تبدیل نہیں کیا جا سکتا۔ ترمیم کے لیے، NSMutableAttributedString ذیلی کلاس موجود ہے، جو کسی بھی رینج میں خصوصیات کو شامل کرنے، ہٹانے اور تبدیل کرنے کے طریقے فراہم کرتی ہے۔ یہ فرق ملٹی تھریڈنگ کے لیے اہم ہے: ناقابل تغیر NSAttributedString تھریڈ محفوظ ہے، جبکہ NSMutableAttributedString نہیں ہے۔

ٹیکسٹ فارمیٹنگ کی بنیادی خصوصیات

NSAttributedString NSAttributedStringKey میں متعین تقریباً 40 معیاری خصوصیات کو سپورٹ کرتا ہے۔ ہر خصوصیت ٹیکسٹ کی ظاہری شکل کے ایک مخصوص پہلو کو متاثر کرتی ہے: فونٹ، رنگ، پوزیشن، انڈر لائن، سایہ، کرننگ، پیراگراف اسٹائل اور ہائپر لنکس۔ خصوصیت سیٹ کرنے کے لیے، آپ ایک NSAttributedStringKey مستقل استعمال کرتے ہیں اور اسے متعلقہ قسم کا ایک آبجیکٹ تفویض کرتے ہیں۔

NSParagraphStyle — پیراگراف فارمیٹنگ

NSMutableParagraphStyle ایک آبجیکٹ ہے جو پیراگراف کی بصری خصوصیات کا انتظام کرتا ہے: سیدھ (.alignment: .left, .center, .right, .justified)، لائن کا فاصلہ (.lineSpacing)، پیراگراف کا فاصلہ (.paragraphSpacing)، پہلی لائن کا انڈینٹ (.firstLineHeadIndent)، بائیں اور دائیں انڈینٹیشن (.headIndent, .tailIndent) اور ٹیکسٹ کی سمت (.baseWritingDirection)۔ ParagraphStyle ایک ایسی رینج پر لاگو کیا جاتا ہے جس میں نیو لائن حروف شامل ہوں اگر پورے پیراگراف کے لیے ایک ہی فارمیٹنگ کی ضرورت ہو۔

کوڈ میں 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 پھینکتا ہے۔ محفوظ رینج آپریشنز کے لیے، Foundation کے NSRange طریقے جیسے 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 کو ڈسپلے کرنے کا سب سے عام طریقہ اسے UILabel کی attributedText پراپرٹی کو تفویض کرنا ہے۔ 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 میں انٹرایکٹو لنکس کو سپورٹ کرتا ہے۔ NSURL کے ساتھ .link خصوصیت ٹیکسٹ کو کلک ایبل بناتی ہے۔ ٹیپس کو ہینڈل کرنے کے لیے، textView(_:shouldInteractWith:in:interaction:) طریقہ کے ساتھ UITextViewDelegate استعمال کریں۔ UITextView ٹیکسٹ سلیکشن اور معیاری آپریشنز (کاپی، تلاش) کے لیے UIMenuController کے استعمال کو بھی سپورٹ کرتا ہے۔

NSAttributedString کو HTML اور RTF میں تبدیل کرنا

NSAttributedString NSAttributedString.DocumentType کے ذریعے HTML اور RTF سے تبدیلی کو سپورٹ کرتا ہے۔ HTML لوڈ کرنے کے لیے، documentAttributes پیرامیٹر کے ساتھ انیشیالائزر استعمال کریں: NSAttributedString(data: htmlData, options: [.documentType: .html], documentAttributes: nil)۔ اسی طرح RTF کے لیے: .rtf یا .rtfd۔ یہ طریقہ کار WebView کے بغیر HTML مواد ڈسپلے کرنے کے لیے مفید ہے۔

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)