Sistema de Comentários

Xingluo integra três sistemas de comentários — giscus, twikoo e waline — selecionáveis através de features.comments.

Configuration

Choose a provider and supply its config in features.comments in xingluo.config.ts:

ts
features: {
  comments: {
    provider: "giscus", // "giscus" | "twikoo" | "waline" | false
    giscus: { /* giscus config */ },
    // twikoo: { /* twikoo config */ },
    // waline: { /* waline config */ },
  },
}

Com provider: false (padrão), os comentários estão desativados e as páginas de post não emitem marcadores ou scripts de comentário.

Localização da seção de comentários

A seção de comentários aparece apenas na parte inferior das páginas de detalhe do post (após a navegação anterior/próximo), renderizada por src/components/comments/Comments.astro.

giscus

Um sistema de comentários baseado em GitHub Discussions; o repositório deve ser público com Discussions ativado.

Configuração

ts
comments: {
  provider: "giscus",
  giscus: {
    repo: "owner/repo",           // Repositório GitHub
    repoId: "R_...",              // ID do repositório (gerado por giscus.app)
    category: "Announcements",    // Nome da categoria de discussão
    categoryId: "DIC_...",        // ID da categoria (gerado por giscus.app)
    mapping: "pathname",          // opcional, mapeamento página-para-discussão
    strict: false,                // opcional, correspondência estrita de título
    reactionsEnabled: true,       // opcional, reações
    inputPosition: "bottom",      // opcional, posição da caixa de comentário: top | bottom
    loading: "lazy",              // opcional, carregamento: lazy | eager
  },
}

Obtendo repoId / categoryId

1. Visite giscus.app
2. Insira o repositório e a categoria para gerar a configuração
3. Copie data-repo-id e data-category-id para sua configuração

Como funciona

giscus injeta um iframe via client.js oficial, com atributos data-* carregando a configuração. O idioma é mapeado automaticamente para a locale atual (zh-cn → zh-CN, en → en). O tema é sincronizado na alternância via postMessage.

twikoo

Um sistema de comentários sem dependência de backend, suportando Tencent CloudBase ou auto-hospedagem.

Configuração

ts
comments: {
  provider: "twikoo",
  twikoo: {
    envId: "https://your-twikoo.example.com", // ID do ambiente cloud ou URL de auto-hospedagem completa
    lang: "zh-CN",                            // opcional, idioma
  },
}

Notas sobre envId

• Tencent CloudBase: preencha o ID do ambiente (requer o SDK cloudbase)
• Auto-hospedado: preencha a URL completa (ex. https://twikoo.example.com); twikoo detecta automaticamente o modo API HTTP

Como funciona

twikoo importa dinamicamente import("twikoo") e chama init quando o contêiner de comentários entra no viewport. twikoo não suporta alternância de tema em tempo de execução; o site o reconstrói na mudança de tema para aplicar estilos escuros.

waline

Um sistema de comentários com backend, com contadores de comentários e visualizações.

Configuração

ts
comments: {
  provider: "waline",
  waline: {
    serverURL: "https://waline.example.com", // Endereço do servidor Waline
    lang: "zh-CN",                           // opcional, idioma
    pageSize: 10,                            // opcional, tamanho da página de comentários
    dark: "html.dark",                       // opcional, seletor escuro (padrão site .dark)
  },
}

Implantação do serverURL

Consulte a documentação do Waline para implantar o servidor (Vercel / Cloudflare / auto-hospedagem), então coloque o endereço em serverURL.

Como funciona

waline importa dinamicamente import("@waline/client") e o estilo @waline/client/style quando o contêiner de comentários entra no viewport, então chama init. O seletor dark:"html.dark" segue automaticamente o modo escuro do site; nenhuma sincronização manual necessária.

Carregamento lento

Todos os sistemas de comentários são carregados lentamente via IntersectionObserver: requisições e inicialização ocorrem apenas quando o contêiner de comentários está a 200px do viewport, evitando custo de desempenho no primeiro paint.

Veja src/scripts/comments.ts.

Sincronização de tema

Quando o tema do site muda, o tema do sistema de comentários sincroniza automaticamente:

A observação do tema usa um MutationObserver nos atributos class e data-theme de document.documentElement.

Adaptação de View Transitions

O script de comentário escuta astro:page-load e reexamina os pontos de montagem após cada carregamento de página. A reinicialização é prevenida via marcadores dataset (xng-setup, xng-init).

i18n

O título da seção de comentários é localizado via UIStrings.comments.title (“Comentários” em zh-cn.ts e en.ts). O idioma da interface do sistema de comentários é controlado pelo campo lang de cada provedor.

Extensões personalizadas

Trocar provedores

Altere features.comments.provider em xingluo.config.ts; nenhuma alteração de código necessária. Xingluo renderiza o subcomponente correspondente automaticamente.

Adicionar um sistema de comentários

1. Crie um novo componente em src/components/comments/ (ex. Disqus.astro) que renderiza um contêiner de montagem
2. Adicione um novo ramo de provedor na renderização condicional de Comments.astro
3. Adicione lógica de inicialização em src/scripts/comments.ts
4. Estenda CommentProvider e tipos de configuração em src/types/config.ts