PersonNameComponents.FormatStyle

Overview 概要

Personal names deserve careful and respectful treatment in your apps. Each locale has its own set of rules and conventions to construct and represent personal names. These rules vary widely across different locales in several ways, including the sort and display order of given and family names, the use of salutations and honorifics, and other concerns related to the grammar, spelling, punctuation, and formatting.

A PersonNameComponents.FormatStyle creates human readable text from an instance of PersonNameComponents. You can customize the formatting using the style and locale properties. The system automatically caches instances with unique configurations of the format style to enhance performance.

Format Styles

You can configure a PersonNameComponents.FormatStyle to represent names in a variety of styles:

• Long (PersonNameComponents.FormatStyle.Style.long)

• Medium (PersonNameComponents.FormatStyle.Style.medium)

• Short (PersonNameComponents.FormatStyle.Style.short)

• Abbreviated (PersonNameComponents.FormatStyle.Style.abbreviated)

When determining how to represent a name in a particular style, a number of factors determine the final format. In order of priority:

1. Script derived behaviors — Scripts may specify a strict sort or display order of given and family names, and the availability of styles. The format style assigns an “Unknown” script, which has its own set of behaviors and characteristics, to a name that contains more than one script (for example, given name: John; family name: 王).

2. User specified preferences — Users can enable and configure the display of short names, as well as whether to display nicknames when available. Users can also override the default sort and display order of given and family names for their current locale. ユーザはまた、名および苗字のそれらの現在のロケールに対する省略時のソートおよび表示の順序をオーバーライドできます。

3. Locale derived defaults — Locales specify a default sort and display order for given and family names.

4. Developer specified configuration — The style property value set for the PersonNameComponent.FormatStyle.

In the case of a conflict, the format style uses the factor with the highest precedence. For example, the U.S. English (en-US) style formats names in “given name followed by the family name” (for example, Anne Johnson). This behavior would be overridden if the user changed their system preferences to have names displayed as family name followed by given name (for example, Johnson, Anne), because user-specified preferences take precedence over locale-derived defaults. Furthermore, if the name to be formatted were Japanese (for example, given name: 泰夫; family name: 木田), the behavior derived for the name’s script (CJK, for Chinese, Japanese, and Korean languages) would take precedence over any locale-derived defaults or user-specified preferences to have the name displayed as family name followed by given name (for example, 木田 泰夫).

These considerations extend to the availability of certain format styles as well. Because developer-specified configurations have the lowest precedence, the value set for the formatter’s style property is invalidated if it isn’t supported for the locale, user preferences, or script. If the specified style isn’t available, it uses the next longest valid style. For example, a name in Arabic script (for example, أحمد الراجحي) doesn’t support the Abbreviated style, so it uses the Short style instead.

For more information and examples, see style.

Formatting Person Name Components

Use either formatted() or formatted(_:), both instance methods of PersonNameComponents, to create a string representation of a name.

The formatted() method to applies the default format style to a name. For example: 例えば：

var tlc = PersonNameComponents()
tlc.familyName = "Clark"
tlc.givenName = "Thomas"
tlc.middleName = "Louis"
tlc.namePrefix = "Dr."
tlc.nickname = "Tom"
tlc.nameSuffix = "Esq."


tlc.formatted()
// Thomas Clark

The formatted(_:) method applies a custom format style to a name. You can use the static factory method name(style:) to create a custom format style as a parameter to the method. For example: 例えば：

tlc.formatted(.name(style: .long))
// Dr. Thomas Louis Clark Esq.


tlc.formatted(.name(style: .medium))
// Thomas Clark


tlc.formatted(.name(style: .short))
// Tom


tlc.formatted(.name(style: .abbreviated))
// TC

You can create and reuse a format style instance to format multiple names. For example: 例えば：

let customPersonFormatStyle = PersonNameComponents.FormatStyle(style: .medium, locale: Locale(identifier: "en_US"))


tlc.formatted(customPersonFormatStyle)
// Thomas Clark


mlr.formatted(customPersonFormatStyle)
// Maria Ruiz