استيفاء النصوص وString.Format في C#: محدّدات التنسيق والمحاذاة والثقافة

يبني استيفاء النصوص (string interpolation) نصًا من نص حرفي وتعابير. ضع البادئة $ قبل القيمة الحرفية، وضع أي تعبير C# بين أقواس معقوصة، فتُحوَّل قيمته إلى نص وتُدرج:

using System;

class Program
{
    static void Main()
    {
        string customer = "Maya";
        int items = 3;
        decimal price = 4.5m;

        Console.WriteLine($"Hello, {customer}!");
        Console.WriteLine($"{items} items at {price} = {items * price}");
        Console.WriteLine($"Name has {customer.Length} letters, upper: {customer.ToUpper()}");
        Console.WriteLine($"Free shipping: {(items * price > 10 ? "yes" : "no")}");
    }
}

المخرجات:

Hello, Maya!
3 items at 4.5 = 13.5
Name has 4 letters, upper: MAYA
Free shipping: yes

وصل الاستيفاء في C# 6. يحوّله المترجم إلى استدعاء string.Format أو string.Concat (أو، منذ C# 10، إلى شيفرة معالج أكفأ)، فلا يكون أبطأ من بناء النص يدويًا.

يحتاج التعبير الشرطي في السطر الأخير إلى أقواس. داخل فتحة الاستيفاء تبدأ النقطتان محدّد تنسيق، فتكون {x > 10 ? "yes" : "no"} دون أقواس خطأ ترجمة.

محدّدات التنسيق

بعد التعبير تتحكم نقطتان ونص تنسيق في طريقة كتابة القيمة. تعمل نصوص التنسيق نفسها مع ToString("...") وstring.Format.

using System;

class Program
{
    static void Main()
    {
        decimal total = 1234567.891m;
        int orderId = 42;
        double ratio = 0.8127;

        Console.WriteLine($"{total:F2}");     // fixed-point, 2 decimals
        Console.WriteLine($"{total:N2}");     // with thousands separators
        Console.WriteLine($"{total:N0}");     // no decimals, rounded
        Console.WriteLine($"{orderId:D5}");   // integer padded to 5 digits
        Console.WriteLine($"{255:X}");        // hexadecimal
        Console.WriteLine($"{255:x4}");       // lowercase hex, 4 digits
        Console.WriteLine($"{total:E2}");     // scientific
        Console.WriteLine($"{ratio:F3}");
        Console.WriteLine($"{ratio:0.0%}");   // custom: percent with 1 decimal
        Console.WriteLine($"{total:#,##0.00}"); // custom pattern
        Console.WriteLine($"{7.5:000.0}");    // leading zeros
        Console.WriteLine($"{3.10m:0.##}");   // drop trailing zeros
    }
}

المخرجات:

1234567.89
1,234,567.89
1,234,568
00042
FF
00ff
1.23E+006
0.813
81.3%
1,234,567.89
007.5
3.1

الرموز القياسية، ويمكن أن يلي كلًّا منها رقم دقة:

تبني الأنماط المخصصة التنسيق من عناصر نائبة: 0 رقم يظهر دائمًا، و# رقم يظهر فقط إن كان معنويًا، و. الفاصلة العشرية، و, داخل الرقم تفعّل فواصل التجميع، و% تضرب في 100. يُظهر "0.##" حتى منزلتين عشريتين ويحذف الأصفار اللاحقة؛ و"#,##0.00" هو التنسيق المحاسبي التقليدي.

كل تنسيق رقمي يقرّب القيمة المعروضة؛ والمتغيّر نفسه لا يتغيّر. حين تقع القيمة في المنتصف تمامًا (2.25 معروضة بمنزلة عشرية واحدة) قد تقرّب أوقات تشغيل وأنواع مختلفة حالة التعادل بشكل مختلف، فإن كانت القاعدة مهمة فقرّب صراحة أولًا بـ Math.Round(value, 1, MidpointRounding.AwayFromZero) ثم نسّق.

التواريخ في الاستيفاء

تأخذ قيم DateTime نصوص تنسيق التواريخ بالطريقة نفسها:

using System;

