Componentes

Tradução Beta Não Oficial

Esta página foi traduzida por PageTurner AI (beta). Não é oficialmente endossada pelo projeto. Encontrou um erro? Reportar problema →

O React Intl oferece um conjunto de componentes React que proporcionam uma abordagem declarativa para configurar um contexto i18n e formatar datas, números e strings para exibição em interfaces web. Esses componentes renderizam elementos React baseando-se na API imperativa do React Intl.

Por que Componentes?

Além de fornecer uma integração idiomática de internacionalização em apps React, os componentes <Formatted*> oferecem vantagens sobre o uso direto da API imperativa:

Renderizam elementos React que se integram perfeitamente com outros componentes
Suportam formatação de strings/mensagens em rich-text no <FormattedMessage>
Implementam recursos avançados como atualização dinâmica no <FormattedRelativeTime>
Disponibilizam definições de tipos para TypeScript

IntlProvider

O React Intl utiliza o padrão provider para delimitar um contexto i18n a uma árvore de componentes. Isso permite que configurações como locale atual e mensagens traduzidas sejam fornecidas na raiz da árvore e disponibilizadas aos componentes <Formatted*>. É o mesmo conceito usado por frameworks Flux como Redux para prover acesso a stores.

cuidado

Todos os apps usando React Intl devem utilizar <IntlProvider> ou <RawIntlProvider>.

Este componente configura o contexto i18n para uma árvore. Geralmente envolve o componente raiz do app, garantindo que toda aplicação esteja no contexto i18n configurado. As seguintes props de configuração podem ser definidas:

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 e messages

O locale atual do usuário e no qual o aplicativo deve ser renderizado. Enquanto defaultLocale e defaultFormats servem para fallbacks ou durante o desenvolvimento, representando os padrões do aplicativo. Note que não há defaultMessages, pois cada Message Descriptor fornece seu próprio defaultMessage.

defaultLocale e defaultFormats

Locale e formatos padrão para quando uma mensagem não está traduzida (ausente em messages). defaultLocale deve ser o locale onde defaultMessages são declarados, garantindo coerência na sentença. Sem defaultLocale ou configurado incorretamente, pode ocorrer uma sentença em inglês com data/hora em espanhol.

textComponent

Configura o wrapper padrão para componentes <Formatted*> do React Intl. Se não especificado, usa <React.Fragment>. Antes da v3, usava-se span; consulte o guia de migração para detalhes.

onError

Permite fornecer um tratador de erros personalizado. Por padrão, erros são registrados via console.error se NODE_ENV não estiver definido como production.

onWarn

Permite fornecer um tratador personalizado de avisos. Por padrão, avisos são registrados via console.warning quando NODE_ENV não é production.

wrapRichTextChunksInFragment

Ao formatar mensagens rich text, a saída Array<string | React.ReactElement> causa erros de chave. Esta prop envolve a saída em um único React.Fragment para suprimir isso.

defaultRichTextElements

Um mapeamento de tags para funções de formatação de rich text. Fornece uma forma centralizada de formatar tags comuns como <b>, <p>... ou aplicar sistemas de design (ex: <a> ou <button> padronizados). Veja https://github.com/formatjs/formatjs/issues/1752 para contexto.

Essas props combinam-se com as específicas do componente <IntlProvider>:

Propriedades:

props: IntlConfig &
  {
    children: ReactNode,
  }

Elementos filhos devem ser fornecidos ao <IntlProvider>.

Exemplo:

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

Supondo navigator.language como "fr":

<div>mardi 5 avril 2016</div>

RawIntlProvider

Este é o objeto subjacente React.Context.Provider utilizado pelo IntlProvider. Pode ser usado com createIntl:

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

Este componente utiliza as APIs formatDate e Intl.DateTimeFormat e possui props que correspondem às DateTimeFormatOptions especificadas acima.

Propriedades:

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

Por padrão, <FormattedDate> renderiza a data formatada em <React.Fragment>. Para customizar, envolva com outro elemento React (recomendado) ou passe uma função como filho.

Exemplo:

Live Editor

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

Result

Exemplo com Opções:

Live Editor

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

Result

FormattedDateParts

suporte do navegador

Este recurso requer Intl.DateTimeFormat.prototype.formatToParts, que não está disponível no IE11. Use nosso polyfill se precisar dar suporte ao IE11.

Este componente oferece mais personalização ao FormattedDate ao permitir que a função children tenha acesso às partes subjacentes da data formatada. As partes disponíveis estão listadas aqui.

Propriedades:

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

Este componente usa as APIs formatTime e Intl.DateTimeFormat, com props correspondentes às DateTimeFormatOptions mencionadas anteriormente e os seguintes padrões:

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

Propriedades:

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

Por padrão, o <FormattedTime> renderiza o tempo formatado em um React.Fragment. Para personalizar a renderização, envolva-o com outro elemento React (recomendado) ou passe uma função como children.

