6000 字 | 終於，給網站插上了留言的翅膀

這是悟空的第 111 篇原創文章css

本文主要內容以下：

1、背景

個人開源項目 PassJava 有個在線的技術文檔，可是沒有評論功能，總感受缺了點什麼，此次來給它加上留言功能。html

最後留言的效果圖以下：java

文檔演示地址：http://www.passjava.cnreact

以前作了一個介紹 PassJava 的短視頻，你們能夠雙擊 666 哦！git

一款基於 Spring Cloud 的面試刷題系統github

首先個人這個文檔網站是基於開源的 docsify 的：
web

docsify 是一個動態生成文檔網站的工具。不一樣於 GitBook、Hexo 的地方是它不會生成將 .md 轉成 .html 文件，全部轉換工做都是在運行時進行。面試

若是隻是須要快速的搭建一個小型的文檔網站，或者不想由於生成的一堆 .html 文件「污染」 commit 記錄，只須要建立一個 index.html 就能夠開始寫文檔並且直接部署在 GitHub Pages。小程序

開源項目 PassJava 地址：https://github.com/Jackson0714/PassJava-Platform，歡迎 Star。segmentfault

本文已收錄至：www.passjava.cn

那如何給 docsify 添加評論呢？這裏就是要用到 Gitalk 了。

2、Gitalk 介紹

Gitalk 是一個基於 GitHub Issue 和 Preact 開發的評論插件。

擴展知識：Preact 是 React 的 3KB 輕量級替代方案，它擁有着和 React 同樣的 API。React 用於構建用戶界面的 JavaScript 庫。

2.1 Gitalk 特性

使用 GitHub 登陸。
支持多語言。
支持我的或組織。
無干擾模式（設置 distractionFreeMode 爲 true 開啓）。
快捷鍵提交評論（cmd|ctrl + enter）。

2.3 Gitalk 原理

2.3.1 原理介紹

Gitalk 嵌入到我的網站中，而後利用了 Github 的 Issue 功能，把 Github 的 Issue 中的 Comments 看成某篇文章的評論。固然，這些功能都是 Gitalk 自帶的，咱們不用關心，這裏我仍是剖析下 Gitalk 的原理。

Github 的 Issue 功能，可能你們不知道，能夠理解爲貼吧的帖子，我截個圖你們就懂了。在 Github 的開源項目中，Issue Tab 下能夠提出問題，也能夠在裏面加 comments（評論）。

2.3.2 添加評論的原理

首先建立評論時 Gitalk 會調用 Github API 在 Github 的 Issue 中添加 Comments。咱們也能夠到 Github 的 Issue 中查看評論或者添加評論。

添加評論的 API：

https://api.github.com/repos/Jackson0714/PassJava-Learning/17/comments

請求的參數：

{
 body: "有什麼問題嗎？"
}

以下圖所示：

2.3.3 獲取評論列表

當咱們打開網站查看評論列表時，Gitalk 會根據倉庫名、標籤 獲取 Github 上 Issue 的評論列表。

獲取評論列表請求的 API:

https://api.github.com/repos/Jackson0714/PassJava-Learning/issues

以下圖所示：

倉庫名：PassJava-Learning

標籤：Gitalk、02.PassJava架構篇/24.緩存實戰（四）SpringCache。

倉庫名是配置出來的，標籤是 Gitalk 自動獲取的。

2.3.4 受權

Gitalk 要想使用 Github 的 Issue 功能，則須要在 Github 上建立一個受權應用，拿到應用的 id 和密鑰配置到 Gitalk 腳本中就能夠了。

2.3.5 顯示評論功能

Gitalk 提供了評論功能的 JavaScript 腳本和評論的樣式，直接在網站中引入便可。後面會有詳細的配置方法。

3、配置 Github 的受權應用

Gitalk 是藉助 Github 的倉庫的 Issues 功能的，因此咱們須要在 Github 上配置受權應用（GitHub OAuth application），讓本身的網站可以經過這個受權應用將評論放到 Issues 上。

建立 GitHub OAuth application流程：

一、打開github網站登錄後，點擊右上角的用戶圖標，選擇Settings。

二、在Settings頁面選擇Developer settings選項。

三、在Developer settings選擇OAuth Apps,而後會在頁面右邊有一個New OAuth App按鈕，點擊這個按鈕就進入到新建OAuth application頁面。

四、也能夠直接代開這個連接：進入新建頁面。

https://github.com/settings/applications/new

以下圖所示：

接着填寫應用的基本信息：App name，任意填寫，Homepage URL 和 Callback URL 填寫網站的域名，兩個地方的域名保持一致，以下所示：

