Locale.Builder

java.lang.Object

|---java.util.Locale.Builder

public static final class Locale.Builder
extends Object

Builder 用于根据 setter 配置的值构建 Locale 的实例。 与 Locale 构造函数不同，Builder 检查由 setter 配置的值是否满足 Locale 类定义的语法要求。 由 Builder 创建的 Locale 对象格式正确，可以转换为格式正确的 IETF BCP 47 语言标签而不会丢失信息。

注意：Locale 类不对变体提供任何语法限制，而 BCP 47 要求每个变体子标签为 5 到 8 个字母数字或单个数字后跟 3 个字母数字。 对于不满足此限制的变体，方法 setVariant 会引发 IllformedLocaleException。 如果需要支持这种变体，请使用 Locale 构造函数。 但是，请记住，以这种方式创建的 Locale 对象在转换为 BCP 47 语言标签时可能会丢失变体信息。

以下示例显示如何使用 Builder 创建 Locale 对象。

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

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

构造函数摘要

构造函数	描述
Builder()	构造一个空的 Builder。

方法总结

修饰符和类型	方法	描述
Locale.Builder	addUnicodeLocaleAttribute(String attribute)	添加 unicode 语言环境属性，如果不存在，否则无效。
Locale	build()	返回从此构建器上设置的字段创建的 Locale 实例。
Locale.Builder	clear()	将构建器重置为其初始的空状态。
Locale.Builder	clearExtensions()	将扩展重置为其初始的空状态。
Locale.Builder	removeUnicodeLocaleAttribute(String attribute)	删除 unicode 语言环境属性（如果存在），否则无效。
Locale.Builder	setExtension(char key, String value)	设置给定键的扩展名。
Locale.Builder	setLanguage(String language)	设置语言。
Locale.Builder	setLanguageTag(String languageTag)	重置 Builder 以匹配提供的 IETF BCP 47 语言标签。
Locale.Builder	setLocale(Locale locale)	重置 Builder 以匹配提供的语言环境。
Locale.Builder	setRegion(String region)	设置区域。
Locale.Builder	setScript(String script)	设置脚本。
Locale.Builder	setUnicodeLocaleKeyword(String key, String type)	设置给定键的 Unicode 语言环境关键字类型。
Locale.Builder	setVariant(String variant)	设置变体。

从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造函数详细信息

Builder

public Builder()

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

方法详情

setLocale

public Locale.Builder setLocale(Locale locale)

重置 Builder 以匹配提供的语言环境。 现有状态被丢弃。

语言环境的所有字段必须格式正确。

具有任何格式错误的字段的语言环境会导致抛出 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	语言环境

返回:

这个建设者。

Throws:

Throw名称	Throw描述
IllformedLocaleException	如果 locale 有任何格式错误的字段。
NullPointerException	如果 locale 为空

setLanguageTag

public Locale.Builder setLanguageTag(String languageTag)

重置 Builder 以匹配提供的 IETF BCP 47 语言标签。 丢弃现有状态。 Null 和空字符串会导致构建器被重置，如 clear()。 祖代标签（请参阅 Locale#forLanguageTag）在处理之前转换为它们的规范形式。 否则，语言标记必须是格式正确的，否则会引发异常（与 Locale.forLanguageTag 不同，它只会丢弃格式错误的标记和后续部分）。

参数：

参数名称	参数描述
languageTag	语言标签

返回:

这个建设者。

Throws:

Throw名称	Throw描述
IllformedLocaleException	如果 languageTag 格式不正确

setLanguage

public Locale.Builder setLanguage(String language)

设置语言。 如果 language 为空字符串或 null，则删除此 Builder 中的语言。 否则，语言必须格式正确，否则会引发异常。

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

参数：

参数名称	参数描述
language	语言

返回:

这个建设者。

Throws:

Throw名称	Throw描述
IllformedLocaleException	如果 language 格式不正确

setScript

public Locale.Builder setScript(String script)

设置脚本。 如果 script 为 null 或空字符串，则删除此 Builder 中的脚本。 否则，脚本必须格式正确，否则会引发异常。

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

参数：

参数名称	参数描述
script	脚本

返回:

这个建设者。

Throws:

