intl

方法概述

方法详细说明

convertDateFormatToIntlOptions(format){Intl.DateTimeFormatOptions}

将 web 地图日期格式字符串转换为 Intl.DateTimeFormat 选项对象。

参数

format String optional 要转换的 web 地图日期格式字符串。 可能值："short-date"|"short-date-short-time"|"short-date-short-time-24"|"short-date-long-time"|"short-date-long-time-24"|"long-month-day-year"|"long-month-day-year-short-time"|"long-month-day-year-short-time-24"|"long-month-day-year-long-time"|"long-month-day-year-long-time-24"|"day-short-month-year"|"day-short-month-year-short-time"|"day-short-month-year-short-time-24"|"day-short-month-year-long-time"|"day-short-month-year-long-time-24"|"long-date"|"long-date-short-time"|"long-date-short-time-24"|"long-date-long-time"|"long-date-long-time-24"|"long-month-year"|"short-month-year"|"year"|"short-time"|"long-time"

返回

类型	描述
Intl.DateTimeFormatOptions	从 web 地图规范定义的格式字符串派生的日期格式选项。

另请参阅

• FieldInfoFormat.dateFormat

示例

const dateFormatIntlOptions = intl.convertDateFormatToIntlOptions("short-date-short-time");

// See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat#Parameters
// Setting the string value 'short-date-short-time' is similar to what is set in the object below
// dateFormatIntlOptions = {
//   day: "numeric",
//   month: "numeric",
//   year: "numeric",
//   hour: "numeric",
//   minute: "numeric"
// }

const now = Date.now(); // 1560375191812
const formattedDate = intl.formatDate(now, dateFormatIntlOptions);

console.log(formattedDate); // expected output for US English locale: "6/12/2019, 2:33 PM"

convertNumberFormatToIntlOptions(format){Intl.NumberFormatOptions}

将 NumberFormat 转换为 Intl.NumberFormatOptions 对象。

参数

format NumberFormat optional 要转换的 NumberFormat

返回

类型	描述
Intl.NumberFormatOptions	Intl 数字格式选项。

另请参阅

• FieldInfoFormat

示例

const numberFormatIntlOptions = intl.convertNumberFormatToIntlOptions({
  places: 2,
  digitSeparator: true
});

// See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat#Parameters
// Setting the places and digitSeparator above is similar to what is set below
// numberFormatIntlOptions = {
//   useGrouping: true,
//   minimumFractionDigits: 2,
//   maximumFractionDigits: 2
// }

const number = 123456.789;
const formattedNumber = intl.formatNumber(number, numberFormatIntlOptions);
console.log(formattedNumber); // expected output for English locale: 123,456.79

createJSONLoader(params){MessageBundleLoader}

起始版本：GeoScene Maps SDK for JavaScript 4.18

创建一个消息包加载器，专门用于将翻译文件作为 JSON 文件加载。在内部，这是用于加载 GeoScene Maps SDK for JavaScript 的区域设置的加载程序。

参数

规范

params Object 加载程序的配置。 规范 pattern String|RegExp 用于检查是否应使用加载程序来加载候选消息包。 base String 用于计算要加载的文件的相对路径。 location String|URL|Function 翻译文件的位置。它可以是指向文件所在文件夹的 string 或 URL，也可以是使用指定路径调用的函数。该函数应返回最终路径。

返回

类型	描述
MessageBundleLoader	loader - 消息包加载程序。

另请参阅

• fetchMessageBundle()

• registerMessageBundleLoader()

• 示例 - 创建自定义微件

示例

// Assume the following directory structure
src/
  assets/
    translations/
      MyBundle.json
      MyBundle_fr.json
  widgets/
    MyWidget.ts

// Configure the message bundle loader given the directory structure noted above

const loader = intl.createJSONLoader({
  pattern: "my-application/", // The pattern is used to match the string in `intl.fetchMessageBundle("my-application/translations/MyBundle")`
  base: "my-application", // This removes the base, ie. "translations/MyBundle"
  location: new Url("./assets/", window.location.href) // Add the location, ie. "assets/translations/MyBundle"
});

