Nápověda LibreOffice 24.8
Služba Region nabízí sadu vlastností a metod pro práci s národním prostředím a dalšími částmi programování souvisejícími s regionem, například:
Přístup k národnímu prostředí a nastavením závisejícím na regionu, jako jsou formátování čísel, měna a časová pásma.
Převod mezi časovými pásmy a výpočet posunů pro letní čas.
Převod čísel na text v podporovaných jazycích.
Řetězec s kombinací jazyka a země ve tvaru „la-CO“. Část s jazykem, vyjádřeným 2 nebo 3 malými písmeny, následuje pomlčka a 2 velká písmena představující zemi.
Například „en-US“ odpovídá angličtině ve Spojených státech, „fr-BE“ francouzštině v Belgii, „cs-CZ“ češtině v České republice atd.
V některých případech není úplné označení národního prostředí vyžadováno a stačí určit pouze jazyk či zemi.
Většina vlastností a metoda má národní prostředí jako argument. Není-li žádné uvedeno, použije se národní prostředí uživatelského rozhraní, které je definováno ve vlastnosti OfficeLocale služby Platform.
Řetězec ve formátu „Region/město“, například „Europe/Prague“, nebo identifikátor časového pásma, například „UTC“ nebo „GMT-8:00“. Seznam názvů a identifikátorů časových pásem naleznete na wiki stránce List of tz database and timezones.
Bude-li jakékoliv metodě služby Region zadáno neplatná neplatné časové pásmo, nenastane chyba při běhu programu. Místo toho se pomocí metod jako UTCDateTime a UTCNow vrátí aktuální datum a čas z operačního systému.
Posun času mezi časovým pásmem a greenwichským středním časem (Greenwich Meridian Time, GMT) je vyjádřen v minutách.
Dodatečný posun způsobuje letní čas (Daylight Saving Time, DST).
Posun časového pásma a posun pro letní čas mohou být kladné, nebo záporné.
Před používáním služby Region je nutné načíst či naimportovat knihovnu ScriptForge pomocí:
V níže uvedených příkladech v Basicu a Pythonu je vytvořena instance služby Region a je získán přístup k vlastnosti Country.
    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Dim oRegion As Variant
    oRegion = CreateScriptService("Region")
    MsgBox oRegion.Country("en-US") ' United States
  
    from scriptforge import CreateScriptService
    oRregion = CreateScriptService("Region")
    bas = CreateScriptService("Basic")
    bas.MsgBox(oRegion.Country("en-US"))
  Všechny následující vlastnosti přijímají argument locale, zadaný jako řetězec. Některý vyžadují, aby byl ve formátu „la-CO“, jiným je možné předat jako vstup formát „la“ nebo „CO“.
| Název | Pouze pro čtení | Typ | Národní prostředí | Popis | 
|---|---|---|---|---|
| Country | ano | String | "la‑CO" | Vrátí v angličtině název země odpovídající zadanému regionu. | 
| Currency | ano | String | "la-CO" | Vrátí pro zadaný region kód měny podle normy ISO 4217. | 
| DatePatterns | ano | pole řetězců (String) | "la-CO" | Vrátí pole řetězců začínající od 0, které obsahuje pro zadaný region masky pro rozpoznání data. | 
| DateSeparator | ano | String | "la-CO" | Vrátí oddělovač data používaný v zadaném regionu. | 
| DayAbbrevNames | ano | pole řetězců (String) | "la-CO" | Vrátí pole řetězců začínající od 0, které obsahuje seznam zkratek dnů v zadaném jazyce. | 
| DayNames | ano | pole řetězců (String) | "la-CO" | Vrátí pole řetězců začínající od 0, které obsahuje seznam názvů dnů v zadaném jazyce. | 
| DayNarrowNames | ano | pole řetězců (String) | "la-CO" | Vrátí pole řetězců začínající od 0, které obsahuje seznam počátečních písmen dnů v zadaném jazyce. | 
| DecimalPoint | ano | String | "la-CO" | Vrátí desetinný oddělovač používaný u čísel v zadaném regionu. | 
| Language | ano | String | "la-CO" | Vrátí v angličtině název jazyka pro zadaný region. | 
| ListSeparator | ano | String | "la-CO" | Vrátí oddělovač seznamu používaný v zadaném regionu. | 
| MonthAbbrevNames | ano | pole řetězců (String) | "la-CO" | Vrátí pole řetězců začínající od 0, které obsahuje seznam zkratek měsíců v zadaném jazyce. | 
| MonthNames | ano | pole řetězců (String) | "la-CO" | Vrátí pole řetězců začínající od 0, které obsahuje seznam názvů měsíců v zadaném jazyce. | 
| MonthNarrowNames | ano | pole řetězců (String) | "la-CO" | Vrátí pole řetězců začínající od 0, které obsahuje seznam počátečních písmen měsíců v zadaném jazyce. | 
| ThousandSeparator | ano | String | "la-CO" | Vrátí oddělovač tisíců používaný u čísel v zadaném regionu. | 
| TimeSeparator | ano | String | "la-CO" | Vrátí oddělovač seznamu používaný v zadaném regionu pro formátování časů. | 
| Seznam metod služby Region | ||
|---|---|---|
Vypočítá dodatečný posun pro letní čas (DST) v minutách, který odpovídá zadanému regionu a časovému pásmu.
svc.DSTOffset(localdatetime: date, timezone: str, opt locale: str): int
localdatetime: místní datum a čas vyjádřené jako datum.
timezone: časová zóna, pro niž se posun vypočítá.
locale: národní prostředí určující zemi, pro niž se má posun vypočítat, ve formátu „la-CO“ nebo „CO“. Výchozí hodnotou je národní prostředí definované ve vlastnosti OfficeLocale služby Platform.
      ' Vypočítá posun pro časové pásmo "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)
    Vypočítá místní datum a čas z data a času v UTC.
