Usługa ScriptForge.Region

Usługa Region udostępnia zbiór właściwości i metod do obsługi lokalnych i regionalnych aspektów programowania, takich jak:

• Dostęp do ustawień regionalnych i zależnych od regionu, takich jak formatowanie liczb, waluta i strefy czasowe.

• Konwersja stref czasowych i obliczanie przesunięcia czasu letniego (DST).

• Przekształcanie liczb w tekst w dowolnym obsługiwanym języku.

Definicje

Ustawienie lokalne lub region

Ciąg łączący język i kraj w formacie "la-CO". Część językowa wyrażana jest za pomocą 2 lub 3 małych liter, po których następuje myślnik i 2 wielkie litery oznaczające kraj.

Na przykład "en-US" odpowiada językowi angielskiemu w Stanach Zjednoczonych; "fr-BE" odpowiada językowi francuskiemu w Belgii i tak dalej.

W niektórych sytuacjach pełne ustawienia regionalne nie są wymagane i można określić jedynie język lub kraj.

Większość właściwości i metod akceptuje ustawienia regionalne jako argument. Jeśli nie określono ustawień regionalnych, używane są ustawienia regionalne interfejsu użytkownika zdefiniowane we właściwości OfficeLocale usługi Platform.

Strefa czasowa

Ciąg w formacie "Region/Miasto", np. "Europa/Berlin", lub identyfikator strefy czasowej, np. "UTC" lub"GMT-8:00". Zobacz stronę wiki Lista stref czasowych bazy danych tz, aby uzyskać listę możliwych nazw i identyfikatorów stref czasowych.

Podanie nieprawidłowego ciągu strefy czasowej do którejkolwiek metody w usłudze Region nie spowoduje błędu w czasie wykonywania. Zamiast tego metody takie jak UTCDateTime i UTCNow zwrócą bieżącą datę i godzinę systemu operacyjnego.

Przesunięcie czasowe między strefą czasową a średnim czasem słonecznym Greenwich (GMT) wyrażane jest w minutach.

Czas letni (DST) to dodatkowe przesunięcie.

Przesunięcie strefy czasowej i czasu letniego może być dodatnie lub ujemne.

Wywoływanie usługi

Przed użyciem usługi Region należy załadować lub zaimportować bibliotekę ScriptForge:

• Podstawowe makra wymagają załadowania biblioteki ScriptForge przy użyciu następującej instrukcji:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Skrypty Pythona wymagają importu z modułu scriptforge:
from scriptforge import CreateScriptService

Poniższe przykłady w języku Basic i Python tworzą instancję usługi Region i uzyskują dostęp do właściwości Country.

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

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

Właściwości

Wszystkie właściwości wymienione poniżej akceptują argument locale podany w postaci ciągu znaków. Niektóre właściwości wymagają, aby ten argument był w formacie "la-CO", podczas gdy inne mogą przyjmować jako dane wejściowe "la" lub "CO".

DSTOffset

Oblicza dodatkowe przesunięcie czasu letniego (DST) w minutach, które ma zastosowanie do danego regionu i strefy czasowej.

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

localdatetime: lokalna data i godzina wyrażona jako data.

timezone: strefa czasowa, dla której zostanie obliczone przesunięcie.

locale: ustawienia regionalne określające kraj, dla którego zostanie obliczone przesunięcie, podane w formacie "la-CO" lub "CO". Wartość domyślna to ustawienia regionalne zdefiniowane we właściwości OfficeLocale usługi Platform.

      ' Oblicza przesunięcie obowiązujące w strefie czasowej "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 (minut)
      aDateTime = DateSerial(2022, 1, 1) + TimeSerial(16, 0, 0)
      offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minut)
    

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

LocalDateTime

Oblicza lokalną datę i godzinę na podstawie daty i godziny UTC.

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

utcdatetime: data i godzina UTC wyrażona za pomocą obiektu daty.

timezone: strefa czasowa, dla której będzie obliczany czas lokalny.

locale: ustawienia regionalne określające kraj, dla którego będzie obliczany czas lokalny, podane w formacie "la-CO" lub "CO". Wartość domyślna to ustawienia regionalne zdefiniowane we właściwości OfficeLocale usługi Platform.

      ' 6 czerwca 2022 r. o godzinie 10:30:45 (tutaj używany czas UTC)
      Dim UTCTime As Date, localTime As Date
      UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)
      ' Oblicza czas lokalny w Sao Paulo w Brazylii
      ' 6 czerwca 2022 o godzinie 07:30:45
      localTime = oRegion.LocalDateTime(UTCTime, "America/Sao_Paulo", "BR")
    

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

Number2Text

Konwertuje liczby i wartości pieniężne na tekst pisany dla dowolnego aktualnie obsługiwanego języka.

Listę wszystkich obsługiwanych języków znajdziesz w artykule Interfejs XNumberText w dokumentacji API.

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

