Spis treści
Indeks 🔎︎

# 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.

##### W języku Basic

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

##### W języku Python

        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".

Nazwa | Tylko do odczytu | Typ | Ustawienia regionalne | Opis
--- | --- | --- | --- | ---
Country | Tak | String | "la‑CO" "CO" | Zwraca nazwę kraju w języku angielskim odpowiadającą danemu regionowi.
Currency | Tak | String | "la-CO" "CO" | Zwraca kod waluty ISO 4217 określonego regionu.
DatePatterns | Tak | Macierz ciągów znakowych | "la-CO" | Zwraca macierz ciągów od zera zawierającą wzorce akceptacji dat dla określonego regionu.
DateSeparator | Tak | String | "la-CO" | Zwraca separator daty używany w danym regionie.
DayAbbrevNames | Tak | Macierz ciągów znakowych | "la-CO" "la" | Zwraca macierz ciągów znaków od zera zawierającą listę skróconych nazw dni tygodnia w określonym języku.
DayNames | Tak | Macierz ciągów znakowych | "la-CO" "la" | Zwraca macierz ciągów znaków od zera zawierającą listę nazw dni tygodnia w określonym języku.
DayNarrowNames | Tak | Macierz ciągów znakowych | "la-CO" "la" | Zwraca macierz ciągów znaków od zera zawierającą listę inicjałów nazw dni tygodnia w określonym języku.
DecimalPoint | Tak | String | "la-CO" | Zwraca separator dziesiętny używany w liczbach w określonym regionie.
Language | Tak | String | "la-CO" "la" | Zwraca nazwę w języku angielskim dla określonego regionu.
ListSeparator | Tak | String | "la-CO" | Zwraca separator listy używany w określonym regionie.
MonthAbbrevNames | Tak | Macierz ciągów znakowych | "la-CO" "la" | Zwraca macierz ciągów znaków od zera zawierającą listę skróconych nazw miesięcy w określonym języku.
MonthNames | Tak | Macierz ciągów znakowych | "la-CO" "la" | Zwraca macierz ciągów znaków od zera zawierającą listę nazw miesięcy w określonym języku.
MonthNarrowNames | Tak | Macierz ciągów znakowych | "la-CO" "la" | Zwraca macierz ciągów znaków od zera zawierającą listę inicjałów nazw miesięcy w określonym języku.
ThousandSeparator | Tak | String | "la-CO" | Zwraca separator tysięcy używany w liczbach w określonym regionie.
TimeSeparator | Tak | String | "la-CO" | Zwraca separator używany do formatowania godzin w określonym regionie.

Lista metod w usłudze Region
DSTOffset LocalDateTime | Number2Text TimeZoneOffset | UTCDateTime UTCNow

## DSTOffset

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

### Składnia:

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

### Parametry:

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.

### Przykład:

##### W języku Basic

          ' 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)

##### W języku Python

          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.

### Składnia:

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

### Parametry:

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

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

locale: the locale specifying the country for which the local time will be calculated, given either in "la-CO" or "CO" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

### Przykład:

##### W języku Basic

          ' June 6th, 2022 at 10:30:45 (used here as UTC time)
          Dim UTCTime As Date, localTime As Date
          UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)
          ' Calculates local time in Sao Paulo, Brazil
          ' June 6th, 2022 at 07:30:45
          localTime = oRegion.LocalDateTime(UTCTime, "America/Sao_Paulo", "BR")

##### W języku Python

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

## Number2Text

Converts numbers and monetary values into written text for any of the currently supported languages.

For a list of all supported languages visit the XNumberText Interface API reference.

### Składnia:

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

### Parametry:

number: the number to be converted into written text. It can be provided either as a numeric type or as a string. When a string is provided, it can be preceded by a prefix informing how the numbers should be written. It is also possible to include ISO 4217 currency codes. See examples below for more information.

locale: the locale defining the language into which the number will be converted to, given either in "la-CO" or "la" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

### Przykład:

##### W języku Basic

          ' Returns "one hundred five"
          Dim numText As String
          numText = oRegion.Number2Text(105, "en-US")
          ' Returns: "two point four two"
          numText = oRegion.Number2Text(2.42, "en-US")
          ' Returns: "twenty-five euro and ten cents" Notice the "EUR" currency symbol
          numText = oRegion.Number2Text("EUR 25.10", "en-US")
          ' Returns: "fifteenth"; Notice the "ordinal" prefix
          numText = oRegion.Number2Text("ordinal 15", "en-US")

##### W języku 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")

To get a list of all supported prefixes in a given language, call Number2Text with the special "help" argument. In the example below, assume your locale is set to "en-US", then the list of available prefixes for "en-US" will be shown by 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

The first line in the message box does not have a prefix, which means that it is the standard format. The subsequent lines include the prefix and some examples of numbers using its format.

Each language has its own set of supported prefixes. The number of available prefixes may vary from language to language.

To get the list of prefixes for a specific language or locale, it can be specified as the second argument in Number2Text. The example below shows the available prefixes available for the "pt-BR" locale:

          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

Returns the offset between GMT and the given timezone and locale, in minutes.

### Składnia:

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

### Parametry:

timezone: the timezone for which the offset to the GMT will be calculated.

locale: the locale specifying the country for which the offset will be calculated, given either in "la-CO" or "CO" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

### Przykład:

##### W języku Basic

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

##### W języku Python

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

## UTCDateTime

Returns the UTC date and time considering a given local date and time in a timezone.

### Składnia:

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

### Parametry:

localdatetime: the local date and time in a specific timezone expressed as a date.

timezone: the timezone for which the localdatetime argument was given.

locale: the locale specifying the country for which the localdatetime argument was given, expressed either in "la-CO" or "CO" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

### Przykład:

##### W języku Basic

          ' Date/Time in Berlin, June 23, 2022 at 14:30:00
          Dim localDT As Date, utcTime As Date
          localDT = DateSerial(2022, 6, 23) + TimeSerial(14, 30, 0)
          ' The UTC date/time is June 23, 2022 at 12:30:00
          utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")

##### W języku Python

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

## UTCNow

Returns the current UTC date and time, given a timezone and locale.

This method uses the current date and time of your operating system to calculate the UTC time.

### Składnia:

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

### Parametry:

timezone: the timezone for which the current UTC time will be calculated.

locale: the locale specifying the country for which the current UTC time will be calculated, given either in "la-CO" or "CO" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

### Przykład:

##### W języku Basic

          ' Suppose the operating system time is June 23rd, 2022 at 10:42:00
          ' If the computer is in Europe/Berlin, then UTC time is June 23rd, 2022 at 08:42:00
          Dim utcTime As Date
          utcTime = oRegion.UTCNow("Europe/Berlin", "DE")

##### W języku Python

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

Tematy pokrewne

Usługa ScriptForge.Platform