
語言 🇹🇼 繁體中文
基本
外觀與風格
即時評論
分頁與排序
回覆框
SSO
匿名評論
其他
自訂與設定
背景
在此您將找到關於評論小工具支援的每項功能與設定的深入文件。
本文件將涵蓋核心概念,並深入探討各功能領域,包含操作說明與常見陷阱。
將提供程式碼範例並以重點標示相關行;在適用情況下也會提供設定頁面的截圖。
程式碼範例將使用我們的原生 JavaScript 函式庫;然而,設定選項在所有版本的評論小工具(React、Vue 等)中使用完全相同的名稱。
本指南中概述的大多數設定與功能都不需要撰寫任何程式碼。
識別您的帳戶 
您可能會注意到,可以使用租戶 ID 為 "demo" 的評論小工具,例如:
Run 
這僅供您試用評論小工具。在生產環境中,您會像下面這樣傳遞您的租戶 ID:
Run 
您的租戶 ID 已套用在評論小工具的 程式碼片段 中,您可以在那裡找到。
您也可以在 API 憑證頁面 找到您的租戶 ID 並管理您的 API 金鑰。
從此之後,如果您已登入 FastComments,程式碼範例將會使用您的實際租戶 ID(如果您是在 https://fastcomments.com 登入的話)。
評論如何與頁面和文章關聯 
在呈現留言串或發表留言時,FastComments 需要知道那些留言屬於哪個頁面、文章或產品。
為此,我們使用一個稱為 "URL ID" 的東西。它可以是像字串或數字之類的識別碼,或是一個 URL。
預設情況下,如果您沒有指定 urlId,它將成為頁面 URL。我們會取得當前頁面的 URL,並清理它以移除任何常見的行銷參數或追蹤識別碼。
在第三方整合的情況下,例如 WordPress,我們的外掛通常會使用代表當前正在檢視資訊的識別碼作為 URL ID,例如文章/頁面的 id。
Run 
本文檔中我們經常會參考的一項功能是 Widget Customization UI。
此介面可用於在不撰寫程式碼的情況下對留言元件進行多項變更。
在建立自訂規則時,我們通常希望它套用到網站上的所有頁面。然而,在某些情況下,我們只想在特定頁面上自訂留言元件,可能是套用自訂樣式,或是讓該頁面的留言匿名。舉例來說,您也可以讓某些頁面的即時留言立即顯示,而在其他頁面則將其隱藏在通知按鈕下。
這些都可以透過此頁面的 URL ID 輸入欄位實現,其外觀如下:
此欄位中的值應與傳入留言元件的 urlId 參數相符。如果您希望自訂規則與 urlId 無關,請將此欄位留空或輸入 *。
從 2023 年起,widget 自訂中的 URL ID 欄位現在也接受模式!例如,您可以使用 */blog/* 為您的部落格加入特定樣式,或使用 */store/* 為您的商店加入特定樣式,而兩者仍可共用相同的網域。
注意事項
- 如果您的頁面具有 hash 參數(例如 example.com#page-1)— 預設情況下,這會成為 URL ID 的一部分。
- 在進行遷移時,例如從 WordPress 遷移到 Gatsby,您可能需要在初始遷移後遷移 URL ID 的留言值。若需要協助,請與我們聯繫。
在不同頁面呈現相同評論 
由於 urlId 參數允許我們定義留言綁定到哪個頁面或 id,我們只需在那些頁面上將 urlId 設為相同的值即可。
Run 
自訂樣式 
FastComments 設計上允許自訂。為了安全,評論元件本身在 iframe 中執行,因此要套用自訂樣式必須採取下列兩種方法之一。
第一種,也是最簡單且我們推薦的方法,是使用 小工具自訂頁面。
在小工具自訂頁面,請查看「顯示進階選項」區段,在該區段下有一個標示為「Custom CSS」的區域:
這種方法有一些好處:
- 輸入的 CSS 在傳送給使用者之前會被壓縮,且在編輯介面中保持一致的格式。
- 您可以獲得小工具自訂介面的所有好處,例如可以為不同網站輕鬆地以不同方式自訂評論元件。
- 當我們對評論元件進行變更時,您的自訂樣式會作為我們發佈流程的一部分進行測試。
第二種方法是在小工具設定中指定 customCSS 參數,如下:
Run 
然而,這有一些限制:
- 由於標頭大小的限制,可以傳遞的自訂 CSS 大小有限,超過時我們的伺服器會拒絕該請求。
- 您必須在自己的基礎設施與建置系統中管理自訂 CSS。這也可能是優點而非缺點。
- 在此情況下,傳送自訂 CSS 會增加額外的網路負擔,因為必須先傳到我們的伺服器,然後再在 iframe 內容中傳回,總共 兩次。不過對於大多數載入量大小而言,這不會太明顯。
- 常見的優化是將 CSS 最小化(minify)以減少網路傳輸大小,但採用此方法時需由您自行處理。
- 當我們進行變更時,您的自訂 CSS 不會被我們測試。
External CSS Files
您可以透過使用 @import 指示小工具擷取外部檔案!
建議將 @import 放在自訂規則中。這樣一來,如果我們需要對評論元件進行變更,就可以使用自動化工具驗證您的設定。例如,您會在小工具自訂介面中建立一個自訂規則,點選 Advanced,並在 Custom CSS 中輸入:
@import url(https://example.com/styles.css);In Code - Not Recommended
您也可以透過 customCSS 屬性載入外部 CSS 檔案:
Run 
但請記住,如果您這樣做,我們將無法對您的 CSS 進行測試。
User Profile Modal Styling
使用者個人檔案快顯視窗也可以用自訂 CSS 進行樣式設定。然而,為了確保自訂樣式能套用到使用者個人檔案,所有 CSS 選擇器必須以 .user-profile 為前綴。若沒有此一前綴,自訂樣式將會在使用者個人檔案快顯視窗中被忽略。
例如:
Run 
Backwards Compatibility
在 FastComments,我們知道客戶會自訂評論元件。這是我們的設計意圖 — 我們最不希望的是讓我們的產品造成您產品中的設計不一致。
由於這是我們產品的重要部分,我們有一個建置管線,可以在每次發佈時針對每個客戶檢視評論元件的變更。
如果我們發現小問題,我們會更新您的帳戶以確保發佈順利進行;如果發現重大破壞性變更,這也讓我們能夠中止發佈。
自訂字型 
FastComments 設計上可供客製化,我們小工具使用的字型也不例外。
預設情況下,FastComments 使用 system font stack,以在各種裝置上呈現最佳外觀。
若要定義您自己的字型,請參閱 自訂 CSS 文件。
在該處您會找到定義自訂 CSS 的方法,從而讓您能指定所需的字型。
如何定義字型
要覆寫字型,我們建議使用 .fast-comments, textarea 選擇器來定義您的 CSS。範例如下:
Run 
移除品牌標示 
對於擁有 Pro 或 Enterprise 帳戶的客戶,允許進行白牌化。只要 與我們聯絡,我們很樂意協助。
如果您只想從評論小工具移除我們的標誌,這項功能會在 Flex 與 Pro 計畫上自動啟用。
這些計畫也為從我們平台發送的電子郵件提供相同的功能。
支援深色背景(深色模式) 
預設情況下,FastComments 的留言小工具會在大多數網站上自動偵測深色模式。
當偵測到深色模式時,FastComments 會將原本白底黑字的顯示切換為黑底白字。圖片也會相應變化。
在頁面載入時,小工具會嘗試判斷留言小工具背後頁面背景的明暗程度。這表示頁面可能是白色背景,但如果你將留言小工具放在一個黑色背景的容器內,仍應自動啟用深色模式以確保留言可讀。
然而,這個依賴判定「亮度」的偵測機制,有時可能不會在你想要的情況下啟用深色模式。若要強制啟用,請將 hasDarkBackground 標記設為 true,如下所示:
Run 
切換深色模式 
對於允許在初始頁面載入後切換深色模式的網站,這會比較複雜。
首先,所有現行版本的評論元件函式庫(React、Vue)在它們各自的程式庫中都有切換深色模式的範例。
對於 VanillaJS 元件,我們需要多做一些工作。首先,FastCommentsUI 會回傳一個含有 "destroy" 和 "update" 函式的物件。
我們可以在每次想要更新評論元件設定時簡單地呼叫 update 函式,如下所示。以下是一個使用 VanillaJS 元件切換 深色模式的完整可運作範例。
Run 
覆寫文字 
使用 FastComments,留言小工具中的所有文字皆可自訂。
您可以覆寫單一段文字,例如送出按鈕,或是覆寫整個留言小工具中的所有文字。
預設情況下,留言小工具中的文字會根據使用者的語系進行翻譯。不過,如果我們確定使用者族群使用相同的地區/語言,我們可以覆寫這些文字,例如:
Run 
所有可自訂的翻譯可以在 這裡 的「進階選項」分頁中找到。
不過,有更簡單的做法,可以透過小工具自訂化的使用者介面。在那裡,我們只要找到在 EN_US 區域設定中顯示於留言小工具的文字,然後指定一個替換字串即可。
目前所有翻譯覆蓋都會影響所有語系。
變更預設頭像 
當使用者第一次使用 FastComments 發表評論時,我們會嘗試從 http://gravatar.com/ 取得他們的頭像。
不過,如果我們找不到頭像,或使用者從未在帳戶中設定過頭像,我們會顯示一個靜態的預設頭像圖片。
若要指定自訂的靜態頭像圖片,可以使用 defaultAvatarSrc 設定。
Run 
這也可以不透過程式碼完成。在外掛自訂頁面中,請參閱「預設頭像」章節。
請注意,為特定使用者定義頭像(例如使用 SSO)有其自己的章節說明。
停用頭像 
即使使用者已設定自己的大頭貼,仍可完全從留言小工具中移除大頭貼。
Run 
這可以在小工具自訂頁面上,在不撰寫程式碼的情況下自訂:
停用所有預設樣式 
對於較大型的自訂樣式專案,可能會希望從頭開始,不使用任何預設樣式。
可以透過將 noStyles 參數設為 true 來移除所有預設樣式,如下:
Run 
也可以在 widget 自訂頁面的進階選項中,無需撰寫程式碼即可進行自訂:
從評論連結到頁面 
當傳送通知電子郵件,或在像審核頁面這類的使用者介面中呈現留言時,能夠從留言連結回其所在的頁面會很有幫助。
如果 URL ID 並不總是實際的識別碼,我們就必須在其他地方儲存 URL。這就是 "url" 屬性的用途,定義如下。
Run 
一個常見的使用情境是將留言串綁定到一個識別碼(例如文章),然後再連回特定頁面,例如:
Run 
URL 不會移除常見的行銷參數。預設情況下,會以當前頁面的 URL 作為與留言一起儲存的 URL。
預設收合回覆 
預設情況下,頂層留言的回覆會顯示。
可以設定成使用者需點選「顯示回覆」在頂層留言上才能查看子留言。
Run 
這可在小工具自訂頁面上無需撰寫程式碼地自訂:
此設定不會影響最初載入的頂層留言數量。如果您有一則頂層留言和 29 則子留言,啟用此設定後您會:
- 看見頂層留言。
- 在該留言下方看到「顯示回覆 (29)」。
如果您希望在使用此選項的同時顯示所有頂層留言,請將 起始頁面設為 -1。
啟用所見即所得編輯器 
預設情況下,FastComments 的格式化功能是透過在文字周圍加入像 <b></b> 這類可見的標籤來完成。點擊工具列
或使用快速鍵會為你執行這個動作。不過,有些社群可能希望選擇在沒有可見標籤的情況下使用格式化功能。這稱為啟用
WYSIWYG(所見即所得)編輯器。這個編輯器的外觀與預設編輯器完全相同,不同之處在於它會載入一些
額外的程式碼,讓使用者可以在不產生可見標籤的情況下將文字加粗、加底線等。
Run 
這也可以在不撰寫程式碼的情況下完成。在小工具自訂頁面,請查看「啟用進階格式化」選項。
停用工具列 
預設情況下,FastComments 會在撰寫評論時顯示工具列,提供用於裝飾文字及上傳 圖片的捷徑。
此工具列可在程式碼中或透過自訂化介面關閉。
Run 
也可以在不撰寫程式碼的情況下完成。在小工具自訂頁面中,請參閱「停用回覆工具列」選項。
停用封鎖功能 
預設情況下,FastComments 允許使用者封鎖其他使用者。封鎖某位使用者會導致其評論 被隱藏、阻止雙方之間的通知,等等。
有時可能希望停用此功能。可以如此操作:
Run 
也可以透過 Widget 自訂介面在不寫程式碼的情況下完成,並同時啟用適當的伺服器端驗證:
決定要呈現的頁面 
在擷取與呈現評論時,評論小工具需要知道要從哪一頁開始。預設情況下,它會從 第一頁開始,只呈現該頁。
如有需要,可將要呈現的確切頁面作為設定 startingPage 傳給評論小工具。
Run 
請注意,頁碼從零開始,因此上述範例會呈現第二頁。
切換評論串而不重新載入頁面 
我們已說明 urlId 是評論所綁定的頁面或文章識別碼。
再說一次,如果未定義,urlId 將預設為當前頁面的 URL。
那麼對於 SPA(單頁應用程式),當評論所綁定的頁面或內容在沒有重新載入整頁的情況下動態變更時該怎麼辦?
Angular、React、Vue 等
使用我們的函式庫(例如 Angular 與 React),只要更新傳入 widget 的 urlId 屬性,評論元件就會重新整理。你可以在 React 範例中看到這個行為,例如 這裡。
VanillaJS
如果你使用 VanillaJS 函式庫,情況會比較複雜,因為沒有像 Angular 或 React 這類的框架來處理資料綁定或狀態傳播。
當你實例化 VanillaJS widget 時,它會回傳一些函式,可藉由呼叫這些函式來更新元件。
下面是一個實用範例,示範如何更改頁面 hash 並更新評論元件:
Run 
絕對日期(停用人性化時間戳) 
預設會使用在地化的相對日期。例如,在一則最近留下的評論旁你可能會看到 "11 分鐘前"。
在某些情況下可能需要或希望使用絕對日期,此時將此參數設為 true。
Run 
這可以在不撰寫程式碼的情況下自訂,於小工具自訂頁面中的進階選項:
同時顯示絕對與相對日期 
預設會使用本地化的相對日期。例如,在最近留下的評論旁你可能會看到 "11 分鐘前"。
有時你可能需要或希望同時保留此相對日期格式,並在旁邊顯示完整日期,此時可將此參數設為 true。
Run 
這可以在不撰寫程式碼的情況下於小工具自訂頁面的「進階選項」中進行自定義。你必須先啟用「絕對日期」才能在使用者介面中看到此選項。
新增標頭文字 
一些文字,例如標題或訊息,可以呈現在留言數量下方但登入狀態文字上方。
我們稱之為「標頭」,預設為隱藏。
Run 
此項設定可在小工具自訂頁面中的「進階選項」下,無需撰寫程式碼即可自訂:
將連結顯示為純文字 
預設情況下,FastComments 會將連結渲染為如下形式: https://exmaple.com - 連結 URL 會變成可點擊的 HTML 錨點標籤。
有些網站可能想要停用此功能,例如為了阻止詐騙者。我們提供的方法是將 Comment HTML Rendering Option 設為 Links as Text。
此設定可在不撰寫程式碼的情況下自訂,於 Widget 自訂頁面上針對整個網域,或特定頁面:
用按鈕切換評論 
預設情況下,FastComments 會同時渲染評論輸入框和評論串。為了節省垂直空間, 它也會在未與小工具互動之前隱藏任何其他必填欄位。
然而,評論小工具可以隱藏在按鈕後面,例如:
按鈕會根據評論目前是否顯示而使用不同的翻譯文字。如果評論被隱藏,會使用 translations.SHOW_COMMENTS_BUTTON_TEXT。如果
評論已顯示,會使用 translations.HIDE_COMMENTS_BUTTON_TEXT。翻譯字串可以包含文字 [count],該文字將
被替換為當地化的計數。
Run 
這是用來取代 hideCommentsUnderCountTextFormat 設定。
計數會隨評論串即時更新。如果沒有評論則不會顯示該按鈕。
可透過建立自定義規則並啟用「點擊以顯示評論」來在不撰寫程式碼的情況下啟用此功能:
自訂評論數文字 
顯示在留言小工具頂端的留言計數可以自訂。
這可以替換為任何字串,值 [count] 會被替換為計數值,並會為使用者進行本地化。
Run 
無需撰寫程式碼,也可以在小工具自訂頁面上進行自訂:
停用圖片重新導向 
預設情況下,FastComments 允許使用者上傳圖片。當使用者點擊該圖片時,FastComments 預設會, 在新分頁中開啟並完整顯示該圖片。將此旗標設為 true 可停用此行為:
Run 
如果您不打算自行攔截圖片點擊事件(參見 onImageClicked),我們建議將此設定與一些樣式結合使用 以移除圖片可被點擊的外觀。
停用通知鈴 
預設情況下,FastComments 會在評論區的右上方顯示一個通知鈴。
這個鈴會變成紅色並顯示使用者的通知數量。有些通知範例包括:
- 使用者回覆了您。
- 使用者回覆了您曾留言的討論串。
- 使用者對您的評論按了讚。
- 使用者回覆了您已訂閱的頁面。
通知鈴也提供訂閱整個頁面的機制。
不過,我們可以完全停用通知鈴:
Run 
這也可以在不撰寫程式碼的情況下完成。在小工具自訂頁面,請參閱「停用通知鈴」區段。
停用個人檔案 
預設情況下,當您點擊使用者的頭像時,FastComments 會顯示該使用者的個人檔案。
不過,我們可以停用此功能:
Run 
也可以不透過程式碼來完成。在小工具自訂頁面,請參閱「停用個人檔案」區段。
停用成功訊息 
預設情況下,FastComments 會在發表評論後顯示成功訊息。可透過下列方式停用:
Run 
也可以不用撰寫程式碼,在小工具自訂頁面中進行:
變更 GIF 的內容分級 
預設情況下,FastComments 評論小工具會將 gif rating 設為 pg。
可用的選項有 g、pg、pg-13 與 r。
此設定可在程式碼中或透過 UI 設定。在程式碼中可以這樣做:
Run 
在 UI 中,您會在 Gif Picker Rating 下找到此設定,只要 Disable Image Uploads? 未被勾選。
變更投票樣式 
預設情況下,FastComments 會以向上和向下的箭頭顯示投票選項,讓使用者能對留言進行向上或向下投票。
不過,可以變更投票工具列的樣式。當前選項包括預設的向上/向下按鈕,或使用愛心(Heart)樣式的投票機制。
我們使用 voteStyle 標誌如下:
Run 
我們強烈建議您在不撰寫程式碼的情況下進行此設定,因為這同時啟用伺服器端驗證。在小工具自訂頁面,請參閱「投票樣式」區段。
也可以停用投票,請參閱上述樣式選項上方的 Disable Voting。
標示新評論 
FastComments 提供幾種方法來突顯新的留言。
首先,預設情況下,會觸發應用內通知的留言(回覆、同一討論串的回覆,或你訂閱的頁面
上的留言),會自動以使用者頭像略微發光的方式突顯。顏色可以透過 CSS
使用 is-unread 類別自訂。
過去 24 小時內發佈的留言會被套用 24hr 類別,可用於樣式設定。
最後,任何在使用者工作階段中即時出現的新留言會透過動畫突顯數秒鐘。這是透過
is-live CSS 類別實現的,也可以進行自訂。
頁面大小 
預設 FastComments 的頁面大小為 30。這包括串內的回覆。
頁面大小可以在 Widget Configuration UI 中自訂,範圍從 10 到 200 不等。
請注意,變更頁面大小需要重新計算您帳戶中的所有評論串。這可能需要幾分鐘。
這無法在客戶端的小工具設定,因為頁面是在伺服器端計算的。
範例設定如下所示:
頁面大小可以全域自訂、或針對網域、或針對頁面,自行建立不同的自訂規則。
這會影響您透過我們平台顯示評論的所有用戶端、整合和框架。
電子郵件範本 
FastComments 寄給您客戶的電子郵件可以自訂。範本、邏輯與翻譯都可以更改。文字可以針對每個語系自訂,樣式甚至可以針對每個網域更改。 在此了解有關自訂電子郵件範本的更多資訊。
使用者名稱格式 
預設情況下,FastComments 會顯示使用者輸入的名稱,或透過 SSO 傳給我們的名稱。
不過,可能希望以不同方式遮罩或顯示使用者名稱。例如,如果使用者的名字是 Allen Rex,您可能只想顯示 "Allen R."。
這可在 Widget 自訂 UI 中完成,無需撰寫程式碼,位於名為 Commenter Name Format 的設定下:
The available formats are:
- Capitalize (display example user as Example User)
- Last Initial (display Example User as Example U.)
- All Initials (display Example User as E. U.)
- Show "Anonymous"
變更後會立即生效。使用者自己仍會在評論區上方看到完整的使用者名稱,但他們的評論將顯示 已被修改過的使用者名稱。
使用者名稱在伺服器端會被遮罩以保護使用者。
停用圖片上傳 
預設情況下 FastComments 允許上傳圖片。可以透過將 noImageUploads 標誌設為 true 來停用此功能。
Run 
此設定可在小工具自訂頁面上無需撰寫程式碼即可自訂:
啟用搜尋框 
預設情況下,評論小工具中不會顯示搜尋框。
不過,我們可以將 enableSearch 旗標設為 true 來啟用它:
Run 
這也可以不用撰寫程式碼。在小工具自訂頁面中,請查看 "Enable Search Box" 選項。
啟用劇透(隱藏內容) 
我們可以透過將 enableSpoilers 標記設為 true 來啟用劇透支援:
Run 
也可以不透過程式碼來完成。在小工具自訂頁面中,請參閱「啟用劇透」選項。
當文字被選取後,點擊現已可見的 SPOILER 按鈕,文字會被遮罩,直到使用者將滑鼠移到其上方。對於深色模式我們採用相同的做法,使用不同的
顏色以更符合深色模式。
這也相容於 WYSIWYG 編輯器。
啟用評論檢視次數 
預設情況下,FastComments 不會追蹤誰查看了每則留言,也不會提供相關統計資料。
不過,我們可以啟用此功能,系統會在每次使用者捲動到留言時開始追蹤。
當發生這種情況時,每則留言旁邊的眼睛圖示旁的計數會增加。該計數會即時更新,並根據使用者的地區設定進行縮寫。
我們可以透過將 enableViewCounts 標誌設為 true 來啟用此功能:
Run 
這可以在小工具(widget)自訂頁面上免程式碼地進行自訂:
我們會追蹤查看留言的使用者 id*,因此如果您再次查看該留言,計數不會增加。如果您再次查看該留言 在兩年後,計數將會增加。
- *注意:或匿名 session id,或使用者的 IP(以雜湊值形式)。
立即顯示即時評論 
預設情況下,會即時顯示評論功能已啟用。這表示如果有任何評論被新增、刪除、編輯或釘選,變更會同時出現在所有正在檢視該評論串的使用者畫面上。
不過,預設情況下那些新評論會出現在一個動態顯示的按鈕之下,該按鈕上的文字類似 "顯示 2 則新評論"。
如果新評論是對該頁面的直接回覆,按鈕會顯示在評論串的頂部。如果它們是對某則特定評論的回覆,按鈕會顯示在該評論之下。
這樣做是為了避免頁面大小持續變動,避免使用者在嘗試抓取捲軸時產生挫折感。
但對於某些使用情境,例如即時競標或線上活動,這並不是理想的行為 - 你可能希望評論小工具更像一個「聊天」視窗,新的評論會「立即顯示」。
因此,啟用該功能的旗標名稱為:showLiveRightAway。
我們可以按如下方式開啟:
Run 
也可以在小工具自訂頁面上無需撰寫程式碼就進行自訂:
停用即時評論 
預設情況下,FastComments 會啟用即時評論。
這表示評論串的每位檢視者都應該看到相同的內容。
例如,如果新增一則評論,該評論應該會顯示。如果評論被編輯或刪除, 那麼那些評論也會在該串的所有檢視者端被編輯或刪除。投票以及所有的管理操作亦同。
不過,我們可以停用此功能:
Run 
這也可以在不使用程式碼的情況下完成。在 widget 自訂頁面,請參閱「Disable Live Commenting」一節。
新即時評論顯示在底部 
預設情況下,新即時評論會在發佈時即時顯示於評論列表的最上方。
啟用此選項後,新即時評論會改為加入列表底部。這會影響使用者在瀏覽評論串時,即時發佈的評論顯示方式。
Run 
啟用此設定後:
- 其他使用者發表的新即時評論會顯示在評論列表的底部
- 使用者會即時看到新評論出現在現有評論的下方
- 這只會影響即時評論更新 - 不會影響初始頁面載入時的排序
- 當使用者在追蹤討論時,這有助於維持閱讀流程
請注意,此設定僅影響新即時評論在即時到達時的放置位置。它不會影響頁面載入時的初始排序。
啟用無限滾動 
預設情況下,FastComments 小工具會自動在垂直方向調整大小以容納所有可見評論。分頁是透過在目前頁面末端的「檢視下一頁」 按鈕來實現,因為我們發現這種互動對大多數使用者來說是最舒服的。
然而,有些情況會偏好使用無限滾動。例如,我們在 Stream Chat 產品中使用此功能。
我們可以透過將 enableInfiniteScrolling 標誌設為 true 來隱藏「檢視下一頁」按鈕並改用無限滾動:
Run 
這還需要加入自定義 CSS。為 .comments 選擇器新增自定義 CSS 以啟用捲動,例如:
Run 
完整的可運作範例如下:
Run 
在上述範例中我們使用 customCSS 屬性,但建議改為使用 Widget Configuration UI 以提升效能。請參閱自定義 CSS 文件。 See the Custom CSS documentation.
變更預設排序方向 
預設情況下,FastComments 會以「Most Relevant」排序方向來排列留言。
「Most Relevant」排序會同時考量留言發表的時間與投票數來進行排序。
使用者可以在留言小工具的使用者介面中,將排序方向改為「Oldest」或「Newest First」。
不過,我們可以將預設值設定為三者中的任一個。例如,如果你想要預設顯示最舊的留言:
Run 
我們將 defaultSortDirection 的值設為 "OF" 以將排序方向設為 "OF"。
若要設定為「最新優先」排序方向,做法如下:
Run 
defaultSortDirection 的有效值為:
- MR: "Most Recent"
- NF: "Newest First"
- OF: "Oldest First"
這也可以在不使用程式碼的情況下完成。在小工具自訂頁面中,請參閱「Default Sort Direction」章節。
請注意,每個頁面在各種排序方向下的留言都是事先計算好的,因此所有排序方向的效能相同。
一次呈現所有評論 — 停用分頁 
若要停用分頁,並一次呈現所有評論,將 startingPage 設為 -1。
Run 
將回覆框移至評論後方 
預設情況下,留言輸入區位於留言串的 之前。然而,將此設定參數設為 true 時,我們可以將它移到 之後。
Run 
這可以在小工具自訂頁面上無需程式碼地自訂:
限制評論長度 
可輸入於評論輸入欄位的最大字元數可由 maxCommentCharacterLength 參數限制。
預設值為 2000。
像是圖片 URL 等不會包含在長度計算中。
Run 
這可以在無需撰寫程式碼的情況下,在小工具自訂頁面上進行:
停用多行評論 
預設情況下,FastComments 允許使用者輸入任意行數的評論,直到達到預設的字元上限。
然而,有時會希望限制使用者只能輸入單行文字。範例使用情境包括線上出價,或即時聊天,FastComments 可用於這些情境。
我們可如下啟用 useSingleLineCommentInput 標記:
Run 
這也可以在不使用程式碼的情況下完成。在 widget 自訂頁面中,請參閱「啟用單行評論輸入」章節。
請注意,每一頁上針對每種排序方向的評論都是預先計算的,因此所有排序方向在效能上是一樣的。
禁止新增頂層評論 
將 noNewRootComments 設為 true 會使小工具隱藏根回覆區域,但仍允許使用者回覆
子評論。舉例來說,您可以在頁面載入時有條件地設定此項,以僅允許部分使用者發表頂層評論。
Run 
最大回覆深度 
預設情況下,FastComments 允許無限制的回覆層級,會建立一個討論串結構,使用者可以無限地對回覆再進行回覆。
The maxReplyDepth option allows you to limit how deep reply threads can go. When the maximum depth is reached, users will no longer see a reply button on comments at that level.
Run 
當 maxReplyDepth 設為 2:
- 使用者可以在頂層發表評論(深度 0)
- 使用者可以回覆頂層評論(深度 1)
- 使用者可以回覆那些回覆(深度 2)
- 深度超過 2 不允許再有進一步回覆
Setting to 1 would only allow replies to top-level comments, creating a flatter discussion structure.
Setting maxReplyDepth to 0 would disable all replies, allowing only top-level comments. If not specified, replies can be nested without limit.
單一登入 (SSO) 概覽 
SSO,或稱單一登入,是一套慣例,用來讓您或您的使用者在不需建立另一組帳號的情況下使用 FastComments。
假設您不允許匿名留言,則需有帳號才能在 FastComments 留言。我們讓這個註冊流程非常簡單——使用者只要在留言時留下一個電子郵件地址即可。 不過,我們理解連這一點對某些網站來說也是額外摩擦。
我們可以透過為整個網站只使用一個登入流程來減少這種摩擦。
How do I get it?
所有帳號類型目前都可使用 SSO。不過,SSO 使用者的最大數量會依您購買的方案而有所不同。與其他功能一樣,Pro 計畫及以上方案提供直接的開發支援。
讓我們比較各個選項,然後深入說明每個選項的細節。
User and Comment Migrations
當從像 Disqus 這類具有 SSO 的平台遷移時,您原本就會有使用者及其留言。
留言會作為遷移的一部分被匯入,無論是透過 API、我們的匯入介面 (Import UI),或是客服支援。如果匯入介面支援您要遷移的來源平台,則建議使用匯入介面,因為它包含錯誤處理、頭像與媒體的擷取與上傳,以及批次工作監控系統。
使用者本身會在第一次檢視留言串時自動加入。或是,他們也可以透過 API 事先加入,但這樣做沒有太多優勢。
如果留言已被匯入,而 SSO 使用者並未透過 API 手動新增,則當使用者在第一次檢視任何留言串時,留言會自動被遷移到該使用者的帳戶。之後他們就能管理、編輯和刪除自己原本所發表的留言。
自動遷移是透過電子郵件或使用者名稱進行。有些平台在匯出時不提供電子郵件,例如 Disqus,因此在這種情況下我們會退而求其次使用使用者名稱。
- 只要您在 SSO payload 中傳遞相符的使用者名稱及電子郵件,我們就會將電子郵件加入到個別的留言物件中,以便通知和提及功能能正常運作。
如果您希望同時匯入留言和使用者,請與支援團隊合作,在透過 API 匯入使用者後,將留言遷移到對應的使用者帳戶。
總結來說,遷移的最簡單路徑是:
- 匯入留言。
- 如果在
Manage Data -> Imports使用匯入介面,頭像和其他媒體會自動被遷移。
- 如果在
- 設定 Secure 或 Simple SSO。
- 讓遷移在使用者首次登入時自動發生。
- 如果使用者的留言數少於 50k,這通常只會增加不到一秒的頁面載入時間。
WordPress Users
如果您使用我們的 WordPress 外掛,就不需要撰寫任何程式碼!只要前往外掛的管理頁面,點選 SSO 設定,然後啟用即可。
這會帶您進入一個單按鈕的精靈,該精靈會為您建立 API 金鑰、將金鑰傳送到您的 WordPress 安裝並啟用 SSO。我們已將這些步驟整合為單一按鈕點擊以簡化流程。
請注意,如果您是第一次安裝該外掛,必須完成設定流程,才能看到包含 SSO 設定按鈕的管理頁面。
WordPress SSO - Moderators
請注意,目前要在使用者透過 FastComments WordPress 外掛留言時,讓「Moderator」徽章顯示在您的版主旁邊, 他們也必須在 FastComments 儀表板中被新增為版主,並且其電子郵件需經過驗證。
Custom Integrations
對於自訂整合,有兩種選項。
Option One - Secure SSO
使用 Secure SSO 時,FastComments 可以確認正在留言、投票與閱讀留言的使用者確實是您網站上的真實使用者。
只要您建立一個有效的 payload,使用者就會獲得無縫的留言體驗。
在 Secure SSO 中,SSO payload 是在伺服器端使用 HMAC 驗證建立,然後傳遞到客戶端的小工具(widget)。
使用 Secure SSO 時,使用者帳戶與其他 FastComments 使用者群是完全分離的。這表示如果我們有兩個合作夥伴 Company A 與 Company B,兩者都可以擁有使用者名稱為 "Bob" 的 SSO 使用者。
Requirements
- 基本的後端開發知識。
- 基本的祕密 API 金鑰處理知識。
- 基本的 API 開發或伺服器端渲染知識。
Pros
- 安全。
- 無縫的留言體驗。
Cons
- 需要後端開發。
Updating User Data
使用 Secure SSO 時,每次您傳遞 sso user payload,我們都會使用最新的資訊來更新該使用者。例如,如果
使用者原本的使用者名稱是 X,而您在 SSO payload 中傳入 Y,則他們的使用者名稱會變更為 Y。
如果您想用此方法移除某些值,請將它們設定為 null(不是 undefined)。
Secure SSO API
我們也提供與 SSO 使用者互動的 API。請參閱 the docs。
請注意,使用 Secure SSO 時,使用者會在頁面載入時自動在背景建立。您不需要批次匯入使用者。
Option Two - Simple SSO
Simple SSO 的替代方案是直接把使用者資訊傳給留言小工具。
使用 Simple SSO 時並不需要提供電子郵件,但若沒有電子郵件,他們的留言將顯示為「未驗證」。
注意! 截至 2022 年初,使用 Simple SSO 的使用者名稱不需要在整個 FastComments.com 上保持唯一。
理想上,只有在您開發的平台無法提供後端存取時,才應選用 Simple SSO。
Requirements
- 基本的前端(client-side)開發知識。
- 至少需要知道使用者的電子郵件。
Pros
- 簡單。
- 所有活動仍會被驗證。
- 使用者不需輸入他們的使用者名稱或電子郵件。
Cons
- 比 Secure SSO 安全性較低,因為客戶端的 payload 可能被構造為任意使用者。
Simple SSO API
透過 Simple SSO 流程自動建立的使用者會以 SSOUser 物件儲存。它們可以透過 SSOUser API 存取與管理。請參閱 the docs。
自訂整合 - 安全單一登入 (SSO) 
FastComments Secure SSO 使用 HMAC-SHA256 加密作為實作 SSO 的機制。首先我們會介紹整體架構、提供範例,以及詳細步驟。
也有一些關於從具有類似 SSO 機制的其他供應商遷移的文件,以及差異說明。
流程如下所示:
由於 Secure SSO 涉及全端開發,目前 Java/Spring、NodeJS/Express 與純 PHP 的完整工作範例都在 GitHub 上。
雖然我們在 NodeJS 範例中使用 ExpressJS,Java 範例中使用 Spring,但在這些執行環境中實作 FastComments SSO 並不需要任何框架/函式庫 — 原生的加密套件即可運作。
使用 FastComments SSO 時不需要撰寫任何新的 API 端點。只要使用您的密鑰加密使用者資訊並將 payload 傳給評論元件即可。
取得您的 API 秘密金鑰
您的 API Secret 可從 此頁面 取得。您也可以在「My Account」中點選 API/SSO 方塊,然後點選「Get API Secret Key」來找到此頁面。
評論元件參數
評論元件的高階 API 文件可在 這裡 找到。
以下更詳細說明這些參數的含義。
評論元件接收一個設定物件 — 如果您已使用 FastComments 傳遞您的客戶 ID(稱為 tenantId),您會已經在傳遞這個物件。
要啟用 SSO,傳入一個新的 "sso" 物件,該物件必須具有以下參數。這些值應在伺服器端產生。
- userDataJSONBase64: 使用者的資料(JSON 格式),接著以 Base64 編碼。
- verificationHash: 由 UNIX_TIME_MILLIS + userDataJSONBase64 製作的 HMAC-SHA256 雜湊。
- timestamp: 時間戳記,單位為 毫秒。不得為未來時間,且不得早於超過兩天前。
- loginURL: 評論元件可顯示用來讓使用者登入的 URL。
- logoutURL: 評論元件可顯示用來讓使用者登出的 URL。
- loginCallback: 若提供此函式而非 login URL,評論元件在點擊登入按鈕時會呼叫此函式。
- logoutCallback: 若提供此函式而非 logout URL,評論元件在點擊登出按鈕時會呼叫此函式。

使用者物件
The User object contains the following schema:

Moderators and Administrators
For admins and moderators, pass the respective isAdmin or isModerator flags in the SSOUser object.
Notifications
To enable or disable notifications, set the value of optedInNotifications to true or false respectively. The first time the user loads the page with this value in the SSO payload, their notification settings will be updated.
Additionally, if you want users to receive notification emails for activity on pages they subscribed to (as opposed to just in-app notifications), then set optedInSubscriptionNotifications to true.
VIP Users & Special Labels
You can display a special label next to the user's name by using the optional "displayLabel" field.
Unauthenticated users
To represent an unauthenticated user, simply do not populate userDataJSONBase64, verificationHash, or timestamp. Provide a loginURL.
These users will not be able to comment, and instead will be presented with a login message (message, link, or button, depending on configuration).
Direct Examples for Serializing and Hashing User Data
More details as an examples here (js), here (java) and here (php).
We understand that any integration can be a complicated and painful process. Don't hesitate to reach out to your representative or use the support page.
自訂整合 - 簡易單一登入 (SSO) 
With Simple SSO, we can provide the commenting widget with information about the user so that they don't have to enter their username or email to comment.
We can configure Simple SSO as follows:
Run 
The user will be logged in, and will create an SSO User behind the scenes. The user will have createdFromSimpleSSO set to true if fetched from the API.
Notes:
- Email is the unique identifier for Simple SSO.
- Providing an email with Simple SSO is not required, however by default their comments will show as "Unverified". If no email is provided, the user cannot be fully authenticated.
- NEW Since Jan 2022: Usernames do not have to be unique across all of fastcomments.com
- Simple SSO can automatically create and update SSO users, if an email is provided, and the user was not originally created from Secure SSO.
- You can specify badges for the user with the
badgeConfigproperty. ThebadgeIdsarray contains the IDs of badges to associate with the user. Ifoverrideis set totrue, it will replace all existing badges displayed on comments; iffalseit will add to existing badges.
自訂整合 - 從 Disqus SSO 遷移 
Disqus 與 FastComments Secure SSO 之間最大的差異是 Disqus 使用 SHA1 進行加密,而我們使用 SHA256。
這表示從 Disqus 遷移很容易 - 將使用的雜湊演算法從 SHA1 改為 SHA256,並更新傳遞給 UI 的屬性名稱。
自訂整合 - 從 Commento SSO 遷移 
Commento 使用截然不同的 SSO 方式 - 他們要求你有一個端點,他們會呼叫該端點來驗證使用者。FastComments 則相反 - 只需使用你的密鑰對使用者的資訊進行編碼並雜湊,然後傳遞即可。
使用單一登入保護評論串 
FastComments SSO (詳細資訊) 為您的使用者提供一種在不必登入其他平台的情況下發表評論的方式。
然而,僅此並不會保護您的評論串,因為預設情況下評論資料為公開資訊 - 任何能查看該頁面的人都可以看到評論。
無需程式碼設定
當設定 SSO 後,我們可以透過建立一個 自訂規則 來防止檢視及互動評論串。
執行此操作時,搜尋 SSO,您會找到此選項:
啟用它並儲存該自訂規則。
只保護特定的網域或頁面
若只想保護特定的網域或頁面,我們只需在自訂規則中進行設定即可。
在自訂介面的上方,我們會看到兩個輸入欄位:Domain 和 URL ID。
若僅保護某個網域,請在 "domain" 欄位輸入該網域。
若要保護特定頁面,請在 "URL ID" 欄位輸入頁面 URL。如果您與 FastComments 有自訂整合,您也可以在此輸入某種類型的 ID,而非 URL。
安全等級
當要求 SSO 時,您需要決定使用 Simple SSO 還是 Secure SSO。若要求 Simple SSO,兩者都允許;但若要求 Secure SSO,則必須使用以您的 API key 進行雜湊的 Secure SSO 載荷來擷取內容,才能檢視。
當您選擇 "Require SSO To View Comments" 時,會出現安全等級選項。
超出閱讀的保護
啟用此選項會保護該頁面或網域,禁止未透過 SSO 登入的使用者發表評論。
注意事項
在您啟用 SSO 整合之前建立評論的任何使用者,將無法看到那些評論,除非他們透過您的 SSO 整合登入。
停用電子郵件輸入欄位 
當使用者發表留言且尚未登入時,系統會要求他們提供電子郵件。
這會為該使用者建立一個「未驗證的工作階段」,並透過電子郵件要求他們驗證該工作階段。
對於某些網站或應用程式,當使用者評論或投票時不要求提供電子郵件可能比較合適。
啟用匿名留言會使電子郵件輸入欄位變為選填。然而,我們也可以將其完全停用。請先啟用 anonymous commenting,然後停用電子郵件輸入欄位的選項便會出現。
啟用此設定後,電子郵件欄位將在我們所有的留言產品中完全不顯示。
請注意,使用此設定時,所有留言都會是未驗證狀態,除非使用者創建帳號並登入 https://fastcomments.com。
您可能想考慮停用「未驗證」標籤。
停用未驗證標籤 
預設情況下,FastComments 會在留給使用未經驗證瀏覽器工作階段的使用者的評論上顯示「未驗證評論」標籤。關於未驗證評論的更多資訊請見 here。
Run 
此外,這項功能也可以在自訂化 UI 中使用,而無需撰寫程式碼:
回呼 (Callbacks) 
所有評論元件的函式庫(目前支援 Angular、React、Vue)都支援回呼。
回呼在設定物件中指定,各函式庫使用相同的簽章。
支援的回呼有:
- onInit
- onAuthenticationChange
- onRender
- commentCountUpdated
- onReplySuccess
- onVoteSuccess
- onImageClicked
- onOpenProfile
- onCommentSubmitStart
- onCommentsRendered
確切的簽章可以在 TypeScript definitions 找到。
以下為使用所有回呼的範例:
Run 
手動定義使用者的地區語言設定 
預設情況下,FastComments 會以使用者系統與瀏覽器所決定的語系來呈現評論元件。
當使用者留言或登入時,我們會更新他們上次使用的語系,並用該語系來發送電子郵件。
這會影響評論元件對使用者的翻譯顯示。語系由使用者的語言與地區組成,因此設定語系將 通常改變顯示給使用者的語言。
Via The UI
可以使用元件自訂介面來定義。請參閱「語系 / 語言」選項:
Via Code
可以以想要的語系來覆寫。
Run 
支援的語言與語系代碼
SSO 注意事項
如果您正在使用 SSO,您可能會想在 user 物件中傳遞使用者的語系,這樣電子郵件與其他內容才能為他們正確地在地化。
頁面標題 
目前的頁面標題會與指定的 urlId 關聯,並儲存以供審核工具使用。
預設情況下,此值會從 document.title 擷取。
如有需要,可指定自訂的頁面標題,如下所示:
Run 
禁止新增回覆並停用投票 
可以透過將 readonly 標誌設為 true 來鎖定評論,使無法留下新的評論或投票。
評論也將無法被編輯或刪除。
Run 
這可以在 widget 自訂頁面上,為整個網域或頁面進行自訂,無需撰寫程式碼:
更新!
自 2022 年 11 月起,管理員和版主可以透過回覆區上方的三點選單即時鎖定或解鎖討論串。
這將阻止新的評論,但仍允許投票,且允許使用者刪除自己的評論(如欲),而 readonly 則不允許這些功能。
這對應到 Page API 中的 isClosed 欄位。
評論數量與計算所有巢狀回覆 
評論小工具頂部顯示的評論數可以只顯示所有「頂層」評論,也就是那些回覆 是直接回覆頁面或文章本身的,或者它可以是 all 巢狀評論的計數。
預設情況下,這個設定為 true - 它是後者的計數 - 全部評論。在舊版本的評論小工具中,
預設值為 false。
我們可以更改此行為,透過將 countAll 標記設為 true,讓它計算 所有 巢狀評論。
Run 
如果我們希望計數只反映頂層評論,則將標記設為 false。
Run 
目前無法在不更改程式碼的情況下自訂此行為。
啟用評論者連結 
預設情況下,FastComments 只會要求使用者輸入評論、使用者名稱和電子郵件。
不過在某些情況下,你可能想讓使用者留下指向他們自己的部落格或網站的連結。
我們可以透過將 enableCommenterLinks 標記設為 true 來啟用顯示額外的輸入欄位,讓使用者留下網站 URL:
Run 
當提供該 URL 時,使用者的帳戶會被更新,過去與未來的所有評論中的使用者名稱都會連結到這個 URL。
也可以在小工具(widget)自訂頁面上,在不寫程式碼的情況下進行設定:
審核群組 
從 審核群組 頁面產生的 id 列表。
若有指定,使用該設定留下的評論將包含相同的 moderationGroupIds 集合。
如果一位 Moderator 定義了一個或多個 審核群組,他們將會
只在 Moderate Comments 頁面中看到與其群組相關聯的評論。
Run 
提及群組 ID 
一個用於 @mentions 自動完成的 ID 列表。當你想要防止在沒有交集群組的使用者被標註時,這會很有用。
指定時,輸入 @ 字元後,自動完成只會提供其他群組的使用者。
Run 
繞過第三方 Cookie 
對於身份驗證,FastComments 依賴瀏覽器啟用第三方 Cookie。若未啟用,使用者將始終需要 留下電子郵件才能評論(除非電子郵件輸入欄位被隱藏),且他們的評論預設會顯示為未驗證。
為了解決此問題,您可以啟用第三方 Cookie 繞過功能。
啟用此設定時,會出現一個小彈出視窗,顯示使用者正在登入的訊息。這個彈出視窗 會在使用者與評論小工具互動時顯示;例如,當他們發表評論時。
我們可以在程式碼中透過將 enableThirdPartyCookieBypass flag 設為 true 來達成此目的:
Run 
我們也可以在小工具自訂 UI(Widget Customization UI)中設定,路徑為 Enable Third-Party Cookie Popup:
在頂部欄顯示徽章 
預設情況下,FastComments 只會在留言串中的使用者留言旁顯示使用者徽章。
不過,我們可以在 widget 自訂頁面啟用此功能,將使用者徽章顯示在留言表單上方名字旁:
這會在頂部工具列區域於使用者名字旁顯示其徽章,讓他們在撰寫留言時的成就與身分更為顯眼。
請注意,必須在小工具自訂介面中啟用此功能才能生效。即使在伺服器層級已開啟,你也可以在程式碼設定中將 showBadgesInTopBar 標記設為 false,以選擇性地停用它:
Run 