Reactor rápido e preciso do renderizador de noção. Baterias TS incluídas. ⚡️
Se você deseja apenas publicar um site usando noção, é altamente recomendável usar o Super.so - uma solução hospedada com excelente perfil que cuida de todos os detalhes para você.
Se você deseja mais controle sobre o seu site via React, recomendamos verificar o kit inicial do Next.js.js, que é gratuito e usa react-notion-x sob o capô.
E se você quiser ainda mais controle, está no lugar certo! ?
next/dynamicnext/image junto com as imagens de visualização LQIP (demonstração)Primeiro, você deseja buscar o conteúdo para uma página de noção:
import { NotionAPI } from 'notion-client'
const notion = new NotionAPI ( )
const recordMap = await notion . getPage ( '067dd719a912471ea9a3ac10710e7fdf' )Depois de ter os dados para uma página de noção, você pode renderizá -los via React:
import * as React from 'react'
import { NotionRenderer } from 'react-notion-x'
export default ( { recordMap } ) => (
< NotionRenderer recordMap = { recordMap } fullPage = { true } darkMode = { false } />
) NOTA: Para blocos mais pesados, você precisará usá -los por meio de NotionRenderer.components . Eles não estão incluídos na exportação NotionRenderer padrão porque são muito pesados para muitos casos de uso.
Você precisará importar alguns estilos CSS também. Se você estiver usando o Next.js, recomendamos que você coloque essas importações no topo das pages/_app.js :
// core styles shared by all of react-notion-x (required)
import 'react-notion-x/src/styles.css'
// used for code syntax highlighting (optional)
import 'prismjs/themes/prism-tomorrow.css'
// used for rendering equations (optional)
import 'katex/dist/katex.min.css' As importações padrão do react-notion-x se esforçam para ser o mais leve possível. A maioria dos blocos renderiza muito bem, mas alguns blocos maiores, como PDFs e visualizações de coleção (visualizações de banco de dados), não são incluídos por padrão.
Para usá-los, você precisará importar os que deseja do react-notion-x/build/third-party/* :
import { Code } from 'react-notion-x/build/third-party/code'
import { Collection } from 'react-notion-x/build/third-party/collection'
import { Equation } from 'react-notion-x/build/third-party/equation'
import { Modal } from 'react-notion-x/build/third-party/modal'
import { Pdf } from 'react-notion-x/build/third-party/pdf'Observe que recomendamos fortemente a carregamento preguiçoso desses componentes, a menos que você saiba que precisará deles antecipadamente para o seu caso de uso.
Se você estiver usando o Next.js, poderá usar o próximo/dinâmico para carregá -los preguiçosamente. Se o seu conteúdo de noção não usar um desses componentes pesados, ele não será carregado na sua página. Isso mantém o pacote de página inicial pequeno e seu site se sentindo ágil.
import dynamic from 'next/dynamic'
const Code = dynamic ( ( ) =>
import ( 'react-notion-x/build/third-party/code' ) . then ( ( m ) => m . Code )
)
const Collection = dynamic ( ( ) =>
import ( 'react-notion-x/build/third-party/collection' ) . then (
( m ) => m . Collection
)
)
const Equation = dynamic ( ( ) =>
import ( 'react-notion-x/build/third-party/equation' ) . then ( ( m ) => m . Equation )
)
const Pdf = dynamic (
( ) => import ( 'react-notion-x/build/third-party/pdf' ) . then ( ( m ) => m . Pdf ) ,
{
ssr : false
}
)
const Modal = dynamic (
( ) => import ( 'react-notion-x/build/third-party/modal' ) . then ( ( m ) => m . Modal ) ,
{
ssr : false
}
) Você precisará habilitá -los, passando -os para o suporte dos components do NotionRenderer .
export default ( { recordMap } ) => (
< NotionRenderer
recordMap = { recordMap }
components = { {
Code ,
Collection ,
Equation ,
Modal ,
Pdf
} }
/>
) O componente Code usa prisma sob o capô. Ele vem com suporte para JavaScript, TypeScript e CSS por padrão. Para adicionar suporte para sintaxes de linguagem adicionais, siga o exemplo em components/NotionPage.tsx que carrega preguiçosamente os componentes do prisma no tempo de execução. Você provavelmente desejará adicionar prismjs ao seu projeto como uma dependência ao usar o componente Code para que o TypeScript não reclame.
Para suporte Equation , você precisará importar os estilos Katex CSS.
Para cada um desses componentes opcionais, verifique se também está importando o CSS de terceiros relevante, se necessário (acima).
Opcionalmente, você pode passar um authToken e activeUser para a API se desejar acessar as páginas de noção privada. Ambos podem ser recuperados do seu navegador da web. Depois de visualizar seu espaço de trabalho, abra suas ferramentas de desenvolvimento> Aplicativo> Cookie> e copie o token_v2 e notion_user_id . Respectivamente, ActiveUser: noção_user_id, AuthToken: token_v2.
Recomendamos armazená -los como variáveis de ambiente e passá -las para o construtor Noção NotionAPI da seguinte forma:
const notion = new NotionAPI ( {
activeUser : process . env . NOTION_ACTIVE_USER ,
authToken : process . env . NOTION_TOKEN_V2
} ) Observe que esse não é o mesmo que o token da API fornecido pela API de noção oficial, pois notion-client usa a API de noção não oficial (que é o que todos os aplicativos de noção usam).
Aqui está um projeto mínimo de exemplo do próximo.js com o código mais importante nas pages/[pageId].tsx e components/NotionPage.tsx . Você pode visualizar este exemplo ao vivo no vercel.
Aqui está um projeto de exemplo do próximo.js mais completo com o código mais importante nas pages/[pageId].tsx e components/NotionPage.tsx . Você pode visualizar este exemplo ao vivo no vercel.
A demonstração completa adiciona alguns recursos interessantes:
Para um exemplo de produção, consulte o kit inicial do próximo.js noção, que usa react-notion-x sob o capô.
| Pacote | Npm | Ambiente | Descrição |
|---|---|---|---|
| React-notion-x | Navegador + ssr | Reactor rápido do renderizador para noção. | |
| noção-cliente | Lado do servidor* | Cliente Robusto de Typescript para a API de noção. | |
| Tipo de noção | Universal | Notion Typescript Tipos. | |
| noção-utils | Universal | Utilitários úteis para trabalhar com dados de noção. |
* A API da Noção não deve ser chamada de navegadores do lado do cliente devido a restrições de CORS. notion-client é compatível com Node.js e Deno.
A maioria dos blocos de noção e as visualizações de coleção é totalmente suportada.
| Tipo de bloco | Suportado | Tipo de bloco Enum | Notas |
|---|---|---|---|
| Página | ✅ Sim | page | |
| Texto | ✅ Sim | text | Suporta todas as opções conhecidas de formatação de texto |
| Marco | ✅ Sim | bookmark | Visualização incorporada de URL externo |
| Lista de marcadores | ✅ Sim | bulleted_list | <ul> |
| Lista numerada | ✅ Sim | numbered_list | <ol> |
| Cabeçalho 1 | ✅ Sim | header | <h1> |
| Titular 2 | ✅ Sim | sub_header | <h2> |
| Título 3 | ✅ Sim | sub_sub_header | <h3> |
| Citar | ✅ Sim | quote | |
| Chamar | ✅ Sim | callout | |
| Equação (bloco) | ✅ Sim | equation | Katex via React-Katex |
| Equação (embutida) | ✅ Sim | text | Katex via React-Katex |
| Todos (caixas de seleção) | ✅ Sim | to_do | |
| Índice | ✅ Sim | table_of_contents | Veja notion-utils getPageTableOfContents Helper Função |
| Divisor | ✅ Sim | divider | Linha horizontal |
| Coluna | ✅ Sim | column | |
| Lista de colunas | ✅ Sim | column_list | |
| Alternar | ✅ Sim | toggle | <details> |
| Imagem | ✅ Sim | image | <img> |
| Incorporar | ✅ Sim | embed | Incorporações genéricas iframe |
| Vídeo | ✅ Sim | video | iframe |
| Figma | ✅ Sim | figma | iframe |
| Google Maps | ✅ Sim | maps | iframe |
| Google Drive | ✅ Sim | drive | Google Docs, lençóis, etc. incorporação personalizada |
| Tweet | ✅ Sim | tweet | Usa o Twitter incorporando SDK |
| ✅ Sim | pdf | Usa URLs assinados por S3 e react-pdf | |
| Áudio | ✅ Sim | audio | Usa URLs assinados por S3 e elemento audio HTML5 |
| Arquivo | ✅ Sim | file | Usa URLs assinados S3 (arquivo genérico para download) |
| Link | ✅ Sim | text | Links externos |
| Link da página | ✅ Sim | page | Link para uma página de noção no mesmo espaço de trabalho |
| Link de página externa | ✅ Sim | text | Links para uma página de noção ou visualização de coleção em outro espaço de trabalho |
| Código (bloco) | ✅ Sim | code | Sintaxe do código de bloco destacando via prismjs |
| Código (embutido) | ✅ Sim | text | Formatação de código embutido (sem destaque da sintaxe) |
| Coleções | ✅ Sim | Também conhecido como bancos de dados | |
| Visualização da coleção | ✅ Sim | collection_view | As coleções têm um mapeamento de 1: n para as visualizações de coleta |
| Tabela de exibição de coleção | ✅ Sim | collection_view | type = "table" (exibição padrão da tabela) |
| Coleção Ver Gallery | ✅ Sim | collection_view | type = "gallery" (vista da grade) |
| Coleção Visualização de Visualização | ✅ Sim | collection_view | type = "board" (Vista Kanban) |
| Lista de visualizações de coleção | ✅ Sim | collection_view | type = "list" (Visualização da Lista Vertical) |
| Coleta Vista Calendário | Ausente | collection_view | type = "calendar" (vista do calendário incorporado) |
| Página de exibição de coleção | ✅ Sim | collection_view_page | Visualização de coleção como uma página independente |
Informe -nos se encontrar algum problema ou blocos ausentes.
Todos os blocos conhecidos e configurações mais conhecidas podem ser encontradas em nosso conjunto de testes.
O Google Lighthouse pontuações para um exemplo de página renderizada por `react-notion-x` no vercel.
Fora da caixa, react-notion-x é bastante rápido e relativamente leve, mas existem alguns fatores-chave a serem cientes.
O Bundlephobia relata um tamanho de pacote GZIP de ~ 28kb para o pacote react-notion-x principal. Isso não inclui os componentes third-party opcionais que recomendamos carregar preguiçosos via Next/Dynamic somente se uma página precisar deles.
Outro fator importante para o Perf vem de imagens hospedadas por noção. Geralmente, eles são otimizados, de tamanho inadequado e não estão em cache, porque a noção precisa lidar com o controle de acesso de granulação fina que os usuários podem mudar a qualquer momento. Você pode substituir a função mapImageUrl padrão no NotionRenderer para adicionar armazenamento em cache por meio de um CDN como o CloudFlare Workers, que é o que a noção X faz para obter velocidades ideais de carga de página.
NotionRenderer também suporta o carregamento de imagem preguiçoso com visualizações opcionais de espaço reservado para imagens de baixa qualidade. Você pode ver uma demonstração disso na prática nesta página, que está usando imagens de espaço reservado LQIP-Modern para pré-generalidade que são inspirados no carregamento de imagem do Medium.com.
Se você estiver usando o Next.js, recomendamos passar next/image ou next/legacy/image , e next/link para o renderizador da seguinte forma:
import Image from 'next/image' // or import Image from 'next/legacy/image' if you use legacy Image
import Link from 'next/link'
export default ( { recordMap } ) => (
< NotionRenderer
recordMap = { recordMap }
components = { {
nextImage : Image , // or nextLegacyImage: LegacyImage,
nextLink : Link
} }
/>
) <a> <img> esses componentes a NotionRenderer .
Observe que o componente de imagem personalizado está atualmente ativado apenas com a imagem de visualização ou ativando forceCustomImages do NotionRenderer .
react-notion-x sob o capôreact-notion-x começou como um garfo de react-notion com melhor suporte para diferentes tipos de noção de conteúdo (especialmente coleções) e se transformou em algo muito mais abrangentereact-notion não é mais mantido ativamentenotion-types e notion-client são uma reescrita de notion-api-workerreact-notion-x é a renderização do lado do servidor via Next.js, nesse caso o trabalhador da CF é desnecessárioVeja o guia de contribuição e junte -se à nossa incrível lista de colaboradores!
MIT © Travis Fischer
Este projeto estende o trabalho licenciado pelo MIT de Timo Lins, Tobias Lins, Sam Wight e outros colaboradores.
Apoie meu trabalho OSS, seguindo -me no Twitter
Super.so foi gentil o suficiente para patrocinar este projeto. Se você está procurando uma solução hospedada que adote uma abordagem muito semelhante ao react-notion-x mas lida com todos os detalhes para você, definitivamente os confira.