// This loads file, "./assets/translations/MyBundle.json" or
// "./assets/translations/MyBundle_en.json" (unless locale is updated to something, e.g. like `fr`).

// Register the message bundle created from the createJSONLoader method
intl.registerMessageBundleLoader(loader);

// Fetches the message bundle, "./assets/translations/MyBundle.json"
const bundle = await intl.fetchMessageBundle("my-application/MyBundle");

// If no `base` property is specified for the loader method, the assets would read as,
src/
  assets/
    my-application/
      translations/
        MyBundle.json
        MyBundle_en.json
        MyBundle_fr.json

// The method would load file, "./assets/my-application/translations/MyBundle.json" or
// "./assets/my-application/translations/MyBundle_en.json" (unless locale is updated to something, e.g. like `fr`).

fetchMessageBundle(bundleId){Promise<object>}

起始版本：GeoScene Maps SDK for JavaScript 4.18

加载与当前 API 区域设置一起使用的本地化消息包。消息包是一个包含翻译的对象，可作为文件存储在磁盘上，也可作为代码中的对象存储。在内部，GeoScene Maps SDK for JavaScript 使用包含本地化翻译的 JSON 文件。这些捆绑包由唯一的字符串标识，即bundleId。

如果函数使用的是微件之外的翻译字符串，则应使用 fetchMessageBundle 方法。然而，如果微件需要使用消息包，则它应通过 @messageBundle 装饰器来执行此操作。

fetchMessageBundle 方法的工作方式为：通过查找具有与消息标识符相匹配的 pattern 的第一个加载器。然后，调用加载器自己的 fetchMessageBundle 函数。如果返回的 Promise 拒绝，则 fetchMessageBundle 会查找另一个加载器并重复该操作，直到加载器成功获取一个包，或者没有更多的加载器可用。

以下是一个 JSON 消息包示例，用于为英语地区本地化的 Home 微件。下面是同一微件字符串的法语语言环境翻译包。

参数

bundleId String 消息包的标识符，传递给注册到 registerMessageBundleLoader 的加载程序。

返回

类型	描述
Promise<Object>	解析后，将包含本地化消息字符串的对象。

另请参阅

• registerMessageBundleLoader()

• @messageBundle

示例

// This snippet shows the JSON message bundle used for the Home widget in English
{
  "widgetLabel": "Home",
  "button": "Home",
  "title": "Default map view"
}

// This snippet shows the same translation strings in the French locale
{
  "widgetLabel": "Accueil",
  "button": "Accueil",
  "title": "Vue cartographique par défaut"
}

// Fetches the message bundle from the specified location
const bundle = await intl.fetchMessageBundle("my-application/MyBundle");
// English message bundle is loaded

// If needing to update or set locale, call setLocale
intl.setLocale("fr");

// Once locale is updated, fetch the new French message bundle
const bundle = await intl.fetchMessageBundle("my-application/MyBundle");

formatDate(value, formatOptions){String}

将 Date 或 Number 值的格式设置为当前区域设置中的字符串。

formatDate 在内部为当前语言环境创建 Intl formatter 实例。格式化程序使用它们的 options 作为缓存键进行缓存。重复使用相同的 options 对象以获得最佳性能。

参数

value Date|Number 要格式化的 Date 对象，或自 January 1, 1970 00:00:00 UTC 以来经过的毫秒数。

formatOptions Intl.DateTimeFormatOptions optional 日期格式选项。

返回

类型	描述
String	输入日期值的格式化字符串。

另请参阅

• FieldInfoFormat.dateFormat

示例

const now = Date.now(); // 1560375191812
const dateFormatIntlOptions = intl.convertDateFormatToIntlOptions("short-date-short-time");

const formattedDate = intl.formatDate(now, dateFormatIntlOptions);

console.log(formattedDate); // expected output for English locale: "6/12/2019, 2:33 PM"

formatNumber(value, formatOptions){String}

将 Number 值的格式设置为当前区域设置中的字符串。

formatNumber 在内部为当前语言环境创建 Intl formatter 实例。格式化程序使用它们的 options 作为缓存键进行缓存。重复使用相同的 options 对象以获得最佳性能。

