Komponenten

Inoffizielle Beta-Übersetzung

Diese Seite wurde von PageTurner AI übersetzt (Beta). Nicht offiziell vom Projekt unterstützt. Fehler gefunden? Problem melden →

React Intl bietet eine Reihe von React-Komponenten, die einen deklarativen Ansatz zur Einrichtung eines i18n-Kontexts und zur Formatierung von Datumsangaben, Zahlen und Zeichenfolgen für die Anzeige in einer Web-UI bieten. Die Komponenten rendern React-Elemente auf Basis der imperativen API von React Intl.

Warum Komponenten?

Neben der Bereitstellung eines idiomatischen React-Ansatzes zur Integration von Internationalisierung in React-Apps bieten die <Formatted*>-Komponenten Vorteile gegenüber der direkten Verwendung der imperativen API:

Rendern von React-Elementen, die nahtlos mit anderen React-Komponenten kombiniert werden können.
Unterstützen von Rich-Text-Formatierungen für Zeichenfolgen/Nachrichten in <FormattedMessage>.
Implementieren erweiterter Funktionen wie die automatische Aktualisierung von <FormattedRelativeTime> über Zeit.
Bereitstellen von TypeScript-Typdefinitionen.

IntlProvider

React Intl verwendet das Provider-Pattern, um einen i18n-Kontext auf eine Komponenten-Hierarchie zu begrenzen. Dadurch können Konfigurationen wie das aktuelle Locale und übersetzte Zeichenfolgen/Nachrichten an der Wurzel der Komponenten-Hierarchie bereitgestellt und für die <Formatted*>-Komponenten verfügbar gemacht werden. Dies entspricht dem Konzept, das Flux-Frameworks wie Redux verwenden, um Zugriff auf einen Store innerhalb einer Komponenten-Hierarchie zu ermöglichen.

Vorsicht

Alle Apps, die React Intl verwenden, müssen die Komponente <IntlProvider> oder <RawIntlProvider> nutzen.

Diese Komponente dient zur Einrichtung des i18n-Kontexts für eine Hierarchie. Typischerweise umschließt sie die Stammkomponente einer App, sodass die gesamte App im konfigurierten i18n-Kontext operiert. Folgende i18n-Konfigurations-Props können gesetzt werden:

interface IntlConfig {
  locale: string
  formats: CustomFormats
  messages: Record<string, string> | Record<string, MessageFormatElement[]>
  defaultLocale: string
  defaultFormats: CustomFormats
  timeZone?: string
  textComponent?: React.ComponentType | keyof React.JSX.IntrinsicElements
  wrapRichTextChunksInFragment?: boolean
  defaultRichTextElements?: Record<string, FormatXMLElementFn<React.ReactNode>>
  onError(err: string): void
}

locale, formats und messages

Das aktuelle Locale des Benutzers und in welchem die App gerendert werden soll. defaultLocale und defaultFormats dienen als Fallback oder während der Entwicklung und repräsentieren die Standardeinstellungen der App. Beachten Sie, dass es kein defaultMessages gibt, da jeder Nachrichtendeskriptor ein defaultMessage bereitstellt.

defaultLocale und defaultFormats

Standard-Locale und -Formate für den Fall, dass eine Nachricht nicht übersetzt ist (fehlt in messages). defaultLocale sollte das Locale sein, in dem die defaultMessages deklariert sind, um Satzkohärenz in einem Locale zu gewährleisten. Ohne defaultLocale oder bei falscher Konfiguration kann es vorkommen, dass ein Satz auf Englisch ist, aber eingebettete Datums-/Zeitangaben auf Spanisch erscheinen.

textComponent

Ermöglicht die Konfiguration des Standard-Wrappers für die <Formatted*>-Komponenten von React Intl. Wenn nicht angegeben, wird <React.Fragment> verwendet. Vor Version 3 kam span zum Einsatz; weitere Details finden Sie im Migrationsleitfaden.

onError

Ermöglicht die Bereitstellung eines benutzerdefinierten Fehlerhandlers. Standardmäßig werden Fehlermeldungen via console.error protokolliert, sofern NODE_ENV nicht auf production gesetzt ist.

onWarn