class Program
{
    static void Main()
    {
        var shipped = new DateTime(2026, 9, 24, 16, 5, 0);

        Console.WriteLine($"{shipped:yyyy-MM-dd}");
        Console.WriteLine($"{shipped:dd/MM/yyyy HH:mm}");
        Console.WriteLine($"{shipped:ddd, MMM d}");
        Console.WriteLine($"Shipped at {shipped:HH:mm} on {shipped:dddd}");

        TimeSpan eta = TimeSpan.FromMinutes(130);
        Console.WriteLine($"ETA {eta:hh\\:mm}");
        Console.WriteLine($"{eta.TotalHours:F1} hours");
    }
}

المخرجات:

2026-09-24
24/09/2026 16:05
Thu, Sep 24
Shipped at 16:05 on Thursday
ETA 02:10
2.2 hours

يتطلب التنسيق المخصص لـ TimeSpan هروب المحارف الحرفية بشرطة مائلة عكسية، تُكتب في القيمة النصية العادية \\:. القائمة الكاملة لرموز التواريخ (yyyy وMM وHH وtt...) والأخطاء التي يرتكبها الناس معها (mm للدقائق وMM للأشهر) في تنسيق DateTime.

المحاذاة والتبطين

تحدد فاصلة بعد التعبير عرضًا أدنى للحقل. العدد الموجب يحاذي القيمة إلى نهاية الحقل (تُضاف المسافات قبلها)، والعدد السالب يحاذيها إلى بدايته (تُضاف المسافات بعدها). ومع التنسيق يصفّ الجداول في النص العادي:

using System;

class Program
{
    static void Main()
    {
        var names = new[] { "Espresso", "Latte", "Hot chocolate" };
        var prices = new[] { 2.4m, 3.6m, 4.25m };
        var sold = new[] { 118, 64, 9 };

        Console.WriteLine($"{"Item",-14}|{"Price",7}|{"Sold",5}");
        Console.WriteLine(new string('-', 28));
        for (int i = 0; i < names.Length; i++)
        {
            Console.WriteLine($"{names[i],-14}|{prices[i],7:F2}|{sold[i],5}");
        }
    }
}

المخرجات:

Item          |  Price| Sold
----------------------------
Espresso      |   2.40|  118
Latte         |   3.60|   64
Hot chocolate |   4.25|    9

الصياغة {expression,alignment:format}: المحاذاة أولًا ثم التنسيق. القيمة الأطول من العرض لا تُقتطع؛ بل تدفع بقية السطر. وتؤدي PadLeft وPadRight التبطين نفسه خارج الاستيفاء.

هروب الأقواس المعقوصة

لطباعة قوس حرفي ضاعفه: {{ و}}. يحدث هذا حين تكون المخرجات JSON أو CSS أو شيفرة:

using System;

class Program
{
    static void Main()
    {
        int id = 42;
        string name = "Ana";

        Console.WriteLine($"{{ \"id\": {id}, \"name\": \"{name}\" }}");
        Console.WriteLine($"Set literal: {{1, 2, 3}}");
        Console.WriteLine($"{{{id}}}");   // a value wrapped in braces
    }
}

المخرجات:

{ "id": 42, "name": "Ana" }
Set literal: {1, 2, 3}
{42}

بناء JSON يدويًا هكذا مقبول لسطر سجل سريع؛ أما لـ JSON حقيقي فاستخدم أداة تسلسل، فهي تتعامل بشكل صحيح مع علامات الاقتباس والمحارف الخاصة داخل name.

string.Format والتنسيق المركّب

قبل C# 6 كان التنسيق يتم بـ string.Format، التي تأخذ عناصر نائبة مرقّمة وقائمة وسائط. تقبل Console.WriteLine وStringBuilder.AppendFormat وTextWriter.Write صياغة التنسيق المركّب نفسها:

using System;

class Program
{
    static void Main()
    {
        string item = "Notebook";
        decimal price = 3.5m;
        int qty = 4;

        string line = string.Format("{0} x{1}: {2:F2}", item, qty, price * qty);
        Console.WriteLine(line);

        Console.WriteLine("{0,-10}|{1,6:F2}", item, price);   // alignment and format
        Console.WriteLine("{0} {0} {1}", "echo", "!");        // an index can repeat

        string template = "Dear {0}, your order #{1:D6} has shipped.";
        Console.WriteLine(string.Format(template, "Leo", 731));
    }
}

المخرجات:

Notebook x4: 14.00
Notebook  |  3.50
echo echo !
Dear Leo, your order #000731 has shipped.