参数

value Number 要设置格式的数字。

formatOptions Intl.NumberFormatOptions optional 数字格式选项。

返回

类型	描述
String	输入数字的格式化字符串。

示例

// Formats a number with a fixed number of places using a digit separator
const numberFormatIntlOptions = intl.convertNumberFormatToIntlOptions({
  places: 2,
  digitSeparator: true
});

const number = 123456.789;
const formattedNumber = intl.formatNumber(123456.789, numberFormatIntlOptions);
console.log(formattedNumber); // In US English locale: 123,456.79

// Formats a number as currency, in Euros
const amount = 14;
const formattedNumber = intl.formatNumber(amount, {
  style: "currency",
  currency: "EUR",
  currencyDisplay: "symbol"
});
console.log(formattedNumber); // In for US English locale: €14.00

// Formats a number as percentage
const growth = 0.5;
const formattedNumber = intl.formatNumber(growth, {
  style: "percent"
});
console.log(formattedNumber); // In for US English locale: 50%

getLocale(){String}

起始版本：GeoScene Maps SDK for JavaScript 4.16

返回 API 使用的当前区域设置。API 按指定顺序读取此信息。此顺序描述如下：

1. 使用全局 geosceneConfig 变量初始化什么，它也初始化 geoscene/config 模块。
2. 在 dojoConfig.locale 中针对向后兼容性设置了什么
3. navigator.language 的设置是什么，即由 web 浏览器的用户首选项定义的区域设置。

设置区域设置的首选方法是通过 setLocale() 方法。使用 onLocaleChange() 可以调用回调来通知区域设置。

区域设置默认为 en (英语)。

返回

类型	描述
String	当前区域设置字符串。

另请参阅

• MDN Web 文档中的 NavigatorLanguage

• setLocale()

• onLocaleChange()

normalizeMessageBundleLocale(locale){String|null}

起始版本：GeoScene Maps SDK for JavaScript 4.18

返回输入区域设置的已知消息包区域设置之一。例如，"fr-FR" 的已知消息包语言环境是 "fr"。

以下语言环境可用：ar、bs、ca、cs、da、de、el、en、es、et、fi、fr、he、hi、hr、hu、id、it、ja、ko、lt、lv、nb、nl、pl、pt-BR、pt-PT、ro、ru、sk、sl、sr、sv、th、tr、uk、vi、zh-CN、zh-HK 和 zh-TW。

参数

locale String 任何区域设置字符串。

返回

类型	描述
String | null	规范化区域设置，如果未找到已知区域设置，则为 null。

示例

// For example: `en-US`
let locale = intl.getLocale();
// locale is now `en`
locale = intl.normalizeMessageBundleLocale(locale);

onLocaleChange(callback){Handle}

起始版本：GeoScene Maps SDK for JavaScript 4.16

注册一个 callback，以在区域设置更改时收到通知。当调用 setLocale() 时，或者当用户更改 Web 浏览器区域设置并且当前区域设置等于 Web 浏览器的区域设置时，会发生这种情况。

参数

callback LocaleChangeCallback 区域设置更改时触发的函数。它是在执行 setLocale() 方法后使用新设置的区域设置调用的。

返回

类型	描述
Handle	返回一个处理程序，其中包含一个 remove() 方法，调用该方法可移除回调并停止侦听区域设置的更改。

另请参阅

• getLocale()

• setLocale()

示例

// Initially fetches the message bundle in the current language.
let bundle = await intl.fetchMessageBundle("my-application/MyBundle");
// Do something with the bundle

// Set the locale to French
intl.setLocale("fr");

// Listen for when locale is changed and then fetch the updated French message bundle
intl.onLocaleChange(function(locale) {
  console.log("locale changed to: ", locale);
  let bundle = await intl.fetchMessageBundle("my-application/MyBundle");
});

prefersRTL(locale){Boolean}

起始版本：GeoScene Maps SDK for JavaScript 4.16

为输入区域设置提供从右到左的首选项。

参数

