$ - interpolacja ciągu (odwołanie do języka C#)$ - string interpolation (C# reference)

Znak $ specjalny identyfikuje literał ciągu jako interpolowany ciąg.The $ special character identifies a string literal as an interpolated string. Interpolowany ciąg jest literałem ciągu, który może zawierać wyrażenia interpolacji.An interpolated string is a string literal that might contain interpolation expressions. Gdy interpolowany ciąg jest rozpoznawany do ciągu wynikowego, elementy z wyrażeniami interpolacji są zastępowane przez reprezentacje ciągu wyników wyrażenia.When an interpolated string is resolved to a result string, items with interpolation expressions are replaced by the string representations of the expression results. Ta funkcja jest dostępna począwszy od języka C# 6.This feature is available starting with C# 6.

Interpolacja ciągów zapewnia bardziej czytelną i wygodną składnię do tworzenia sformatowanych ciągów niż funkcja formatowania złożonego ciągu.String interpolation provides a more readable and convenient syntax to create formatted strings than a string composite formatting feature. W poniższym przykładzie użyto obu funkcji do uzyskania tego samego wyjścia:The following example uses both features to produce the same output:

string name = "Mark";
var date = DateTime.Now;

// Composite formatting:
Console.WriteLine("Hello, {0}! Today is {1}, it's {2:HH:mm} now.", name, date.DayOfWeek, date);
// String interpolation:
Console.WriteLine($"Hello, {name}! Today is {date.DayOfWeek}, it's {date:HH:mm} now.");
// Both calls produce the same output that is similar to:
// Hello, Mark! Today is Wednesday, it's 19:40 now.

Struktura interpolowanego ciąguStructure of an interpolated string

Aby zidentyfikować literał ciągu jako interpolowany ciąg, $ należy dołączyć go do symbolu.To identify a string literal as an interpolated string, prepend it with the $ symbol. Nie można mieć żadnych $ odstępów " między i który uruchamia literał ciągu.You cannot have any white space between the $ and the " that starts a string literal.

Struktura elementu z wyrażeniem interpolacji jest następująca:The structure of an item with an interpolation expression is as follows:

{<interpolationExpression>[,<alignment>][:<formatString>]}

Elementy w nawiasach kwadratowych są opcjonalne.Elements in square brackets are optional. W poniższej tabeli opisano każdy element:The following table describes each element:

ElementElement OpisDescription
interpolationExpression Wyrażenie, które daje wynik do sformatowania.The expression that produces a result to be formatted. Reprezentacja null ciągów jest String.Empty.String representation of null is String.Empty.
alignment Wyrażenie stałe, którego wartość definiuje minimalną liczbę znaków w reprezentacji ciągu wyniku wyrażenia.The constant expression whose value defines the minimum number of characters in the string representation of the expression result. Jeśli jest dodatnia, reprezentacja ciągu jest wyrównana do prawej; jeśli jest ujemna, jest wyrównana do lewej.If positive, the string representation is right-aligned; if negative, it's left-aligned. Aby uzyskać więcej informacji, zobacz Komponent wyrównania.For more information, see Alignment Component.
formatString Ciąg formatu, który jest obsługiwany przez typ wyniku wyrażenia.A format string that is supported by the type of the expression result. Aby uzyskać więcej informacji, zobacz Formatowanie składnika ciągów.For more information, see Format String Component.

W poniższym przykładzie użyto opisanych powyżej składników formatowania opcjonalnego:The following example uses optional formatting components described above:

Console.WriteLine($"|{"Left",-7}|{"Right",7}|");

const int FieldWidthRightAligned = 20;
Console.WriteLine($"{Math.PI,FieldWidthRightAligned} - default formatting of the pi number");
Console.WriteLine($"{Math.PI,FieldWidthRightAligned:F3} - display only three decimal digits of the pi number");
// Expected output is:
// |Left   |  Right|
//     3.14159265358979 - default formatting of the pi number
//                3.142 - display only three decimal digits of the pi number

Znaki specjalneSpecial characters

Aby uwzględnić nawias klamrowy "{" lub "}", w tekście wywoływanym przez interpolowany ciąg, użyj dwóch nawiasów klamrowych, "{{" lub "}}".To include a brace, "{" or "}", in the text produced by an interpolated string, use two braces, "{{" or "}}". Aby uzyskać więcej informacji, zobacz Ucieczka szelki.For more information, see Escaping Braces.

Ponieważ dwukropek (":") ma specjalne znaczenie w elemencie interpolacji, aby użyć operatora warunkowego w wyrażeniu interpolacji, ująć to wyrażenie w nawiasy.As the colon (":") has special meaning in an interpolation expression item, in order to use a conditional operator in an interpolation expression, enclose that expression in parentheses.

W poniższym przykładzie pokazano, jak dołączyć nawias klamrowy w ciągu wynikowym i jak używać operatora warunkowego w wyrażeniu interpolacji:The following example shows how to include a brace in a result string and how to use a conditional operator in an interpolation expression:

string name = "Horace";
int age = 34;
Console.WriteLine($"He asked, \"Is your name {name}?\", but didn't wait for a reply :-{{");
Console.WriteLine($"{name} is {age} year{(age == 1 ? "" : "s")} old.");
// Expected output is:
// He asked, "Is your name Horace?", but didn't wait for a reply :-{
// Horace is 34 years old.

Interpolowany ciąg dosłowny zaczyna $ się od @ znaku, po którym następuje znak.An interpolated verbatim string starts with the $ character followed by the @ character. Aby uzyskać więcej informacji na temat ciągów dosłownie, zobacz ciąg i dosłownie tematów identyfikatora.For more information about verbatim strings, see the string and verbatim identifier topics.

Uwaga

Począwszy od języka C# 8.0, można użyć $ i $@"..." @$"..." @ tokeny w dowolnej kolejności: zarówno i są prawidłowe interpolowane ciągi dosłownie.Starting with C# 8.0, you can use the $ and @ tokens in any order: both $@"..." and @$"..." are valid interpolated verbatim strings. We wcześniejszych wersjach $ języka C# @ token musi pojawić się przed tokenem.In earlier C# versions, the $ token must appear before the @ token.

Konwersje niejawne IFormatProvider i sposób określania implementacjiImplicit conversions and how to specify IFormatProvider implementation

Istnieją trzy niejawne konwersje z interpolowanego ciągu:There are three implicit conversions from an interpolated string:

  1. Konwersja interpolowanego ciągu String na wystąpienie, które jest wynikiem interpolowanej rozdzielczości ciągu z elementami wyrażenia interpolacji, które są zastępowane prawidłowo sformatowanymi reprezentacjami ciągów ich wyników.Conversion of an interpolated string to a String instance that is the result of interpolated string resolution with interpolation expression items being replaced with the properly formatted string representations of their results. Ta konwersja CurrentCulture używa do formatowania wyników wyrażeń.This conversion uses the CurrentCulture to format expression results.

  2. Konwersja interpolowanego ciągu FormattableString do wystąpienia reprezentującego ciąg formatu złożonego wraz z wynikami wyrażenia, które mają być sformatowane.Conversion of an interpolated string to a FormattableString instance that represents a composite format string along with the expression results to be formatted. Dzięki temu można utworzyć wiele ciągów wyników z FormattableString zawartością specyficzne dla kultury z jednego wystąpienia.That allows you to create multiple result strings with culture-specific content from a single FormattableString instance. Aby to zrobić, należy wywołać jedną z następujących metod:To do that, call one of the following methods:

    Można również użyć ToString(IFormatProvider) tej metody, aby zapewnić IFormatProvider implementację zdefiniowaną przez użytkownika interfejsu, który obsługuje formatowanie niestandardowe.You can also use the ToString(IFormatProvider) method to provide a user-defined implementation of the IFormatProvider interface that supports custom formatting. Aby uzyskać więcej informacji, zobacz sekcję Formatowanie niestandardowe za pomocą formatowania ICustomformatter typów formatowania w artykule .NET.For more information, see the Custom formatting with ICustomFormatter section of the Formatting types in .NET article.

  3. Konwersja interpolowanego ciągu IFormattable do wystąpienia, które umożliwia również tworzenie wielu ciągów wyników IFormattable z zawartością specyficzną dla kultury z jednego wystąpienia.Conversion of an interpolated string to an IFormattable instance that also allows you to create multiple result strings with culture-specific content from a single IFormattable instance.

W poniższym przykładzie FormattableString użyto konwersji niejawnej w celu utworzenia ciągów wyników specyficznych dla kultury:The following example uses implicit conversion to FormattableString to create culture-specific result strings:

double speedOfLight = 299792.458;
FormattableString message = $"The speed of light is {speedOfLight:N3} km/s.";

System.Globalization.CultureInfo.CurrentCulture = System.Globalization.CultureInfo.GetCultureInfo("nl-NL");
string messageInCurrentCulture = message.ToString();

var specificCulture = System.Globalization.CultureInfo.GetCultureInfo("en-IN");
string messageInSpecificCulture = message.ToString(specificCulture);

string messageInInvariantCulture = FormattableString.Invariant(message);

Console.WriteLine($"{System.Globalization.CultureInfo.CurrentCulture,-10} {messageInCurrentCulture}");
Console.WriteLine($"{specificCulture,-10} {messageInSpecificCulture}");
Console.WriteLine($"{"Invariant",-10} {messageInInvariantCulture}");
// Expected output is:
// nl-NL      The speed of light is 299.792,458 km/s.
// en-IN      The speed of light is 2,99,792.458 km/s.
// Invariant  The speed of light is 299,792.458 km/s.

Dodatkowe zasobyAdditional resources

Jeśli jesteś nowy do interpolacji ciągów, zobacz Interpolacji ciągów w języku C# interaktywny samouczek.If you are new to string interpolation, see the String interpolation in C# interactive tutorial. Można również sprawdzić inną interpolację ciągów w samouczku języka C#, który pokazuje, jak używać interpolowanych ciągów do tworzenia sformatowanych ciągów.You can also check another String interpolation in C# tutorial that demonstrates how to use interpolated strings to produce formatted strings.

Kompilacja interpolowanych ciągówCompilation of interpolated strings

Jeśli interpolowany ciąg ma stringtyp , zazwyczaj jest String.Format przekształcany w wywołanie metody.If an interpolated string has the type string, it's typically transformed into a String.Format method call. Kompilator może String.Format String.Concat zastąpić, jeśli analizowane zachowanie byłoby równoważne łączenia.The compiler may replace String.Format with String.Concat if the analyzed behavior would be equivalent to concatenation.

Jeśli interpolowany ciąg ma IFormattable FormattableStringtyp lub kompilator generuje FormattableStringFactory.Create wywołanie metody.If an interpolated string has the type IFormattable or FormattableString, the compiler generates a call to the FormattableStringFactory.Create method.

specyfikacja języka C#C# language specification

Aby uzyskać więcej informacji, zobacz interpolowane ciągi sekcji specyfikacji języka C#.For more information, see the Interpolated strings section of the C# language specification.

Zobacz teżSee also