svc.LocalDateTime(utcdatetime: date, timezone: str, opt locale: str): date
utcdatetime: datum a čas v UTC vyjádřený pomocí objektu s datem.
timezone: časová zóna, pro niž se místní čas vypočítá.
locale: národní prostředí určující zemi, pro niž se má místní čas vypočítat, ve formátu „la-CO“ nebo „CO“. Výchozí hodnotou je národní prostředí definované ve vlastnosti OfficeLocale služby Platform.
      ' 6. června 2022 v 10:30:45 (použito jako čas UTC)
      Dim UTCTime As Date, localTime As Date
      UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)
      ' Vypočítá místní čas v brazilském městě Sao Paulo
      ' 6. června 2022 v 7: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")
    Převede pro aktuálně podporované jazyky čísla a hodnoty měny na psaný text.
Seznam všech podporovaných jazyků naleznete v části XNumberText Interface v referenční příručce API.
svc.Number2Text(number: any, opt locale: str): str
number: číslo, které se má převést na psaný text. Může být zadáno jako číselný typ nebo jako řetězec. Je-li zadán řetězec, lze u něj uvést předponu, která značí, jak mají být čísla zapsána. Je také možné použít kódy měn podle normy ISO 4217. Další informace naleznete v příkladech.
locale: národní prostředí určující jazyk, v němž bude převedené číslo zapsáno, ve formátu „la-CO“ nebo „CO“. Výchozí hodnotou je národní prostředí definované ve vlastnosti OfficeLocale služby Platform.
      ' Vrátí "sto pět"
      Dim numText As String
      numText = oRegion.Number2Text(105, "cs-CZ")
      ' Vrátí: "dvě čárka čtyřicet dva"
      numText = oRegion.Number2Text(2.42, "cs-CZ")
      ' Vrátí: "dvacet pět korun českých 10 haléřů" (použit symbol měny "CZK")
      numText = oRegion.Number2Text("CZK 25.10", "cs-CZ")
      ' Vrátí: "patnáctý" (použita předpona "ordinal" pro řadové číslovky)
      numText = oRegion.Number2Text("ordinal 15", "cs-CZ")
    
      numText = oRegion.Number2Text(105, "cs-CZ")
      numText = oRegion.Number2Text(2.42, "cs-CZ")
      numText = oRegion.Number2Text("EUR 25.10", "cs-CZ")
      numText = oRegion.Number2Text("ordinal 15", "cs-CZ")
    Seznam všech podporovaných předpon pro daný jazyk získáte zavoláním Number2Text se speciálním argumentem "help". Následující příklad předpokládá národní prostředí nastavené na "en-US", pro které se v okně MsgBox proto zobrazí seznam dostupných předpon:
      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
    První řádek v dialogu je bez předpony a značí standardní formát. Na následujících řádcích jsou uvedeny předpony a několik příkladů odpovídajících číslovek.
Každý jazyk má vlastní sadu podporovaných předpon, jejich počet se může v závislosti na jazyku lišit.
Seznam všech podporovaných předpon pro daný jazyk nebo národní prostředí získáte zavoláním Number2Text s druhým argumentem. Následující příklad zobrazí předpony dostupné pro prostředí "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.º
    Vrátí v minutách posun mezi GMT a zadaným časovým pásmem a národním prostředím.
svc.TimeZoneOffset(timezone: str, opt locale: str): int
timezone: časová zóna, pro niž se posun vzhledem k GMT vypočítá.
locale: národní prostředí určující zemi, pro niž se má posun vypočítat, ve formátu „la-CO“ nebo „CO“. Výchozí hodnotou je národní prostředí definované ve vlastnosti OfficeLocale služby 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
    Vrátí datum a čas v UTC pro zadané místní datum a čas v určitém časovém pásmu.
svc.UTCDateTime(localdatetime: date, timezone: str, opt locale: str): date
localdatetime: místní datum a čas v určitém časovém pásmu vyjádřené jako datum.
timezone: časové pásmo, pro nějž byl zadán argument localdatetime.
locale: národní prostředí určující zemi, pro niž byl zadán argument localdatetime, ve formátu „la-CO“ nebo „CO“. Výchozí hodnotou je národní prostředí definované ve vlastnosti OfficeLocale služby Platform.
      ' Datum a čas v Praze je 23. června 2022 14:30:00
      Dim localDT As Date, utcTime As Date
      localDT = DateSerial(2022, 6, 23) + TimeSerial(14, 30, 0)
      ' Datum a čas v UTC je 23. června 2022 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")
    Vrátí aktuální datum a čas UTC pro zadané časové pásmo a národní prostředí.
Pro výpočet času UTC používá tato metoda aktuální datum a čas operačního systému.
svc.UTCNow(timezone: str, opt locale: str): date
timezone: časová zóna, pro niž se aktuální čas UTC vypočítá.
locale: národní prostředí určující zemi, pro niž se má čas UTC vypočítat, ve formátu „la-CO“ nebo „CO“. Výchozí hodnotou je národní prostředí definované ve vlastnosti OfficeLocale služby Platform.
      ' Předpokládejme, že čas operačního systému je 23. června 2022 10:42:00
      ' Nachází-li se počítač v pásmu Europe/Prague, je čas UTC 23. června 2022 8:42:00
      Dim utcTime As Date
      utcTime = oRegion.UTCNow("Europe/Berlin", "DE")
    
      utcTime = oRegion.UTCNow("Europe/Prague", "CZ")