Ermöglicht die Bereitstellung eines benutzerdefinierten Warnungs-Handlers. Standardmäßig werden Warnungen via console.warning protokolliert, sofern NODE_ENV nicht auf production gesetzt ist.

wrapRichTextChunksInFragment

Bei der Formatierung von Rich-Text-Nachrichten erzeugt die Ausgabe den Typ Array<string | React.ReactElement>, was einen Key-Fehler auslösen kann. Dies umschließt die Ausgabe in einem einzelnen React.Fragment, um dies zu unterdrücken.

defaultRichTextElements

Eine Zuordnung von Tags zu Rich-Text-Formatierungsfunktionen. Dient der zentralisierten Formatierung gängiger Tags wie <b>, <p> oder der Durchsetzung von Design-Systemen im Codebase (z.B. standardisierte <a> oder <button>). Siehe https://github.com/formatjs/formatjs/issues/1752 für weitere Details.

Diese Konfigurations-Props werden mit den komponentenspezifischen Props von <IntlProvider> kombiniert:

Props:

props: IntlConfig &
  {
    children: ReactNode,
  }

Kind-Elemente müssen an <IntlProvider> übergeben werden.

Beispiel:

const App = ({importantDate}) => (
  <div>
    <FormattedDate
      value={importantDate}
      year="numeric"
      month="long"
      day="numeric"
      weekday="long"
    />
  </div>
)

ReactDOM.render(
  <IntlProvider locale={navigator.language}>
    <App importantDate={new Date(1459913574887)} />
  </IntlProvider>,
  document.getElementById('container')
)

Annahme: navigator.language ist "fr":

<div>mardi 5 avril 2016</div>

RawIntlProvider

Dies ist das zugrundeliegende React.Context.Provider-Objekt, das IntlProvider verwendet. Es kann in Verbindung mit createIntl genutzt werden:

import {createIntl, createIntlCache, RawIntlProvider} from 'react-intl'

// This is optional but highly recommended
// since it prevents memory leak
const cache = createIntlCache()

const intl = createIntl({
  locale: 'fr-FR',
  messages: {}
}, cache)

// Pass it to IntlProvider
<RawIntlProvider value={intl}>{foo}</RawIntlProvider>

FormattedDate

Diese Komponente verwendet die APIs formatDate und Intl.DateTimeFormat und verfügt über props, die den oben spezifizierten DateTimeFormatOptions entsprechen.

Props:

props: Intl.DateTimeFormatOptions &
  {
    value: any,
    format: string,
    children: (formattedDate: string) => ReactElement,
  }

Standardmäßig rendert <FormattedDate> das formatierte Datum in ein <React.Fragment>. Bei Anpassungsbedarf können Sie es entweder mit einem anderen React-Element umschließen (empfohlen) oder eine Funktion als Kind übergeben.

Beispiel:

Live Editor

<FormattedDate value={new Date(1459832991883)} />

Result

Beispiel mit Optionen:

Live Editor

<FormattedDate
  value={new Date(1459832991883)}
  year="numeric"
  month="long"
  day="2-digit"
/>

Result

FormattedDateParts

Browser-Unterstützung

Dies erfordert Intl.DateTimeFormat.prototype.formatToParts, das in IE11 nicht verfügbar ist. Verwenden Sie unser Polyfill, wenn Sie IE11 unterstützen müssen.

Diese Komponente ermöglicht erweiterte Anpassungen von FormattedDate, indem sie Kind-Funktionen Zugriff auf die zugrundeliegenden Teile des formatierten Datums bietet. Die verfügbaren Teile sind hier aufgelistet.

Props:

props: Intl.DateTimeFormatOptions &
  {
    value: any,
    format: string,
    children: (parts: Intl.DateTimeFormatPart[]) => ReactElement,
  }

Live Editor

<FormattedDateParts
  value={new Date(1459832991883)}
  year="numeric"
  month="long"
  day="2-digit"
>
  {parts => (
    <>
      <b>{parts[0].value}</b>
      {parts[1].value}
      <small>{parts[2].value}</small>
    </>
  )}
</FormattedDateParts>

Result

FormattedTime

Diese Komponente nutzt die APIs formatTime und Intl.DateTimeFormat und hat props, die den oben spezifizierten DateTimeFormatOptions entsprechen. Standardwerte:

