cordova-plugin-globalization 1.0.4

cordova-plugin-globalization 1.0.4

测试已测试
语言语言 Obj-CObjective C
许可证 Apache 2
发布最后发布2016年11月

Holly SchinskyShazron Abdullah 维护。



  • Adobe PhoneGap团队

标题:全球化

描述:访问地区数据。

Android iOS Windows 8.1 Store Windows 8.1 Phone Windows 10 Store Travis CI
Build Status Build Status Build Status Build Status Build Status

cordova-plugin-globalization

此插件获取与用户的地区、语言和时区相关的特定信息和执行操作。注意地区和语言之间的区别:地区控制数字、日期和时间的显示方式,而语言决定文本使用哪种语言,与地区设置无关。开发者通常会使用地区来设定这两种设置,但用户完全可以将语言设置为“英语”但地区设置为“法语”,这样文本将以英语显示,但日期、时间等将以法国的方式显示。遗憾的是,大多数移动平台目前不区分这些设置。

此插件定义了全局navigator.globalization对象。

尽管在全局范围内,它在deviceready事件之后才可用。

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(navigator.globalization);
}

Apache Cordova问题跟踪器上报告此插件的问题

安装

cordova plugin add cordova-plugin-globalization

对象

  • GlobalizationError

方法

  • navigator.globalization.getPreferredLanguage
  • navigator.globalization.getLocaleName
  • navigator.globalization.dateToString
  • navigator.globalization.stringToDate
  • navigator.globalization.getDatePattern
  • navigator.globalization.getDateNames
  • navigator.globalization.isDayLightSavingsTime
  • navigator.globalization.getFirstDayOfWeek
  • navigator.globalization.numberToString
  • navigator.globalization.stringToNumber
  • navigator.globalization.getNumberPattern
  • navigator.globalization.getCurrencyPattern

navigator.globalization.getPreferredLanguage

获取客户端当前语言的BCP 47语言标签。

navigator.globalization.getPreferredLanguage(successCallback, errorCallback);

描述

将符合 BCP-47 的语言标识标签返回给 successCallback,并以一个带有 properties 对象的参数。该对象应有一个具有 String 值的 value 属性。

如果获取语言时发生错误,则使用带有 GlobalizationError 对象的 errorCallback 执行。错误期望的代码是 GlobalizationError.UNKNOWN_ERROR

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows
  • 浏览器

示例

当浏览器设置为 en-US 语言时,应显示一个包含文本 language: en-US 的弹出对话框

navigator.globalization.getPreferredLanguage(
    function (language) {alert('language: ' + language.value + '\n');},
    function () {alert('Error getting language\n');}
);

Android 特性

  • 返回 ISO 639-1 两位语言代码,大写 ISO 3166-1 国家代码和变体(由连字符分隔)。示例:"en", "en-US", "US"。

Windows Phone 8 特性

  • 返回对应于“语言”设置的地区的 ISO 639-1 两位语言代码和 ISO 3166-1 国家代码,由连字符分隔。
  • 请注意,地区变体是“语言”设置的一个属性,而不是由 Windows Phone 上与之无关的“国家/地区”设置确定的。

Windows 特性

  • 返回对应于“语言”设置的地区的 ISO 639-1 两位语言代码和 ISO 3166-1 国家代码,由连字符分隔。

浏览器特性

  • 回退到 getLocaleName

navigator.globalization.getLocaleName

返回客户端当前区域设置的 BCP 47 合规标签。

navigator.globalization.getLocaleName(successCallback, errorCallback);

描述

将符合 BCP 47 的区域标识字符串返回给 successCallback,其中包含一个带有 properties 对象的参数。该对象应有一个具有 String 值的 value 属性。区域标签将包括一个由连字符分隔的两字母小写语言代码、两字母大写国家代码和(未指定的)变体代码。

如果在获取区域时发生错误,则使用带有 GlobalizationError 对象的 errorCallback 执行。错误期望的代码是 GlobalizationError.UNKNOWN_ERROR

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows
  • 浏览器