Throw名称	Throw描述
IllformedLocaleException	如果 script 格式不正确

setRegion

public Locale.Builder setRegion(String region)

设置区域。 如果 region 为 null 或空字符串，则删除此 Builder 中的区域。 否则，该区域必须是格式良好的，否则将引发异常。

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

由 Builder 创建的 Locale 中的 country 值始终标准化为大写。

参数：

参数名称	参数描述
region	该区域

返回:

这个建设者。

Throws:

Throw名称	Throw描述
IllformedLocaleException	如果 region 格式不正确

setVariant

public Locale.Builder setVariant(String variant)

设置变体。 如果 variant 为 null 或空字符串，则删除此 Builder 中的变体。 否则，它必须由一个或多个格式正确的子标签组成，否则将引发异常。

注意：此方法检查变体是否满足 IETF BCP 47 变体子标签的语法要求，并将值规范化为小写字母。 但是，Locale 类对变体没有任何语法限制，并且 Locale 中的变体值区分大小写。 要设置这样的变体，请使用 Locale 构造函数。

参数：

参数名称	参数描述
variant	变体

返回:

这个建设者。

Throws:

Throw名称	Throw描述
IllformedLocaleException	如果 variant 格式不正确

setExtension

public Locale.Builder setExtension(char key, String value)

设置给定键的扩展名。 如果值为 null 或空字符串，则删除扩展名。 否则，扩展必须是格式正确的，否则会引发异常。

注意：键 Locale#UNICODE_LOCALE_EXTENSION ('u') 用于 Unicode 语言环境扩展。 设置此键的值会将任何现有的 Unicode 语言环境键/类型对替换为扩展中定义的那些。

注意：键 Locale#PRIVATE_USE_EXTENSION ('x') 用于私人使用代码。 为了形成良好的格式，此键的值只需具有 1 到 8 个字母数字字符的子标签，而不是一般情况下的 2 到 8 个。

参数：

参数名称	参数描述
key	扩展密钥
value	扩展值

返回:

这个建设者。

Throws:

Throw名称	Throw描述
IllformedLocaleException	如果 key 或 value 格式不正确

setUnicodeLocaleKeyword

public Locale.Builder setUnicodeLocaleKeyword(String key, String type)

设置给定键的 Unicode 语言环境关键字类型。 如果类型为 null，则删除 Unicode 关键字。 否则，键必须为非空，并且键和类型都必须格式正确，否则将引发异常。

键和类型转换为小写。

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

参数：

参数名称	参数描述
key	Unicode 语言环境键
type	Unicode 语言环境类型

返回:

这个建设者。

Throws:

Throw名称	Throw描述
IllformedLocaleException	如果 key 或 type 格式不正确
NullPointerException	如果 key 为空

addUnicodeLocaleAttribute

public Locale.Builder addUnicodeLocaleAttribute(String attribute)

添加 unicode 语言环境属性，如果不存在，否则无效。 该属性不能为空，并且必须格式正确，否则将引发异常。

参数：

参数名称	参数描述
attribute	属性

返回:

这个建设者。

Throws:

Throw名称	Throw描述
NullPointerException	如果 attribute 为空
IllformedLocaleException	如果 attribute 格式不正确

removeUnicodeLocaleAttribute

public Locale.Builder removeUnicodeLocaleAttribute(String attribute)

删除 unicode 语言环境属性（如果存在），否则无效。 该属性不能为空，并且必须格式正确，否则将引发异常。

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

参数：

参数名称	参数描述
attribute	属性

返回:

这个建设者。

Throws:

Throw名称	Throw描述
NullPointerException	如果 attribute 为空
IllformedLocaleException	如果 attribute 格式不正确

clear

public Locale.Builder clear()

将构建器重置为其初始的空状态。

返回:

这个建设者。

clearExtensions

public Locale.Builder clearExtensions()

将扩展重置为其初始的空状态。 语言、文字、地区和变体不变。

返回:

这个建设者。

build

public Locale build()

返回从此构建器上设置的字段创建的 Locale 实例。

这将在构造语言环境时应用 Locale#forLanguageTag 中列出的转换。 （祖父标签在 setLanguageTag(java.lang.String) 中处理。）

返回:

语言环境。