Spis treści

# 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 tablicę liczoną 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 tablicę ciągów znaków liczoną 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 tablicę ciągów znaków liczoną od zera zawierającą listę nazw dni tygodnia w określonym języku.
DayNarrowNames | Tak | Macierz ciągów znakowych | "la-CO" "la" | Zwraca tablicę ciągów znaków liczoną 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 tablicę ciągów znaków liczoną 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 tablicę ciągów znaków liczoną od zera zawierającą listę nazw miesięcy w określonym języku.
MonthNarrowNames | Tak | Macierz ciągów znakowych | "la-CO" "la" | Zwraca tablcię ciągów znaków liczoną 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: 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.

### Przykład:

##### W języku Basic

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

##### W języku Python

          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.

### Składnia:

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

### Parametry:

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.

### Przykład:

##### W języku Basic

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

##### W języku Python

          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.

### Składnia:

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

### Parametry:

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.

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

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

### Składnia:

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

### Parametry:

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.

### Przykład:

##### W języku Basic

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

##### W języku Python

          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.

### Składnia:

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

### Parametry:

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.

### Przykład:

##### W języku Basic

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

##### W języku Python

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

Tematy pokrewne

Usługa ScriptForge.Platform