Widget 展示配置

已发布：Loader 1.2.0

Loader 1.2.0 与配套 Widget 已于 2026-09-14 发布到 widget.open4x.com。旧 Loader 不支持 configure()；自托管 Loader 和 SDK 请同步升级，SDK 源码仍按交付包提供，未发布公共 npm 包。1.2.0 同时修复自动初始化时报 savedToken is not defined 的问题，不会恢复 localStorage 中的旧 Token。附件上传仍需单独配置存储和扫描能力，显示上传按钮不代表已开通。

主题、语言与时区（1.3.0）

2026-09-16 发布。托管 Loader 与 Widget 已同步更新；自托管文件和使用中的 SDK 源码需同步升级。

JS 参数	标签属性	默认值	可选值
theme	theme / data-theme	auto	auto、light、dark、mint
locale	locale / data-locale	auto	auto、en、zh-CN、zh-TW
timeZone	time-zone / data-time-zone	auto	auto 或 IANA 时区名称

默认跟随系统配色、浏览器语言和浏览器时区。未支持的语言回退英文；无效主题按系统处理；无效时区回退浏览器时区，最终回退 UTC。显式配置优先。系统主题变化会即时生效。

<open4x-support-widget session-url="/api/support/session"
  theme="auto" locale="zh-CN" time-zone="Asia/Shanghai">
</open4x-support-widget>

Script 标签用 data-theme、data-locale、data-time-zone。自定义元素属性可动态修改；Script 属性仅在加载时读取。

Open4XWidget.configure({ theme: 'dark', locale: 'zh-TW', timeZone: 'America/New_York' });
Open4XWidget.configure({ theme: 'auto', locale: 'auto', timeZone: 'auto' });

动态配置不重新申请 Session，不重载消息。React 使用相同属性，通过组件 ref 的 configure() 可避免重挂载。

相对时间按实际经过的时间计算，不因时区切换增加或减少小时数；消息时间的悬浮提示及会话列表日期按配置时区显示，支持夏令时。当前聊天没有新增日期分组。只翻译界面文案，不翻译消息正文、商户名称和外部服务返回的任意错误文本。

展示预设

Widget 请求频率

浏览器 Widget 请求将按签名验证后的会话身份隔离：读取和已读确认每分钟 120 次，写入每分钟 30 次，两个计数独立。刷新同一会话的 Token 不重置额度。用户会话目录 Token 按租户和用户标识隔离。未取得有效 Widget 身份的请求（包括此入口的服务端 Key 请求）仍按 IP 每分钟 30 次保护；其他 API Key 配额不变。预检 OPTIONS 不消耗此额度。

遇到 429 应遵循 Retry-After，避免立即循环重试。此防刷限制不替代服务套餐和 API Key 的独立额度。

薄荷主题

theme="mint" 使用浅灰背景、白色客服气泡、浅薄荷绿用户气泡、白色标题栏和圆润气泡。隐藏气泡头像以简化布局，保留发送者名称及时间，便于区分客服与作者。此主题固定为浅色，不随系统深色变化；不包含模拟数据、测试提示或自动回复。

Open4XWidget.configure({ theme: 'mint' });

自定义元素使用 theme="mint"，Script 标签使用 data-theme="mint"，React 使用 theme="mint"。默认仍为 auto，不会自动改变现有商户的配色。

自动重连

临时网络故障时持续重连，采用指数退避和随机抖动，间隔上限约 31 秒，不再在十次失败后放弃。网络恢复或返回页面时尝试恢复连接，重连成功后刷新最近消息并按 ID 合并；更早历史仍可通过“加载更早消息”获取。连接握手超时及心跳长时间无响应也会触发恢复。

这不是无限续期：Session 过期、撤销或退出登录会停止重连，商户仍需通过原有 Session 接口重新获取合法凭证。不会自动重发发送结果不明确的业务消息，避免重复发送。