Exemplo:

Live Editor

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

Result

FormattedTimeParts

suporte do navegador

Este recurso requer Intl.DateTimeFormat.prototype.formatToParts, que não está disponível no IE11. Use nosso polyfill se precisar dar suporte ao IE11.

Este componente oferece mais personalização ao FormattedTime ao permitir que a função children tenha acesso às partes subjacentes da hora formatada. As partes disponíveis estão listadas aqui.

Propriedades:

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

suporte do navegador

Este recurso requer a API em estágio 3 Intl.RelativeTimeFormat.prototype.formatRange, com suporte limitado nos navegadores. Use nosso polyfill se precisar dar suporte a eles.

Este componente usa as APIs formatDateTimeRange e Intl.DateTimeFormat, com props correspondentes às DateTimeFormatOptions mencionadas anteriormente.

Propriedades:

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

Por padrão, o <FormattedDateTimeRange> renderiza o intervalo de data/hora formatado em um React.Fragment. Para personalizar a renderização, envolva-o com outro elemento React (recomendado) ou passe uma função como children.

Exemplo:

Live Editor

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

Result

FormattedRelativeTime

suporte do navegador

Este recurso requer Intl.RelativeTimeFormat, com suporte limitado nos navegadores. Use nosso polyfill se precisar dar suporte a eles.

Este componente usa a API formatRelativeTime, com props correspondentes às seguintes opções de formatação relativa:

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

Tipos de Props:

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

Por padrão, o <FormattedRelativeTime> renderiza o tempo relativo formatado em um React.Fragment. Para personalizar a renderização, envolva-o com outro elemento React (recomendado) ou passe uma função como children.

Exemplo:

Live Editor

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

Result

intervalo máximo

Você pode ajustar o intervalo máximo em que o componente será re-renderizado definindo updateIntervalInSeconds. Um valor falsy desativará a atualização automática. A atualização é inteligente e agendará a próxima atualização para o próximo momento interessante.

Um momento interessante é definido como o próximo value não fracionário para aquela unit. Por exemplo:

Live Editor

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

Result

Isso inicialmente renderizará 59 seconds ago, após 1 segundo, renderizará 1 minute ago, e não será re-renderizado até que um minuto completo passe, então renderizará 2 minutes ago. Não tentará renderizar 1.2 minutes ago.

limitação

updateIntervalInSeconds não pode ser habilitado para unit maior que hour (portanto não para day, week, quarter, year). Isso ocorre principalmente porque não faz sentido agendar um timeout em days, e o número de ms em um dia é maior que o timeout máximo aceito por setTimeout.

FormattedNumber

Este componente usa as APIs formatNumber e Intl.NumberFormat e possui props que correspondem a Intl.NumberFormatOptions.

Propriedades:

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

Por padrão, <FormattedNumber> renderizará o número formatado em um React.Fragment. Se você precisar personalizar a renderização, pode envolvê-lo com outro elemento React (recomendado) ou passar uma função como filho.

Exemplo:

Live Editor

<FormattedNumber value={1000} />

Result

Exemplo Formatando Valores Monetários

Live Editor

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

Result

Formatação numérica usando unit

Atualmente, isso faz parte do ES2020 NumberFormat. Fornecemos um polyfill aqui e os tipos react-intl permitem que os usuários passem uma unidade sancionada. Por exemplo:

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

suporte do navegador

Isso requer Intl.NumberFormat.prototype.formatToParts que não está disponível no IE11. Use nosso polyfill se planejar suportar IE11.

Este componente oferece mais personalização ao FormattedNumber permitindo que a função filho tenha acesso às partes subjacentes do número formatado. As partes disponíveis estão listadas aqui.

Propriedades:

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

Exemplo:

Live Editor

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

Result

FormattedPlural

Este componente usa a API formatPlural e Intl.PluralRules possui props que correspondem a Intl.PluralRulesOptions.

Propriedades:

props: PluralFormatOptions &
  {
    value: any,

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

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

Por padrão, <FormattedPlural> selecionará uma categoria plural (zero, one, two, few, many, ou other) e renderizará o elemento React correspondente em um React.Fragment. Se você precisar personalizar a renderização, pode envolvê-lo com outro elemento React (recomendado) ou passar uma função como filho.

Exemplo:

Live Editor

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

Result

FormattedList

suporte do navegador

Requer Intl.ListFormat com suporte limitado em navegadores. Use nosso polyfill se precisar de compatibilidade.

Este componente utiliza a API formatList e Intl.ListFormat. Suas propriedades correspondem às Intl.ListFormatOptions.

Propriedades:

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

Exemplo:

Quando o locale é en:

Live Editor

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

Result

Live Editor

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

Result

FormattedListParts

suporte do navegador

Requer Intl.ListFormat com suporte limitado em navegadores. Use nosso polyfill se precisar de compatibilidade.

Este componente utiliza a API formatListToParts e Intl.ListFormat. Suas propriedades correspondem às Intl.ListFormatOptions.

Propriedades:

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

Exemplo:

Quando o locale é en:

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

suporte do navegador

Requer Intl.DisplayNames com suporte limitado em navegadores. Use nosso polyfill se precisar de compatibilidade.

Este componente utiliza formatDisplayName e Intl.DisplayNames, tem props que correspondem a DisplayNameOptions. Talvez seja necessário um polyfill.

Propriedades:

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

Exemplo:

Quando o locale é en:

Live Editor

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

Result

Live Editor

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

Result

FormattedMessage

Este componente utiliza a API formatMessage e possui props que correspondem a um Message Descriptor.

Propriedades:

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

Sintaxe da Mensagem

A formatação de strings/mensagens é essencial no React Intl, baseando-se em ICU Message Formatting através da Sintaxe ICU. Essa sintaxe permite definir mensagens simples ou complexas, traduzi-las e formatá-las em tempo de execução.

Mensagem Simples:

Hello, {name}

Mensagem Complexa:

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

Veja: Guia de Sintaxe de Mensagem.

Descritor de Mensagem

O React Intl utiliza o conceito de Message Descriptor para definir mensagens padrão do aplicativo. O <FormattedMessage> possui propriedades que correspondem a um Message Descriptor, contendo:

id: Identificador único e estável para a mensagem
description: Contexto para tradutores sobre o uso na interface
defaultMessage: Mensagem padrão (geralmente em inglês)

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

compilação de descritores

Os pacotes babel-plugin-formatjs e @formatjs/ts-transformer podem compilar Message Descriptors em AST para melhor desempenho.

Fallbacks de Formatação de Mensagem

As APIs de formatação implementam fallbacks robustos para garantir retorno de strings não vazias. O algoritmo é:

Buscar e formatar a mensagem traduzida no id fornecido ao <IntlProvider>.
Fallback para formatação do defaultMessage.
Fallback para a mensagem traduzida na fonte do id.
Fallback para a fonte da defaultMessage.
Fallback para o id literal da mensagem.

Uso

Por padrão, o <FormattedMessage> renderizará a string formatada em um <React.Fragment>. Para personalizar a renderização, você pode envolvê-lo com outro elemento React (recomendado), especificar um tagName diferente (por exemplo, 'div') ou passar uma função como elemento filho.

Exemplo:

Live Editor

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

Result

Exemplo: função como filho

Live Editor

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

Result

simple message

Mensagens podem ser strings simples sem placeholders, sendo o tipo mais comum. Este caso é altamente otimizado, mas mantém os benefícios do procedimento de fallback.

Formatação de Rich Text

O <FormattedMessage> também suporta formatação de rich text especificando uma tag XML na mensagem e resolvendo essa tag na prop values. Veja um exemplo:

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

Ao permitir incorporar tags XML, garantimos que informações contextuais não sejam perdidas ao estilizar parte do texto. Num exemplo mais complexo como:

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

Função como filho

Como a formatação de rich text permite incorporar ReactElement, no cenário de função como filho, a função receberá os chunks da mensagem formatada como parâmetro único.

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

Todo o rich text é traduzido em conjunto, produzindo saída de maior qualidade. Isso traz paridade de recursos com outras bibliotecas como fluent da Mozilla (usando conceito de overlays).

Esta extensão também permite potencialmente utilizar outros formatos de rich text, como Markdown.

Por que Componentes?​

IntlProvider​

locale, formats e messages​

defaultLocale e defaultFormats​

textComponent​

onError​

onWarn​

wrapRichTextChunksInFragment​

defaultRichTextElements​

RawIntlProvider​

FormattedDate​

FormattedDateParts​

FormattedTime​

FormattedTimeParts​

FormattedDateTimeRange​

FormattedRelativeTime​

FormattedNumber​

FormattedNumberParts​

FormattedPlural​

FormattedList​

FormattedListParts​

FormattedDisplayName​

FormattedMessage​

Sintaxe da Mensagem​

Descritor de Mensagem​

Fallbacks de Formatação de Mensagem​

Uso​

Formatação de Rich Text​

Função como filho​

Por que Componentes?

IntlProvider

locale, formats e messages

defaultLocale e defaultFormats

textComponent

onError

onWarn

wrapRichTextChunksInFragment

defaultRichTextElements

RawIntlProvider

FormattedDate

FormattedDateParts

FormattedTime

FormattedTimeParts

FormattedDateTimeRange

FormattedRelativeTime

FormattedNumber

FormattedNumberParts

FormattedPlural

FormattedList

FormattedListParts

FormattedDisplayName

FormattedMessage

Sintaxe da Mensagem

Descritor de Mensagem

Fallbacks de Formatação de Mensagem

Uso

Formatação de Rich Text

Função como filho