number: liczba, która ma zostać przeliczona na tekst pisany. Można go podać jako typ liczbowy lub jako ciąg znaków. W przypadku podania ciągu znaków można go poprzedzić przedrostkiem informującym o sposobie zapisywania liczb. Możliwe jest również uwzględnienie kodów walut ISO 4217. Aby uzyskać więcej informacji, zobacz przykłady poniżej.

locale: ustawienia regionalne definiujące język, na który liczba zostanie przekonwertowana, podane w formacie "la-CO" lub "la". Wartość domyślna to ustawienia regionalne zdefiniowane we właściwości OfficeLocale usługi Platform.

      ' Zwraca „sto pięć”
      Dim numText As String
      numText = oRegion.Number2Text(105, "pl-PL")
      ' Zwraca: „dwa przecinek czterdzieści dwa”
      numText = oRegion.Number2Text(2.42, "pl-PL")
      ' Zwraca: „dwadzieścia pięć złotych i dziesięć groszy”. Zwróć uwagę na symbol waluty „PLN”.
      numText = oRegion.Number2Text("PLN 25.10", "pl-PL")
      ' Zwraca: „piętnasty” (przedrostek „porządkowy” używany w przypadku liczb porządkowych)
      numText = oRegion.Number2Text("ordinal 15", "pl-PL")
    

      numText = oRegion.Number2Text(105, "pl-PL")
      numText = oRegion.Number2Text(2.42, "pl-PL")
      numText = oRegion.Number2Text("PLN 25.10", "pl-PL")
      numText = oRegion.Number2Text("ordinal 15", "pl-PL")
    

Aby uzyskać listę wszystkich obsługiwanych przedrostków w danym języku, wywołaj Number2Text ze specjalnym argumentem "help". W poniższym przykładzie załóżmy, że ustawienia regionalne są ustawione na "en-US", a lista dostępnych przedrostków dla "en-US" zostanie wyświetlona w 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
    

Pierwszy wiersz w oknie komunikatu nie posiada prefiksu, co oznacza, że jest to format standardowy. Kolejne wiersze zawierają przedrostek i kilka przykładów liczb w jego formacie.

Każdy język ma swój własny zestaw obsługiwanych przedrostków. Liczba dostępnych przedrostków może się różnić w zależności od języka.

Aby uzyskać listę przedrostków dla określonego języka lub ustawień regionalnych, można je określić jako drugi argument w Number2Text. Poniższy przykład pokazuje dostępne przedrostki dla ustawień regionalnych "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

Zwraca przesunięcie w minutach między czasem GMT a podaną strefą czasową i ustawieniami regionalnymi.

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

timezone: strefa czasowa, dla której zostanie obliczone przesunięcie w stosunku do GMT.

locale: ustawienia regionalne określające kraj, dla którego zostanie obliczone przesunięcie, podane w formacie "la-CO" lub "CO". Wartość domyślna to ustawienia regionalne zdefiniowane we właściwości OfficeLocale usługi Platform.

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

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

UTCDateTime

Zwraca datę i godzinę UTC, biorąc pod uwagę daną lokalną datę i godzinę w strefie czasowej.

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

localdatetime: lokalna data i godzina w określonej strefie czasowej wyrażona jako data.

timezone: strefa czasowa, dla której podano argument localdatetime.

locale: ustawienia regionalne określające kraj, dla którego podano argument localdatetime, wyrażone w formacie "la-CO" lub "CO". Wartość domyślna to ustawienia regionalne zdefiniowane we właściwości OfficeLocale usługi Platform.

      ' Data i godzina w Berlinie, 23 czerwca 2022 r. o godzinie 14:30:00
      Dim localDT As Date, utcTime As Date
      localDT = DateSerial(2022, 6, 23) + TimeSerial(14, 30, 0)
      ' Data i godzina UTC to 23 czerwca 2022 r. o godzinie 12:30:00
      utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")
    

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

UTCNow

Zwraca bieżącą datę i godzinę UTC, biorąc pod uwagę strefę czasową i ustawienia regionalne.

Ta metoda wykorzystuje bieżącą datę i godzinę systemu operacyjnego do obliczenia czasu UTC.

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

timezone: strefa czasowa, dla której będzie obliczany bieżący czas UTC.

locale: ustawienia regionalne określające kraj, dla którego będzie obliczany bieżący czas UTC, podane w formacie "la-CO" lub "CO". Wartość domyślna to ustawienia regionalne zdefiniowane we właściwości OfficeLocale usługi Platform.

      ' Załóżmy, że czas systemu operacyjnego to 23 czerwca 2022 o godzinie 10:42:00
      ' Jeśli komputer znajduje się w Europie/Berlinie, czas UTC to 23 czerwca 2022 r. o godzinie 08:42:00
      Dim utcTime As Date
      utcTime = oRegion.UTCNow("Europe/Berlin", "DE")
    

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