preset	场景	默认界面
floating	网站悬浮客服	标题、关闭及布局操作显示
embedded	订单页固定区域	隐藏标题、关闭及布局操作
modal	商户自己的弹窗	隐藏标题、关闭及布局操作，由宿主负责弹窗

要实际内嵌，必须同时指定 target 容器，并给它设置高度。preset 本身不创建商户弹窗，也不决定订单或权限。一个页面仍只有一套 Loader 实例，不支持同时挂多个独立聊天。

Script 标签属性

<div id="order-chat" style="height: 560px"></div>
<script
  src="https://widget.open4x.com/widget.js"
  data-lazy="true"
  data-preset="embedded"
  data-target="#order-chat"
  data-show-header="false"
  data-show-close="false"
  data-show-layout-controls="false"
  data-show-upload="true"
  data-show-emoji="false"
  data-show-message-actions="false"
></script>

登录并从商户后端取得短期 Session 后调用 Open4XWidget.init(sessionToken)；内嵌 target 会自动打开。API Key 不得放进标签。Script 的 data-* 只在加载时读取，之后用 JS API 修改。

JS 控制

Open4XWidget.init(sessionToken, {
  preset: 'embedded',
  target: '#order-chat',
  showClose: false,
  showLayoutControls: false,
  showEmoji: false
});

// 不换 Token、不重新请求 Session、不刷新聊天历史。
Open4XWidget.configure({ showHeader: true, showUpload: false });
Open4XWidget.close(); // 隐藏关闭按钮后，宿主仍可主动关闭。
Open4XWidget.open();

configure 未提供的开关保持原值；显式设置 preset 会先清除旧开关覆盖，再应用该次指定值。target: '' 可移回悬浮挂载位置。目标容器必须已经存在。

自定义元素与 React

配套 SDK 注册 <open4x-support-widget> 后可以直接写属性，false 必须显式写出；空属性表示 true：

<open4x-support-widget
  session-url="/api/open4x/order-session"
  preset="embedded"
  target="#order-chat"
  context-type="order"
  context-id="ORDER-123"
  show-close="false"
  show-emoji="false"
></open4x-support-widget>

const chat = document.querySelector('open4x-support-widget');
chat.setAttribute('show-upload', 'false');
chat.configure({ showHeader: false, showMessageActions: false });

元素属性变化会更新展示，无需重新签发 Session。修改订单标识或 Session URL 则会重新初始化。React 组件支持相同的 camelCase 属性，组件 ref 提供 configure(options)，onReady 也可取得 Loader API。SDK 需使用配套交付版本，不代表已发布公共 npm 包。

开关范围

JS 属性	控制内容
showHeader	外层标题栏及内部聊天标题栏
showClose	外层关闭、内部关闭按钮
showLayoutControls	最小化、停靠、最大化及调整大小入口
showUpload	上传入口，不隐藏现有附件与上传失败提示
showEmoji	表情入口及表情面板
showMessageActions	消息上下文菜单，例如回复、编辑等现有操作

会话列表隐藏标题后仍保留必要的“返回会话列表”，避免进入会话后无法返回。若订单页不应切换会话，应使用该订单专属 Token，不要发用户列表 Token。显示开关不是安全权限，上传、订单访问和消息可见性仍由后端校验。隐藏某个原本不支持的操作也不会增加该能力。

AI 提示词

请按 Open4X Widget 展示配置文档，将当前订单聊天改成内嵌模式。
确认 Loader 1.2.0 和配套 SDK/Widget 已在目标环境发布后再接入。
给容器固定响应式高度，使用 preset=embedded 和 target，隐藏关闭/布局按钮。
开关用标签属性或 configure 控制，不操作 iframe 内部 DOM，不重新加载聊天来切换按钮。
保留错误、重试和必要返回导航。订单切换仍由后端授权和重新签发短期 Token。
测试手机/桌面、动态属性、JS 控制、退出登录和快速切换订单。不要记录 Token。