{
    hour: 'numeric',
    minute: 'numeric',
}

Props:

props: DateTimeFormatOptions &
  {
    value: any,
    format: string,
    children: (formattedDate: string) => ReactElement,
  }

Standardmäßig rendert <FormattedTime> die formatierte Zeit in ein React.Fragment. Zur Anpassung können Sie es entweder mit einem anderen React-Element umschließen (empfohlen) oder eine Funktion als Kind übergeben.

Beispiel:

Live Editor

<FormattedTime value={new Date(1459832991883)} />

Result

FormattedTimeParts

Browser-Unterstützung

Dies erfordert Intl.DateTimeFormat.prototype.formatToParts, das in IE11 nicht verfügbar ist. Verwenden Sie unser Polyfill, wenn Sie IE11 unterstützen müssen.

Diese Komponente ermöglicht erweiterte Anpassungen von FormattedTime, indem sie Kind-Funktionen Zugriff auf die zugrundeliegenden Teile der formatierten Zeit bietet. Die verfügbaren Teile sind hier aufgelistet.

Props:

props: Intl.DateTimeFormatOptions &
  {
    value: any,
    format: string,
    children: (parts: Intl.DateTimeFormatPart[]) => ReactElement,
  }

Live Editor

<FormattedTimeParts value={new Date(1459832991883)}>
  {parts => (
    <>
      <b>{parts[0].value}</b>
      {parts[1].value}
      <small>{parts[2].value}</small>
    </>
  )}
</FormattedTimeParts>

Result

FormattedDateTimeRange

Browser-Unterstützung

Dies erfordert die Stage-3-API Intl.RelativeTimeFormat.prototype.formatRange mit begrenzter Browserunterstützung. Verwenden Sie unser Polyfill für Kompatibilität.

Diese Komponente nutzt die APIs formatDateTimeRange und Intl.DateTimeFormat und hat props, die den oben spezifizierten DateTimeFormatOptions entsprechen.

Props:

props: DateTimeFormatOptions &
  {
    from: number | Date,
    to: number | Date,
    children: (formattedDate: string) => ReactElement,
  }

Standardmäßig rendert <FormattedDateTimeRange> den formatierten Zeitbereich in ein React.Fragment. Zur Anpassung können Sie es entweder mit einem anderen React-Element umschließen (empfohlen) oder eine Funktion als Kind übergeben.

Beispiel:

Live Editor

<FormattedDateTimeRange
  from={new Date('2020-1-1')}
  to={new Date('2020-1-15')}
/>

Result

FormattedRelativeTime

Browser-Unterstützung

Dies erfordert Intl.RelativeTimeFormat mit begrenzter Browserunterstützung. Verwenden Sie unser Polyfill für Kompatibilität.

Diese Komponente nutzt die formatRelativeTime-API und hat props, die folgenden Optionen für die relative Zeitformatierung entsprechen:

type RelativeTimeFormatOptions = {
  numeric?: 'always' | 'auto'
  style?: 'long' | 'short' | 'narrow'
}

Eigenschaftstypen:

props: RelativeTimeFormatOptions &
  {
    value: number,
    unit: Unit,
    format: string,
    updateIntervalInSeconds: number,
    children: (formattedDate: string) => ReactElement,
  }

Standardmäßig rendert <FormattedRelativeTime> die formatierte relative Zeit in ein React.Fragment. Zur Anpassung können Sie es entweder mit einem anderen React-Element umschließen (empfohlen) oder eine Funktion als Kind übergeben.

Beispiel:

Live Editor

<FormattedRelativeTime value={0} numeric="auto" updateIntervalInSeconds={1} />

Result

maximales Intervall

Sie können das maximale Intervall für das Neu-Rendern der Komponente durch Setzen von updateIntervalInSeconds anpassen. Ein falscher Wert deaktiviert die automatische Aktualisierung. Die Aktualisierung ist intelligent und plant das nächste Update für den nächsten interessanten Moment.

Ein interessanter Moment ist definiert als der nächste nicht gebrochene value für diese unit. Beispiel:

Live Editor

<FormattedRelativeTime value={-50} updateIntervalInSeconds={1} />

Result