點擊 Register Application 就能夠建立成功了，會生成應用的 id 和密鑰，以下圖所示。這兩個信息在配置 gitalk 的時候用到，很是重要。並且 secret 你要第一時間備份下，後面再進來就是隱藏的了，除非從新生成一個新的。

4、如何引入 Gitalk

官方的使用方式很簡單，直接在本身的網站中加入 Gitalk 的腳本庫文件和 css 文件

<link rel="stylesheet" href="//cdn.bootcss.com/gitalk/1.5.0/gitalk.min.css">
<script src="//cdn.bootcss.com/gitalk/1.5.0/gitalk.min.js"></script>

在 html 文件中添加一個容器，Gitalk組件會在此處顯示

<div id="gitalk-container"></div>

而後使用下面的 JavaScript 代來生成 Gitalk 評論

var gitalk = new Gitalk({
  clientID: '7de8e380bec2231f0544', // GitHub Application Client ID
  clientSecret: 'xxxx', // GitHub Application Client Secret
  repo: 'PassJava-Learning'      // 存放評論的倉庫
  owner: 'Jackson0714',          // 倉庫的建立者，
  admin: ['Jackson0714'],        // 若是倉庫有多我的能夠操做，那麼在這裏以數組形式寫出
  id: location.pathname,      // 用於標記評論是哪一個頁面的，確保惟一，而且長度小於50
})

gitalk.render('gitalk-container');    // 渲染Gitalk評論組件

更多參數介紹詳見本文附錄。

5、改造 Gitalk 的腳本

Gitalk 官方提供的使用腳本對於我用 docsify 搭建的網站有些不足之處，因此我就動手本身改了。

5.1 問題一：URL 中文轉義問題

首先個人網站每一個頁面的標題都攜帶了中文，好比這個：

http://www.passjava.cn/#/94.Git/01.Git常見問題

若是評論這篇文章，就會在個人 PassJava-Learning 倉庫的 issues 中生成一個 url 編碼後的標題。

就像下面這樣，沒人看得懂吧，因此須要在 gitalk 的腳本中解碼 url 。

加一行解碼的代碼搞定：

decodeURI(title)

若是你須要到 Github 上更方便地維護留言記錄，就能夠應用上面的代碼了。

5.2 問題二：截取標題

由於 docsify 是用 # 符號來表示每篇文章的 url 的，我想把 # 符號後面的取出來。好比下面這個：

http://www.passjava.cn/#/02.PassJava架構篇/22.緩存實戰（二）Redis分佈式鎖

我只想要 02.PassJava架構篇/22.緩存實戰（二）Redis分佈式鎖 做爲標題。改造以下：

