Contenu

# Service ScriptForge.Region

Le service Region fournit un ensemble de propriétés et de méthodes pour gérer les aspects de programmation liés aux paramètres locaux et régionaux, tels que :

- Accéder aux paramètres locaux et régionaux tels que le formatage des nombres, la devise et les fuseaux horaires.

- Convertir les fuseaux horaires et calculer les décalages de l'heure d'été (DST).

- Transformer des nombres en texte dans n'importe quelle langue prise en charge.

## Définitions

### Locale ou région

Une chaîne combinant une langue et un pays au format "la-CO". La partie langue est exprimée avec 2 ou 3 caractères minuscules suivis d'un tiret et de 2 caractères majuscules représentant le pays.

Par exemple, « en-US » correspond à la langue anglaise aux États-Unis ; « fr-BE » correspond à la langue française en Belgique, et ainsi de suite.

Dans certaines situations, les paramètres régionaux complets ne sont pas requis et seuls la langue ou le pays peuvent être spécifiés.

La plupart des propriétés et méthodes acceptent une locale comme argument. Si aucun paramètre régional n'est spécifié, les paramètres régionaux de l'interface utilisateur sont utilisés, qui sont définis dans OfficeLocale propriété du service Platform.

### Fuseau horaire

Une chaîne au format "Région/Ville", telle que "Europe/Berlin", ou un ID de fuseau horaire tel que "UTC" ou "GMT-8:00". Reportez-vous à la page wiki Liste des fuseaux horaires de la base de données tz pour obtenir une liste des noms et identifiants de fuseaux horaires possibles.

Fournir une chaîne de fuseau horaire incorrecte à l'une des méthodes du service Region n'entraînera pas d'erreur d'exécution. Au lieu de cela, des méthodes telles que UTCDateTime et UTCNow renverront la date et l'heure actuelles du système d'exploitation.

Le décalage horaire entre le fuseau horaire et l'heure du méridien de Greenwich (GMT) est exprimé en minutes.

L'heure d'été (DST) est un décalage supplémentaire.

Les décalages de fuseau horaire et DST peuvent être positifs ou négatifs.

## Invocation du service

Avant d'utiliser le service Region, la bibliothèque ScriptForge doit être chargée ou importée :

• Les macros Basic nécessitent de charger la bibliothèque ScriptForge à l'aide de l'instruction suivante :
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Les scripts Python nécessitent un import depuis le module scriptforge :
from scriptforge import CreateScriptService

Les exemples ci-dessous en Basic et Python instancient le service Region et accèdent à la propriété Country.

##### En Basic :

        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        Dim oRegion As Variant
        oRegion = CreateScriptService("Region")
        MsgBox oRegion.Country("en-US") ' United States

##### En Python

        from scriptforge import CreateScriptService
        oRregion = CreateScriptService("Region")
        bas = CreateScriptService("Basic")
        bas.MsgBox(oRegion.Country("en-US"))

## Propriétés

Toutes les propriétés répertoriées ci-dessous acceptent un argument locale, fourni sous forme de chaîne. Certaines propriétés exigent que cet argument soit au format "la-CO", tandis que d'autres peuvent recevoir "la" ou "CO" en entrée.

Nom | Lecture seule | Type | Locale | Description
--- | --- | --- | --- | ---
Country | Oui | String | "la‑CO" "CO" | Renvoie le nom du pays en anglais correspondant à une région donnée.
Currency | Oui | String | "la-CO" "CO" | Renvoie le code de devise ISO 4217 de la région spécifiée.
DatePatterns | Oui | Matrice de chaîne | "la-CO" | Renvoie une matrice de chaînes de base zéro contenant les modèles d'acceptation de date pour la région spécifiée.
DateSeparator | Oui | String | "la-CO" | Renvoie le séparateur de date utilisé dans la région donnée.
DayAbbrevNames | Oui | Matrice de chaîne | "la-CO" "la" | Renvoie une matrice de chaînes de base zéro contenant la liste des noms abrégés des jours de la semaine dans la langue spécifiée.
DayNames | Oui | Matrice de chaîne | "la-CO" "la" | Renvoie un tableau de chaînes de base zéro contenant la liste des noms de jours de la semaine dans la langue spécifiée.
DayNarrowNames | Oui | Matrice de chaîne | "la-CO" "la" | Renvoie une de chaînes de base zéro contenant la liste des initiales des noms de jours de la semaine dans la langue spécifiée.
DecimalPoint | Oui | String | "la-CO" | Renvoie le séparateur décimal utilisé dans les nombres de la région spécifiée.
Language | Oui | String | "la-CO" "la" | Renvoie le nom de la langue, en anglais, de la région spécifiée.
ListSeparator | Oui | String | "la-CO" | Renvoie le séparateur de liste utilisé dans la région donnée.
MonthAbbrevNames | Oui | Matrice de chaîne | "la-CO" "la" | Renvoie une matrice de chaînes de base zéro contenant la liste des noms de mois abrégés dans la langue spécifiée.
MonthNames | Oui | Matrice de chaîne | "la-CO" "la" | Renvoie une matrice de chaînes de base zéro contenant la liste des noms de mois dans la langue spécifiée.
MonthNarrowNames | Oui | Matrice de chaîne | "la-CO" "la" | Renvoie une matrice de chaînes de base zéro contenant la liste des initiales des noms de mois dans la langue spécifiée.
ThousandSeparator | Oui | String | "la-CO" | Renvoie le séparateur de milliers utilisé dans les nombres de la région spécifiée.
TimeSeparator | Oui | String | "la-CO" | Renvoie le séparateur utilisé pour formater les heures dans la région spécifiée.