Dies rendert zunächst 59 seconds ago, nach 1 Sekunde 1 minute ago und wird erst nach einer vollen Minute neu gerendert, dann als 2 minutes ago. Es wird nicht versuchen, 1.2 minutes ago zu rendern.

Einschränkung

updateIntervalInSeconds kann nicht für unit länger als hour aktiviert werden (also nicht für day, week, quarter, year). Hauptgrund: Es ist unsinnig, Timeouts in day-Einheiten zu planen, da die Anzahl der ms pro Tag größer ist als das Maximum, das setTimeout akzeptiert.

FormattedNumber

Diese Komponente nutzt die APIs formatNumber und Intl.NumberFormat mit props, die Intl.NumberFormatOptions entsprechen.

Props:

props: NumberFormatOptions &
  {
    value: number,
    format: string,
    children: (formattedNumber: string) => ReactElement,
  }

Standardmäßig rendert <FormattedNumber> die formatierte Zahl in ein React.Fragment. Für angepasstes Rendering: Umschließen mit einem anderen React-Element (empfohlen) oder Übergeben einer Funktion als Child-Element.

Beispiel:

Live Editor

<FormattedNumber value={1000} />

Result

Beispiel: Währungsformatierung

Live Editor

<FormattedNumber value={1000} style="currency" currency="USD" />

Result

Zahlenformatierung mit unit

Aktuell Teil von ES2020 NumberFormat. Wir bieten ein Polyfill hier und react-intl-Typen erlauben das Übergeben sanktionierter Einheiten. Beispiel:

Live Editor

<FormattedNumber
  value={1000}
  style="unit"
  unit="kilobyte"
  unitDisplay="narrow"
/>

Result

Live Editor

<FormattedNumber
  value={1000}
  unit="fahrenheit"
  unitDisplay="long"
  style="unit"
/>

Result

FormattedNumberParts

Browser-Unterstützung

Erfordert Intl.NumberFormat.prototype.formatToParts, nicht verfügbar in IE11. Verwenden Sie unser Polyfill für IE11-Support.

Diese Komponente ermöglicht tiefere Anpassung von FormattedNumber, indem Child-Funktionen Zugriff auf Unterkomponenten der formatierten Zahl erhalten. Verfügbare Teile sind hier gelistet.

Props:

props: NumberFormatOptions &
  {
    value: number,
    format: string,
    children: (parts: Intl.NumberFormatPart[]) => ReactElement,
  }

Beispiel:

Live Editor

<FormattedNumberParts value={1000}>
  {parts => (
    <>
      <b>{parts[0].value}</b>
      {parts[1].value}
      <small>{parts[2].value}</small>
    </>
  )}
</FormattedNumberParts>

Result

FormattedPlural

Diese Komponente nutzt die API formatPlural und Intl.PluralRules mit props, die Intl.PluralRulesOptions entsprechen.

Props:

props: PluralFormatOptions &
  {
    value: any,

    other: ReactElement,
    zero: ReactElement,
    one: ReactElement,
    two: ReactElement,
    few: ReactElement,
    many: ReactElement,

    children: (formattedPlural: ReactElement) => ReactElement,
  }

Standardmäßig wählt <FormattedPlural> eine Pluralkategorie (zero, one, two, few, many, other) und rendert das entsprechende React-Element in ein React.Fragment. Für angepasstes Rendering: Umschließen mit anderem React-Element (empfohlen) oder Übergeben einer Funktion als Child-Element.

Beispiel:

Live Editor

<FormattedPlural value={10} one="message" other="messages" />

Result

FormattedList

Browser-Unterstützung

Dies erfordert Intl.ListFormat, das nur eingeschränkte Browserunterstützung bietet. Verwenden Sie unser Polyfill, falls Sie diese Browser unterstützen möchten.

Diese Komponente nutzt die formatList-API und Intl.ListFormat. Ihre Props entsprechen Intl.ListFormatOptions.

Props:

props: ListFormatOptions &
  {
    children: (chunksOrString: string | React.ReactElement[]) => ReactElement,
  }

Beispiel:

Wenn das Locale en ist:

Live Editor

<FormattedList type="conjunction" value={['Me', 'myself', 'I']} />

Result

Live Editor

<FormattedList type="conjunction" value={['Me', <b>myself</b>, 'I']} />

Result

FormattedListParts

Browser-Unterstützung

