Componentes Personalizados do Markstream

Visão Geral

Personalize nós específicos do Markstream ou tags personalizadas confiáveis sem substituir o parser ou vazar o estado global do renderer. Leia references/patterns.md primeiro.

Quando Usar

Use para substituir built-ins como image, link, code_block, mermaid ou inline_code; renderizar tags confiáveis como thinking; ou escopar substituições para um renderer ou aplicativo. Use transformações de parser apenas quando for necessário remodelar tokens ou AST.

Fluxo de Trabalho

Antes de alterar dependências ou arquivos de origem, inspecione o gerenciador de pacotes existente e as convenções do projeto, visualize as edições pretendidas e obtenha aprovação explícita do usuário.

1. Classifique a alteração como substituição de built-in, tag confiável ou transformação de parser.
2. Prefira mapeamentos com escopo. Vue, Vue 2, Svelte e Angular podem usar setCustomComponents(customId, mapping); Svelte e Angular também podem passar mapas locais do renderer.
3. No React, prefira streamingComponents para nós baseados em parser e htmlComponents para atributos e filhos higienizados.
4. Comece com nós folha antes de contêineres que devem preservar os filhos.
5. Para corpos de tags confiáveis contendo Markdown, use um renderer aninhado com a mesma lista de permissões. Não adicione um segundo loop de streaming suave.
6. Preserve props de nó/carregamento, chaves de identidade, IDs de escopo, estado de tema e estimativas de altura de pré-visualização para diagramas assíncronos.
7. Remova registros com escopo temporários na limpeza e valide tags repetidas e aninhadas.

Exemplo

import MarkdownRender, {
  type NodeComponentProps,
  setCustomComponents,
} from 'markstream-react'
import 'markstream-react/index.css'

function ThinkingNode({ node }: NodeComponentProps<any>) {
  return <details><summary>Thinking</summary>{node.content}</details>
}

setCustomComponents('assistant-panel', { thinking: ThinkingNode })

export function Answer({ markdown }: { markdown: string }) {
  return (
    <MarkdownRender
      content={markdown}
      customId="assistant-panel"
      customHtmlTags={['thinking']}
      htmlPolicy="safe"
    />
  )
}

Limitações

• Substituições de componentes não podem reproduzir transformações arbitrárias de remark/rehype.
• Substituições de contêiner exigem renderização cuidadosa de filhos e revisão de acessibilidade.
• APIs de registro de framework não são intercambiáveis.

Notas de Segurança e Proteção

Trate tags semelhantes a HTML personalizadas apenas como entrada confiável. Mantenha o HTML seguro ativado e não passe atributos não higienizados para componentes host.