locale String optional 用于获取从右到左信息的区域设置字符串。默认情况下，使用当前区域设置。

返回

类型	描述
Boolean	如果输入 locale 首选从右到左，则返回 true。例如，如果语言环境是 ar 或 he，则返回 true。

registerMessageBundleLoader(loader){Object}

起始版本：GeoScene Maps SDK for JavaScript 4.18

注册消息加载器，以加载翻译字符串所需的指定消息包。此方法需要在获取应用程序的消息包之前调用。

有两个选项可用于创建所需的 MessageBundleLoader 参数。

1. 通过实现 MessageBundleLoader 来定义您自己的加载器，或者
2. 使用 loader API 通过便捷方法 createJSONLoader 实现。

下面提供了两者的示例。

参数

loader MessageBundleLoader 消息包加载程序。

返回

类型	描述
Object	返回一个带有 remove() 方法的处理程序，可以调用该方法来取消注册消息加载器。 属性 类型 描述 remove Function 调用时，取消注册消息加载器。

另请参阅

• 示例 - 创建自定义微件

• fetchMessageBundle()

• registerMessageBundleLoader()

• normalizeMessageBundleLocale()

• @messageBundle
• MessageBundleLoader
• createJSONLoader

示例

// This example defines a loader by implementing a MessageBundleLoader.

// Register a loader that loads bundles with the specified bundle identifier
// starting with "my-application\/"

const patternBundle = /^my-application\/(.+)/g;

intl.registerMessageBundleLoader({
  pattern: patternBundle,
  // Calls the FetchMessageBundle function of the loader, passing in the bundle identifier and locale
  async fetchMessageBundle(bundleId, locale) {
    // extract the filename from the bundle id.
    const filename = pattern.exec(bundleId)[1];
    // normalize the locale, e.g. 'fr-FR' > 'fr'
    const knownLocale = intl.normalizeMessageBundleLocale(locale);
    // Fetch the corresponding JSON file given the specified url path
    const response = await fetch(new Url(`./assets/translations/${filename}_${knownLocale}.json`, window.location.href));
    return response.json();
  }
});

// If the locale changes, calling fetchMessageBundle resolves to the new localized message bundle.
intl.onLocaleChange((newLocale) => {
  const bundle = await intl.fetchMessageBundle("my-application/translations/MyBundle");
  // loads file: "https://myserver/my-application/translations/MyBundle_fr.json"
});

// Updates the locale
intl.setLocale("fr");

// This example defines the loader via the createJSONLoader method.

// Register a loader that loads bundles with the specified bundle identifier
// starting with "my-application\/"

const patternBundle = /^my-application\/(.+)/g;

intl.registerMessageBundleLoader(
  intl.createJSONLoader({
    pattern: patternBundle,
    base: "my-application/",
    location: new URL("./assets/", window.location.href)
  })
);

// If the locale changes, calling fetchMessageBundle resolves to the new localized message bundle.
intl.onLocaleChange((newLocale) => {
  const bundle = await intl.fetchMessageBundle("my-application/MyBundle");
 // loads file: "https://myserver/my-application/MyBundle_fr.json"
});

// Updates the locale
intl.setLocale("fr");

setLocale(locale)

起始版本：GeoScene Maps SDK for JavaScript 4.16

设置 API 所使用的区域设置。这是设置 API 区域设置的首选方法。

当区域设置更改时，将调用 onLocaleChange() 的注册回调。

当语言环境在运行时发生变化时，JavaScript API 微件会做出反应。请注意，这被认为是实验性的。

JavaScript API 为 number 和格式化为 web 浏览器的 Intl API 的 date 提供相同级别的支持。对于微件的翻译，可使用以下一组语言环境：ar、bg、bs、ca、cs、da、de、el、en、es、et、fi、fr、he、hr、hu、id、it、ja、ko、lt、lv、nb、nl、pl、pt-BR、pt-PT、ro、ru、sk、sl、sr、sv、th、tr、uk、vi、zh-CN、zh-HK 和 zh-TW。

如果翻译消息对于当前的区域设置不可用，则语言根据 getLocale() 中描述的顺序进行确定；否则默认为英文消息。

