Comment vérifier la locale et les options réellement utilisées par un formateur ?
Utilisez la méthode resolvedOptions() pour inspecter la configuration réelle de n'importe quel formateur Intl
Introduction
Lorsque vous créez un formateur Intl en JavaScript, les options que vous demandez ne sont pas toujours celles que vous obtenez. Le navigateur effectue une négociation de locale, remplit les valeurs par défaut et normalise vos paramètres pour créer la configuration finale. La méthode resolvedOptions() vous permet d'inspecter exactement ce que le formateur utilise réellement.
Chaque formateur de l'API Intl possède une méthode resolvedOptions(). Cela inclut Intl.DateTimeFormat, Intl.NumberFormat, Intl.ListFormat, Intl.PluralRules, Intl.Collator et d'autres. La méthode renvoie un objet contenant tous les détails de configuration avec lesquels le formateur s'est finalement retrouvé après avoir traité votre entrée.
Cette méthode est principalement utile pour le débogage, la compréhension du comportement du navigateur et la détection des fonctionnalités disponibles dans l'environnement actuel.
La syntaxe de base
La méthode resolvedOptions() ne prend aucun paramètre. Vous l'appelez sur n'importe quelle instance de formateur et elle renvoie un objet.
const formatter = new Intl.DateTimeFormat('en-US');
const options = formatter.resolvedOptions();
console.log(options);
// {
// locale: 'en-US',
// calendar: 'gregory',
// numberingSystem: 'latn',
// timeZone: 'America/Los_Angeles',
// ...
// }
L'objet renvoyé inclut toujours au minimum les propriétés locale, calendar et numberingSystem pour les formateurs de date, ou locale et numberingSystem pour les formateurs de nombre. Les propriétés supplémentaires dépendent des options que vous avez spécifiées et de ce que le type de formateur prend en charge.
Pourquoi les options demandées diffèrent des options résolues
Il existe trois raisons principales pour lesquelles les options que vous avez demandées peuvent différer des options résolues.
Premièrement, la négociation de locale trouve la meilleure locale disponible lorsque votre demande exacte n'est pas prise en charge. Si vous demandez de-AT mais que le navigateur ne dispose que de de, la locale résolue sera de.
const formatter = new Intl.DateTimeFormat('de-AT-u-ca-buddhist');
const options = formatter.resolvedOptions();
console.log(options.locale);
// Likely outputs: 'de-AT' or 'de'
console.log(options.calendar);
// Likely outputs: 'gregory' (if Buddhist calendar is not supported)
Deuxièmement, le navigateur remplit les valeurs par défaut pour toutes les options que vous ne spécifiez pas. Ces valeurs par défaut sont spécifiques à la locale.
const formatter = new Intl.NumberFormat('en-US');
const options = formatter.resolvedOptions();
console.log(options.style);
// Outputs: 'decimal'
console.log(options.minimumFractionDigits);
// Outputs: 0
console.log(options.maximumFractionDigits);
// Outputs: 3
Troisièmement, le navigateur normalise certaines options dans leur forme canonique. Si vous utilisez dateStyle ou timeStyle, le navigateur ne les inclut pas dans les options résolues. Au lieu de cela, il inclut les options de composants individuels auxquelles elles se développent.
Vérifier la locale réellement utilisée
La propriété locale dans les options résolues vous indique exactement quelle locale le formateur utilise. C'est le résultat de la négociation de locale.
const formatter = new Intl.DateTimeFormat(['zh-TW', 'zh-CN', 'en-US']);
const options = formatter.resolvedOptions();
console.log(options.locale);
// Outputs the first supported locale from the list
Si vous demandez une locale qui inclut des mots-clés d'extension Unicode, la locale résolue pourrait ne pas inclure ces mots-clés s'ils n'étaient pas pris en charge ou s'ils ont été appliqués en tant qu'options séparées.
const formatter = new Intl.NumberFormat('en-US-u-nu-arab');
const options = formatter.resolvedOptions();
console.log(options.locale);
// Might output: 'en-US'
console.log(options.numberingSystem);
// Might output: 'arab' or 'latn' depending on support
Inspecter les options de formatage de date et d'heure
Pour Intl.DateTimeFormat, les options résolues incluent des détails sur les composants de date et d'heure qui seront affichés et comment.
const formatter = new Intl.DateTimeFormat('en-US', {
year: 'numeric',
month: 'long',
day: 'numeric',
timeZone: 'America/New_York'
});
const options = formatter.resolvedOptions();
console.log(options.year);
// Outputs: 'numeric'
console.log(options.month);
// Outputs: 'long'
console.log(options.day);
// Outputs: 'numeric'
console.log(options.timeZone);
// Outputs: 'America/New_York'
console.log(options.calendar);
// Outputs: 'gregory'
Lorsque vous utilisez dateStyle ou timeStyle, ces raccourcis ne sont pas inclus dans les options résolues. Le navigateur les développe en options de composants individuels en fonction de la locale.
const formatter = new Intl.DateTimeFormat('en-US', {
dateStyle: 'full'
});
const options = formatter.resolvedOptions();
console.log(options.dateStyle);
// Outputs: undefined
console.log(options.weekday);
// Outputs: 'long'
console.log(options.year);
// Outputs: 'numeric'
console.log(options.month);
// Outputs: 'long'
console.log(options.day);
// Outputs: 'numeric'
Si vous créez un formateur de date sans aucune option, les options résolues vous montrent ce que le navigateur a choisi comme valeurs par défaut pour cette locale.
const formatter = new Intl.DateTimeFormat('ja-JP');
const options = formatter.resolvedOptions();
console.log(options);
// Shows default date component options for Japanese locale
Inspecter les options de formatage de nombres
Pour Intl.NumberFormat, les options résolues vous indiquent le style, la précision, le regroupement et d'autres détails de formatage.
const formatter = new Intl.NumberFormat('en-US', {
style: 'currency',
currency: 'USD'
});
const options = formatter.resolvedOptions();
console.log(options.style);
// Outputs: 'currency'
console.log(options.currency);
// Outputs: 'USD'
console.log(options.currencyDisplay);
// Outputs: 'symbol'
console.log(options.minimumFractionDigits);
// Outputs: 2
console.log(options.maximumFractionDigits);
// Outputs: 2
Vous pouvez voir que même si vous n'avez spécifié que la devise, le navigateur a rempli les valeurs par défaut pour currencyDisplay et les chiffres de fraction.
Lorsque vous utilisez des options d'arrondi, les options résolues vous montrent exactement comment les nombres seront arrondis.
const formatter = new Intl.NumberFormat('en-US', {
minimumSignificantDigits: 3,
maximumSignificantDigits: 5
});
const options = formatter.resolvedOptions();
console.log(options.minimumSignificantDigits);
// Outputs: 3
console.log(options.maximumSignificantDigits);
// Outputs: 5
Inspection des autres types de formateurs
La méthode resolvedOptions() fonctionne de la même manière sur tous les formateurs Intl.
Pour Intl.ListFormat, elle affiche le type et le style.
const formatter = new Intl.ListFormat('en-US', {
style: 'long',
type: 'conjunction'
});
const options = formatter.resolvedOptions();
console.log(options.locale);
// Outputs: 'en-US'
console.log(options.style);
// Outputs: 'long'
console.log(options.type);
// Outputs: 'conjunction'
Pour Intl.PluralRules, elle affiche le type et les chiffres minimum/maximum.
const formatter = new Intl.PluralRules('en-US', {
type: 'ordinal'
});
const options = formatter.resolvedOptions();
console.log(options.locale);
// Outputs: 'en-US'
console.log(options.type);
// Outputs: 'ordinal'
console.log(options.minimumIntegerDigits);
// Outputs: 1
Cas d'usage courants pour resolvedOptions()
Le cas d'usage le plus courant est le débogage. Lorsque la sortie formatée ne correspond pas à vos attentes, resolvedOptions() vous aide à comprendre ce que le formateur fait réellement.
const formatter = new Intl.DateTimeFormat('en-US', {
dateStyle: 'medium'
});
console.log(formatter.format(new Date()));
// Check the output
console.log(formatter.resolvedOptions());
// See exactly which options produced that output
Un autre cas d'usage est la détection de fonctionnalités. Vous pouvez vérifier si un calendrier, un système de numération ou une autre fonctionnalité spécifique est pris en charge en le demandant et en observant ce qui a été réellement résolu.
const formatter = new Intl.DateTimeFormat('en-US', {
calendar: 'islamic'
});
const options = formatter.resolvedOptions();
if (options.calendar === 'islamic') {
console.log('Islamic calendar is supported');
} else {
console.log('Islamic calendar is not supported, using ' + options.calendar);
}
Vous pouvez également utiliser resolvedOptions() pour obtenir les préférences de locale de l'utilisateur. Lorsque vous créez un formateur sans argument de locale, le navigateur utilise les préférences de l'utilisateur.
const formatter = new Intl.DateTimeFormat();
const options = formatter.resolvedOptions();
console.log(options.locale);
// Outputs: the user's preferred locale
console.log(options.timeZone);
// Outputs: the user's time zone
console.log(options.hourCycle);
// Outputs: the user's hour cycle preference (12 or 24 hour)
Enfin, vous pouvez utiliser les options résolues pour recréer un formateur identique. L'objet retourné peut être transmis au constructeur.
const formatter1 = new Intl.NumberFormat('en-US', {
style: 'currency',
currency: 'USD'
});
const options = formatter1.resolvedOptions();
const formatter2 = new Intl.NumberFormat(options.locale, options);
// formatter2 will format numbers identically to formatter1
Points clés à retenir
La méthode resolvedOptions() retourne un objet contenant la configuration réelle qu'un formateur utilise. Cette configuration peut différer de ce que vous avez demandé en raison de la négociation de locale, des valeurs par défaut et de la normalisation.
Chaque formateur Intl possède cette méthode. Vous l'appelez sans paramètres et recevez un objet avec des propriétés telles que locale, calendar, numberingSystem, et des options spécifiques au formateur.
Utilisez resolvedOptions() principalement pour déboguer le comportement du formateur, détecter les fonctionnalités disponibles et comprendre comment le navigateur a interprété vos options. L'objet retourné peut également être utilisé pour recréer un formateur identique ou inspecter les préférences de l'utilisateur.