示例

当浏览器设置为 en-US 区域时,这将显示一个包含文本 locale: en-US 的弹出对话框。

navigator.globalization.getLocaleName(
    function (locale) {alert('locale: ' + locale.value + '\n');},
    function () {alert('Error getting locale\n');}
);

Android 特性

  • Java 无法区分“语言”和“区域”的设置,因此此方法基本上与 navigator.globalization.getPreferredLanguage() 相同。

Windows Phone 8 特性

  • 返回对应于“区域格式”设置的地区的 ISO 639-1 两位语言代码和 ISO 3166-1 国家代码,由连字符分隔。

Windows 特性

  • 区域设置可以在控制面板 -> 时钟,语言和区域 -> 区域 -> 格式 -> 格式,以及在 Windows Phone 8.1 的设置 -> 区域 -> 区域格式中进行更改。

浏览器怪癖

  • IE 返回操作系统的区域设置。Chrome 和 Firefox 返回浏览器语言标签。

navigator.globalization.dateToString

根据客户端的区域设置和时区返回日期的字符串格式。

navigator.globalization.dateToString(date, successCallback, errorCallback, options);

描述

通过从传递给 successCallback 的对象中访问的 value 属性返回格式化日期的 String

传入的 date 参数应该是 Date 类型。

如果格式化日期时发生错误,那么 errorCallback 将以 GlobalizationError 对象作为参数执行。错误的预期代码是 GlobalizationError.FORMATTING_ERROR

options 参数是可选的,其默认值是

{formatLength:'short', selector:'date and time'}

options.formatLength 可以是 short(短)、medium(中)、long(长)或 full(完整)。

options.selector 可以是 date(日期)、time(时间)或 date and time(日期和时间)。

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows
  • 浏览器

示例

如果浏览器设置为 en_US 区域设置,则使用默认选项显示包含类似 date: 9/25/2012 4:21PM 文本的弹出对话框

navigator.globalization.dateToString(
    new Date(),
    function (date) { alert('date: ' + date.value + '\n'); },
    function () { alert('Error getting dateString\n'); },
    { formatLength: 'short', selector: 'date and time' }
);

Android 怪癖

  • formatLength 选项是 Unicode UTS #35 的一个子集。默认选项 short 依赖于用户在 设置 -> 系统 -> 日期和时间 -> 选择日期格式 中选择的日期格式,只提供带 4 位的 模式,不是 2 位。这意味着它并不完全与 ICU 保持一致。

Windows Phone 8 怪癖

  • formatLength 选项仅支持 shortfull 值。

  • 'data and time' 选择器的模式始终是完整的日期时间格式。

  • 返回的值可能与 ICU 的用户区域设置不完全一致。

Windows 怪癖

  • formatLength 选项仅支持 shortfull 值。

  • 'data and time' 选择器的模式始终是完整的日期时间格式。

  • 返回的值可能与 ICU 的用户区域设置不完全一致。

浏览器怪癖

  • 由于在此方法中使用 moment.js,因此仅支持 79 个区域。

  • 返回的值可能与 ICU 的用户区域设置不完全一致。

  • 时间选择器仅支持 fullshort 格式的 formatLength

Firefox OS 怪癖

  • formatLength 无法区分 longfull
  • 只有一种显示日期的方法(没有 longfull 版本)

navigator.globalization.getCurrencyPattern

返回一个模式字符串来格式化和解析货币值,该字符串根据客户端的用户偏好和 ISO 4217 货币代码。

 navigator.globalization.getCurrencyPattern(currencyCode, successCallback, errorCallback);

描述

将模式返回给带有 properties 对象的 successCallback,该对象应包含以下属性

  • 模式:用于格式化和解析货币值的货币模式。模式遵循Unicode 技术标准 #35(字符串)

  • code:该模式使用的 ISO 4217 货币代码。(字符串)

  • fraction:解析和格式化货币时使用的分数位数。(数字)

  • rounding:解析和格式化时使用的舍入增量。(数字)

  • decimal:解析和格式化时使用的十进制符号。(字符串)

  • grouping:解析和格式化时使用的分组符号。(字符串)

