Version: 2.0.0-beta.3

Client API do Docusaurus

O Docusaurus oferece algumas APIs nos clientes que podem ser úteis na construção do seu site.

Componentes#

`<Head/>`#

Este componente React reutilizável irá gerenciar todas as suas alterações na cabeça do documento. Ele leva tags HTML simples e produz tags HTML simples e é amigável para iniciantes. É um wrapper em torno de React Helmet.

Exemplo de uso:

import React from 'react';import Head from '@docusaurus/Head';
const MySEO = () => (  <Head>    <meta property="og:description" content="My custom description" />    <meta charSet="utf-8" />    <title>My Title</title>    <link rel="canonical" href="http://mysite.com/example" />  </Head>);

Os componentes aninhados ou posteriores substituirão os usos duplicados:

<Parent>  <Head>    <title>My Title</title>    <meta name="description" content="Helmet application" />  </Head>  <Child>    <Head>      <title>Nested Title</title>      <meta name="description" content="Nested component" />    </Head>  </Child></Parent>

Resultados:

<head>  <title>Nested Title</title>  <meta name="description" content="Nested component" /></head>

`<Link/>`#

Este componente permite vincular a páginas internas, bem como um poderoso recurso de desempenho chamado pré-carregamento. O pré-carregamento é usado para pré-carregar os recursos para que eles sejam buscados quando o usuário navegar com este componente. Usamos um IntersectionObserver para obter uma solicitação de baixa prioridade quando <Link> estiver na janela de visualização e usar um evento onMouseOver para disparar uma solicitação de alta prioridade quando é provável que um usuário navegue até o recurso solicitado.

O componente é um componente wrapper em torno do componente <Link> do react-router que adiciona melhorias úteis específicas ao Docusaurus. Todas as propriedades são passadas para o componente <Link> de react-router.

import React from 'react';import Link from '@docusaurus/Link';
const Page = () => (  <div>    <p>      Check out my <Link to="/blog">blog</Link>!    </p>    <p>      {/* Note that external links still use `a` tags, but automatically opens in new tab. */}      Follow me on <a href="https://twitter.com/docusaurus">Twitter</a>!    </p>  </div>);

`to`: string#

O local de destino navegar. Exemplo: /docs/introduction.

<Link to="/courses" />

`<Redirect/>`#

Renderizar um <Redirect> navegará para um novo local. O novo local irá substituir a localização atual na pilha de histórico, como redirecionamentos no lado do servidor (HTTP 3xx). Você pode consultar Documentação de Redirecionamento do React Router para mais informações sobre as propriedades disponíveis.

Exemplo de Uso:

import React from 'react';import {Redirect} from '@docusaurus/router';
const Home = () => {  return <Redirect to="/docs/test" />;};

note

@docusaurus/router implementa React Router e suporta suas funcionalidades.

`<BrowserOnly/>`#

O componente <BrowserOnly> aceita uma propriedade children, uma função de renderização que não será executada durante a fase de pré-renderização do processo de compilação. Isso é útil para ocultar o código que deve ser executado apenas nos navegadores (por exemplo, onde os objetos window/document estão sendo acessados). Para melhorar o SEO, você também pode fornecer conteúdo substituto usando o prop fallback, que será pré-renderizado até o processo de construção e substituído pelo conteúdo apenas do lado do cliente quando visualizado no navegador.

