FastComments 图像聊天功能通过允许用户在图像的任意位置单击来创建讨论点，从而实现对图像的交互式讨论。用户可以点击图像的特定部分来就这些区域发起对话，并创建显示讨论位置的可视标记。
此功能非常适合用于设计反馈、产品评论、带有图示的教学材料、含评论的照片图库，以及任何需要将上下文讨论锚定到特定图像位置的场景。
入门 
使用场景
Image Chat 非常适合用于需要就设计稿或屏幕截图中的特定元素进行讨论的设计反馈。产品评价网站可以让客户讨论产品照片中可见的特定功能。教育平台可以用来讨论图表、地图或科学图像。照片画廊可以通过基于位置的评论变得互动。房地产网站可以让查看者讨论房源照片中可见的特定特征。
快速开始
开始使用 Image Chat 很简单。您需要 FastComments Image Chat 脚本、一个包含图像的图像元素或容器，以及包含您的 Tenant ID 的配置对象。
安装
将 Image Chat 脚本添加到您的页面：
基本实现
下面是一个最小示例：
Run 
将 'demo' 替换为您实际的 FastComments Tenant ID（如果尚未设置），您可以在 FastComments 仪表板 中找到它。
工作原理
初始化后，用户可以在图像的任意位置点击。发生点击时，会在该位置显示一个可视的方形标记并打开聊天窗口。其他用户可以看到所有标记并点击它们以查看或参与这些讨论。所有讨论会在所有访问者之间实时同步。
该小部件使用基于百分比的定位，因此即使图像调整大小或在不同屏幕尺寸上查看，标记也会保持在正确的位置。
在线演示
您可以在我们的 在线演示页面 上查看 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 and simpleSSO
使用单点登录将其与您的身份验证系统集成。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
sso: {
// SSO 配置
}
});有关身份验证选项的完整详细信息，请参阅 SSO 文档。
maxReplyDepth
控制回复可以嵌套的层数。默认情况下，Image Chat 将其设置为 0，表示所有评论都是平铺的（没有嵌套回复）。如果您想要线程式对话，可以更改此设置。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
maxReplyDepth: 3 // 允许 3 层嵌套
});内部配置
这些选项由 Image Chat 自动设置，不应被覆盖：
对于 Image Chat，productId 会自动设置为 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 配置文档。
响应式设计
Percentage-Based Positioning
Image Chat 使用基于百分比的坐标来定位图像上的聊天标记，而不是像素坐标。当用户点击图像时，小部件会将点击的像素坐标转换为图像宽度和高度的百分比。这种方法可确保无论图像如何显示，标记都保持在正确的位置。
例如，如果用户在一个宽度为 1000px 的图像上从左边缘向右点击 250 像素，小部件会将此存储为距左侧 25%。当另一个用户在移动设备上以 500px 宽查看同一图像时，标记会显示在距左侧 125 像素的位置，这仍然是宽度的 25%。
Benefits for Responsive Layouts
该百分比系统使 Image Chat 能在所有设备大小和方向上无缝工作。根据屏幕宽度、CSS 规则或容器约束，你的图像可能以不同尺寸显示，但标记始终与预期位置对齐。
在大型显示器的桌面电脑上的用户，会在与智能手机小屏幕用户相同的相对位置看到标记。标记会随着图像本身按比例缩放。
Image Scaling and Aspect Ratio
只要你的图像在缩放时保持纵横比（这是浏览器的默认行为），基于百分比的标记将保持完美对齐。小部件假定图像按比例缩放并基于此假设计算位置。
如果你应用会扭曲图像纵横比的 CSS（例如使用 object-fit: cover 并设置特定尺寸），标记位置可能无法正确对齐。为了获得最佳效果，允许图像自然缩放或使用 object-fit: contain 来保持纵横比。
Chat Square Sizing
聊天标记的视觉大小也是基于百分比的。chatSquarePercentage 配置选项的默认值为 5%，意味着每个方块为图像宽度的 5%。这能确保在不同图像大小下视觉权重的一致性。
在宽度为 1000px 的图像上，使用默认的 5% 设置时，标记为 50px 的方块。在宽度为 500px 的图像上，相同的标记为 25px 的方块。它们始终与图像大小成比例。
Mobile Behavior
在宽度小于 768px 的屏幕上，Image Chat 会切换到为移动设备优化的布局。聊天窗口会全屏打开，而不是浮动在标记旁边。这在小屏幕上更易用，因为浮动窗口会遮挡过多图像内容。
标记本身仍然可见并可在其基于百分比的位置被点击。用户仍然可以看到所有讨论的位置并点击标记以打开全屏聊天界面。
Dynamic Image Loading
即使图像是异步加载或在页面加载后改变大小，基于百分比的系统仍能正常工作。小部件会监控图像元素并在图像尺寸发生变化时重新计算标记位置。
如果你正在进行懒加载图像或在不同断点使用不同尺寸的响应式图像，当图像尺寸改变时，标记会自动调整。
Cross-Device Consistency
由于坐标以百分比形式存储在数据库中，桌面电脑上创建的讨论在平板或手机上查看时会出现在完全相同的相对位置。用户可以跨设备协作而不会出现位置不一致的情况。
这也是双向有效的。在移动设备上通过点击特定位置创建的讨论，在大屏幕桌面显示器上查看时会出现在相同的相对位置。
Viewport Considerations
小部件计算的百分比是相对于图像元素本身，而不是视口。这意味着页面滚动或更改浏览器窗口大小不会影响标记位置。无论视口如何变化，标记都固定在图像上的位置。
Future-Proofing Content
基于百分比的方法使你的图像讨论对布局、设计或设备生态系统的变化具有弹性。随着新的屏幕尺寸和设备的出现，现有的讨论将继续正确显示，而无需任何更新或迁移。
自定义
深色模式支持
Image Chat 包含内置的深色模式支持。当您在配置中将 hasDarkBackground: true 设置为 true 时，聊天窗口和 UI 元素会自动调整以适应深色背景。
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
hasDarkBackground: true
});深色模式样式适用于聊天窗口、标记方块和所有交互元素。如果您站点有深色模式切换，可以在模式更改时重新初始化小部件，或者使用下面描述的 body class 方法。
动态深色模式
如果您站点的深色模式是通过向 body 元素添加 .dark 类来控制的，Image Chat UI 会自动响应这一点，而无需重新初始化。该小部件的样式设计为会对该类的存在作出响应。
/* 您的深色模式 CSS */
body.dark {
background: #1a1a1a;
color: #ffffff;
}使用 CSS 的自定义样式
您可以使用 CSS 自定义标记、聊天窗口和其他元素的外观。该小部件会添加特定的类，您可以在样式表中针对这些类进行样式设置。
聊天方块和窗口使用 FastComments 的评论气泡样式系统，因此您对标准评论小部件所做的任何自定义也会影响 Image Chat。
聊天方块大小
chatSquarePercentage 选项控制可点击标记的大小。默认是图像宽度的 5%：
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
chatSquarePercentage: 7 // 更大、更醒目的方块
});较小的值会创建更细微的标记，使其更融合于图像。较大的值会使标记更突出、更容易点击，尤其是在移动设备上或为了无障碍目的。
移动端行为
在宽度小于 768px 的屏幕上，Image Chat 会自动切换到移动优化布局。聊天窗口将以全屏方式出现，而不是在标记旁浮动，从而在小屏幕上提供更好的可用性。
标记仍会在图像上的响应位置可见。用户可以点击任何标记以打开全屏聊天界面。此行为为内置功能，无需任何配置。
聊天窗口外观
在桌面端，聊天窗口宽度为 300px，并有一个指向标记的 16px 箭头。窗口会根据可用视口空间自动定位，使用类似 to-right、to-left、to-top 和 to-bottom 的定位类。
您可以添加自定义 CSS 来调整这些窗口的颜色、字体、间距或其他视觉属性。聊天窗口使用与标准 FastComments 小部件相同的组件结构，因此它们会继承您应用的任何全局自定义。
惰性初始化
聊天窗口在桌面用户悬停时或在创建时立即初始化。这通过仅在用户实际与标记交互时才渲染聊天界面来减少初始加载开销。
惰性初始化是透明进行的。用户不会注意到任何延迟，但如果图像上有许多标记，浏览器就不需要渲染几十个隐藏的聊天窗口。
本地化
Image Chat 支持与标准 FastComments 小部件相同的所有本地化选项。设置 locale 选项以在不同语言中显示 UI 文本：
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
locale: 'fr' // 法语
});FastComments 支持多种语言。locale 设置会影响所有 UI 文本，包括提示、按钮和占位符文本。
继承的自定义选项
由于 Image Chat 扩展了标准评论小部件，它继承了基础小部件的所有自定义选项。这包括自定义 CSS 类、自定义翻译、头像自定义、日期格式化等更多内容。
请参阅 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 相匹配。
这确保了流畅的交互：用户在界面上立即看到自己的更改，而无需等待通过服务器的往返，同时仍能确保所有其他用户接收到该更新。
连接弹性
如果因网络问题或服务器维护导致 WebSocket 连接中断，组件会自动尝试重新连接。在重连期间，用户仍然可以与现有标记交互，但他们在连接重新建立之前不会看到其他用户的实时更新。
一旦重新连接，组件会重新同步以确保没有错过任何更新。此过程是透明的，不需要用户干预。
带宽考量
WebSocket 消息轻量且仅包含同步状态所需的必要信息。创建新标记通常使用的带宽小于 1KB。该系统还包括智能批处理，以在高活动期间减少消息频率。
您在 FastComments 仪表板中的使用统计会跟踪 pubSubMessageCount 和 pubSubBandwidth，以便您监控跨站点的实时同步活动。
跨标签页同步
如果用户在多个浏览器标签页中打开同一页面，一个标签页中的更新会立即出现在其他标签页中。这通过相同的 WebSocket 同步机制实现，无需任何额外配置。
用户可以在多台设备上同时打开您的站点，所有设备都会保持同步。如果两台设备都在查看同一图像，在桌面上创建的标记会立即出现在用户的平板上。
安全
WebSocket 消息通过安全连接（WSS）传输，并包含租户验证，以确保用户仅接收其有权查看的对话更新。服务器在广播之前会验证所有操作，以防止未授权的访问或篡改。
离线行为
当用户完全离线时，他们仍然可以查看现有标记，但无法创建新标记或查看他人的更新。组件会检测离线状态并显示适当的提示信息。
如果用户在离线时尝试创建标记然后重新上线，该操作将失败而不是排队，从而确保数据一致性。用户应在连接恢复后重试该操作。
性能影响
WebSocket 连接对性能的影响最小。当没有更新发生时，连接保持空闲，只有在发生活动时才处理消息。在具有中等标记活动的典型图像上，WebSocket 使用的 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 租户 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 租户 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 租户 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 的实际运行效果。