入站 currencyCode 参数应是一个 ISO 4217 货币代码的字符串,例如 'USD'。

如果在获取模式时发生错误,则 errorCallback 会执行,并带有 GlobalizationError 对象作为参数。错误的预期代码为 GlobalizationError.FORMATTING_ERROR

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • iOS
  • Windows

示例

当浏览器设置为 en_US 区域设置且选择的货币为美元时,此示例将弹出包含类似以下文本的弹出对话框

navigator.globalization.getCurrencyPattern(
    'USD',
    function (pattern) {
        alert('pattern: '  + pattern.pattern  + '\n' +
              'code: '     + pattern.code     + '\n' +
              'fraction: ' + pattern.fraction + '\n' +
              'rounding: ' + pattern.rounding + '\n' +
              'decimal: '  + pattern.decimal  + '\n' +
              'grouping: ' + pattern.grouping);
    },
    function () { alert('Error getting pattern\n'); }
);

预期结果

pattern: $#,##0.##;($#,##0.##)
code: USD
fraction: 2
rounding: 0
decimal: .
grouping: ,

Windows 的一些问题

  • 仅支持 'code' 和 'fraction' 属性

navigator.globalization.getDateNames

根据客户端的用户偏好和日历返回月份或一周的天数的名称数组。

navigator.globalization.getDateNames(successCallback, errorCallback, options);

描述

将包含 value 属性的 properties 对象作为参数传递给 successCallback。该对象包含一个包含 String 值的 Array。数组具有从一年中的第一个月或一周的第一天开始的名称,具体取决于所选选项。

如果在获取名称时发生错误,则 errorCallback 会执行,并带有 GlobalizationError 对象作为参数。错误的预期代码为 GlobalizationError.UNKNOWN_ERROR

options 参数是可选的,其默认值是

{type:'wide', item:'months'}

options.type 的值可以是 'narrow' 或 'wide'。

options.item 的值可以是 'months' 或 'days'。

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows
  • 浏览器

示例

当浏览器设置为 en_US 区域设置时,此示例将显示一系列12个弹出对话框,每个代表一个月,文本类似于 month: January

navigator.globalization.getDateNames(
    function (names) {
        for (var i = 0; i < names.value.length; i++) {
            alert('month: ' + names.value[i] + '\n');
        }
    },
    function () { alert('Error getting names\n'); },
    { type: 'wide', item: 'months' }
);

Firefox OS 的一些问题

  • options.type 支持一个 'genitive' 值,这对某些语言来说很重要。

Windows Phone 8 的一些问题

  • 月份数组包含13个元素。
  • 返回的数组可能不完全与 ICU 一致,这取决于用户的区域。

Windows 的一些问题

  • 月份数组包含12个元素。
  • 返回的数组可能不完全与 ICU 一致,这取决于用户的区域。

浏览器的一些问题

  • 日期名称不完全与 ICU 一致。
  • 月份数组包含12个元素。

navigator.globalization.getDatePattern

返回一个模式字符串以按客户端用户首选项格式化和解析日期。

navigator.globalization.getDatePattern(successCallback, errorCallback, options);

描述

将模式返回给 成功回调。作为参数传入的对象包含以下属性

  • 模式:用于格式化和解析日期的日期和时间模式。模式遵循Unicode技术标准#35(字符串)

  • 时区:客户端上的时区的简称。(字符串)

  • utc_offset:客户端时区与协调世界时之间的当前秒数差。(数字)

  • dst_offset:客户端非夏令时时区与客户端夏令时时区之间当前的夏令时偏移量。(数字)

如果获取模式时出错,则 错误回调 会以 GlobalizationError 对象作为参数执行。错误预期代码为 GlobalizationError.PATTERN_ERROR

选项 参数是可选的,默认值为以下值。

{formatLength:'short', selector:'date and time'}