فضّل الاستيفاء في الشيفرة: تجلس القيم حيث تظهر، فلا يمكن لعنصر نائب أن يشير إلى الوسيط الخطأ. تبقى string.Format الأداة الصحيحة حين يكون القالب بيانات، مثل رسالة مترجمة محمّلة من ملف موارد. فهرس عنصر نائب بلا وسيط مقابل ({2} مع وسيطين) يرمي FormatException وقت التشغيل.

الثقافة: التحكم في الفواصل والعملة

يستخدم الاستيفاء وToString وstring.Format كلها الثقافة الحالية للخيط افتراضيًا. على جهاز مضبوط على الألمانية تنتج {1234.5:N2} القيمة 1.234,50؛ وفي الولايات المتحدة تنتج 1,234.50. ويستخدم تنسيق العملة C رمز الثقافة. لاختيار الثقافة صراحة التقط النص المستوفى كـ FormattableString ونسّقه بمزوّد:

using System;
using System.Globalization;

class Program
{
    static void Main()
    {
        decimal amount = 1234.5m;
        var us = new CultureInfo("en-US");
        var de = new CultureInfo("de-DE");

        FormattableString line = $"Total: {amount:N2}";
        Console.WriteLine(line.ToString(us));
        Console.WriteLine(line.ToString(de));

        Console.WriteLine(amount.ToString("C", us));
        Console.WriteLine(string.Format(de, "{0:N2}", amount));

        // For files, logs and URLs: always the invariant culture
        string csv = FormattableString.Invariant($"{amount},{0.75}");
        Console.WriteLine(csv);
    }
}

المخرجات:

Total: 1,234.50
Total: 1.234,50
$1,234.50
1.234,50
1234.5,0.75

استخدم ثقافة المستخدم للنص الذي يقرؤه الناس، وCultureInfo.InvariantCulture لكل ما يقرؤه برنامج آخر. ملف CSV مكتوب بالثقافة الحالية على جهاز ألماني يحتوي على فواصل داخل الأرقام ولا يمكن قراءته في مكان آخر. في .NET 6 وما بعده تفعل string.Create(CultureInfo.InvariantCulture, $"...") ما تفعله FormattableString.Invariant دون الكائن الوسيط.

النصوص المستوفاة الحرفية والخام

تتّحد $ مع @ لنص مستوفى حرفي (verbatim): الشرطات المائلة العكسية حرفية ويمكن للنص الامتداد على عدة أسطر. تقبل C# 8 وما بعدها الترتيبين ($@ أو @$)؛ وتتطلب C# 6 و7 الشكل $@:

using System;

class Program
{
    static void Main()
    {
        string user = "ana";
        int year = 2026;
        Console.WriteLine($@"C:\Users\{user}\Reports\{year}\summary.txt");
        Console.WriteLine($@"Report for {user}
Year: {year}");
    }
}

المخرجات:

C:\Users\ana\Reports\2026\summary.txt
Report for ana
Year: 2026

أضافت C# 11 النصوص المستوفاة الخام. مع $ واحدة تميّز الأقواس التعابير كالمعتاد. ومع $$ يكون القوس المفرد حرفيًا وتحتاج التعابير إلى قوسين، وهذا يجعل قوالب JSON والشيفرة سهلة القراءة:

// C# 11 and later
int id = 42;
string name = "Ana";
string json = $$"""
    {
      "id": {{id}},
      "name": "{{name}}"
    }
    """;

تسمح C# 11 أيضًا بأسطر جديدة داخل فتحة الاستيفاء، فيمكن تقسيم تعبير طويل أو تعبير switch على عدة أسطر.

أخطاء شائعة

• نسيان $. تطبع "Total: {total}" الأقواس حرفيًا. ولا يحذّر المترجم.
• معامل ثلاثي دون أقواس داخل الأقواس المعقوصة: تُقرأ النقطتان كفاصل تنسيق.
• تنسيق المخرجات المقروءة آليًا بالثقافة الحالية. الفواصل العشرية تكسر CSV وJSON وSQL. استخدم الثقافة الثابتة.
• استخدام ToString() دون تنسيق للمال. تُطبع 2.5m كـ 2.5 لا 2.50. استخدم F2 أو N2 أو C.
• بناء نصوص كبيرة بالاستيفاء في حلقة. كل تكرار ينشئ نصًا جديدًا؛ استخدم StringBuilder أو string.Join.