影像聊天
FastComments Image Chat 讓影像上的互動討論成為可能，使用者可以在影像上的任意位置點擊以建立討論點。使用者可以點選影像的特定部分以針對那些區域開始對話，建立顯示討論位置的視覺標記。
此功能非常適合設計回饋、產品評論、帶有示意圖的教學材料、附有評論的相片庫，以及任何需要將情境式討論錨定於特定影像位置的場合。
入門指南 
使用情境
Image Chat 非常適合用於設計回饋，團隊需要就 mockup 或截圖中的特定元素進行討論。產品評論網站可以讓客戶就產品照片中可見的特定功能進行討論。教育平台可以用它來討論圖表、地圖或科學圖片。相片畫廊可以透過針對特定位置的評論變得互動化。房地產網站可以讓觀眾針對房屋照片中可見的特定特色進行討論。
快速開始
開始使用 Image Chat 很簡單。你需要 FastComments Image Chat 腳本、一個包含圖片的 image 元素或容器，還有一個包含你的 Tenant ID 的設定物件。
安裝
將 Image Chat 腳本新增到你的頁面：
基本實作
以下是一個最小範例：
Run 
如果尚未替換，請將 'demo' 替換為你的實際 FastComments Tenant ID，你可以在你的 FastComments dashboard 找到它。
運作方式
初始化後，使用者可以在圖片的任意位置點擊。當發生點擊時，該位置會顯示一個視覺上的方形標記並開啟聊天視窗。其他使用者可以看到所有標記並點擊它們以檢視或參與那些討論。所有討論會在所有訪客之間即時同步。
此 widget 使用百分比定位，因此即使圖片大小改變或在不同螢幕尺寸上檢視，標記仍會保持在正確位置。
線上示範
你可以在我們的 線上示範頁面 見到 Image Chat 的實際運作。
下一步
在基本功能運作後，你可以在 設定選項 指南 中自訂外觀和行為。查看 響應式設計 指南 以了解百分比定位的運作方式。於 自訂 指南 中了解樣式與深色模式支援。欲進行進階整合，請參閱 API 參考。
前端函式庫
所有 FastComments 的前端函式庫（react、vue、angular 等）都包含 Image Chat。
範例
基本範例
使用 Image Chat 最簡單的方法是針對單一圖片元素。此範例示範如何在圖片上啟用互動討論：
Run 使用容器元素的範例
你也可以傳入一個內含圖片的容器元素：
Run 使用自訂 URL ID 的範例
預設情況下，Image Chat 使用頁面 URL 結合圖片來源與座標來識別對話。你可以提供自訂的 urlId：
Run 如果你的 URL 結構改變但想保留相同的對話，或想在多個頁面間共用相同的討論點，這會很有用。
使用深色模式的範例
如果你的網站具有深色背景，而元件未像應該的自動偵測到，我們可以手動啟用深色模式支援：
Run 自訂聊天方塊大小的範例
你可以調整顯示在圖片上的可點擊方塊的大小。大小以圖片寬度的百分比來指定：
Run 使用評論數量回調的範例
使用 commentCountUpdated 回調來追蹤評論新增或更新的情況：
多張圖片範例
你可以在多張圖片上初始化 Image Chat。每張圖片都會有獨立的討論點：
Run 設定選項
概覽
FastComments Image Chat 擴展了標準的 FastComments 留言小工具，因此它繼承了基礎小工具的所有配置選項，同時新增了幾個專屬於圖片標註的選項。
必要配置
tenantId
必須提供您的 FastComments Tenant ID。您可以在 FastComments 儀表板 中找到它。
FastCommentsImageChat(imageElement, {
tenantId: 'demo'
});Image Chat 專屬選項
urlId
預設情況下，Image Chat 會根據頁面 URL、圖片來源以及 X/Y 座標，為每個對話產生一個唯一識別碼。您可以使用自訂的 urlId 來覆蓋此行為。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
urlId: 'my-custom-image-id'
});當您的 URL 結構可能會變動但您希望保留相同的對話時，或者當您想在多個頁面之間共享標註時，這會很有用。
chatSquarePercentage
以圖片寬度的百分比控制可點擊聊天標記的大小。預設值為 5%，表示每個標記佔圖片寬度的 5%。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
chatSquarePercentage: 8 // 更大、更醒目的標記
});較小的值會產生較不干擾的標記，更適合細節豐富的圖片。較大的值則讓標記在內容繁雜的圖片上或對行動裝置使用者來說更容易看到和點擊。
hasDarkBackground
當您的頁面具有深色背景時，啟用深色模式樣式。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
hasDarkBackground: true
});commentCountUpdated
每當留言數變更時觸發的回呼函式。這對於更新徽章或頁面標題等 UI 元素很有用。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
commentCountUpdated: function(count) {
console.log('Total comments:', count);
document.getElementById('badge').textContent = count;
}
});繼承的配置選項
由於 Image Chat 擴展了標準留言小工具，您可以使用基礎 FastComments 小工具的任何配置選項。以下是一些常用的選項：
locale
設定小工具 UI 的語言。FastComments 支援數十種語言。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
locale: 'es' // 西班牙語
});readonly
將所有對話設為唯讀。使用者可以檢視現有的標記與討論，但無法建立新的標記或回覆。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
readonly: true
});sso 和 simpleSSO
使用單一登入（Single Sign-On）與您的驗證系統整合。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
sso: {
// SSO 配置
}
});有關驗證選項的完整詳細資訊，請參閱 SSO 文件。
maxReplyDepth
控制回覆可以嵌套多少層。預設情況下，Image Chat 將此值設為 0，表示所有留言都是扁平的（沒有嵌套回覆）。如果您想要有討論串式的對話，可以更改此值。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
maxReplyDepth: 3 // 允許 3 層嵌套
});內部配置
這些選項由 Image Chat 自動設定，不應被覆蓋：
productId 會自動設為 2 以供 Image Chat 使用。floating-chat 擴充功能會自動載入以提供聊天視窗功能。小工具會自動偵測行動裝置（寬度低於 768px 的螢幕），並相應地以全螢幕聊天視窗調整 UI。
目標元素的彈性
FastCommentsImageChat 的第一個參數可以直接是 <img> 元素，或是內含圖片的容器元素：
// 直接傳入圖片元素
FastCommentsImageChat(document.getElementById('my-image'), config);
// 傳入內含圖片的容器
FastCommentsImageChat(document.querySelector('.image-wrapper'), config);如果您傳入的是容器元素，小工具會自動找到其中的圖片。
完整範例
以下是一個同時展示多個配置選項的範例：
FastCommentsImageChat(document.getElementById('product-image'), {
tenantId: 'demo',
urlId: 'product-v2-main',
chatSquarePercentage: 6,
hasDarkBackground: false,
locale: 'en',
commentCountUpdated: function(count) {
document.title = count > 0 ? `(${count}) Product Photo` : 'Product Photo';
},
sso: {
// 您的 SSO 配置
},
maxReplyDepth: 1
});有關從基礎小工具繼承的所有可用配置選項的完整清單，請參閱 FastComments 主要配置文件。
響應式設計
百分比定位
圖片聊天室使用基於百分比的座標，而不是像素座標，來在影像上定位聊天標記。當使用者點擊影像時，元件會將點擊的像素座標轉換為相對於影像寬度和高度的百分比。這種做法可確保標記無論圖像如何顯示都會保持在正確的位置。
例如，如果使用者在一張寬度為 1000px 的影像上從左邊緣向右點擊 250 像素，元件會將這個位置儲存為從左邊緣算起的 25%。當另一位使用者在行動裝置上以 500px 寬度查看相同影像時，標記會出現在從左邊緣 125 像素處，這仍然是寬度的 25%。
對響應式佈局的好處
這個百分比系統讓圖片聊天室能在所有裝置尺寸與方向上無縫運作。你的圖像可能會根據螢幕寬度、CSS 規則或容器限制而以不同大小顯示，但標記總是會與預期位置對齊。
使用大型螢幕的桌面電腦使用者會看到與使用小螢幕智慧型手機的使用者相同相對位置的標記。標記會隨著影像本身等比例縮放。
影像縮放與長寬比
只要你的影像在縮放時維持其長寬比（這是瀏覽器的預設行為），基於百分比的標記就會保持完美對齊。元件假設影像是等比例縮放，並基於此假設來計算位置。
如果你套用會扭曲影像長寬比的 CSS（例如使用 object-fit: cover 並搭配特定尺寸），標記位置可能無法正確對齊。為獲得最佳結果，讓影像自然縮放或使用 object-fit: contain 以維持長寬比。
聊天方塊大小
聊天標記的視覺大小也是基於百分比的。chatSquarePercentage 配置選項預設為 5%，表示每個方塊為影像寬度的 5%。這確保了不同影像尺寸間一致的視覺權重。
在寬度為 1000px 的影像上使用預設 5% 設定時，標記為 50px 的方形。在寬度為 500px 的影像上，相同的標記為 25px 的方形。它們會與影像尺寸保持比例。
行動裝置行為
在寬度小於 768px 的螢幕上，圖片聊天室會切換到行動優化的佈局。聊天視窗會以全螢幕方式開啟，而不是浮動在標記旁邊。這在小螢幕上提供更好的可用性，避免浮動視窗遮擋過多影像。
標記本身仍會在其百分比位置上可見且可點擊。使用者仍可看到所有討論的位置，並點選標記以開啟全螢幕聊天介面。
動態圖片載入
即使影像是非同步載入或在頁面載入後改變大小，基於百分比的系統仍會正常運作。元件會監控影像元素，並在影像尺寸改變時重新計算標記位置。
如果你使用延遲載入影像或在不同斷點實作具有不同尺寸的響應式影像，當影像尺寸改變時標記會自動調整。
跨裝置一致性
因為座標以百分比形式儲存在資料庫中，在桌面電腦建立的討論在平板或手機上查看時會出現在完全相同的相對位置。使用者可以跨裝置協作，而不會產生定位不一致的問題。
這個行為是雙向的。在行動裝置上點選特定位置建立的討論，在大型桌面顯示器上查看時會出現在相同的相對位置。
視口考量
元件計算百分比是相對於影像元素本身，而非視口。這表示捲動頁面或改變瀏覽器視窗大小不會影響標記位置。標記會固定在影像上的位置，不受視口變動影響。
未來相容性
基於百分比的方法讓你的影像討論能抵抗佈局、設計或裝置生態系的變化。隨著新螢幕尺寸與裝置的出現，既有的討論會持續正確顯示，而不需要任何更新或遷移。
自訂
深色模式支援
Image Chat 內建深色模式支援。當您在設定中設定 hasDarkBackground: true 時,聊天視窗和 UI 元素會自動調整以適應深色背景。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
hasDarkBackground: true
});深色模式樣式適用於聊天視窗、標記方塊以及所有互動元素。如果您的網站有深色模式切換功能,您可以在模式變更時重新初始化小工具,或使用下方描述的 body class 方法。
動態深色模式
如果您的網站深色模式是透過在 body 元素上加入 .dark class 來控制,Image Chat UI 會自動遵循此設定,無需重新初始化。小工具的樣式設計為會回應此 class 的存在。
/* 您的深色模式 CSS */
body.dark {
background: #1a1a1a;
color: #ffffff;
}使用 CSS 自訂樣式
您可以使用 CSS 自訂標記、聊天視窗和其他元素的外觀。小工具會加入特定的 class,您可以在樣式表中針對這些 class 進行設定。
聊天方塊和視窗使用 FastComments 的留言氣泡樣式系統,因此您對標準留言小工具所做的任何自訂也會影響 Image Chat。
聊天方塊尺寸
chatSquarePercentage 選項控制可點擊標記的大小。預設值為圖片寬度的 5%:
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
chatSquarePercentage: 7 // 更大、更明顯的方塊
});較小的數值會產生更融入圖片的細緻標記。較大的數值會讓標記更醒目且更容易點擊,尤其是在行動裝置上或為了無障礙用途。
行動裝置行為
在寬度低於 768px 的螢幕上,Image Chat 會自動切換為針對行動裝置最佳化的版面配置。聊天視窗會以全螢幕顯示,而不是浮動在標記旁邊,在小螢幕上提供更好的使用體驗。
標記會保持在圖片上其響應式位置並維持可見。使用者可以點擊任何標記來開啟全螢幕聊天介面。此行為是內建的,不需要任何設定。
聊天視窗外觀
聊天視窗在桌面上寬度為 300px,並帶有指向標記的 16px 箭頭。視窗會根據可用的視窗空間自動定位,使用 to-right、to-left、to-top 和 to-bottom 等定位 class。
您可以加入自訂 CSS 來調整這些視窗的顏色、字型、間距或其他視覺屬性。聊天視窗使用與標準 FastComments 小工具相同的元件結構,因此會繼承您已套用的任何全域自訂設定。
延遲初始化
聊天視窗會在桌面使用者滑鼠懸停時初始化,或在建立時立即初始化。這透過僅在使用者實際與標記互動時才渲染聊天介面,來減少初始載入的負擔。
延遲初始化是透明進行的。使用者不會察覺任何延遲,但如果圖片上有許多標記,瀏覽器就不需要渲染數十個隱藏的聊天視窗。
本地化
Image Chat 支援與標準 FastComments 小工具相同的所有本地化選項。設定 locale 選項即可顯示不同語言的 UI 文字:
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
locale: 'fr' // 法文
});FastComments 支援數十種語言。locale 設定會影響所有 UI 文字,包括提示訊息、按鈕和佔位文字。
繼承的自訂選項
由於 Image Chat 擴充了標準留言小工具,因此它繼承了基礎小工具的所有自訂選項。這包括自訂 CSS class、自訂翻譯、頭像自訂、日期格式設定等等。
請參閱 FastComments 主要自訂文件,以取得可用自訂選項的完整清單。
使用自訂字型
如果您的網站使用自訂字型,Image Chat UI 會從您頁面的 CSS 繼承這些字型。聊天視窗在您頁面的 DOM 內渲染,並遵循您現有的字型排版設定。
為獲得最佳效果,請確保在初始化 Image Chat 之前已載入您的自訂字型,或接受在字型載入期間可能會出現短暫的無樣式文字閃爍。
標記視覺設計
方形標記具有細緻的視覺設計,使其引人注意而不會干擾圖片。如果您想要不同的視覺效果,可以使用 CSS 自訂其外觀。
標記包含懸停狀態,當使用者將滑鼠移到其上時會提供回饋。在觸控裝置上,點擊互動會透過開啟聊天視窗提供即時回饋。
即時同步
即時更新
Image Chat 使用 WebSocket 連線來即時同步所有已連線使用者之間的對話。當有人建立新的標記、加入留言或刪除討論時，所有正在檢視相同圖片的其他使用者會立即看到更新而不需重新整理。
WebSocket 同步如何運作
當您初始化 Image Chat 時，這個小工具會與 FastComments 伺服器建立一個 WebSocket 連線。此連線在使用者的會話期間保持開啟，並監聽與當前圖片相關的更新。
WebSocket 系統為 Image Chat 使用三種類型的廣播訊息。new-image-chat 事件在有人於圖片上建立新標記時觸發。image-chat-updated 事件在有人更新既有對話時觸發。deleted-image-chat 事件在有人刪除標記時觸發。
廣播 ID 系統
為防止回音效應（使用者看到自己執行的動作又被廣播回來），每次更新都包含唯一的 broadcastId。當使用者建立或更新標記時，他們的用戶端會為該操作產生一個 UUID。當 WebSocket 將更新廣播回所有用戶端時，原始用戶端會忽略該更新，因為它與自己的 broadcastId 相符。
這確保了順暢的互動體驗：使用者能立即在 UI 中看到他們的變更，而不必等伺服器往返的回應，同時也確保所有其他使用者會收到該更新。
連線復原能力
如果 WebSocket 連線因網路問題或伺服器維護而中斷，該小工具會自動嘗試重新連線。在重新連線期間，使用者仍可與現有標記互動，但在連線重新建立之前，他們不會看到其他使用者的即時更新。
一旦重新連線，小工具會重新同步以確保沒有遺漏的更新。這個過程是透明的，不需要使用者介入。
頻寬考量
WebSocket 訊息輕量，只包含同步狀態所需的必要資訊。建立新標記通常使用不到 1KB 的頻寬。系統亦包含智慧批次處理，以在高活動期間減少訊息頻率。
您在 FastComments 儀表板中的使用量指標會追蹤 pubSubMessageCount 與 pubSubBandwidth，以便您監控跨網站的即時同步活動。
跨分頁同步
如果使用者在多個瀏覽器分頁開啟相同頁面，一個分頁的更新會立即出現在其他分頁。這是透過相同的 WebSocket 同步機制運作，且不需要任何額外設定。
使用者也可以在多個裝置同時開啟您的網站，所有裝置都會保持同步。若在桌機上建立標記，且平板也在檢視相同圖片，該標記會立即出現在平板上。
安全性
WebSocket 訊息經由安全連線（WSS）傳輸，並包含租戶驗證以確保使用者僅收到其有權檢視的對話更新。伺服器在廣播前會驗證所有操作，以防止未授權的存取或操控。
離線行為
當使用者完全離線時，他們仍可檢視既有標記，但無法建立新標記或看到其他人的更新。小工具會偵測離線狀態並顯示適當的訊息。
如果使用者在離線時嘗試建立標記，之後回到線上時該操作會失敗而非排隊，這可確保資料一致性。使用者應在連線恢復後重試該操作。
效能影響
WebSocket 連線對效能的影響極小。當沒有更新發生時，連線處於閒置狀態，僅在有活動時處理訊息。在標記活動適中的一般圖片上，WebSocket 使用的 CPU 通常少於渲染圖片本身所需的 CPU。
對於有數百名同時使用者且標記建立活動頻繁的頁面，系統會橫向擴展以維持效能，同時不影響單一用戶端的連線。
協作使用情境
即時同步使 Image Chat 對協作工作流程特別有用。設計團隊可以一起檢閱模型，所有人會即時看到標記位置。客戶支援團隊可以共同註解截圖以找出問題。教學群組可以討論圖表，所有參與者在標記建立時即時看到彼此的標記。
即時回饋相較於需要重新整理才能看到更新的傳統留言系統，能提供更具互動性與生產力的協作體驗。
API 參考
API 總覽
Image Chat 提供三個 REST API 端點，用於以程式方式管理圖片對話。這些端點讓您無需使用瀏覽器小工具即可擷取、建立及刪除標記。
所有 API 端點都需要驗證，並遵循標準的 FastComments API 模式。這些是透過瀏覽器 Cookie（而非 API 金鑰）進行驗證的公開端點。
基底 URL
所有 Image Chat API 端點都位於：
https://fastcomments.com/comment-image-chats驗證
這些端點透過瀏覽器 Cookie 驗證使用者。它們不使用 API 金鑰。使用者必須在瀏覽器中登入 FastComments 才能存取這些端點。
取得所有對話
擷取特定圖片的所有圖片對話。
端點
GET /comment-image-chats/:tenantId?urlId=<urlId>參數
tenantId（路徑參數，必填）是您的 FastComments Tenant ID。
urlId（查詢參數，必填）是您要擷取對話的圖片識別碼。
回應
回應包含 API 狀態、已驗證時的目前使用者工作階段資訊、包含對話 ID、URL 與 X/Y 座標的對話陣列、清理後的 URL 識別碼、表示目前使用者是否為網站管理員或版主的旗標，以及用於即時同步的 WebSocket 連線詳細資訊，包括 tenantIdWS、urlIdWS 與 userIdWS。
範例請求
curl "https://fastcomments.com/comment-image-chats/demo?urlId=my-product-image" \
--cookie "your-session-cookie"範例回應
{
"status": "success",
"user": {
"id": "user123",
"username": "john_doe"
},
"conversations": [
{
"_id": "conv123",
"urlId": "my-product-image:/images/product.jpg:25:30",
"x": 25.5,
"y": 30.2
},
{
"_id": "conv456",
"urlId": "my-product-image:/images/product.jpg:60:45",
"x": 60.8,
"y": 45.1
}
],
"urlIdClean": "my-product-image",
"isSiteAdmin": false,
"tenantIdWS": "demo",
"urlIdWS": "my-product-image",
"userIdWS": "user123"
}建立對話
為圖片上的特定位置建立新的圖片對話。
端點
POST /comment-image-chats/:tenantId參數
tenantId（路徑參數，必填）是您的 FastComments Tenant ID。
請求主體必須為 JSON，並包含以下必填欄位。
urlId（字串，必填）是基礎頁面識別碼。
windowUrlId（字串，必填）是結合圖片來源與座標的 URL，例如 my-page:/images/photo.jpg:25.5:30.2。
pageTitle（字串，必填）是頁面的標題。
src（字串，必填）是圖片來源 URL。
x（數字，必填）是以百分比表示的 X 座標（0-100）。
y（數字，必填）是以百分比表示的 Y 座標（0-100）。
createdFromCommentId（字串，必填）是發起此對話的留言 ID。
broadcastId（字串，必填）是用於即時同步以防止回音效應的 UUID。
回應
回應包含 API 狀態與新建對話的 ID。
範例請求
curl -X POST "https://fastcomments.com/comment-image-chats/demo" \
--cookie "your-session-cookie" \
-H "Content-Type: application/json" \
-d '{
"urlId": "my-product-image",
"windowUrlId": "my-product-image:/images/product.jpg:25.5:30.2",
"pageTitle": "Product Gallery",
"src": "/images/product.jpg",
"x": 25.5,
"y": 30.2,
"createdFromCommentId": "comment789",
"broadcastId": "550e8400-e29b-41d4-a716-446655440000"
}'範例回應
{
"status": "success",
"createdChatId": "conv789"
}刪除對話
刪除現有的圖片對話。此端點需要管理員或版主權限，或者該對話必須是由已驗證的使用者所建立。
端點
DELETE /comment-image-chats/:tenantId/:chatId參數
tenantId（路徑參數，必填）是您的 FastComments Tenant ID。
chatId（路徑參數，必填）是要刪除的對話 ID。
broadcastId（請求主體，必填）是用於即時同步的 UUID。
範例請求
curl -X DELETE "https://fastcomments.com/comment-image-chats/demo/conv789" \
--cookie "your-session-cookie" \
-H "Content-Type: application/json" \
-d '{
"broadcastId": "550e8400-e29b-41d4-a716-446655440001"
}'範例回應
{
"status": "success"
}座標系統
X 與 Y 座標以圖片尺寸的百分比儲存。X 代表距離左邊緣的水平位置（0 = 左邊緣，100 = 右邊緣）。Y 代表距離頂部邊緣的垂直位置（0 = 頂部邊緣，100 = 底部邊緣）。
這些百分比值可以包含小數以提升精確度。例如，x: 25.5 表示距離圖片左邊緣 25.5%。
速率限制
這些端點受標準 FastComments API 速率限制約束。速率限制中介軟體按租戶套用，以防止濫用，同時允許正常的使用模式。
錯誤回應
所有端點都會回傳標準的 HTTP 狀態碼。400 回應表示請求參數無效。401 回應表示驗證失敗。403 回應表示權限不足。404 回應表示找不到對話。429 回應表示超出速率限制。
錯誤回應包含帶有詳細資訊的 JSON 主體：
{
"status": "error",
"message": "Conversation not found"
}用量追蹤
建立對話會增加您的 conversationCreateCount 用量指標。所有 WebSocket 同步活動會增加 pubSubMessageCount 與 pubSubBandwidth。您可以在 FastComments 儀表板的用量分析中監控這些指標。
有問題嗎？
以上就是 FastComments Image Chat 的所有內容！如果您有任何問題、需要實作協助，或有功能建議，請在下方告訴我們，或聯絡我們的支援團隊。
請查看我們的 示範頁面 以觀看 Image Chat 的即時示範。