选项.formatLength 可以是 shortmediumlongfull选项.selector 可以是 datetimedate and time

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • iOS
  • Windows Phone 8
  • Windows
  • 浏览器

示例

当浏览器设置为 en_US 位置时,此示例将显示一个包含文本如 pattern: M/d/yyyy h:mm a 的弹出对话框。

function checkDatePattern() {
    navigator.globalization.getDatePattern(
        function (date) { alert('pattern: ' + date.pattern + '\n'); },
        function () { alert('Error getting pattern\n'); },
        { formatLength: 'short', selector: 'date and time' }
    );
}

Windows Phone 8 怪癖

  • formatLength 支持仅为 shortfull 值。

  • date and time 模式的 pattern 返回仅为完整日期时间格式。

  • timezone 返回完整的时区名称。

  • dst_offset 属性不受支持,且始终返回零。

  • 模式可能不完全与 ICU 一致,具体取决于用户的地区。

Windows 怪癖

  • formatLength 支持仅为 shortfull 值。

  • date and time 模式的 pattern 返回仅为完整日期时间格式。

  • timezone 返回完整的时区名称。

  • dst_offset 属性不受支持,且始终返回零。

  • 模式可能不完全与 ICU 一致,具体取决于用户的地区。

浏览器怪癖

  • 'pattern' 属性不受支持并返回空字符串。

  • 只有 Chrome 返回 'timezone' 属性。其格式为 "Part of the world/{City}"。其他浏览器返回空字符串。

navigator.globalization.getFirstDayOfWeek

根据客户端用户首选项和日历返回周的第一天。

navigator.globalization.getFirstDayOfWeek(successCallback, errorCallback);

描述

周日从 1 开始编号,其中 1 表示周天。将带 properties 对象的日期作为参数返回给 成功回调。该对象应有一个包含 Number 值的 value 属性。

如果获取模式时出错,则 错误回调GlobalizationError 对象作为参数执行。错误预期代码为 GlobalizationError.UNKNOWN_ERROR

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows
  • 浏览器

示例

当浏览器设置为 en_US 位置时,此显示类似 day: 1 的弹出对话框。

navigator.globalization.getFirstDayOfWeek(
    function (day) {alert('day: ' + day.value + '\n');},
    function () {alert('Error getting day\n');}
);

Windows 怪癖

  • 在Windows 8.0/8.1系统中,此值取决于用户的日历首选项。在Windows Phone 8.1中,此值取决于当前的区域设置。

浏览器特性

  • 由于在此方法中使用 moment.js,因此仅支持 79 个区域。

navigator.globalization.getNumberPattern

返回一个模式字符串,用于根据客户端用户的偏好格式化和解析数字。

navigator.globalization.getNumberPattern(successCallback, errorCallback, options);

描述

将模式返回给 successCallback,并以其作为参数的 properties 对象。该对象包含以下属性

  • pattern:用于格式化和解析数字的数字模式。模式遵循 Unicode技术规范#35(String)

  • symbol:用于格式化和解析时的符号,例如百分号或货币符号。 (String)

  • fraction:解析和格式化数字时使用的分数位数。 (Number)

  • rounding:解析和格式化时使用的舍入增量。(数字)

  • positive:解析和格式化正数时使用的符号。 (String)

  • negative:解析和格式化负数时使用的符号。 (String)

  • decimal:解析和格式化时使用的十进制符号。(字符串)

  • grouping:解析和格式化时使用的分组符号。(字符串)

如果获取模式时出现错误,则执行 errorCallback,并以其作为参数的 GlobalizationError 对象。错误的预期代码是 GlobalizationError.PATTERN_ERROR

options 参数是可选的,默认值如下

{type:'decimal'}

Fiji la.options.type 可以是 decimalpercentcurrency

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • iOS
  • Windows Phone 8
  • Windows
  • 浏览器

示例

当浏览器设置为 en_US 区域时,这应显示一个弹出对话框,其中包含以下类似的文本