Liste des méthodes dans le service Region
DSTOffset LocalDateTime | Number2Text TimeZoneOffset | UTCDateTime UTCNow

## DSTOffset

Calcule le décalage supplémentaire de l'heure d'été (DST), en minutes, qui s'applique à une région et à un fuseau horaire donnés.

### Syntaxe :

svc.DSTOffset(localdatetime: date, timezone: str, opt locale: str): int

### Paramètres :

localdatetime : la date et l'heure locales exprimées sous forme de date.

timezone : le fuseau horaire pour lequel le décalage sera calculé.

locale : la locale spécifiant le pays pour lequel le décalage sera calculé, donnée au format "la-CO" ou "CO". La valeur par défaut est la locale définie dans la propriété OfficeLocale du service Platform.

### Exemple :

##### En Basic :

          ' Calcule le décalage applicable dans le fuseau horaire "America/Los_Angeles"
          Dim aDateTime As Date, offset As Integer
          aDateTime = DateSerial(2022, 7, 1) + TimeSerial(16, 0, 0)
          offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 60 (minutes)
          aDateTime = DateSerial(2022, 1, 1) + TimeSerial(16, 0, 0)
          offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minutes)

##### En Python

          import datetime
          aDateTime = datetime.datetime(2022, 7, 1, 16, 0, 0)
          offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 60 (minutes)
          aDateTime = datetime.datetime(2022, 1, 1, 16, 0, 0)
          offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minutes)

## LocalDateTime

Calcule la date et l'heure locales à partir d'une date et d'une heure UTC.

### Syntaxe :

svc.LocalDateTime(utcdatetime: date, timezone: str, opt locale: str): date

### Paramètres :

utcdatetime : la date et l'heure UTC, exprimées à l'aide d'un objet date.

timezone : le fuseau horaire pour lequel l'heure locale sera calculée.

locale : la locale spécifiant le pays pour lequel l'heure locale sera calculée, donnée au format "la-CO" ou "CO". La valeur par défaut est la locale définie dans la propriété OfficeLocale du service Platform.

### Exemple :

##### En Basic :

          ' 6 juin 2022 à 10:30:45 (utilisé ici comme heure UTC)
          Dim UTCTime As Date, localTime As Date
          UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)
          ' Calcule l'heure locale à Sao Paulo, Brésil
          ' 6 juin 2022 à 07:30:45
          localTime = oRegion.LocalDateTime(UTCTime, "America/Sao_Paulo", "BR")

##### En Python

          import datetime
          utcTime = datetime.datetime(2022, 6, 23, 10, 30, 45)
          localTime = oRegion.LocalDateTime(utcTime, "America/Sao_Paulo", "BR")

## Number2Text

Convertit les nombres et les valeurs monétaires en texte écrit pour l'une des langues actuellement prises en charge.

Pour une liste de toutes les langues prises en charge, visitez la référence de l'API XNumberText Interface.

### Syntaxe :

svc.Number2Text(number: any, opt locale: str): str

### Paramètres :

number : le nombre à convertir en texte écrit. Il peut être fourni sous la forme d'un type numérique ou d'une chaîne. Lorsqu'une chaîne est fournie, elle peut être précédée d'un préfixe indiquant comment les nombres doivent être écrits. Il est également possible d'inclure des codes de devise ISO 4217. Voir les exemples ci-dessous pour plus d'informations.

locale : la langue définissant la langue dans laquelle le nombre sera converti, donnée au format "la-CO" ou "la". La valeur par défaut est la locale définie dans la propriété OfficeLocale du service Platform.

### Exemple :

##### En Basic :

          ' Renvoie "cent cinq"
          Dim numText As String
          numText = oRegion.Number2Text(105, "en-US")
          ' Renvoie : "deux virgule quatre deux"
          numText = oRegion.Number2Text(2.42, "en-US")
          ' Renvoie : "vingt-cinq euros et dix cents" Remarquez le symbole monétaire "EUR"
          numText = oRegion.Number2Text("EUR 25.10", "en-US")
          ' Renvoie : "quinzième" ; Remarquez le préfixe "ordinal"
          numText = oRegion.Number2Text("ordinal 15", "en-US")

##### En Python

          numText = oRegion.Number2Text(105, "en-US")
          numText = oRegion.Number2Text(2.42, "en-US")
          numText = oRegion.Number2Text("EUR 25.10", "en-US")
          numText = oRegion.Number2Text("ordinal 15", "en-US")

