Система комментариев

Xingluo интегрирует три системы комментариев — giscus, twikoo и waline — выбираемые через features.comments.

Конфигурация

Выберите провайдера и укажите его конфигурацию в features.comments в xingluo.config.ts:

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

С provider: false (по умолчанию) комментарии отключены, и страницы постов не содержат маркеров или скриптов комментариев.

Расположение раздела комментариев

Раздел комментариев появляется только внизу страниц деталей постов (после навигации предыдущий/следующий), рендерится компонентом src/components/comments/Comments.astro.

giscus

A comment system based on GitHub Discussions; the repository must be public with Discussions enabled.

Configuration

ts
comments: {
  provider: "giscus",
  giscus: {
    repo: "owner/repo",           // GitHub repository
    repoId: "R_...",              // Repository ID (generated by giscus.app)
    category: "Announcements",    // Discussion category name
    categoryId: "DIC_...",        // Category ID (generated by giscus.app)
    mapping: "pathname",          // optional, page-to-discussion mapping
    strict: false,                // optional, strict title matching
    reactionsEnabled: true,       // optional, reactions
    inputPosition: "bottom",      // optional, comment box position: top | bottom
    loading: "lazy",              // optional, loading: lazy | eager
  },
}

Получение repoId / categoryId

1. Посетите giscus.app
2. Введите репозиторий и категорию для генерации конфигурации
3. Скопируйте data-repo-id и data-category-id в свою конфигурацию

Как это работает

giscus внедряет iframe через официальный client.js, с атрибутами data-*, содержащими конфигурацию. Язык автоматически сопоставляется с текущей локалью (zh-cn → zh-CN, en → en). Тема синхронизируется при переключении через postMessage.

twikoo

Система комментариев без зависимости от бэкенда, поддерживающая Tencent CloudBase или самостоятельный хостинг.

Конфигурация

ts
comments: {
  provider: "twikoo",
  twikoo: {
    envId: "https://your-twikoo.example.com", // ID облачной среды или полный URL самостоятельного хостинга
    lang: "zh-CN",                            // опционально, язык
  },
}

Примечания к envId

• Tencent CloudBase: заполните ID среды (требуется cloudbase SDK)
• Самостоятельный хостинг: заполните полный URL (напр. https://twikoo.example.com); twikoo автоматически определяет режим HTTP API

Как это работает

twikoo динамически импортирует import("twikoo") и вызывает init, когда контейнер комментариев попадает в область просмотра. twikoo не поддерживает переключение темы во время выполнения; сайт перестраивает его при изменении темы для применения тёмных стилей.

waline

Система комментариев с бэкендом, поддерживающая счётчики комментариев и просмотров.

Конфигурация

ts
comments: {
  provider: "waline",
  waline: {
    serverURL: "https://waline.example.com", // Адрес сервера Waline
    lang: "zh-CN",                           // опционально, язык
    pageSize: 10,                            // опционально, размер страницы комментариев
    dark: "html.dark",                       // опционально, тёмный селектор (по умолчанию следует .dark сайта)
  },
}

Развёртывание serverURL

Обратитесь к документации Waline для развёртывания сервера (Vercel / Cloudflare / самостоятельный хостинг — всё работает), затем укажите адрес в serverURL.

Как это работает

waline динамически импортирует import("@waline/client") и стиль @waline/client/style, когда контейнер комментариев попадает в область просмотра, затем вызывает init. Селектор dark:"html.dark" автоматически следует тёмному режиму сайта; ручная синхронизация не требуется.

Ленивая загрузка

Все системы комментариев лениво загружаются через IntersectionObserver: запросы и инициализация происходят только когда контейнер комментариев находится в пределах 200px от области просмотра, избегая затрат производительности при первой отрисовке.

См. src/scripts/comments.ts.

Синхронизация темы

Когда тема сайта меняется, тема системы комментариев синхронизируется автоматически:

Отслеживание темы использует MutationObserver на атрибутах class и data-theme элемента document.documentElement.

Адаптация View Transitions

Скрипт комментариев прослушивает astro:page-load и повторно сканирует точки монтирования после каждой загрузки страницы. Повторная инициализация предотвращается маркерами dataset (xng-setup, xng-init).

i18n

Заголовок раздела комментариев локализован через UIStrings.comments.title (“Comments” в обоих zh-cn.ts и en.ts). Язык интерфейса системы комментариев управляется полем lang каждого провайдера.

Пользовательские расширения

Смена провайдера

Измените features.comments.provider в xingluo.config.ts; изменения кода не требуются. Xingluo автоматически рендерит соответствующий подкомпонент.

Добавление системы комментариев

1. Создайте новый компонент в src/components/comments/ (например, Disqus.astro), который рендерит placeholder для монтирования
2. Добавьте новую ветку провайдера в условном рендеринге Comments.astro
3. Добавьте логику инициализации в src/scripts/comments.ts
4. Расширьте CommentProvider и типы конфигурации в src/types/config.ts