intl

方法列表

方法详细说明

convertDateFormatToIntlOptions(format){Intl.DateTimeFormatOptions}

将 web 地图日期格式字符串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 要转换的数字格式。

返回值:

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

示例:

• 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 API for JavaScript 4.22

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

参数:

规范:

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

返回值:

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

示例:

• 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 API for JavaScript 4.22

加载与当前 API 语言环境一起使用的本地化消息包。消息包是一个包含翻译的对象，可以作为文件存储在磁盘上，也可以作为代码中的对象存储。在内部，适用于 JavaScript 的 GeoScene API 使用包含本地化翻译的 JSON 文件。这些捆绑包由唯一的字符串标识，即。 bundleId.

fetchMessageBundle 方法应该在函数使用小部件之外的翻译字符串时使用。然而，如果一个 widget 需要使用消息包，它应该通过 @messageBundle 装饰器。

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

以下是 JSON 的示例 Home 小部件使用的消息包已本地化为美国英语语言环境。下面是同一个小部件字符串的法国法语语言环境翻译包。

参数:

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

返回值:

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

示例:

• registerMessageBundleLoader()

• @messageBundle

示例代码:

// 此片段显示了用于英文主页小部件的 JSON 消息包
{
  "widgetLabel": "Home",
  "button": "Home",
  "title": "Default map view"
}

// 此片段显示法语语言环境中的相同翻译字符串
{
  "widgetLabel": "Accueil",
  "button": "Accueil",
  "title": "Vue cartographique par défaut"
}

// 从指定位置获取消息包
const bundle = await intl.fetchMessageBundle("my-application/MyBundle");
// 英文消息包已加载

// 如果需要更新或设置语言环境，请调用 setLocale
intl.setLocale("fr");

// 更新语言环境后，获取新的法语消息包
const bundle = await intl.fetchMessageBundle("my-application/MyBundle");

formatDate(value, formatOptions){String}

将 Date 或 Number 值格式化为当前语言环境中的字符串。

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

参数:

value Date|Number 要格式化的 Date 对象或自 1970 年 1 月 1 日 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 格式化程序 当前语言环境的实例。 格式化程序使用它们的 options 作为缓存键进行缓存。 重复使用相同的 options 对象以获得最佳性能。

参数:

value Number 要设置格式的数字。

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

返回值:

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

示例代码:

// 使用数字分隔符格式化具有固定位数的数字
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

// 将数字格式化为货币，以欧元为单位
const amount = 14;
const formattedNumber = intl.formatNumber(amount, {
  style: "currency",
  currency: "EUR",
  currencyDisplay: "symbol"
});
console.log(formattedNumber); // In for US English locale: €14.00

// 将数字格式化为百分比
const growth = 0.5;
const formattedNumber = intl.formatNumber(growth, {
  style: "percent"
});
console.log(formattedNumber); // In for US English locale: 50%

getLocale(){String}

起始版本: GeoScene API for JavaScript 4.22

返回 API 使用的当前语言环境。 API 按指定顺序读取此信息。这个顺序描述如下：

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

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

语言环境默认为 en（英文）。

返回值:

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

示例:

• MDN Web 文档上的 NavigatorLanguage

• setLocale()

• onLocaleChange()

normalizeMessageBundleLocale(locale){String|null}

起始版本: GeoScene API for JavaScript 4.22

返回输入语言环境的已知消息包语言环境之一。 例如，"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 API for JavaScript 4.22

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

参数:

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

返回值:

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

示例:

• getLocale()

• setLocale()

示例代码:

// 用当前语言获取消息包初始化。
let bundle = await intl.fetchMessageBundle("my-application/MyBundle");
// 使用消息包

// 将语言环境设置为法语
intl.setLocale("fr");

// 监听区域设置何时更改，然后获取更新的法语消息包
intl.onLocaleChange(function(locale) {
  console.log("locale changed to: ", locale);
  let bundle = await intl.fetchMessageBundle("my-application/MyBundle");
});

prefersRTL(locale){Boolean}

起始版本: GeoScene API for JavaScript 4.22

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

参数:

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

返回值:

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

registerMessageBundleLoader(loader){Object}

起始版本: GeoScene API for JavaScript 4.22

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

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

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

下面提供了两者的示例。

参数:

loader MessageBundleLoader 消息包加载程序。

返回值:

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

示例:

• 示例 - 创建自定义微件

• 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 API for JavaScript 4.22

设置 API 使用的语言环境。这是设置 API 区域设置的首选方法。

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

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

JavaScript API 为 number 和 date 格式化为 Web 浏览器的 Intl API 提供相同级别的支持。对于小部件的翻译，可以使用以下一组语言环境：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。

如果当前没有翻译消息locale，语言根据 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 字符串中的键替换为参数 data 中的值。 null 或 undefined 值不会打印在输出结果中。

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

在内部 substitute 创建 当前语言环境的国际格式化程序实例。 格式化程序使用 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 API for JavaScript 4.22

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

参数:

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

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

返回值:

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

示例:

• 示例 - 创建自定义微件

• registerMessageBundleLoader()

LocaleChangeCallback(newLocale)

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

参数:

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

MessageBundleLoader

起始版本: GeoScene API for JavaScript 4.22

消息包加载程序是用于在用户区域设置中加载翻译字符串的对象。它必须在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"。 该值始终为"日期"。

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" 。 该值始终为"数字"。

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"
      }
    }
  }
});

Property:

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

示例:

• substitute()