import BrowserOnly from '@docusaurus/BrowserOnly';
const MyComponent = () => {  return (    <BrowserOnly      fallback={<div>The fallback content to display on prerendering</div>}>      {() => {        // Something that should be excluded during build process prerendering.      }}    </BrowserOnly>  );};

`<Interpolate/>`#

Um componente simples de interpolação para o texto contendo espaços reservados dinâmicos.

Os espaços reservados serão substituídos pelos valores dinâmicos fornecidos e pelos elementos JSX de sua escolha (strings, links, styled elements...).

Props#

children: texto contendo espaços reservados interpolação como {placeholderName}
values: objeto contendo valores de espaço reservado interpolado

import React from 'react';import Link from '@docusaurus/Link';import Interpolate from '@docusaurus/Interpolate';
export default function VisitMyWebsiteMessage() {  return (    <Interpolate      values={{        firstName: 'Sébastien',        website: (          <Link to="https://docusaurus.io" className="my-website-class">            website          </Link>        ),      }}>      {'Hello, {firstName}! How are you? Take a look at my {website}'}    </Interpolate>  );}

`<Translate/>`#

Quando localizar seu site, o componente <Translate/> permitirá fornecer suporte de tradução para componentes React, como a sua página inicial. O componente <Translate> suporta interpolação.

As strings de tradução serão extraídas de seu código com a CLI docusaurus write-translations e criadas um arquivo de tradução code.json em website/i18n/<locale>.

note

As propriedades <Translate/> devem ser strings codificadas.

Além da propriedade values usada para interpolação, não é possível usar variáveis, ou a extração estática não funcionaria.

Props#

children: string não traduzida na localidade padrão do site (pode conter espaços reservados de interpolação)
id: valor opcional para usar como chave em arquivos de tradução JSON
description: texto opcional para ajudar o tradutor
values: objeto opcional contendo valores de espaço reservado de interpolação

Exemplo#

src/pages/index.js

import React from 'react';import Layout from '@theme/Layout';
import Translate from '@docusaurus/Translate';
export default function Home() {  return (    <Layout>      <h1>        <Translate          id="homepage.title"          description="The homepage welcome message">          Welcome to my website        </Translate>      </h1>      <main>        <Translate values={{firstName: 'Sébastien'}}>          {'Welcome, {firstName}! How are you?'}        </Translate>      </main>    </Layout>  );}

Ganchos#

`useDocusaurusContext`#

React hook para acessar o Contexto do Docusaurus. Contexto contém objeto siteConfig do docusaurus.config.jse alguns metadados adicionais do site.

type DocusaurusPluginVersionInformation =  | {readonly type: 'package'; readonly version?: string}  | {readonly type: 'project'}  | {readonly type: 'local'}  | {readonly type: 'synthetic'};
interface DocusaurusSiteMetadata {  readonly docusaurusVersion: string;  readonly siteVersion?: string;  readonly pluginVersions: Record<string, DocusaurusPluginVersionInformation>;}
interface DocusaurusContext {  siteConfig: DocusaurusConfig;  siteMetadata: DocusaurusSiteMetadata;}

Exemplo de uso:

import React from 'react';import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
const MyComponent = () => {  const {siteConfig, siteMetadata} = useDocusaurusContext();  return (    <div>      <h1>{siteConfig.title}</h1>      <div>{siteMetadata.siteVersion}</div>      <div>{siteMetadata.docusaurusVersion}</div>    </div>  );};

`useBaseUrl`#

React hook para preceder seu site baseUrl para uma string.

caution

Não use para links regulares!

O prefixo /baseUrl/ é adicionado automaticamente a todos os caminhos absolutos por padrão:

Markdown: [link](/my/path) vinculará ao /baseUrl/my/path
React: <Link to="/my/path/">link</Link> irá vincular para /baseUrl/my/path

Opções#

type BaseUrlOptions = {  forcePrependBaseUrl: boolean;  absolute: boolean;};

Exemplo de Uso:#

import React from 'react';import useBaseUrl from '@docusaurus/useBaseUrl';
const SomeImage = () => {  const imgSrc = useBaseUrl('/img/myImage.png');  return <img src={imgSrc} />;};

tip

Na maioria dos casos, você não precisa de useBaseUrl.

Prefira uma chamada require() para assets:

<img src={require('@site/static/img/myImage.png').default} />

`useBaseUrlUtils`#

Às vezes useBaseUrl não é bom o suficiente. Este hook retorna utilitários adicionais relacionados ao url base do seu site.

withBaseUrl: útil se você precisa adicionar Urls de base a várias urls de uma só vez.

import React from 'react';import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
const Component = () => {  const urls = ['/a', '/b'];  const {withBaseUrl} = useBaseUrlUtils();  const urlsWithBaseUrl = urls.map(withBaseUrl);  return <div>{/* ... */}</div>;};

`useGlobalData`#

React hook para acessar os dados globais do Docusaurus criados por todos os plugins.

Os dados globais são colocados em namespaces pelo nome do plug-in e pelo id do plug-in.

info

Id do plugin só é útil quando um plugin é usado várias vezes no mesmo site. Cada instância do plugin é capaz de criar seus próprios dados globais.

type GlobalData = Record<  PluginName,  Record<    PluginId, // "default" by default    any // plugin-specific data  >>;

Exemplo de uso:

import React from 'react';import useGlobalData from '@docusaurus/useGlobalData';
const MyComponent = () => {  const globalData = useGlobalData();  const myPluginData = globalData['my-plugin']['default'];  return <div>{myPluginData.someAttribute}</div>;};

tip

Inspecione os dados globais do seu site em ./docusaurus/globalData.json

`usePluginData`#

Acesse dados globais criados por uma instância específica do plugin.

Este é o hook mais conveniente para acessar dados globais do plugin e deve ser usado a maior parte do tempo.

pluginId é opcional se você não usa plugins de múltiplas instâncias.

usePluginData(pluginName: string, pluginId?: string)

Exemplo de uso:

import React from 'react';import {usePluginData} from '@docusaurus/useGlobalData';
const MyComponent = () => {  const myPluginData = usePluginData('my-plugin');  return <div>{myPluginData.someAttribute}</div>;};

`useAllPluginInstancesData`#

Acesso a dados globais criados por um plugin específico. Dado o nome do plugin, ele retorna os dados de todas as instâncias de plugins desse nome, pelo id do plugin.

useAllPluginInstancesData(pluginName: string)

Exemplo de uso:

import React from 'react';import {useAllPluginInstancesData} from '@docusaurus/useGlobalData';
const MyComponent = () => {  const allPluginInstancesData = useAllPluginInstancesData('my-plugin');  const myPluginData = allPluginInstancesData['default'];  return <div>{myPluginData.someAttribute}</div>;};

Funções#

`interpolação`#

A contrapartida obrigatória do componente <Interpolate>.

Assinatura#

// Simple string interpolationfunction interpolate(text: string, values: Record<string, string>): string;
// JSX interpolationfunction interpolate(  text: string,  values: Record<string, ReactNode>,): ReactNode;

Exemplo#

import {interpolate} from '@docusaurus/Interpolate';
const message = interpolate('Welcome {firstName}', {firstName: 'Sébastien'});

`traduzir`#

A contraparte imperativa do componente <Translate>. Também suporta interpolação de placeholders.

tip

Use a API imperativa para os casos raros em que um componente não pode ser usado, como:

o metadado da página title
as propriedades placeholder de entradas de formulário
as propriedades aria-label para acessibilidade

Assinatura#

function translate(  translation: {message: string; id?: string; description?: string},  values: Record<string, string>,): string;

Exemplo#

src/pages/index.js

import React from 'react';import Layout from '@theme/Layout';
import {translate} from '@docusaurus/Translate';
export default function Home() {  return (    <Layout      title={translate({message: 'My page meta title'})}    >      <img        src={'https://docusaurus.io/logo.png'}        aria-label={          translate(            {              message: 'The logo of site {siteName}',              // Optional              id: 'homepage.logo.ariaLabel',              description: 'The home page logo aria label',            },            {siteName: 'Docusaurus'},          )        }      />    </Layout>  );}

Módulos#

`ExecutionEnvironment`#

Um módulo que expõe algumas variáveis booleanas para verificar o ambiente de renderização atual. Útil se você deseja apenas executar determinado código no cliente/servidor ou precisa escrever código compatível com a renderização do lado do servidor.

import React from 'react';import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
const MyPage = () => {  const location = ExecutionEnvironment.canUseDOM ? window.location.href : null;  return <div>{location}</div>;};

Campo	Descrição
`ExecutionEnvironment.canUseDOM`	`true` se no cliente, `false` se pré-renderizar.
`ExecutionEnvironment.canUseEventListeners`	`true` se estiver no cliente e estiver `window.addEventListener`.
`ExecutionEnvironment.canUseIntersectionObserver`	`true` se estiver no cliente e tiver `IntersectionObserver`.
`ExecutionEnvironment.canUseViewport`	`true` se estiver no cliente e tiver `window.screen`.

`constantes`#

Um módulo que expõe constantes úteis para o código do tema do lado do cliente.

import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';

Exportação nomeada	Valor
`DEFAULT_PLUGIN_ID`	`default`

Componentes#

<Head/>#

<Link/>#

to: string#

<Redirect/>#

note

<BrowserOnly/>#

<Interpolate/>#

Props#

<Translate/>#

note

Props#

Exemplo#

Ganchos#

useDocusaurusContext#

useBaseUrl#

caution

Opções#

Exemplo de Uso:#

tip

useBaseUrlUtils#

useGlobalData#

info

tip

usePluginData#

useAllPluginInstancesData#

Funções#

interpolação#

Assinatura#

Exemplo#

traduzir#

tip

Assinatura#

Exemplo#

Módulos#

ExecutionEnvironment#

constantes#

`<Head/>`#

`<Link/>`#

`to`: string#

`<Redirect/>`#

`<BrowserOnly/>`#

`<Interpolate/>`#

`<Translate/>`#

`useDocusaurusContext`#

`useBaseUrl`#

`useBaseUrlUtils`#

`useGlobalData`#

`usePluginData`#

`useAllPluginInstancesData`#

`interpolação`#

`traduzir`#

`ExecutionEnvironment`#

`constantes`#