模块 java.base
包 java.util

类 Locale.Builder

java.lang.Object
java.util.Locale.Builder
封闭类：
Locale
public static final class Locale.Builder extends Object
Builder 用于根据 setter 配置的值构建 Locale 的实例。与 Locale 构造函数或 Locale.of() 工厂方法不同，Builder 检查由 setter 配置的值是否满足 Locale 类定义的语法要求。从 Builder 获得的 Locale 对象格式正确，可以在不丢失信息的情况下转换为格式正确的 IETF BCP 47 语言标签。
实现注意事项：
Locale 类不对变体提供任何句法限制，而 BCP 47 要求每个变体子标签为 5 到 8 个字母数字或单个数字后跟 3 个字母数字。对于不满足此限制的变体，方法 setVariant 会抛出 IllformedLocaleException。如果有必要支持这样的变体，请使用 Locale.of(String, String, String) 。但是，请记住，以这种方式获得的 Locale 对象在转换为 BCP 47 语言标签时可能会丢失变体信息。

以下示例显示如何使用 Builder 获取 Locale 对象。

Locale aLocale = new Locale.Builder().setLanguage("sr").setScript("Latn").setRegion("RS").build();

建造者可以重复使用； clear() 将所有字段重置为其默认值。

自从：
1.7
参见：

  • 构造方法详细信息

    • 建设者

      public Builder()
      构造一个空的 Builder。所有字段、扩展名和私人使用信息的默认值为空字符串。

  • 方法详情

    • setLocale

      public Locale.Builder  setLocale(Locale  locale)
      重置 Builder 以匹配提供的 locale。现有状态被丢弃。

      locale的所有字段都必须格式正确，请参阅 Locale 。

      具有任何格式错误的字段的locale会导致抛出 IllformedLocaleException，但出于兼容性原因接受的以下三种情况除外：

      • Locale("ja", "JP", "JP") 被视为"ja-JP-u-ca-japanese"
      • Locale("th", "TH", "TH") 被视为"th-TH-u-nu-thai"
      • Locale("no", "NO", "NY") 被视为"nn-NO"
      参数：
      locale - locale
      返回：
      这个建造师。
      抛出：
      IllformedLocaleException - 如果 locale 有任何格式错误的字段。
      NullPointerException - 如果 locale 为空。

    • setLanguageTag

      public Locale.Builder  setLanguageTag(String  languageTag)
      重置构建器以匹配提供的 IETF BCP 47 语言标记。丢弃现有状态。 Null 和空字符串会导致构建器被重置，如 clear() 。遗留标签（参见 Locale.forLanguageTag(java.lang.String) ）在处理之前被转换为它们的规范形式。否则，语言标记必须格式正确（请参阅 Locale ）或抛出异常（与 Locale.forLanguageTag 不同，后者仅丢弃标记的格式错误和后续部分）。
      参数：
      languageTag - 语言标签
      返回：
      这个建造师。
      抛出：
      IllformedLocaleException - 如果 languageTag 格式错误
      参见：

    • setLanguage

      public Locale.Builder  setLanguage(String  language)
      设置语言。如果 language 为空字符串或 null，则删除此 Builder 中的语言。否则，语言必须是 良构的 否则会抛出异常。

      典型的语言值是 ISO639 中定义的两个或三个字母的语言代码。

      参数：
      language - 语言
      返回：
      这个建造师。
      抛出：
      IllformedLocaleException - 如果 language 格式错误

    • setScript

      public Locale.Builder  setScript(String  script)
      设置脚本。如果 script 为 null 或空字符串，则删除此 Builder 中的脚本。否则，脚本必须是 良构的 否则会抛出异常。

      典型的脚本值是由 ISO 15924 定义的四字母脚本代码。

      参数：
      script - 脚本
      返回：
      这个建造师。
      抛出：
      IllformedLocaleException - 如果 script 格式错误

    • setRegion

      public Locale.Builder  setRegion(String  region)
      设置区域。如果 region 为 null 或空字符串，则删除此 Builder 中的区域。否则，区域必须是 良构的 否则将抛出异常。

      典型的区域值是两个字母的 ISO 3166 代码或一个三位数的 UN M.49 区号。

      从 Builder 获得的 Locale 中的国家/地区值始终标准化为大写。

      参数：
      region - 地区
      返回：
      这个建造师。
      抛出：
      IllformedLocaleException - 如果 region 格式错误

    • setVariant

      public Locale.Builder  setVariant(String  variant)
      设置变体。如果 variant 为 null 或空字符串，则删除此 Builder 中的 variant。否则，它必须包含一个或多个 良构的 子标签，否则将抛出异常。

      笔记：此方法检查 variant 是否满足 IETF BCP 47 变体子标签的语法要求，并将值规范化为小写字母。但是Locale类并没有对variant做任何句法限制，Locale中的variant值区分大小写。要设置这样的变体，请使用 Locale.of(String, String, String) 。

      参数：
      variant - 变体
      返回：
      这个建造师。
      抛出：
      IllformedLocaleException - 如果 variant 格式错误
      参见：

    • setExtension

      public Locale.Builder  setExtension(char key, String  value)
      设置给定键的扩展名。如果值为 null 或空字符串，则删除扩展名。否则，扩展名必须是 良构的 否则会抛出异常。

      笔记：密钥 UNICODE_LOCALE_EXTENSION ('u') 用于 Unicode locale扩展。为该键设置一个值会将任何现有的 Unicode 区域设置键/类型对替换为扩展中定义的那些。

      笔记：密钥 PRIVATE_USE_EXTENSION ('x') 用于私人使用代码。为了格式正确，这个键的值只需要有 1 到 8 个字母数字字符的子标签，而不是一般情况下的 2 到 8 个。

      参数：
      key - 扩展密钥
      value - 扩展值
      返回：
      这个建造师。
      抛出：
      IllformedLocaleException - 如果 key 非法或 value 格式错误
      参见：

    • setUnicodeLocaleKeyword

      public Locale.Builder  setUnicodeLocaleKeyword(String  key, String  type)
      为给定键设置 Unicode locale关键字类型。如果类型为 null，则删除 Unicode 关键字。否则，key 必须是非 null 且 key 和 type 都必须是 良构的 否则会抛出异常。

      键和类型转换为小写。

      笔记通过 setExtension(char, java.lang.String) 设置 'u' 扩展名会将所有 Unicode locale关键字替换为扩展名中定义的关键字。

      参数：
      key - Unicode locale键
      type - Unicode locale类型
      返回：
      这个建造师。
      抛出：
      IllformedLocaleException - 如果 key 或 type 格式错误
      NullPointerException - 如果 key 为空
      参见：

    • addUnicodeLocaleAttribute

      public Locale.Builder  addUnicodeLocaleAttribute(String  attribute)
      添加 unicode locale属性（如果尚未存在），否则无效。该属性不能为 null，必须为 良构的 否则将引发异常。
      参数：
      attribute - 属性
      返回：
      这个建造师。
      抛出：
      NullPointerException - 如果 attribute 为空
      IllformedLocaleException - 如果 attribute 格式错误
      参见：

    • removeUnicodeLocaleAttribute

      public Locale.Builder  removeUnicodeLocaleAttribute(String  attribute)
      删除 unicode locale属性（如果存在），否则无效。该属性不能为 null，必须为 良构的 否则将引发异常。

      删除的属性比较不区分大小写。

      参数：
      attribute - 属性
      返回：
      这个建造师。
      抛出：
      NullPointerException - 如果 attribute 为空
      IllformedLocaleException - 如果 attribute 格式错误
      参见：

    • clear

      public Locale.Builder  clear()
      将构建器重置为其初始的空状态。
      返回：
      这个建造师。

    • clearExtensions

      public Locale.Builder  clearExtensions()
      将扩展重置为其初始的空状态。语言、脚本、区域和变体不变。
      返回：
      这个建造师。
      参见：

    • build

      public Locale  build()
      返回 Locale 的实例，该实例是从此构建器上设置的字段中获得的。

      这会在构建区域设置时应用 Locale.forLanguageTag(java.lang.String) 中列出的转换。 （遗留标签在 setLanguageTag(java.lang.String) 中处理。）

      返回：
      locale。