聊天嵌入发布 · 使用说明

适用版本：灵讯AI v1.12.1 路径：系统管理 → 聊天嵌入发布维护内容：通用聊天嵌入脚本的发布开关、浮窗样式、动态宽度和接入方式

一、功能概述

「聊天嵌入发布」用于将灵讯AI的对话能力以侧边浮窗的形式嵌入到第三方业务系统中，访客无需跳转页面，即可在当前网页上直接唤起 AI 对话窗口。

通过本模块，您可以：

控制通用聊天嵌入脚本的启用 / 停用；
自定义浮窗容器的展示方式与挂载位置；
调整浮动按钮的尺寸、颜色、阴影、边距以及图标；
配置不同场景（普通、历史、预览）下的动态布局宽度，兼顾 PC 与移动端体验。

二、入口与界面布局

区域	说明
顶部 Tab	`发布配置`（默认）、`使用说明`（即本文档）
顶部按钮	`重新加载`（放弃改动并拉取最新配置）、`保存配置`（写入并发布）
状态指示	「已停用 / 已启用」开关 + 「最近更新时间」

页面从上到下分为三个配置区块：

发布配置：总开关与浮窗容器
浮动按钮：底部悬浮气泡的样式与图标
动态布局宽度：不同状态下浮窗的宽度规则

三、配置项详解

3.1 发布配置

字段	默认值	说明
已停用	关闭	总开关。关闭时为停用状态，已嵌入站点的浮窗脚本不会渲染按钮和窗口。务必启用后，外网页面的通用聊天脚本才会显示按钮和对话框。
展示模式	侧边浮窗	通用聊天脚本在宿主页面的呈现形态，目前支持「侧边浮窗」。
容器 CSS 类选择器	`#chat-container`	通用脚本挂载的 DOM 容器选择器，默认为 `#chat-container`。当宿主页面已存在该 ID 容器时，对话框将挂载到该节点下；如宿主页面无此节点，脚本会自动在 `body` 末尾创建。
面板宽度	520px	浮窗在普通状态下的宽度。
面板高度	100%	浮窗高度，默认撑满容器高度，可改为具体像素值（如 `800px`）。

3.2 浮动按钮

用于控制右下角悬浮气泡的视觉样式与位置。

字段	默认值	说明
宽度	56px	按钮直径，建议 40–72px 之间。
高度	56px	按钮直径，建议与宽度保持一致以呈现圆形。
圆角	9999px	9999px 即「胶囊/圆形」效果，常规矩形可改为 `8px`、`12px` 等。
背景色	`#ffffff`	按钮背景色，建议与品牌色形成对比。
阴影	`0 12px 30px rgba(15, 23, 42, 0.25)`	标准 CSS 阴影语法，可调整 X/Y 偏移、模糊半径与透明度。
距底部	24px	按钮距视口底部的距离，移动端建议 ≥16px，避免与系统手势冲突。
距右侧	24px	按钮距视口右侧的距离，与底部保持一致更协调。
浮动按钮图标	默认图标	上传 JPG/PNG 图片，系统会自动裁剪为 128 × 128 PNG。未上传时使用默认图标。

建议：上传透明背景的 PNG 图标，以保证在深色 / 浅色站点上都贴合自然。

3.3 动态布局宽度

根据不同的对话状态自动切换浮窗宽度，做到「窄时不打扰、宽时多信息」。

场景	默认宽度	适用说明
普通	520px	用户首次进入、纯对话状态。
历史展开	760px	展开历史会话列表 / 侧边目录。
预览打开	1120px	同时展示对话 + 内容预览（如文档、报表预览）。
最大宽度	92vw	浮窗的最大宽度上限，避免在大屏上挤压。
移动端	`calc(100vw - 24px)`	移动端自适应宽度，左右各留 12px 安全边距。

单位说明：除「移动端」使用 calc(100vw - 24px) 动态表达式外，其余场景均按 像素（px） 填写；最大宽度支持 vw 等相对单位。

四、操作流程