然后，可以将语言环境设置为 en-US 或 en-GB。微件使用 en 消息进行翻译，而日期和数字使用其相应的格式。

参数

locale String 新的 Unicode 区域设置标识符字符串，类似于 Intl API。如果这是 undefined，则区域设置将重置为其在 getLocale() 中描述的默认值。

另请参阅

• MDN Web Docs 上有关语言环境的更多信息

• getLocale()

• onLocaleChange()

• 示例 - 创建自定义微件

示例

// Sets the locale to French
intl.setLocale("fr");

// Sets the locale to UK English.
// Dates are formatted in day/month/year order.
intl.setLocale("en-GB");

// Sets the locale to US English.
// Dates are formatted in month/day/year order.
intl.setLocale("en-US");

substitute(template, data, options){String}

使用此选项可将 template 字符串中的 substitute 键替换为参数 data 中的值。null 或 undefined 值不会打印在输出结果中。

可以指定 data 中的值的格式。默认情况下，这些值将根据其原生 JavaScript 类型进行格式化。

substitute 在内部为当前语言环境创建 Intl formatter 实例。格式化程序使用 options 作为缓存键进行缓存。重复使用相同的 options 对象以获得最佳性能。

参数

template String 用于替换的模板字符串。

data Object 要替换的数据对象。

options SubstituteOptions optional 用于确定如何替换模板字符串中的键的选项。

返回

类型	描述
String	格式化字符串。

示例

// Format a date
const data = {
  increasedValue: 500,
  time: Date.UTC(2019),
}

const dateFormatOptions = intl.convertDateFormatToIntlOptions("short-date-short-time-24");

intl.substitute("Date: {time}", data, {
  format: {
    time: {
      type: "date",
      intlOptions: dateFormatOptions
    }
  }
});

// Format a number
const data = {
  increasedValue: 500,
  time: Date.UTC(2019),
}

intl.substitute("Number: {value}", data, {
  format: {
    value: {
      type: "number",
      intlOptions: {
        maximumFractionDigits: 21
      }
    }
  }
});

const data = {
  increasedValue: 500,
  time: Date.UTC(2019),
}

intl.substitute("Median income increased by {increasedValue} in {time:yearFormat}", data, {
  format: {
    increasedValue: {
      type: "number",
      intlOptions: {
        useGrouping: true,
        currency: "EUR",
        currencyDisplay: "symbol",
        maximumFractionDigits: 2
      }
    },
    yearFormat: {
      type: "date",
      intlOptions: {
        year: "numeric"
      }
    }
  }
});

类型定义

FetchMessageBundle(bundleId, locale){Promise<object>}

起始版本：GeoScene Maps SDK for JavaScript 4.18

负责为特定区域设置获取消息包资源的函数。

参数

bundleId String 要本地化的包的标识符。

locale String 要在其中加载包的区域设置。

返回

类型	描述
Promise<Object>	解析为包含本地化消息字符串的对象。

另请参阅

• 示例 - 创建自定义微件

• registerMessageBundleLoader()

LocaleChangeCallback(newLocale)

onLocaleChange() 方法可在区域设置更改时注册此回调。

参数

newLocale String 一个字符串，包含对已更改区域设置的引用。

MessageBundleLoader

起始版本：GeoScene Maps SDK for JavaScript 4.18

消息包加载程序是用于在用户区域设置中加载翻译字符串的对象。它必须在 intl 中使用 registerMessageBundleLoader 进行注册。在 API 中加载消息捆绑包时，首先评估最后注册的加载程序。

属性

pattern String|RegExp 用于检查是否应使用加载程序来加载候选消息包。

fetchMessageBundle FetchMessageBundle 调用以加载消息包，如果 pattern 匹配包标识符。

另请参阅

• 示例 - 创建自定义微件

• fetchMessageBundle()

• registerMessageBundleLoader()

• createJSONLoader

示例

