Diversity Comments SDK

三步接入：引入 SDK → 放置容器 → 调用 init()。

Step 1 — 放置容器

<div id="diversity-comments"></div>

Step 2 — 引入 SDK

<script src="https://huazie.github.io/js/diversity-comments.1.0.0.min.js"></script>

Step 3 — 初始化

DiversityComments.init({
    container: '#diversity-comments',
    comments: {
        pageId: '/comments',
        style: 'tabs',
        active: 'utterances',
        lazyload: true,
        storage: true,
        darkMode: 'auto',
        lang: 'zh-CN'
    },
    utterances: {
        enable: true,
        repo: 'user/repo',
        issue_term: 'pathname'
    },
    giscus: {
        enable: true,
        repo: 'user/repo',
        repo_id: 'R_xxx',
        category: 'Announcements',
        category_id: 'DIC_xxx',
        mapping: 'pathname'
    },
    onReady: function(iframe, active) {
        console.log('评论已就绪，当前:', active);
    },
    onActiveChange: function(active) {
        console.log('切换到:', active);
    },
    onError: function(msg) {
        console.error('加载失败: ' + msg);
    }
});

基础配置

参数	类型	默认值	说明
server	string	自动检测	评论服务地址，SDK 自动捕获脚本加载地址
container	string	'#diversity-comments'	挂载容器的 CSS 选择器

评论通用配置 (comments)

参数	类型	默认值	说明
pageId	string	空（按各插件模式取父页面值）	页面唯一标识。传入则所有评论系统统一使用此值；未传则各插件按 issue_term/mapping/path 模式从父页面取 pathname/url/title
style	string	'tabs'	显示模式：tabs 选项卡 / dropdown 下拉菜单
active	string	'utterances'	默认激活的评论系统
lazyload	boolean	true	进入视口才加载评论
storage	boolean	true	记住用户选择的评论系统
darkMode	string	'auto'	明暗模式：auto / light / dark
lang	string	''	语言设置，统一覆盖各评论系统的语言配置（Utterances 不支持）；为空则各插件使用自身默认语言
nav	object	六系统默认	导航配置：文字、排序、图标

回调函数

参数	类型	说明
onReady	function	初始化完成回调，参数 iframe 为 iframe 元素，active 为当前激活的评论系统名
onError	function	错误回调，参数 msg 为错误信息
onActiveChange	function	激活评论系统变更回调，参数 active 为变更后的评论系统名

API 方法

方法	参数	说明
switchTo(name)	评论系统名称	切换到指定评论系统
setColorScheme(scheme)	'light' | 'dark' | 'auto'	切换深色/浅色模式
refresh()	无	刷新当前评论
getConfig()	无	获取当前配置（深拷贝）
destroy()	无	销毁实例，移除 iframe 和事件监听

Giscus 会检查顶层父页面域名而非 iframe 的 src 域名，因此需将所有嵌入域名加入白名单。

1. 配置 giscus.json

在 Giscus 评论仓库根目录创建：

{
  "origins": [
    "http://localhost:4000",
    "http://localhost:3000",
    "http://127.0.0.1:4000",
    "https://你的生产域名.com"
  ]
}

2. 提交并推送

git add giscus.json && git commit -m "Add Giscus origins" && git push

3. 验证

等待 1-2 分钟，用无痕模式打开，F12 → Network 查看 giscus.app 的 Response Headers：

content-security-policy: frame-ancestors 'self' http://localhost:4000 ...

要点	说明
文件位置	放在 Giscus 评论仓库根目录，不是博客仓库
域名区分	localhost 和 127.0.0.1 是不同 origin，需分别配置
端口号	不同端口是不同 origin，如 :3000 和 :4000 需分开列出
协议	http:// 和 https:// 需分别配置

每个评论系统通过 init() 的同名属性传入配置，只需配置 enable: true 的系统。

Utterances

utterances: {
    enable: true,
    repo: 'user-name/repo-name',            // 必填：GitHub 用户名/GitHub 评论仓库
    issue_term: 'pathname',                 // Issue 映射方式
    theme: 'github-light',                  // 浅色主题
    dark: 'github-dark'                     // 深色主题
}

注：Utterances 不支持语言配置，comments.lang 对其无效。

更多配置

Gitalk

gitalk: {
    enable: true,
    github_id: 'user-name',                 // 必填：GitHub 用户名
    repo: 'repo-name',                      // 必填：GitHub 评论仓库
    client_id: 'your-client-id',            // 必填：OAuth App Client ID
    client_secret: 'your-client-secret',    // 必填：OAuth App Client Secret
    admin_user: 'your-github-id',
    distraction_free_mode: true,
    proxy: 'https://your-oauth-proxy.com/api/auth',
    issue_term: 'pathname',
    language: 'zh-CN'
}

更多配置

Giscus

giscus: {
    enable: true,
    repo: 'your-username/your-repo-name',   // 必填：GitHub 用户名/GitHub 评论仓库
    repo_id: 'R_xxxxxxxxxxxxx',             // 必填：从 giscus.app 获取
    category: 'Announcements',              // 必填
    category_id: 'DIC_xxxxxxxxxxxxxxxxx',   // 必填
    mapping: 'pathname',
    reactions_enabled: 1,
    theme: 'light',
    dark: 'dark',
    lang: 'zh-CN',
    input_position: 'bottom'
}

更多配置

Twikoo

twikoo: {
    enable: true,
    env_id: 'https://your-twikoo.vercel.app',  // 必填：云函数地址
    lang: 'zh-CN'
}

更多配置

Gitment

gitment: {
    enable: true,
    owner: 'user-name',                     // 必填：GitHub 用户名
    repo: 'repo-name',                      // 必填：GitHub 评论仓库
    client_id: 'your-client-id',            // 必填：OAuth App Client ID
    client_secret: 'your-client-secret',    // 必填：OAuth App Client Secret
    issue_term: 'pathname',
    proxy: 'https://your-oauth-proxy.com/api/auth',
    gitmint: true,
    lang: zh-CN
}

更多配置

Waline

waline: {
    enable: true,
    server_url: 'https://your-waline-server.vercel.app/.netlify/functions/comment',  // 必填
    lang: 'zh-CN',
    dark: '.dark-theme',
    reaction: true,
    page_size: 10
}

更多配置

切换评论系统 switchTo(name)

明暗模式 setColorScheme(scheme)

实例操作