如何将Giscus评论集成到AstroPaper中（译）

原文章：How to integrate Giscus comments into AstroPaper

在像 GitHub Pages 这样的平台上托管一个简单的静态博客有许多优点，但也失去了一些互动性。幸运的是，Giscus 的存在为静态网站嵌入用户评论提供了一种解决方案。

Table of contents

Giscus 如何工作

Giscus 使用 GitHub API 来读取和存储在与存储库关联的 Discussions 中由 GitHub 用户发表的评论。

在您的网站上嵌入 Giscus 客户端脚本包，使用正确的存储库 URL 进行配置，用户就可以查看和撰写评论（在登录 GitHub 的情况下）。

这种方法是无服务器的，因为评论存储在 GitHub 上，并通过客户端动态加载，因此非常适合像 AstroPaper 这样的静态博客。

设置 Giscus

Giscus 可以在 giscus.app 上轻松设置，但我仍将简要介绍这个过程。

前置条件

使 Giscus 正常工作的前置条件是：

• 仓库是 公开的
• 已安装 Giscus 应用
• 为您的仓库开启了 Discussions 功能

如果由于任何原因无法满足这些条件，遗憾的是，无法集成 Giscus。

配置 Giscus

接下来，需要配置 Giscus。在大多数情况下，预选的默认值是合适的，只有在您有特定原因并且知道自己在做什么时才应该修改它们。

不必太担心选错，您可以随时稍后调整配置。

但您需要：

• 为 UI 选择正确的语言
• 指定要连接的 GitHub 仓库，通常是在 GitHub Pages 上托管静态 AstroPaper 博客的仓库
• 如果您想确保没有人可以直接在 GitHub 上创建随机评论，请在 GitHub 上创建并设置一个 Announcement 类型的讨论
• 定义配色方案

配置完成后，Giscus 会为您提供一个生成的 <script> 标签，您将在后续步骤中用到它。

简单的 script 标签

您现在应该有一个类似这样的 script 标签：

<script
  src="https://giscus.app/client.js"
  data-repo="[在此输入仓库名]"
  data-repo-id="[在此输入仓库 ID]"
  data-category="[在此输入分类名称]"
  data-category-id="[在此输入分类 ID]"
  data-mapping="pathname"
  data-strict="0"
  data-reactions-enabled="1"
  data-emit-metadata="0"
  data-input-position="bottom"
  data-theme="preferred_color_scheme"
  data-lang="zh-CN"
  crossorigin="anonymous"
  async
></script>

只需将其添加到网站的源代码中。如果您正在使用 AstroPaper 并希望在文章上启用评论，导航到 PostDetails.astro 并将其粘贴到您希望评论显示的位置，比如 “分享这篇文章：” 按钮的下方。

<Layout {...layoutProps}>
  <main>
    <ShareLinks />

    <script
      src="https://giscus.app/client.js"
      data-repo="[在此输入仓库名]"
      data-repo-id="[在此输入仓库 ID]"
      data-category="[在此输入分类名称]"
      data-category-id="[在此输入分类 ID]"></script>
  </main>
  <Footer />
</Layout>src/layouts/PostDetails.astro

这样就完成了！您已经成功地将评论集成到 AstroPaper 中！

支持明/暗主题的 React 组件

布局中嵌入的 script 标签相当静态，包括 theme 在内的 Giscus 配置都被硬编码在布局中。考虑到 AstroPaper 具有明/暗主题切换功能，如果评论能够随着网站的其他部分在明暗主题之间无缝切换，那将会很棒。为了实现这一点，需要采用更复杂的方法来嵌入 Giscus。

首先，我们将安装 Giscus 的 React 组件：

npm i @giscus/react && npx astro add react

然后我们在 src/components 中创建一个新的 Comments.tsx React 组件

import Giscus, { type Theme } from "@giscus/react";
import { GISCUS } from "@/constants";
import { useEffect, useState } from "react";

interface CommentsProps {
  lightTheme?: Theme;
  darkTheme?: Theme;
}

export default function Comments({
  lightTheme = "light",
  darkTheme = "dark",
}: CommentsProps) {
  const [theme, setTheme] = useState(() => {
    const currentTheme = localStorage.getItem("theme");
    const browserTheme = window.matchMedia("(prefers-color-scheme: dark)")
      .matches
      ? "dark"
      : "light";

    return currentTheme || browserTheme;
  });

  useEffect(() => {
    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
    const handleChange = ({ matches }: MediaQueryListEvent) => {
      setTheme(matches ? "dark" : "light");
    };

    mediaQuery.addEventListener("change", handleChange);

    return () => mediaQuery.removeEventListener("change", handleChange);
  }, []);

  useEffect(() => {
    const themeButton = document.querySelector("#theme-btn");
    const handleClick = () => {
      setTheme(prevTheme => (prevTheme === "dark" ? "light" : "dark"));
    };

    themeButton?.addEventListener("click", handleClick);

    return () => themeButton?.removeEventListener("click", handleClick);
  }, []);

  return (
    <div className="mt-8">
      <Giscus theme={theme === "light" ? lightTheme : darkTheme} {...GISCUS} />
    </div>
  );
}src/components/Comments.tsx

这个 React 组件不仅包装了原生的 Giscus 组件，还引入了额外的属性，即 lightTheme 和 darkTheme。利用两个事件监听器，Giscus 评论将与网站主题保持一致，在网站或浏览器主题更改时动态地在暗色和亮色主题之间切换。

我们还需要定义 GISCUS 配置，最佳位置是在 constants.ts 中：

import type { GiscusProps } from "@giscus/react";

...

export const GISCUS: GiscusProps = {
  repo: "[在此输入仓库名]",
  repoId: "[在此输入仓库 ID]",
  category: "[在此输入分类名称]",
  categoryId: "[在此输入分类 ID]",
  mapping: "pathname",
  reactionsEnabled: "0",
  emitMetadata: "0",
  inputPosition: "bottom",
  lang: "zh-CN",
  loading: "lazy",
};src/constants.ts

请注意，在此处指定 theme 会覆盖 lightTheme 和 darkTheme 属性，导致主题设置变为静态，类似于之前使用 <script> 标签嵌入 Giscus 的方法。

要完成该过程，请将新的 Comments 组件添加到 PostDetails.astro 中（替换上一步中的 script 标签）。

import Comments from "@/components/Comments";

<ShareLinks />

<Comments client:only="react" />

<hr class="my-6 border-dashed" />

<Footer />src/layouts/PostDetails.astro

就这样！大功告成！

（完）

如果这篇文章刚好帮到了你，欢迎请我喝杯咖啡！