const loader = {
  // The loader matches all the bundle identifiers starting with "my-application/"
  pattern: "my-application/",
  // fetch the JSON file from a `translations` folder
  async fetchMessageBundle(bundleId, locale) {
    const url = new URL(`/assets/translations/${bundleId}_${locale}.json`, window.location.href);
    const response = await fetch(url);
    return response.json();
  }
};

registerMessageBundleLoader(loader);

// Fetch file `./translations/my-application/MyBundle_en-US.json`
const bundle = await fetchMessageBundle("my-application/translations/MyBundle");

NumberFormat

用于设置数字格式的 Web 地图定义。这提供了有关如何显示数字值的更多详细信息。

属性

digitSeparator Boolean optional 指示是否应使用千位分隔符设置数字的格式。这等效于 useGrouping。

places Number optional 指定应在格式化数字中显示的小数位数。超出此值的任何地方都将四舍五入。这等效于定义 minimumFractionDigits 和 maximumFractionDigits。

另请参阅

• FieldInfoFormat

• Web 地图规范 - 格式

• FieldInfoFormat

SubstituteDateTimeFormatOptions

日期值的格式设置选项。

属性

type String 此格式的类型。值通常是 "date"。 值通常是 "date"。

intlOptions Intl.DateTimeFormatOptions Intl.DateTimeFormat 对象的日期格式选项。

另请参阅

• SubstituteOptions

示例

const dateFormat = {
  type: "date",
  intlOptions: {
    year: "numeric",
    month: "numeric",
    day: "numeric",
    hour: "numeric",
    minute: "numeric"
  }
};

let data = {
  time: Date.now()
};

intl.substitute("Date: {time}", data, {
  format: {
    time: dateFormat
  }
});

SubstituteNumberFormatOptions

数值的格式设置选项。

属性

type String 此格式的类型。值通常是 "number"。 值通常是 "number"。

intlOptions Intl.NumberFormatOptions Intl.NumberFormat 对象的 Intl 数字格式选项。

另请参阅

• SubstituteOptions

示例

// Formats a number with a fixed number of fraction digits
const numberFormat = {
  type: "number",
  intlOptions: {
    style: "decimal",
    useGrouping: true,
    minimumFractionDigits: 2,
    maximumFractionDigits: 2
  }
});

let data = {
  value: 10
};

intl.substitute("A number: {value}", data, {
  value: numberFormat
});

// Formats a number as currency, in Euros.
const currencyFormat = {
  type: "number",
  intlOptions: {
    style: "currency",
    currency: "EUR",
    currencyDisplay: "symbol"
  }
};

let data = {
  amount: 14
};

intl.substitute("Amount: {amount}", data, {
  amount: currencyFormat
});

// Formats a number as a percentage.
const percentFormat = {
  type: "number",
  intlOptions: {
    style: "percent"
  }
};

let data = {
  growth: 0.5
};

intl.substitute("Growth: {growth}", data, {
  growth: percentFormat
});

SubstituteOptions

指定替换选项的对象。

使用 format 属性可定义字符串模板中引用的每个值的格式。format 是一个键值对对象。每个键可以是：

• data 参数的属性或 substitute()
• 可以在模板字符串中引用的命名格式化程序。

在以下示例中，data 的 time 属性将格式化为日期，每个组件都采用数字格式。

const data = {
  time: Date.now()
};

intl.substitute("Date: {time}", data, {
  format: {
    time: {
      type: "date",
      intlOptions: {
        year: "numeric",
        month: "numeric",
        day: "numeric",
        hour: "numeric",
        minute: "numeric"
      }
    }
  }
});

以下示例使用命名格式化程序以使用不同的格式设置选项对 time 属性进行两次格式化。

const data = {
  time: Date.now()
};

intl.substitute("In {time:monthFormat} of {time:yearFormat}", data, {
  format: {
    monthFormat: {
      type: "date",
      intlOptions: {
        month: "long"
      }
    },
    yearFormat: {
      type: "date",
      intlOptions: {
        year: "numeric"
      }
    }
  }
});

属性

format HashMap<(SubstituteDateTimeFormatOptions|SubstituteNumberFormatOptions)> 字符串键到格式设置选项的哈希映射。

另请参阅

• substitute()