进入页面 左侧菜单选择 系统管理 → 聊天嵌入发布，默认进入「发布配置」Tab。
开启总开关 打开「已停用」开关，状态变为「已启用」。未启用前，所有外网页面均不会显示聊天浮窗。
调整发布配置
- 确认「展示模式」为「侧边浮窗」（当前唯一支持的形态）。
- 如需将对话窗口挂到指定 DOM 节点，修改「容器 CSS 类选择器」（如 #my-chat、.chat-mount），否则保持默认 #chat-container。
- 设定「面板宽度 / 高度」。
设置浮动按钮样式
- 按品牌规范调整宽度、高度、圆角、背景色、阴影。
- 设置「距底部 / 距右侧」的偏移。
- 上传自定义图标（建议透明背景 PNG），未上传则使用默认图标。
配置动态布局宽度
- 按实际业务调整普通 / 历史展开 / 预览打开的宽度。
- 调整最大宽度上限和移动端宽度。
保存配置 点击右上角「保存配置」。保存成功后，顶部「最近更新时间」会更新为最新时间，所有已嵌入通用脚本的页面将在 下一次刷新 或下次访问时生效。
嵌入通用脚本 在需要展示聊天浮窗的页面中引入通用脚本，并按实际业务传入 usercode。详见下文「七、脚本接入方式」。
重新加载（可选） 误操作后想放弃本地改动，点击「重新加载」可从服务器拉取最新配置覆盖当前编辑。

五、最小可用配置示例

在不懂任何前端的情况下，按以下参数保存即可让外网站点正常显示聊天浮窗。

模块	字段	推荐值
发布配置	已停用	关闭（即启用）
发布配置	展示模式	侧边浮窗
发布配置	容器 CSS 类选择器	`#chat-container`
发布配置	面板宽度	520px
发布配置	面板高度	100%
浮动按钮	宽 × 高	56 × 56
浮动按钮	圆角	9999px
浮动按钮	背景色	`#ffffff`
浮动按钮	阴影	`0 12px 30px rgba(15, 23, 42, 0.25)`
浮动按钮	距底部 / 距右侧	24px / 24px
浮动按钮	图标	透明背景 PNG，自动裁剪 128×128
动态布局宽度	普通 / 历史 / 预览	520 / 760 / 1120 px
动态布局宽度	最大宽度	92vw
动态布局宽度	移动端	`calc(100vw - 24px)`

保存后，宿主页面只需引入通用聊天脚本即可生效。

六、注意事项

总开关 = 关闭 = 停用：未启用前已嵌入脚本的页面不会显示浮窗。修改后必须点击「保存配置」才生效。
保存后外网生效：通用聊天脚本会拉取最新配置；如线上页面没有立即变化，请让访客刷新页面或清理 CDN 缓存。
容器选择器：若选择器在宿主页面不存在，脚本会自动挂到 body 末尾，无需额外改动宿主代码。
图标规范：仅支持 JPG / PNG，系统统一裁剪为 128 × 128，建议上传正方形、清晰度足够的图标。
移动端适配：「移动端」字段支持 calc(100vw - 24px) 这类动态表达式，普通 / 历史 / 预览建议使用固定像素值，便于在手机与平板之间取得平衡。
安全色与对比度：按钮背景色与图标颜色请保证足够的对比度，避免在浅色 / 深色站点上出现「看不见」的情况。
不要把按钮放在内容热区：「距底部 / 距右侧」建议 ≥16px，避免遮挡页面底部 CTA、Cookie 横幅、客服图标等。

七、脚本接入方式

通用聊天脚本必须拿到 usercode 后才会展示入口。拿到 usercode 后，脚本会打开页面 http://lingsi.zhoujusoft.com/general-chat?usercode=<USER_CODE>&embed=true 作为嵌入对话页。

根据业务场景不同，提供三种向脚本传入 usercode 的方式。

7.1 方式一：在脚本标签中写死 `usercode`

适合页面初始化时已经知道当前用户编码的场景，例如：用户登录态已写入页面模板、服务端渲染场景。

<script
  src="http://lingsi.zhoujusoft.com/general-chat-embed.js"
  data-user-code="USER_CODE"
  defer
></script>