title = location.hash.match(/#(.*?)([?]|$)/)
if (title != null) {
  title = location.hash.match(/#(.*?)([?]|$)/)[1]
}
title = decodeURI(title.substring(1, title.length))

5.3 問題三：Gitalk id 只支持 50 個字符

id 和 title 我都是用的 URL 中 # 後的標題。有時候標題太長了，致使發起評論和加載評論。頁面會報 Github 的 api 問題。

因此我就把 id 和 title 限制在 50 個字符之內，若是超出了就用 home page做爲 id 和 title。

// 限制 50 個字符
if (title != null) {
    title = decodeURI(title.substring(1, title.length))
    if (title.length >= 50) {
        title = title.substring(title.length - 50, title.length)
    }
} else {
    title = 'home page'
}

通過上面的改造後，Gitlab 中 issue 的列表就是下面這樣了

你們能夠看到有兩個標籤，一個是 Gitalk，一個是 url 標題，Gitalk 就是經過這兩個標籤來獲取評論列表的，咱們能夠點一個 issue 進去看下：

由於 Gitalk 是基於 Gitlab 的 Issue 功能，因此咱們能夠直接在 issue 裏面加評論的，博客上會同步顯示這些評論哦。

注意：千萬別點 close issue 按鈕，關閉 issue 後，評論就都看不到了，並且即便你再 reopen issue，也不行。只能從新在博客評論，可是會在 Github 上自動新建一個 issue，不能和以前的評論關聯起來，有點坑呀。。

5.4 問題四：切換文章後，評論列表未變

因爲docsify的連接 URL 使用的是 hash 的方式，致使切換頁面的時候不會刷新頁面，致使整個網站的Gitalk評論使用的是一個評論，所以作了監聽 hash 事件，來刷新頁面，這樣就能每次切換頁面刷新，而後加載對應的評論。

window.onhashchange = function(event) {
    if(event.newURL.split('?')[0] !== event.oldURL .split('?')[0]) {
        location.reload()
    }
}

通過改造的代碼，在公衆號悟空聊架構回覆 博客獲取。

6、遇到的坑

在使用 Gitalk 也遇到了一些奇怪的問題，這裏作個記錄：

6.1 收到一堆提醒郵件

這個問題是個人好朋友 飛羽 提出的。

若是你在某篇文章中評論了，若是有其餘人跟帖，你也會收到 Gitlab 的郵件提醒哦，相似朋友圈功能。

若是你想取消掉，直接在你評論的 issue 裏面取消訂閱就能夠了。以下圖所示：

6.2 未找到相關的 issues 進行評論

用 F12 調試工具看了後，是由於本身寫的 JS 報錯了。

6.3 HTTP 請求 401 權限問題

這是由於我最開始建立的Github 應用是 Github App 而不是 OAuth App，這裏你們注意下。

6.4 每篇文章對應的評論都是同樣的

須要在切換文章時，從新給 location 變量賦值，詳見本文 5.4 的改進代碼。

6.5 HTTP 請求 422 問題

id 太長了，修復代碼詳見本文 5.3。

通過改造的代碼，在公衆號悟空聊架構回覆 博客獲取。

6.6 Github 訪問太慢了

7、附錄

7.1 Gitalk 主要的參數

clientID 類型：字符串，必填，申請的 OAuth App的 Client ID
clientSecret 類型：字符串，必填，申請的 OAuth App的 Client Secret
repo 類型：字符串，必填，github上的倉庫名字，用於存放Gitalk評論
owner 類型：字符串，必填，github倉庫的全部者的名字
admin 類型：數組(元素是字符串)，必填，github倉庫的全部者和合做者 (對這個 repository 有寫權限的用戶)
id 類型：字符串，選填，頁面的惟一標識。長度必須小於50。此參數用於評論和頁面對應的標識，若是想讓兩個頁面用一個評論，可設置兩個頁面的id同樣。默認值：location.href(頁面URL)
title 類型：字符串，選填，GitHub issue 的標題，默認值：document.title(HTML中title標籤中的值)

注意：

雖然id和title參數是否是必填的選項，可是這個兩個參數很重要建議填上：

一、id參數用於評論記錄和頁面對應的惟一標記，有的時候發現好幾個頁面評論是同樣的，就是因爲配置id參數的時候，這幾個頁面的id是同樣致使。因爲id參數默認值是location.href頁面URL，而有的時候URL中帶着頁面標題的連接，致使URL長度超過了50個字符長度，會致使建立評論issues失敗(長度超過50個會建立失敗)，這點要注意。

二、title用於在 Github 倉庫issues的標題，若是你想管理評論能夠設置一下這個參數，來區分該評論是來自於那個文章。

‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍7.2 Gitalk 其餘參數

number: 類型：數字，選填，頁面的 issue ID 標識，若未定義number屬性則會使用id進行定位。默認值：-1。

labels：類型：數組，選填，GitHub issue 的標籤，默認值：Gitalk

body：類型：字符串，選填， GitHub issue 的內容，默認值：URL + HTML中meta標籤中description的值。

language：類型：字符串，選填，設置語言，支持 [en, zh-CN, zh-TW]。默認值：navigator.language 或者 navigator.userLanguage。

perPage：類型：數字，選填，每次加載的數據大小，最多 100。默認值：10。

distractionFreeMode：類型：布爾值，選填，相似Facebook評論框的全屏遮罩效果。默認值：false。

pagerDirection：類型：字符串，選填，評論排序方式，last爲按評論建立時間倒敘，first爲按建立時間正序。默認值：last。

createIssueManually：類型：布爾值，選填，若是當前頁面沒有相應的 isssue 且登陸的用戶屬於 admin，則會自動建立 issue。若是設置爲 true，則顯示一個初始化頁面，建立 issue 須要點擊 init 按鈕。默認值：false。

proxy：類型：字符串，選填，GitHub oauth 請求到反向代理，爲了支持 CORS。默認值:https://cors-anywhere.herokuapp.com/https://github.com/login/oauth/access_token。

flipMoveOptions：類型：對象，選填，評論列表的動畫。參考 react-flip-move

enableHotKey：類型：布爾值，選填，啓用快捷鍵(cmd/ctrl + enter)提交評論。默認值：true。

參考資料：

https://segmentfault.com/a/1190000018072952

https://github.com/gitalk/gitalk

開源項目 PassJava 地址：https://github.com/Jackson0714/PassJava-Platform，歡迎 Star。

本文已收錄至：www.passjava.cn

- END -

本文分享自微信公衆號 - 悟空聊架構（PassJava666）。
若有侵權，請聯繫 support@oschina.cn 刪除。
本文參與「OSC源創計劃」，歡迎正在閱讀的你也加入，一塊兒分享。