Dies erfordert Intl.ListFormat, das nur eingeschränkte Browserunterstützung bietet. Verwenden Sie unser Polyfill, falls Sie diese Browser unterstützen möchten.

Diese Komponente nutzt die formatListToParts-API und Intl.ListFormat. Ihre Props entsprechen Intl.ListFormatOptions.

Props:

props: ListFormatOptions &
  {
    children: (chunks: Array<React.ReactElement | string>) => ReactElement,
  }

Beispiel:

Wenn das Locale en ist:

Live Editor

<FormattedListParts type="conjunction" value={['Me', 'myself', 'I']}>
  {parts => (
    <>
      <b>{parts[0].value}</b>
      {parts[1].value}
      <small>{parts[2].value}</small>
      {parts[3].value}
      <small>{parts[4].value}</small>
    </>
  )}
</FormattedListParts>

Result

FormattedDisplayName

Browser-Unterstützung

Dies erfordert Intl.DisplayNames, das nur eingeschränkte Browserunterstützung bietet. Verwenden Sie unser Polyfill, falls Sie diese Browser unterstützen möchten.

Diese Komponente nutzt formatDisplayName und Intl.DisplayNames. Ihre props entsprechen DisplayNameOptions. Eventuell benötigen Sie ein Polyfill.

Props:

props: FormatDisplayNameOptions &
  {
    value: string | number | Record<string, unknown>,
  }

Beispiel:

Wenn das Locale en ist:

Live Editor

<FormattedDisplayName type="language" value="zh-Hans-SG" />

Result

Live Editor

<FormattedDisplayName type="currency" value="JPY" />

Result

FormattedMessage

Diese Komponente nutzt die formatMessage-API und hat props, die einem Nachrichtendeskriptor entsprechen.

Props:

props: MessageDescriptor &
  {
    values: object,
    tagName: string,
    children: (chunks: ReactElement) => ReactElement,
  }

Nachrichtensyntax

Die String-/Nachrichtenformatierung ist eine Kernfunktion von React Intl und basiert auf ICU Message Formatting mittels ICU Message Syntax. Diese Syntax ermöglicht die Definition, Übersetzung und Laufzeitformatierung einfacher bis komplexer Nachrichten.

Einfache Nachricht:

Hello, {name}

Komplexe Nachricht:

Hello, {name}, you have {itemCount, plural,
    =0 {no items}
    one {# item}
    other {# items}
}.

Siehe: Nachrichtensyntax-Leitfaden.

Nachrichtendeskriptor

React Intl verwendet Nachrichtendeskriptoren zur Definition Ihrer Standardnachrichten. Die Props von <FormattedMessage> entsprechen einem Nachrichtendeskriptor. Diese Deskriptoren eignen sich ideal für Übersetzungen und enthalten folgende Eigenschaften:

id: Eindeutige, stabile Kennung der Nachricht
description: Kontextinformation für Übersetzer zur Verwendung in der UI
defaultMessage: Standardnachricht (üblicherweise auf Englisch)

type MessageDescriptor = {
  id?: string
  defaultMessage?: string
  description?: string
}

Nachrichtendeskriptoren kompilieren

Die Pakete babel-plugin-formatjs und @formatjs/ts-transformer kompilieren Nachrichtendeskriptoren aus JavaScript-Dateien in AST für bessere Performance.

Fallbacks bei der Nachrichtenformatierung

Die Nachrichtenformatierungs-APIs gehen einen Schritt weiter, um Fallbacks für häufige Fehlersituationen bereitzustellen; mindestens sollte immer ein nicht-leerer String zurückgegeben werden. Hier ist der Fallback-Algorithmus für die Nachrichtenformatierung:

Übersetzte Nachricht mit id suchen und formatieren, die an <IntlProvider> übergeben wurde.
Fallback: defaultMessage formatieren.
Fallback: Übersetzte Nachricht an der Quellposition von id.
Fallback: defaultMessage-Quelle verwenden.
Fallback: Literale Nachricht id ausgeben.

Verwendung

Standardmäßig rendert <FormattedMessage> den formatierten String in ein <React.Fragment>. Bei Bedarf können Sie es mit einem anderen React-Element umschließen (empfohlen), ein anderes tagName angeben (z.B. 'div') oder eine Funktion als Child übergeben.

Beispiel:

Live Editor

<FormattedMessage
  id="app.greeting"
  description="Greeting to welcome the user to the app"
  defaultMessage="Hello, {name}!"
  values={{
    name: 'Eric',
  }}
/>

Result

Beispiel: Funktion als Child

Live Editor

<FormattedMessage id="title">{txt => <h1>{txt}</h1>}</FormattedMessage>

Result

einfache Nachricht

Nachrichten können einfache Strings ohne Platzhalter sein - der häufigste Nachrichtentyp. Dieser Fall ist hochoptimiert, bietet aber trotzdem die Vorteile des Fallback-Verfahrens.

Rich-Text-Formatierung

<FormattedMessage> unterstützt auch Rich-Text-Formatierung durch XML-Tags in der Nachricht und deren Auflösung in der values-Prop. Beispiel:

Live Editor

<FormattedMessage
  id="app.greeting"
  description="Greeting to welcome the user to the app"
  defaultMessage="Hello, <b>Eric</b> {icon}"
  values={{
    b: chunks => <b>{chunks}</b>,
    icon: <svg />,
  }}
/>

Result

Durch das Einbetten von XML-Tags bleibt der Kontext erhalten, wenn Teile des Strings formatiert werden sollen. Komplexeres Beispiel:

Live Editor

<FormattedMessage
  id="foo"
  defaultMessage="To buy a shoe, <a>visit our website</a> and <cta>buy a shoe</cta>"
  values={{
    a: chunks => (
      <a
        class="external_link"
        target="_blank"
        href="https://www.example.com/shoe"
      >
        {chunks}
      </a>
    ),
    cta: chunks => <strong class="important">{chunks}</strong>,
  }}
/>

Result

Funktion als Child

Da Rich-Text-Formatierung ReactElement einbetten kann, erhält die Funktion im Child-Szenario die formatierten Nachrichtenchunks als Parameter.

Live Editor

<FormattedMessage
  id="foo"
  defaultMessage="To buy a shoe, <a>visit our website</a> and <cta>buy a shoe</cta>"
  values={{
    a: chunks => (
      <a
        class="external_link"
        target="_blank"
        href="https://www.example.com/shoe"
      >
        {chunks}
      </a>
    ),
    cta: chunks => <strong class="important">{chunks}</strong>,
  }}
>
  {chunks => <h2>{chunks}</h2>}
</FormattedMessage>

Result

Der gesamte Rich-Text wird gemeinsam übersetzt, was höhere Qualität liefert. Dies schafft Feature-Parität mit anderen Übersetzungsbibliotheken wie Fluent von Mozilla (mittels overlays-Konzept).

Die Erweiterbarkeit ermöglicht auch die Nutzung anderer Rich-Text-Formate wie Markdown.

Warum Komponenten?​

IntlProvider​

locale, formats und messages​

defaultLocale und defaultFormats​

textComponent​

onError​

onWarn​

wrapRichTextChunksInFragment​

defaultRichTextElements​

RawIntlProvider​

FormattedDate​

FormattedDateParts​

FormattedTime​

FormattedTimeParts​

FormattedDateTimeRange​

FormattedRelativeTime​

FormattedNumber​

FormattedNumberParts​

FormattedPlural​

FormattedList​

FormattedListParts​

FormattedDisplayName​

FormattedMessage​

Nachrichtensyntax​

Nachrichtendeskriptor​

Fallbacks bei der Nachrichtenformatierung​

Verwendung​

Rich-Text-Formatierung​

Funktion als Child​

Warum Komponenten?

IntlProvider

locale, formats und messages

defaultLocale und defaultFormats

textComponent

onError

onWarn

wrapRichTextChunksInFragment

defaultRichTextElements

RawIntlProvider

FormattedDate

FormattedDateParts

FormattedTime

FormattedTimeParts

FormattedDateTimeRange

FormattedRelativeTime

FormattedNumber

FormattedNumberParts

FormattedPlural

FormattedList

FormattedListParts

FormattedDisplayName

FormattedMessage

Nachrichtensyntax

Nachrichtendeskriptor

Fallbacks bei der Nachrichtenformatierung

Verwendung

Rich-Text-Formatierung

Funktion als Child