Module java.base
Package java.util

Class 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()将所有字段重置为默认值。

自 JDK 版本:
1.7
参见:

  • Constructor Details

    • Builder

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

  • Method Details

    • setLocale

      public Locale.Builder setLocale(Locale locale)
      重置Builder以匹配提供的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 - 区域设置
      返回:
      此构建器。
      抛出:
      IllformedLocaleException - 如果locale具有任何格式不良字段。
      NullPointerException - 如果locale为null。

    • setLanguageTag

      public Locale.Builder setLanguageTag(String languageTag)
      重置Builder以匹配提供的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)
      设置地区。如果地区为null或空字符串，则在此Builder中删除地区。否则，地区必须是格式良好的，否则将抛出异常。

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

      从Builder获取的Locale中的国家值始终被规范化为大写。

      参数:
      region - 地区
      返回:
      此构建器。
      抛出:
      IllformedLocaleException - 如果region格式不良

    • setVariant

      public Locale.Builder setVariant(String variant)
      设置变体。如果变体为null或空字符串，则在此Builder中删除变体。否则，它必须由一个或多个格式良好的子标记组成，否则将抛出异常。

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

      参数:
      variant - 变体
      返回:
      此构建器。
      抛出:
      IllformedLocaleException - 如果variant格式不良
      参见:

    • setExtension

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

      注意:键UNICODE_LOCALE_EXTENSION（'u'）用于Unicode语言环境扩展。为此键设置值将用定义在扩展中的值替换任何现有的Unicode语言环境键/类型对。

      注意:键PRIVATE_USE_EXTENSION（'x'）用于私有使用代码。为了格式良好，此键的值只需具有一个到八个字母数字字符的子标记，而不是一般情况下的两到八个。

      参数:
      key - 扩展键
      value - 扩展值
      返回:
      此构建器。
      抛出:
      IllformedLocaleException - 如果key非法或value格式不良
      参见:

    • setUnicodeLocaleKeyword

      public Locale.Builder setUnicodeLocaleKeyword(String key, String type)
      为给定键设置Unicode语言环境关键字类型。如果类型为null，则删除Unicode关键字。否则，键必须为非null，键和类型必须是格式良好的，否则将抛出异常。

      键和类型将转换为小写。

      注意:通过setExtension(char, java.lang.String)设置'u'扩展将用扩展中定义的所有Unicode语言环境关键字替换。

      参数:
      key - Unicode 语言环境键
      type - Unicode 语言环境类型
      返回值:
      此构建器。
      抛出:
      IllformedLocaleException - 如果key或type格式不正确
      NullPointerException - 如果key为null
      参见:

    • addUnicodeLocaleAttribute

      public Locale.Builder addUnicodeLocaleAttribute(String attribute)
      添加一个Unicode语言环境属性，如果尚未存在，则不起作用。属性不能为空且必须是格式正确的，否则将抛出异常。
      参数:
      attribute - 属性
      返回值:
      此构建器。
      抛出:
      NullPointerException - 如果attribute为null
      IllformedLocaleException - 如果attribute格式不正确
      参见:

    • removeUnicodeLocaleAttribute

      public Locale.Builder removeUnicodeLocaleAttribute(String attribute)
      移除一个Unicode语言环境属性，如果存在，则不起作用。属性不能为空且必须是格式正确的，否则将抛出异常。

      用于移除的属性比较不区分大小写。

      参数:
      attribute - 属性
      返回值:
      此构建器。
      抛出:
      NullPointerException - 如果attribute为null
      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)中处理传统标签。）

      返回值:
      一个语言环境。