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 dashboard 找到它。
FastCommentsImageChat(imageElement, {
tenantId: 'demo'
});圖像聊天特定選項
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 and simpleSSO
使用單一登入整合您的驗證系統。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
sso: {
// SSO 設定
}
});完整的驗證選項請參閱 SSO 文件。
maxReplyDepth
控制回覆可以有多少層深度。預設情況下，Image Chat 將此設為 0，表示所有評論為平鋪（無巢狀回覆）。如果您想要線程式對話，可以變更此數值。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
maxReplyDepth: 3 // 允許 3 層巢狀
});內部設定
這些選項由 Image Chat 自動設定，不應被覆寫：
productId 會自動為 Image Chat 設為 2。會自動載入 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 的螢幕上，圖片聊天室會切換到行動優化的佈局。聊天視窗會以全螢幕方式開啟，而不是浮動在標記旁邊。這在小螢幕上提供更好的可用性，避免浮動視窗遮擋過多影像。
標記本身仍會在其百分比位置上可見且可點擊。使用者仍可看到所有討論的位置，並點選標記以開啟全螢幕聊天介面。
動態圖片載入
即使影像是非同步載入或在頁面載入後改變大小，基於百分比的系統仍會正常運作。元件會監控影像元素，並在影像尺寸改變時重新計算標記位置。
如果你使用延遲載入影像或在不同斷點實作具有不同尺寸的響應式影像，當影像尺寸改變時標記會自動調整。
跨裝置一致性
因為座標以百分比形式儲存在資料庫中，在桌面電腦建立的討論在平板或手機上查看時會出現在完全相同的相對位置。使用者可以跨裝置協作，而不會產生定位不一致的問題。
這個行為是雙向的。在行動裝置上點選特定位置建立的討論，在大型桌面顯示器上查看時會出現在相同的相對位置。
視口考量
元件計算百分比是相對於影像元素本身，而非視口。這表示捲動頁面或改變瀏覽器視窗大小不會影響標記位置。標記會固定在影像上的位置，不受視口變動影響。
未來相容性
基於百分比的方法讓你的影像討論能抵抗佈局、設計或裝置生態系的變化。隨著新螢幕尺寸與裝置的出現，既有的討論會持續正確顯示，而不需要任何更新或遷移。
自訂
Dark Mode Support
Image Chat 包含內建的深色模式支援。當您在設定中將 hasDarkBackground: true 設定時，聊天視窗與 UI 元素會自動調整，以便在深色背景上良好顯示。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
hasDarkBackground: true
});深色模式樣式會套用到聊天視窗、標記方塊，以及所有互動元素。如果您的網站有深色模式切換，您可以在模式改變時重新初始化 widget，或使用下方描述的 body class 方法。
Dynamic Dark Mode
如果您網站的深色模式是透過在 body 元素新增 .dark 類別來控制，Image Chat 的 UI 會自動配合此類別，無需重新初始化。該 widget 的樣式設計會回應此類別的存在。
/* 您的深色模式 CSS */
body.dark {
background: #1a1a1a;
color: #ffffff;
}Custom Styling with CSS
您可以使用 CSS 自訂標記、聊天視窗和其他元素的外觀。widget 會新增特定的類別，您可以在樣式表中針對這些類別進行調整。
聊天方塊與視窗使用 FastComments 的評論氣泡樣式系統，因此您對標準評論 widget 所做的任何自訂也會影響 Image Chat。
Chat Square Sizing
chatSquarePercentage 選項控制可點擊標記的大小。預設為影像寬度的 5%：
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
chatSquarePercentage: 7 // 較大、更醒目的方塊
});較小的數值會產生較不突出的標記，能與影像更好地融合。較大的數值則會讓標記更顯眼、也更容易點擊，尤其是在行動裝置或為了無障礙性考量時。
Mobile Behavior
在寬度小於 768px 的螢幕上，Image Chat 會自動切換為行動裝置最佳化的版面配置。聊天視窗會以全螢幕方式顯示，而非在標記旁浮動，以在小螢幕上提供更好的可用性。
標記仍會保留在影像上其回應式的位置。使用者可以點擊任何標記以開啟全螢幕聊天介面。此行為為內建功能，無需任何額外設定。
Chat Window Appearance
桌面上聊天視窗寬度為 300px，並有一個指向標記的 16px 箭頭。視窗會根據可用的視窗空間自動定位，使用像是 to-right、to-left、to-top 和 to-bottom 的定位類別。
您可以加入自訂 CSS 以調整這些視窗的顏色、字型、間距或其他視覺屬性。聊天視窗使用與標準 FastComments widget 相同的元件結構，因此會繼承您所套用的任何全域自訂。
Lazy Initialization
聊天視窗會在桌面使用者滑鼠懸停時初始化，或在建立時立即初始化。這降低了初始載入的開銷，因為只有在使用者與標記互動時才會渲染聊天介面。
延遲初始化發生得很透明。使用者不會察覺到任何延遲，但如果影像上有許多標記，瀏覽器也不需要渲染數十個隱藏的聊天視窗。
Localization
Image Chat 支援與標準 FastComments widget 相同的所有在地化選項。設定 locale 選項以在不同語言中顯示 UI 文字：
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
locale: 'fr' // 法語
});FastComments 支援數十種語言。locale 設定會影響所有 UI 文字，包括提示、按鈕和佔位文字。
Inherited Customization Options
由於 Image Chat 擴充了標準評論 widget，它會繼承來自基礎 widget 的所有自訂選項。這包括自訂 CSS 類別、自訂翻譯、頭像自訂、日期格式化等等。
請參閱主要的 FastComments 自訂文件以取得可用自訂選項的完整清單。
Working with Custom Fonts
如果您的網站使用自訂字型，Image Chat 的 UI 會從您頁面的 CSS 繼承這些字型。聊天視窗會在您的頁面 DOM 中渲染並遵循您現有的排版設定。
為取得最佳效果，請確保在初始化 Image Chat 之前載入自訂字型，或接受在字型載入期間可能出現的短暫無樣式文字閃爍。
Marker Visual Design
方形標記具有細緻的視覺設計，使其在不搶走影像焦點的情況下仍然顯眼。如果您想要不同的視覺處理，可以使用 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 金鑰。
Base URL
所有 Image Chat API 端點位於：
https://fastcomments.com/comment-image-chatsAuthentication
這些端點透過瀏覽器 cookie 來認證使用者。它們不使用 API 金鑰。使用者必須在其瀏覽器中登入 FastComments 才能存取這些端點。
Get All Conversations
擷取特定圖片的所有影像對話。
Endpoint
GET /comment-image-chats/:tenantId?urlId=<urlId>Parameters
tenantId (path parameter, required) 是您的 FastComments Tenant ID。
urlId (query parameter, required) 是您要檢索對話的圖片識別碼。
Response
回應包含 API 狀態、若已認證的當前使用者會話資訊、包含其 ID、URL 及 X/Y 座標的對話陣列、清理過的 URL 識別碼、一個標示目前使用者是否為網站管理員或版主的旗標，以及用於即時同步的 WebSocket 連線詳細資訊，包括 tenantIdWS、urlIdWS 和 userIdWS。
Example Request
curl "https://fastcomments.com/comment-image-chats/demo?urlId=my-product-image" \
--cookie "your-session-cookie"Example Response
{
"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"
}Create Conversation
為圖片上的特定位置建立新的影像對話。
Endpoint
POST /comment-image-chats/:tenantIdParameters
tenantId (path parameter, required) 是您的 FastComments Tenant ID。
請求主體必須為 JSON 並包含以下必要欄位。
urlId (string, required) 是基礎頁面識別碼。
windowUrlId (string, required) 是結合了 URL、圖片來源與座標的識別字串，例如 my-page:/images/photo.jpg:25.5:30.2。
pageTitle (string, required) 是頁面的標題。
src (string, required) 是圖片來源 URL。
x (number, required) 是 X 座標，表示百分比 (0-100)。
y (number, required) 是 Y 座標，表示百分比 (0-100)。
createdFromCommentId (string, required) 是啟動此聊天室的評論 ID。
broadcastId (string, required) 是用於即時同步以避免回音效應的 UUID。
Response
回應包含 API 狀態以及新建立對話的 ID。
Example Request
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"
}'Example Response
{
"status": "success",
"createdChatId": "conv789"
}Delete Conversation
刪除現有的影像對話。此端點需要管理員或版主權限，或該對話必須由已驗證的使用者所建立。
Endpoint
DELETE /comment-image-chats/:tenantId/:chatIdParameters
tenantId (path parameter, required) 是您的 FastComments Tenant ID。
chatId (path parameter, required) 是要刪除的對話 ID。
broadcastId (request body, required) 是用於即時同步的 UUID。
Example Request
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"
}'Example Response
{
"status": "success"
}Coordinate System
X 和 Y 座標以影像尺寸的百分比儲存。X 表示從左邊緣開始的水平方向位置 (0 = 左邊緣，100 = 右邊緣)。Y 表示從上邊緣開始的垂直方向位置 (0 = 上邊緣，100 = 下邊緣)。
這些百分比值可以包含小數以提高精準度。例如，x: 25.5 意味著從影像左邊緣起算的 25.5%。
Rate Limiting
這些端點受到標準 FastComments API 的速率限制。速率限制中介軟體會以每個租戶為單位進行限制，以防止濫用同時允許正常使用模式。
Error Responses
所有端點會回傳標準的 HTTP 狀態碼。HTTP 400 表示請求參數無效。HTTP 401 表示認證失敗。HTTP 403 表示權限不足。HTTP 404 表示未找到該對話。HTTP 429 表示超過速率限制。
錯誤回應包含帶有詳細資訊的 JSON 主體：
{
"status": "error",
"message": "Conversation not found"
}Usage Tracking
建立對話會增加您的 conversationCreateCount 使用量指標。所有 WebSocket 同步活動會增加 pubSubMessageCount 與 pubSubBandwidth。您可以在 FastComments 儀表板的使用量分析中監控這些指標。
有問題嗎？
以上就是 FastComments Image Chat！如果您有任何問題、需要實作上的協助，或有功能建議，請在下方告訴我們或聯絡我們的支援團隊。
請到我們的 示範頁面 查看即時示範，以觀賞 Image Chat 的實際運作。