树叶云鸿蒙OS教程：鸿蒙OS Locale.Builder

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

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”

参数：

返回:

这个建设者。

Throws:

setLanguageTag

public Locale.Builder setLanguageTag(String languageTag)

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

参数：

返回:

这个建设者。

Throws:

setLanguage

public Locale.Builder setLanguage(String language)

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

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

参数：

返回:

这个建设者。

Throws:

setScript

public Locale.Builder setScript(String script)

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

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

参数：

返回:

这个建设者。

Throws:

setRegion

public Locale.Builder setRegion(String region)

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

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

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

参数：

返回:

这个建设者。

Throws:

setVariant

public Locale.Builder setVariant(String variant)

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

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

参数：

返回:

这个建设者。

Throws:

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 个。

参数：

返回:

这个建设者。

Throws:

setUnicodeLocaleKeyword

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

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

键和类型转换为小写。

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

参数：

返回:

这个建设者。

Throws:

addUnicodeLocaleAttribute

public Locale.Builder addUnicodeLocaleAttribute(String attribute)

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

参数：

返回:

这个建设者。

Throws:

removeUnicodeLocaleAttribute

public Locale.Builder removeUnicodeLocaleAttribute(String attribute)

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

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

参数：

返回:

这个建设者。

Throws:

clear

public Locale.Builder clear()

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

返回:

这个建设者。

clearExtensions

public Locale.Builder clearExtensions()

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

返回:

这个建设者。

build

public Locale build()

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

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

返回:

语言环境。