navigator.globalization.getNumberPattern(
    function (pattern) {alert('pattern: '  + pattern.pattern  + '\n' +
                              'symbol: '   + pattern.symbol   + '\n' +
                              'fraction: ' + pattern.fraction + '\n' +
                              'rounding: ' + pattern.rounding + '\n' +
                              'positive: ' + pattern.positive + '\n' +
                              'negative: ' + pattern.negative + '\n' +
                              'decimal: '  + pattern.decimal  + '\n' +
                              'grouping: ' + pattern.grouping);},
    function () {alert('Error getting pattern\n');},
    {type:'decimal'}
);

结果

pattern: #,##0.###
symbol: .
fraction: 0
rounding: 0
positive:
negative: -
decimal: .
grouping: ,

Windows Phone 8 特性

  • pattern 属性不支持,并返回一个空字符串。

  • fraction 属性不支持,并返回零。

Windows 特性

  • pattern 属性不支持,并返回一个空字符串。

浏览器特性

  • getNumberPattern仅在Chrome中得到支持;唯一的定义属性是 pattern

navigator.globalization.isDayLightSavingsTime

指示给定日期是否使用客户端的时间和日历实施夏令时。

navigator.globalization.isDayLightSavingsTime(date, successCallback, errorCallback);

描述

指示是否实施夏令时到 successCallback,并以其作为参数的 properties 对象。该对象应有一个名为 dst 的属性,其值为 Boolean。如果夏令时应用于给定日期,则返回 true,否则返回 false

传入参数 date 应为 Date 类型。

如果读取日期出错,则执行 errorCallback。错误的预期代码是 GlobalizationError.UNKNOWN_ERROR

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows
  • 浏览器

示例

在夏季,如果浏览器设置为启用DST的时间区域,则应显示一个弹出对话框,其中包含类似 dst: true 的文本

navigator.globalization.isDayLightSavingsTime(
    new Date(),
    function (date) {alert('dst: ' + date.dst + '\n');},
    function () {alert('Error getting names\n');}
);

navigator.globalization.numberToString

根据客户端用户偏好返回格式化后的数字字符串。

navigator.globalization.numberToString(number, successCallback, errorCallback, options);

描述

使用包含一个具有 String 值的 value 属性的 properties 对象,将格式化后的数字字符串返回给 successCallback

如果数字格式化出错,则执行 errorCallback 并传递一个作为参数的 GlobalizationError 对象。错误预期代码是 GlobalizationError.FORMATTING_ERROR

options 参数是可选的,其默认值是

{type:'decimal'}

Fiji la.options.type 可以是 decimalpercentcurrency

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • iOS
  • Windows Phone 8
  • Windows
  • 浏览器

示例

当浏览器设置为 en_US 区域时,此操作将弹出类似 number: 3.142 的对话框。

navigator.globalization.numberToString(
    3.1415926,
    function (number) {alert('number: ' + number.value + '\n');},
    function () {alert('Error getting number\n');},
    {type:'decimal'}
);

Windows 特性

  • Windows 8.0 不支持数字四舍五入,因此值不会被自动四舍五入。

  • 在 Windows 8.1 和 Windows Phone 8.1 中,对于 percent 类型的数字,小数部分将被截断而不是四舍五入,因此小数位数设置为 0。

  • 当分组时无法在 stringToNumber 中解析,因此 percent 数字不会被分组。

浏览器特性

  • 不支持 currency 类型。

navigator.globalization.stringToDate

根据客户端用户偏好和客户端时区,使用字符串格式解析日期,并返回相应日期对象。

navigator.globalization.stringToDate(dateString, successCallback, errorCallback, options);

描述

使用作为参数的 properties 对象返回日期到成功回调。该对象应具有以下属性

  • year: 四位数字年份。 (Number)

  • month: 从 (0-11) 的月份。(Number)

  • day: 从 (1-31) 的日期。(Number)

  • hour: 从 (0-23) 的小时。(Number)

  • minute: 从 (0-59) 的分钟。(Number)

  • second: 从 (0-59) 的秒。(Number)

  • millisecond: 毫秒(从 0-999),并非所有平台都提供。(Number)