参数	说明
`src`	通用聊天嵌入脚本地址，固定为 `http://lingsi.zhoujusoft.com/general-chat-embed.js`
`data-user-code`	当前用户的唯一标识，替换为真实的 `usercode`
`defer`	脚本按标准 `defer` 方式加载，避免阻塞页面解析

7.2 方式二：通过事件传入 `usercode`

适合登录态异步获取完成后再传入用户编码的场景，例如：前端通过 AJAX 请求拿到登录态后，再触发脚本初始化。

<!-- 先引入通用脚本，不设置 usercode -->
<script src="http://lingsi.zhoujusoft.com/general-chat-embed.js" defer></script>

<script>
  // 登录态获取完成后，派发事件把 usercode 交给脚本
  window.dispatchEvent(new CustomEvent('lingsi:general-chat-user-code', {
    detail: { userCode: 'USER_CODE' }
  }));
</script>

事件名	`lingsi:general-chat-user-code`
事件类型	`CustomEvent`
载荷字段	`detail.userCode`
适用场景	异步登录、单点登录、登录态延迟返回

7.3 方式三：`postMessage` 兼容写法

适合模块化 / 跨 iframe / 微前端等需要解耦传递的场景，也可以向当前页面发送同名消息。

window.postMessage({
  type: 'lingsi:general-chat-user-code',
  userCode: 'USER_CODE'
}, '*');

注意：

targetOrigin 使用 '*' 会放宽安全限制，生产环境建议改为目标域名 http://lingsi.zhoujusoft.com。

该方式主要用于脚本已加载、但需要通过其他模块或父子页面传递 usercode 的复杂场景。

7.4 完整接入示例

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>嵌入灵讯AI对话</title>
</head>
<body>
  <!-- 方式一：适合页面初始化时就有 usercode 的场景 -->
  <script
    src="http://lingsi.zhoujusoft.com/general-chat-embed.js"
    data-user-code="USER_CODE"
    defer
  ></script>

  <!-- 方式二：异步登录态场景（与方式一任选其一即可） -->
  <!--
  <script src="http://lingsi.zhoujusoft.com/general-chat-embed.js" defer></script>
  <script>
    window.dispatchEvent(new CustomEvent('lingsi:general-chat-user-code', {
      detail: { userCode: 'USER_CODE' }
    }));
  </script>
  -->
</body>
</html>

八、常见问题

Q1：保存了配置，为什么站点上没生效？ A：请检查「已停用」开关是否打开；同时让访客刷新页面或确认 CDN 缓存是否刷新。

Q2：浮窗位置不对，被页面元素遮挡？ A：调大「距底部 / 距右侧」；若仍被遮挡，可改用更大的 z-index 样式（在容器 CSS 中覆盖）。

Q3：自定义图标上传后变形？ A：系统会统一裁剪为 128 × 128 的 PNG，建议先在本地把图标处理成正方形透明背景 PNG。

Q4：移动端浮窗太窄？ A：调整「动态布局宽度 → 移动端」，可写为 calc(100vw - 16px) 或具体像素值（如 360px）。

Q5：想让浮窗只挂在指定节点？ A：修改「容器 CSS 类选择器」为目标节点的 ID 或类选择器（如 #app、.chat-root），保存后脚本会优先挂到该节点。

Q6：脚本已引入，但页面没有浮窗入口？ A：通用脚本必须拿到 usercode 后才会展示入口。请确认已通过 data-user-code 属性、lingsi:general-chat-user-code 事件或 postMessage 正确传入 usercode。

Q7：异步登录场景如何传入 usercode？ A：先引入脚本但不要写 data-user-code，登录态返回后通过 CustomEvent 派发 lingsi:general-chat-user-code 事件，脚本会自动接收 detail.userCode 并初始化浮窗。

一、功能概述​

二、入口与界面布局​

三、配置项详解​

3.1 发布配置​

3.2 浮动按钮​

3.3 动态布局宽度​

四、操作流程​

五、最小可用配置示例​

六、注意事项​

七、脚本接入方式​

7.1 方式一：在脚本标签中写死 usercode​

7.2 方式二：通过事件传入 usercode​

7.3 方式三：postMessage 兼容写法​

7.4 完整接入示例​

八、常见问题​