Pour obtenir une liste de tous les préfixes pris en charge dans une langue donnée, appelez Number2Text avec l'argument spécial "help". Dans l'exemple ci-dessous, supposons que vos paramètres régionaux sont définis sur "en-US", alors la liste des préfixes disponibles pour "en-US" sera affichée par MsgBox :

          prefixes = oRegion.Number2Text("help")
          MsgBox prefixes
          ' one, two, three
          ' ordinal: first, second, third
          ' ordinal-number: 1st, 2nd, 3rd
          ' year: nineteen ninety-nine, two thousand, two thousand one
          ' currency (for example, USD): two U.S. dollars and fifty cents
          ' money USD: two and 50/100 U.S. dollars

La première ligne de la boîte de message n'a pas de préfixe, ce qui signifie qu'il s'agit du format standard. Les lignes suivantes incluent le préfixe et quelques exemples de nombres utilisant son format.

Chaque langue a son propre ensemble de préfixes pris en charge. Le nombre de préfixes disponibles peut varier d'une langue à l'autre.

Pour obtenir la liste des préfixes pour une langue ou un paramètre régional spécifique, il peut être spécifié comme deuxième argument dans Number2Text. L'exemple ci-dessous montre les préfixes disponibles pour la locale "pt-BR":

          prefixes = oRegion.Number2Text("help", "pt-BR")
          MsgBox prefixes
          ' um, dois, três
          ' feminine: uma, duas, três
          ' masculine: um, dois, três
          ' ordinal-feminine: primeira, segunda, terceira
          ' ordinal-masculine: primeiro, segundo, terceiro
          ' ordinal-number-feminine: 1.ª, 2.ª, 3.ª
          ' ordinal-number-masculine: 1.º, 2.º, 3.º

## TimeZoneOffset

Renvoie le décalage entre GMT et le fuseau horaire et les paramètres régionaux donnés, en minutes.

### Syntaxe :

svc.TimeZoneOffset(timezone: str, opt locale: str): int

### Paramètres :

timezone : le fuseau horaire pour lequel le décalage par rapport à l'heure GMT sera calculé.

locale : la locale spécifiant le pays pour lequel le décalage sera calculé, donnée au format "la-CO" ou "CO". La valeur par défaut est la locale définie dans la propriété OfficeLocale du service Platform.

### Exemple :

##### En Basic :

          Dim offset As Integer
          offset = oRegion.TimeZoneOffset("America/New_York", "US") ' -300
          offset = oRegion.TimeZoneOffset("Europe/Berlin", "DE") ' 60

##### En Python

          offset = oRegion.TimeZoneOffset("America/New_York", "US") # -300
          offset = oRegion.TimeZoneOffset("Europe/Berlin", "DE") # 60

## UTCDateTime

Renvoie la date et l'heure UTC en tenant compte d'une date et d'une heure locales données dans un fuseau horaire.

### Syntaxe :

svc.UTCDateTime(localdatetime: date, timezone: str, opt locale: str): date

### Paramètres :

localdatetime : la date et l'heure locales dans un fuseau horaire spécifique exprimées sous forme de date.

timezone : le fuseau horaire pour lequel l'argument localdatetime a été donné.

locale : la locale spécifiant le pays pour lequel l'argument localdatetime a été donné, exprimé au format "la-CO" ou "CO". La valeur par défaut est la locale définie dans la propriété OfficeLocale du service Platform.

### Exemple :

##### En Basic :

          ' Date/Heure à Berlin, le 23 juin 2022 à 14:30:00
          Dim localDT As Date, utcTime As Date
          localDT = DateSerial(2022, 6, 23) + TimeSerial(14, 30, 0)
          ' La date/heure UTC est le 23 juin 2022 à 12:30:00
          utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")

##### En Python

          import datetime
          localDT = datetime.datetime(2022, 6, 23, 14, 30, 0)
          utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")

## UTCNow

Renvoie la date et l'heure UTC actuelles, en fonction d'un fuseau horaire et de paramètres régionaux.

Cette méthode utilise la date et l'heure actuelles de votre système d'exploitation pour calculer l'heure UTC.

### Syntaxe :

svc.UTCNow(timezone: str, opt locale: str): date

### Paramètres :

timezone : le fuseau horaire pour lequel l'heure UTC actuelle sera calculée.

locale : la locale spécifiant le pays pour lequel l'heure UTC actuelle sera calculée, donnée au format "la-CO" ou "CO". La valeur par défaut est la locale définie dans la propriété OfficeLocale du service Platform.

### Exemple :

##### En Basic :

          ' Supposons que l'heure du système d'exploitation soit le 23 juin 2022 à 10:42:00
          ' Si l'ordinateur est en Europe/Berlin, alors l'heure UTC est le 23 juin 2022 à 08:42:00
          Dim utcTime As Date
          utcTime = oRegion.UTCNow("Europe/Berlin", "DE")

##### En Python

          utcTime = oRegion.UTCNow("Europe/Berlin", "DE")

Rubriques connexes

Service ScriptForge.Platform