入站的 dateString 参数应为 String 类型。

选项 参数是可选的,默认值为以下值。

{formatLength:'short', selector:'date and time'}

选项.formatLength 可以是 shortmediumlongfull选项.selector 可以是 datetimedate and time

如果解析日期字符串出错,则执行 errorCallback 并传递一个作为参数的 GlobalizationError 对象。错误预期代码是 GlobalizationError.PARSING_ERROR

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows
  • 浏览器

示例

当浏览器设置为 en_US 区域时,此操作将显示一个弹出对话框,内容类似 month:8 day:25 year:2012。注意,月份整数比字符串小一个,因为月份整数代表数组索引。

navigator.globalization.stringToDate(
    '9/25/2012',
    function (date) {alert('month:' + date.month +
                           ' day:'  + date.day   +
                           ' year:' + date.year  + '\n');},
    function () {alert('Error getting date\n');},
    {selector: 'date'}
);

Windows Phone 8 特性

  • formatLength 选项仅支持 shortfull 值。

  • 'data and time' 选择器的模式始终是完整的日期时间格式。

  • 入站的 dateString 参数应符合 getDatePattern 返回的模式。根据用户区域,该模式可能与 ICU 不完全一致。

Windows 特性

  • formatLength 选项仅支持 shortfull 值。

  • 'data and time' 选择器的模式始终是完整的日期时间格式。

  • 入站的 dateString 参数应符合 getDatePattern 返回的模式。根据用户区域,该模式可能与 ICU 不完全一致。

浏览器怪癖

  • 由于在此方法中使用 moment.js,因此仅支持 79 个区域。

  • 传入的字符串应与 dateToString 输出格式一致,并且根据用户的区域设置可能与 ICU 不完全对齐。

  • 时间选择器仅支持 fullshort 格式的 formatLength

navigator.globalization.stringToNumber

根据客户端用户的偏好将格式化为字符串的数字解析出来,并返回相应的数字。

navigator.globalization.stringToNumber(string, successCallback, errorCallback, options);

描述

将数字返回到以一个具有 properties 对象的参数调用 successCallback。该对象应具有一个具有 Number 值的 value 属性。

如果解析数字字符串时出错,则执行 errorCallback,并以一个包含 GlobalizationError 对象的参数。错误的预期代码是 GlobalizationError.PARSING_ERROR

选项 参数是可选的,默认值为以下值。

{type:'decimal'}

Fiji la.options.type 可以是 decimalpercentcurrency

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • iOS
  • Windows Phone 8
  • Windows

示例

当浏览器设置为 en_US 区域设置时,此操作应显示一个类似数字:1234.56的弹出对话框。

navigator.globalization.stringToNumber(
    '1234.56',
    function (number) {alert('number: ' + number.value + '\n');},
    function () {alert('Error getting number\n');},
    {type:'decimal'}
);

Windows Phone 8 怪癖

  • 对于 percent 类型的,返回的值不会除以 100。

Windows 怪癖

  • 字符串必须严格符合区域格式。例如,在 'en-US' 区域设置中,如果类型参数是 'percent',则百分比符号应通过空格分隔。

  • percent 数字必须分组以正确解析。

GlobalizationError

代表 Globalization API 错误的对象。

属性

  • code:以下错误类型之一 (数字)
    • GlobalizationError.UNKNOWN_ERROR: 0
    • GlobalizationError.FORMATTING_ERROR: 1
    • GlobalizationError.PARSING_ERROR: 2
    • GlobalizationError.PATTERN_ERROR: 3
  • message:包含错误的解释和/或详细信息的文本消息。 (字符串)

描述

此对象由Cordova创建并填充,并在出现错误时返回到回调。

支持的平台

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows

示例

当以下错误回调执行时,它将显示一个包含类似 code: 3message: 的文本的弹出对话框:

function errorCallback(error) {
    alert('code: ' + error.code + '\n' +
          'message: ' + error.message + '\n');
};