@fusioni/client-sdk

中文文档
1.1.42发布于 2026/11/13MITTypeScriptESM + CJS近 30 天下载 3094

Fusioni SDK 用于网络应用程序

中文使用文档
文档目录36 节
  1. 特征
  2. 安装
  3. 作为图书馆( npm)
  4. 作为脚本( 没有构建步骤)
  5. 快速启动
  6. 基本用途
  7. 脚本tag 使用( 不需要 React app)
  8. 搜索
  9. 输入后更改语言和主题
  10. 事件处理器的高级使用
  11. 小型应用程序渲染
  12. 动作按钮
  13. 配置选项
  14. FusioniSDK 配置
  15. 事件处理器
  16. ChatWidget 选项
  17. API 整合
  18. 样式
  19. 黑暗主题
  20. 浏览器支持
  21. 录音要求
  22. 发展
  23. 建造SDK
  24. 发展模式
  25. 类型检查
  26. 测试
  27. 线性
  28. 实例
  29. 自定义样式
  30. 有条件渲染
  31. 解决问题
  32. 共同问题
  33. 调试模式
  34. 许可证
  35. 支助
  36. 正在链接 npm

幻想聊天SDK

一个反应TypeScript SDK,用于将Fusioni Chat功能整合到网络应用中. 这个 SDK 提供了一个可以嵌入到任何网页的浮动聊天部件,提供 AI 驱动的聊天能力,支持文本,图像和音频消息.

特征

  • 🤖 AI 聊天接口 - 提供实时信息的现代、响应性聊天UI
  • 🎤 音频记录 - 录音和回放语音信息支持
  • 📁 文件上传 - 图像上传和预览功能
  • 💬 对话管理 - 创建、管理和删除对话
  • 🎨 自定义主题 - 有自定义颜色的浅/暗主题支持
  • 📱 响应设计 - 桌面和移动设备无缝工作
  • 🔄 实时更新 - 实时消息流的服务器发送事件
  • 🛡️ 类型脚本支持 - 全面安全和情报支持
  • 小型应用程序 - 按位置或标记选择的可信任的网络组件捆绑或收藏
  • 搜索 - 用页码、输入式自动完成和自定义结果容器进行聚合数据搜索

安装

你可以用SDK的两种方式:

作为图书馆( npm)

npm install @fusioni/client-sdk

作为脚本( 没有构建步骤)

在您的页面上添加一个脚本标签 。 浏览器捆绑是一个 IIFE (英语) (文件名称仍然) fusioni-sdk.umd.js 用于 CDN URL : 它指定全局 Fusioni 包括反应和风格。 IIFE是用来代替经典UMD的 Fusioni 即使主机页面的捆绑器定义了普通JS,仍然正确 module编号 :exports 同一范围(UMD方案) Fusioni 作为 {} (见a/cn.9/wg.iii/wp.iii/wp.1号文件).

<script src="https://unpkg.com/@fusioni/client-sdk/dist/fusioni-sdk.umd.js"></script>
<!-- or use your own path -->
<script src="/path/to/fusioni-sdk.umd.js"></script>

快速启动

基本用途

import React from 'react';
import { ChatWidget } from '@fusioni/client-sdk';

function App() {
  const config = {
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    accessToken: 'your-access-token', // Optional
    theme: 'light', // 'light' | 'dark' | 'auto'
    position: 'bottom-right', // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
    primaryColor: '#6366f1',
    showConversationList: true,
    enableAudioRecording: true,
    enableFileUpload: true,
    maxFileSize: 10, // MB
    allowedFileTypes: ['image/*']
  };

  return (
    <div className="App">
      <h1>My Website</h1>
      <ChatWidget config={config} />
    </div>
  );
}

export default App;

脚本tag 使用( 不需要 React app)

包含通过 <script src="...">SDK暴露了一个全球 Fusioni 对象。 不需要建立步骤或反应设置 .

初始化一次和链式特性 :

<label for="site-search">Search the site</label>
<input id="site-search" type="search">
<div id="search-widget"></div>
<div id="mini-apps"></div>
<div id="actions"></div>

<script src="path/to/fusioni-sdk.umd.js"></script>
<script>
  const sdk = Fusioni.init({
    apiBaseUrl: 'https://your-fusioni-api.com/api',
    agencyId: 'your-agency-id',
    accessToken: 'your-access-token'
  })
    .search('#search-widget', {
      mode: 'autocomplete',
      inputElement: '#site-search'
    })
    .mountMiniApp('#mini-apps', {position: 'dashboard'})
    .mountActionButtons('#actions', {tags: ['tools']})
    .chatWidget();

  // sdk.getSearch('#search-widget').search('setup');
  // sdk.getMiniApp('#mini-apps').run();
  // sdk.getActionButtons('#actions').executeAction('report');
  // sdk.getChatWidget().setLanguage('el');
  // sdk.unmount('#search-widget'); // Unmount one feature.
  // sdk.unmount();                 // Unmount all features belonging to this instance.
</script>

init() 初始化共享设置和默认的 API 客户端而不创建 UI 或请求 。 每个挂载方法返回相同 FusioniSDKInstance特征继承 apiBaseUrl, (中文(简体) ), agencyId, (中文(简体) ), accessToken,和配置的语言;搜索也继承主题。 每个地物选项可以覆盖这些默认或提供明确 apiClient。搜索、 Mini Apps 和 Action Buttons 在创建另一个实例时保留其初始化的连接,并且将清理范围扩大到每个实例.

每个后端API请求包括 agency_id 在查询字符串中,包括POST/PUT请求其JSON正文也包含. SDK从初始或每个地貌机构提供,而明确要求的参数优先。 对于低级使用,将代理作为第三个论据传递至 new ApiClient(apiBaseUrl, accessToken, agencyId) 或者说 initializeApiClient(apiBaseUrl, accessToken, agencyId)。在发出请求前,未对请求进行范围审查的请求被拒绝.

.chatWidget() 明确挂载浮动聊天。 使用 .chatWidget({theme: 'dark'}) 用于聊天覆盖或 .chatWidget('#my-chat', {theme: 'dark'}) 用于特定的容器。 可连锁 .mount() 方法也可以作为聊天别名. .search() 财务报告和审定财务报表 .mountSearch() 在初始化的情况下是别名.

移徙: Fusioni.init(config) 以前自动挂载的聊天。 使用 Fusioni.init(config).chatWidget() 以保持这种行为。 要访问聊天控制, 请使用 sdk.getChatWidget(); 独立 Fusioni.mount(container, config) 仍然直接返回聊天控点 .

默认位置( 浮动聊天部件) :

<script src="path/to/fusioni-sdk.umd.js"></script>
<script>
  Fusioni.init({
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    accessToken: 'your-access-token',
    theme: 'light',
    position: 'bottom-right',
    primaryColor: '#6366f1',
    showConversationList: true,
    showThoughts: false,
    enableAudioRecording: true,
    enableFileUpload: true,
    maxFileSize: 10,
    allowedFileTypes: ['image/*']
  }).chatWidget();
</script>

挂入特定容器 :

<div id="my-chat"></div>
<script src="path/to/fusioni-sdk.umd.js"></script>
<script>
  Fusioni.mount('#my-chat', {
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    theme: 'light',
    position: 'bottom-right',
    primaryColor: '#6366f1'
  });
  // Optional: unmount or change language/theme later
  // const result = Fusioni.mount('#my-chat', config);
  // result.unmount();
  // result.setLanguage('el');
  // result.setTheme('auto');
</script>

脚本 API :

方法说明
Fusioni.init(config)初始化共享设置并返回可链条 FusioniSDKInstance;挂载无UI.
Fusioni.mount(container, config)装入 container (CSS 选择字符串或 HTMLElement) (中文(简体) ). 回返 FusioniMountResult。 。 。 .
Fusioni.mountSearch(container, props)挂载 搜索,可选择性地约束现有输入,并生成一个单独要素.
Fusioni.mountMiniApp(container, props)挂起迷你Apps并返回他们的手柄.
Fusioni.mountActionButtons(container, props)Mounts Action按钮并返回其手柄.
Fusioni.versionSDK版本字符串.

初始化案例提供 chatWidget, (中文(简体) ), search, (中文(简体) ), mountMiniApp,以及 mountActionButtons,所有返回 同一实例. getChatWidget, (中文(简体) ), getSearch, (中文(简体) ), getMiniApp,以及 getActionButtons 返回相应的组件控件,或 null 当此实例没有匹配挂载时 . unmount(container?) 清理一个或所有由实例拥有的挂载。 集装箱可以是CSS选取器或DOM元件;组件把手一挂起即可使用.

Search 支持两种模式: search (默认)呼叫 FusionDataResource.search_paginated 提交时,和 autocomplete 电话 FusionDataResource.search_autocomplete 作为用户类型。 选择结果 url 在当前标签中。 没有可用的 HTTP( S) 或相对 URL 的结果作为非交互式项目显示 .

反应 :

import {Search} from '@fusioni/client-sdk';

function SiteSearch() {
  return <Search
    apiBaseUrl="https://your-fusioni-api.com/api"
    agencyId="your-agency-id"
    accessToken="your-access-token"
    mode="autocomplete"
    placeholder="Search the site…"
  />;
}

搜索包括自己的范围样式. 切换到 mode="search" 对于带有前一个/下一个控件的搜索窗体。 在自动完成模式下,在页面滚动或调整大小时会随输入而下放. 使用 Up/ Down 来选择, Enter 来跟踪结果, 而 Escape 则去掉 .

脚本标记, 绑定在您现有的输入上 :

<label for="site-search">Search the site</label>
<input id="site-search" type="search" placeholder="Search…">
<div id="search-widget"></div>

<script src="path/to/fusioni-sdk.umd.js"></script>
<script>
  const search = Fusioni.mountSearch('#search-widget', {
    apiBaseUrl: 'https://your-fusioni-api.com/api',
    agencyId: 'your-agency-id',
    accessToken: 'your-access-token',
    mode: 'autocomplete',
    inputElement: '#site-search'
  });

  // search.search('setup'); // Run immediately, skipping the debounce.
  // search.clear();
  // search.focus();
  // search.unmount();
</script>

离开 inputElement 制造SDK自己的球场 将装入的容器与装入的输入相分离,因此装入不能将其取出。 卸载会移除下放,取消待定的工作,并恢复输入的原始自動完整和可访问性属性.

渲染结果为:

<form>
  <label for="query">Search</label>
  <input id="query" type="search">
  <button type="submit">Search</button>
</form>
<div id="search-controller"></div>
<section id="search-results" aria-label="Search results"></section>

<script>
  const search = Fusioni.mountSearch('#search-controller', {
    apiBaseUrl: 'https://your-fusioni-api.com/api',
    agencyId: 'your-agency-id',
    accessToken: 'your-access-token',
    mode: 'search',
    inputElement: '#query',
    resultElement: '#search-results',
    pageSize: 10
  });
</script>

inputElement 财务报告和审定财务报表 resultElement 接受 CSS 选择器或 DOM 元素在 React 和脚本标签使用中。 搜索挂载时, 元素必须存在 。 所提供的结果要素在两种模式中都收到内入结果,保留其现有子女;没有这种结果,自动完成将使用下放,全面搜索将低于其域。 输入或提交绑定输入的表单运行搜索.

选项默认说明
agencyId需求联合机构要搜索.
apiBaseUrl, (中文(简体) ), accessToken初始化的 SDK 客户端连接设置 。 替代供应 apiClient。 。 。 .
mode'search''search' 或者说 'autocomplete'。 。 。 .
inputElementSDK 字段现有输入选择器或 HTMLInputElement。 。 。 .
resultElement自动放置结果选择者或 HTMLElement。 。 。 .
pageSize25请求的页面大小 。 Fusion目前以10个建议自动完成封顶,无论这个值如何.
minLength2在请求结果前最小修剪了查询长度 。 空问从不请求结果 .
debounceMs250输入自动完成模式时出现延迟 .
label, (中文(简体) ), placeholder本地化搜索文本SDK自己的字段的文本. 在主机页面上标记外部输入 .
currentLanguage'en''en' 或者说 'el'。 。 。 .
theme'light''light', (中文(简体) ), 'dark',或 'auto'。 。 。 .
className, (中文(简体) ), style—— 说根样式;内置样式也适用于出入口结果面板.
onResults(response)—— 说接收 {body, pagination} 在成功请求后.
onError(error)—— 说接收请求错误; UI 也提供重试 .
onSelect(item)导航到 item.url返回时 false 防止导航,例如,在使用您的应用程序的路由器处理时.

脚本挂载返回 search(query?, page?), (中文(简体) ), clear(), (中文(简体) ), focus(), (中文(简体) ), unmount(),则只读 results 财务报告和审定财务报表 pagination在反应中,附加一个 ref 类型 SearchHandle 用于同一API的除外 unmount()。页码为零。 新输入立即取消待决请求,而更古老的响应无法覆盖新的结果.

在没有UI的情况下获取时,使用明确输出的服务 ApiClient 或初始化的 SDK 客户端 :

import {ApiClient, SearchService} from '@fusioni/client-sdk';

const search = new SearchService(new ApiClient('https://your-fusioni-api.com/api', 'your-access-token', 'your-agency-id'));
const suggestions = await search.autocomplete('your-agency-id', 'set');
const results = await search.search('your-agency-id', 'setup guide', {page: 0, size: 10});
// Both return {body: SearchItem[], pagination: SearchPagination | null}.
// Options also accept an AbortSignal as `signal`.

两种方法 {agency_id, inp} 与 agency_id, (中文(简体) ), page,以及 size 查询参数。 自动完成使用 /sdk-client/dasearch; 全部搜索用途 /sdk-client/dpsearch使用 SDK 的请求 ApiKey 认证和要求 Fusion 数据视图访问.

输入后更改语言和主题

聊天手柄( 在 TypeScript 中: FusioniMountResult包括 setLanguage 财务报告和审定财务报表 setTheme 从而可以在不重挂的情况下切换地盘或外观. 拿着 sdk.getChatWidget() 之后 sdk.chatWidget(),或直接从独立的 Fusioni.mount(container, config)。 。 。 .

属性/方法说明
unmount()删除部件并清理反应根.
setLanguage(language)设置用户界面语言到 'en' 或者说 'el'。无效的值会被忽略.
setTheme(theme)设置外观到 'light', (中文(简体) ), 'dark',或 'auto' (遵循系统偏好). 恒相如入微软主题控制.

脚本示例 :

<script src="path/to/fusioni-sdk.umd.js"></script>
<script>
  const sdk = Fusioni.init({
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    theme: 'light',
    language: 'en'
  }).chatWidget();

  document.getElementById('locale-el').addEventListener('click', () => {
    sdk.getChatWidget().setLanguage('el');
  });
  document.getElementById('theme-dark').addEventListener('click', () => {
    sdk.getChatWidget().setTheme('dark');
  });
</script>

反应( npm) 实例 : 传回 ChatWidget 并调用相同方法(类型 : FusioniChatWidgetHandle) (中文(简体) ).

import { useRef } from 'react';
import { ChatWidget, type FusioniChatWidgetHandle, type FusioniSDKConfig } from '@fusioni/client-sdk';

function App() {
  const chatRef = useRef<FusioniChatWidgetHandle>(null);
  const config: FusioniSDKConfig = {
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
  };

  return (
    <>
      <button type="button" onClick={() => chatRef.current?.setLanguage('el')}>
        Greek
      </button>
      <button type="button" onClick={() => chatRef.current?.setTheme('dark')}>
        Dark mode
      </button>
      <ChatWidget ref={chatRef} config={config} />
    </>
  );
}

事件处理器的高级使用

import React from 'react';
import type { Conversation, FusioniMemoryMessage, FusioniSDKConfig } from '@fusioni/client-sdk';
import { ChatWidget } from '@fusioni/client-sdk';

function App() {
  const config: FusioniSDKConfig = {
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    accessToken: 'your-access-token',
    theme: 'auto',
    position: 'bottom-right',
    primaryColor: '#6366f1',
    showConversationList: true,
    enableAudioRecording: true,
    enableFileUpload: true,
    maxFileSize: 10,
    allowedFileTypes: ['image/*', 'application/pdf']
  };

  const handleMessageSent = (message: FusioniMemoryMessage) => {
    console.log('Message sent:', message);
    // Track analytics, update UI, etc.
  };

  const handleMessageReceived = (message: FusioniMemoryMessage) => {
    console.log('Message received:', message);
    // Handle AI responses
  };

  const handleConversationCreated = (conversation: Conversation) => {
    console.log('New conversation:', conversation);
    // Update conversation list, analytics, etc.
  };

  const handleError = (error) => {
    console.error('Chat error:', error);
    // Handle errors, show notifications, etc.
  };

  return (
    <div className="App">
      <h1>My Website</h1>
      <ChatWidget
        config={config}
        onMessageSent={handleMessageSent}
        onMessageReceived={handleMessageReceived}
        onConversationCreated={handleConversationCreated}
        onError={handleError}
      />
    </div>
  );
}

export default App;

小型应用程序渲染

MiniAppRenderer 是Fusion Web的Angular微型应用程序渲染器的等效反应. 它导入了快照的网络组件捆绑,并挂载其条目ES模块所注册的自定义元素.

import {MiniAppRenderer} from '@fusioni/client-sdk';
import '@fusioni/client-sdk/dist/index.css';

function Dashboard() {
  return (
    <MiniAppRenderer
      apiBaseUrl="https://your-fusioni-api.com/api"
      accessToken="your-access-token"
      agencyId="your-agency-id"
      position="dashboard"
      columns={2}
      options={{title: 'Dashboard', rows: 25}}
      onReady={element => console.log('Mini App mounted', element)}
      onFailed={error => console.error(error)}
    />
  );
}

使用 miniApp={snapshot} 一个应用或 miniApps={snapshots} 用于提供收藏。 每张快照都需要一张 bundle 与 element, (中文(简体) ), entry,并且文件元数据 :

const snapshot = {
  id: 'your-mini-app-id',
  name: 'Reports',
  bundle: {
    element: 'fusion-reports',
    entry: 'frontend/index.js',
    files: [{path: 'frontend/index.js', sha256: 'file-content-hash', size: 1024}],
  },
};

文件在Mini App运行时直播. 输入必须调用 customElements.define('fusion-reports', …) ;导出一个类或等待 DOMContentLoaded 不够充分。 浏览器装入相对导入和 new URL(path, import.meta.url) 从已签名的运行时间 URL 中获取资产.

要通过标签加载已安装的应用程序, 请使用 agencyId 财务报告和审定财务报表 tags={['billing', 'reports']}选择优先 位置 标签 小型Apps 小型Apps位置和标签检查需要一个机构;安装捆绑还需要一个机构,要么是道具,要么是明确的运行时间。 单一结果可转化为外部结果 element; 多个结果每个得到自己的容器。 收藏使用移动和 columns 宽度为768px及以上.

Prop默认目的
miniApp—— 说包含自定义元素捆绑的快照
miniApps—— 说要一起制作的快照
agencyId, (中文(简体) ), position, (中文(简体) ), tags—— 说从 API 中选择应用程序
element自有容器将自定义元素挂入的外部容器
columns1桌面列的正整数
options, (中文(简体) ), context{}自定义组件配置和主机服务, 在连接前指定
reloadable, (中文(简体) ), showStatustrue显示重新装入控制和空态消息
currentLanguage'en'控制/状态语言('en' 或者说 'el'(中文(简体) )
apiBaseUrl, (中文(简体) ), accessToken初始化的 SDK 客户端查询和后端调用的独立连接; 基址包括 /api
apiClient—— 说明确 ApiClient中,优先于 URL/token
onReady, (中文(简体) ), onFailed—— 说接收挂载自定义元素或文件/模块/注册失败
className, (中文(简体) ), style—— 说外包装样式

变化 options, (中文(简体) ), context,回调,或 columns 不重新启动元素。 使用一个 ref 类型为 MiniAppRendererHandle 打电话 ref.current.run() 重新装入当前选项/文本。 内容 api getter 显示挂载 MiniAppElement 为单一应用程序,或 null 为了收藏. loadMiniApps() 重试当前服务器查询 。 替换、再装入和卸载删除元素,取出其原生元素 disconnectedCallback() 当连接时.

对于一个快照, element.context.backend.request(path, request?) 自动调用 /api/mini-app-runtime/{miniAppId}{path} 与代理和SDK认证。 请求选项包括: method, (中文(简体) ), query, (中文(简体) ), headers, (中文(简体) ), body,以及 responseType (单位:千美元)'json' 或者说 'text') (中文(简体) ). 提供 context.backend 优先; MiniAppBackendService.createBuilderContext() 为文件和后端调用选择构建器运行时间. element.context.lifecycle.signal 和后端请求信号在重新装入或卸载时中止。 使用该信号取消同步工作 disconnectedCallback() 删除听众/计时器.

冰冻的 element.context.files 提供 base (已签名的文件库 URL)和 url(path) 用于解决捆绑资产。 档案赠款的使用 /api/mini-app-files/{installed|builder}/{miniAppId} 并且通过连接、运行时间、应用、代理和捆绑版本被缓存,所以同一模块在重载时保留相同的URL。 失败的赠款可以再审。 浏览器无法重新定义自定义元素:使用已注册名的不同捆绑版本需要重新装入页面. 用无关的主机代码已经注册的名称被拒绝.

脚本捆绑在Shadow DOM中提供了具有SDK风格的同一种渲染器:

<div id="mini-apps"></div>
<script src="path/to/fusioni-sdk.umd.js"></script>
<script>
  const apps = Fusioni.mountMiniApp('#mini-apps', {
    apiBaseUrl: 'https://your-fusioni-api.com/api',
    accessToken: 'your-access-token',
    agencyId: 'your-agency-id',
    position: 'dashboard',
    columns: 2,
    reloadable: false
  });
  // apps.run(); apps.loadMiniApps(); apps.unmount();
</script>

以主机页面权限执行并不存在沙盒 。 Render只信任Mini App快照. 内容安全 政策必须允许运行时间模块和资产来源; unsafe-eval 此渲染器不再需要.

动作按钮

ActionButtons 是Fusion Web的动作按钮组件的对应反应。 它启用了组标记的动作,并用其对话配置字段执行它们.

import { useRef } from 'react';
import { ActionButtons, type ActionButtonsHandle } from '@fusioni/client-sdk';
import '@fusioni/client-sdk/dist/index.css';

function Tools() {
  const actions = useRef<ActionButtonsHandle>(null);
  return (
    <ActionButtons
      ref={actions}
      agencyId="your-agency-id"
      tags={['tools']}
      apiBaseUrl="https://your-fusioni-api.com/api"
      accessToken="your-access-token"
      currentLanguage="en"
      showButtonsPanel
      actionInputFieldValues={{ '*': { customer_id: '123' }, report: { format: 'pdf' } }}
      actionEnabledStates={{ report: true }}
      onResponse={results => console.log(results)}
      onError={error => console.error(error)}
    />
  );
}

你可以提供 apiClient 而不是 URL/token 道具,或者使用 SDK 的初始客户端. 标记被修剪并被破解;要装入动作,既需要代理标记,也需要非空标记. 共享价值 '*' 被行动所压倒 key。只发送已宣布的字段。 应用值隐藏其控制并必须通过验证. actionEnabledStates 仅在动作 键 地图到 false。 。 。 .

配置文件格式为支持文本,数字,布尔,日期,JSON,列表,文件,即时和嵌入式聊天字段,包括默认,本地化标签和验证规则. 即使动作选择了配置文件的子集,也包含必要的字段. 文件字段接受最多8个文件,并通过执行请求发送数据 URL image 频道. 快速字段再利用 ChatInput,在验证失败后保留草稿,并提交 Enter 或 Send。 嵌入式聊天字段创建了配置关联的对话并再用SDK的聊天输入,消息,图像相册,出行执行和流出进度.

维持的行动有独立的对话历史和按页面路由和代理所显示的会话存储ID. conversationStorageKey 自定义存储前缀;代理总是附加. 历史修复没有发出任何响应事件,无法保存的存储会回到内存. results_sort 控制器转动命令 。 结果包括已消毒的HTML,带有画廊预览的图像,文档链接,执行时间和输出变量. onResponse 行动累积结果 show_results,而当前执行的结果除外.

Prop默认目的
showRunButtontrue显示表单的提交按钮; 及时发送仍然提交
showLoadingPaneltrue显示执行进度
showActionResulttrue显示并恢复结果; 隐藏时回调仍然会起火
showButtonsPanelfalse在动作卡周围添加一个容器
fullscreenfalse打开配置格式全屏
onFullscreenChange—— 说接收全屏切换, 包括 Escape
sidePanel 编号 : children—— 说在全屏显示窗体旁边的内容

裁判曝光 executeAction(actionOrIdOrKey), (中文(简体) ), submitFields(), (中文(简体) ), cancelFields(), (中文(简体) ), startNewConversation(actionOrIdOrKey?), (中文(简体) ), loadActions(),以及用于 selectedAction, (中文(简体) ), results,以及 conversationMessages。如果需要输入,执行动作将打开其形式。 更改代理或标签会取消待决请求并重放视图 。 卸载也会取消请求和定时器.

对于脚本-tag集成,使用与孤立的Shadow DOM风格相同的道具:

const actions = Fusioni.mountActionButtons('#actions', {
  agencyId: 'your-agency-id',
  tags: ['tools'],
  apiBaseUrl: 'https://your-fusioni-api.com/api',
  accessToken: 'your-access-token',
  onResponse: results => console.log(results),
});
// actions.executeAction('report'); // call after actions have loaded
// actions.startNewConversation();
// actions.unmount();

配置选项

FusioniSDK 配置

选项类型默认说明
apiBaseUrlstring需求您 Fusioni API 的基础 URL
agencyIdstring需求您的代理身份证明
accessTokenstringundefined认证的可选访问符
ownerIdstringSDK客户端ID或JWT oid目前的发送者融合所有者身份 。 通常从 SDK 客户端配置或 JWT 访问符自动解决
theme'light' | 'dark' | 'auto''light'UI 主题偏好( 稍后可通过 setTheme(中文(简体) )
language'en' | 'el''en'UI 复制语言( 稍后可通过 setLanguage(中文(简体) )
showThemeTogglebooleantrue在聊天标题中显示/ 隐藏主题切换按钮
showFullscreenTogglebooleantrue在聊天头显示/隐藏全屏切换按钮
showLanguageSwitcherbooleantrue在聊天头显示/ 隐藏语言切换器
showThoughtsbooleanfalse显示每个信件 thoughts 在相撞面板中的字段
showContextUsagebooleantrue当回答包含使用数据时,在聊天作曲器上方显示上下文窗口表.
showContextUsageDetailsbooleanfalse让用户打开上下文窗口表来查看每个代理符数,窗口大小,以及模型名. 要求数 showContextUsage。 。 。 .
position'bottom-right' | 'bottom-left' | 'top-right' | 'top-left''bottom-right'浮动按钮的位置
primaryColorstring'#6366f1'界面的主要颜色
showConversationListbooleantrue是否显示对白侧边栏
enableAudioRecordingbooleantrue启用语音信件记录
enableFileUploadbooleantrue启用文件上传功能
maxFileSizenumber10MB 最大文件大小
allowedFileTypesstring[]['image/*']允许上传的 MIME 类型
buttonVariant'minimal' | 'glass' | 'solid''glass'浮动启动器按钮样式

事件处理器

ChatWidget 选项

处理器类型说明
onMessageSent(message: FusioniMemoryMessage) => void当用户发送消息时调用
onMessageReceived(message: FusioniMemoryMessage) => void收到大赦国际的答复后打电话
onConversationCreated(conversation: Conversation) => void创建新对话时调用
onConversationDeleted(conversationId: string) => void对话被删除时调用
onError(error: Error) => void发生错误时调用

API 整合

SDK自动处理与您的 Fusioni API 端点的通信 :

  • 对话数字 : /api/conversation
  • 信件数字 : /api/mem
  • 巡回处决数字 : /api/journey/exec_async (承认)
  • 文件上传数字 : /api/upload
  • 服务器事件数字 : /api/sse/connect (单位:千美元)chat_stream 进展和 message_stream 答复)

样式

SDK包括可使用 CSS 变量定制的综合 CSS 样式 :

:root {
  --fusioni-primary: #6366f1;
  --fusioni-primary-light: #818cf8;
  --fusioni-primary-dark: #4f46e5;
  --fusioni-bg-primary: #ffffff;
  --fusioni-text-primary: #1e293b;
  /* ... more variables */
}

黑暗主题

SDK 当 theme: 'dark' 或者说 theme: 'auto' (带有系统偏好)设置.

浏览器支持

  • 颜色60+
  • Firefox 55+ (英语)
  • 第12条+
  • 边缘79+

录音要求

  • HTTPS 或本地主机( 安全上下文)
  • 麦克风权限
  • 有 Media Recorder API 支持的现代浏览器

发展

建造SDK

npm run build

发展模式

npm run dev

类型检查

npm run type-check

测试

npm test -- --runInBand

Mini App测试覆盖渲染,同步的生命周期清理,目录查询,后端传输,和脚本-tag上架. 搜索测试覆盖了Fusion API运输,自动完成交互,结果导航,pagination,外部元素绑定,取消,以及脚本-tag上架. SDK初始化测试涵盖流畅的链路,共享的默认,每个地貌的覆盖,明确的聊天挂起,独立实例,以及清理.

线性

npm run lint

实例

自定义样式

import React from 'react';
import { ChatWidget } from '@fusioni/client-sdk';
import './custom-chat-styles.css';

function App() {
  const config = {
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    theme: 'light',
    position: 'bottom-right',
    primaryColor: '#6366f1'
  };

  return (
    <div>
      <ChatWidget config={config} />
    </div>
  );
}
/* custom-chat-styles.css */
.fusioni-chat-widget {
  --fusioni-primary: #your-brand-color;
  --fusioni-bg-primary: #your-background-color;
}

.fusioni-floating-button {
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);
}

有条件渲染

import React, { useState } from 'react';
import { ChatWidget } from '@fusioni/client-sdk';

function App() {
  const [showChat, setShowChat] = useState(false);

  const config = {
    apiBaseUrl: 'https://your-fusioni-api.com',
    agencyId: 'your-agency-id',
    theme: 'light',
    position: 'bottom-right',
    primaryColor: '#6366f1'
  };
  
  return (
    <div>
      <button onClick={() => setShowChat(!showChat)}>
        Toggle Chat
      </button>
      {showChat && <ChatWidget config={config} />}
    </div>
  );
}

解决问题

共同问题

  1. 录音不工作

    • 确保您在 HTTPS 或本地主机
    • 检查麦克风权限
    • 验证 Media Recorder API 的浏览器支持
  2. 文件上传失败

    • 检查文件大小限制
    • 校验允许的文件类型
    • 确保适当的 API 端点配置
  3. 未出现的消息

    • 验证 API 基础 URL 和代理 ID
    • 检查网络连接
    • 浏览器检查出错

调试模式

SDK使用过 accessToken 向您的 Fusioni API 认证请求。 (Logging,如果存在的话,由您的应用/构建环境控制,而不是由符号值控制. )

const config = {
  // ... other config
  accessToken: 'your-access-token',
};

许可证

麻省理工学院许可证 - 详情见LICENSE文件.

支助

支助和问题:

  • 在 GitHub 上创建一期
  • 联系Fusioni团队

正在链接 npm

. . . . .

. . . . . . . . .

版本与发布记录

@fusioni/client-sdk 共发布 41 个版本,首次发布于 2026/03/26;过去 12 个月发布了 41 个版本。

版本发布日期距今
1.1.42latest2026/11/133 天前
1.1.412026/11/123 天前
1.1.402026/11/123 天前
1.1.392026/11/114 天前
1.1.382026/11/087 天前
1.1.372026/11/087 天前

关于 @fusioni/client-sdk 的常见问题

@fusioni/client-sdk 是什么?

Fusioni SDK 用于网络应用程序

如何安装 @fusioni/client-sdk?

在项目目录运行 npm install @fusioni/client-sdk,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=16.8.0)、react-dom(>=16.8.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@fusioni/client-sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@fusioni/client-sdk 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@fusioni/client-sdk 可以商用吗?

@fusioni/client-sdk 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@fusioni/client-sdk 的下载量有多少?

根据 npm 官方下载统计,@fusioni/client-sdk 在 2026/10/16 – 2026/11/14 这 30 天内被下载 3,094 次,日均约 103 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@fusioni/client-sdk 还在维护吗?

最新版本 1.1.42 发布于 2026/11/13(3 天前);至今共发布 41 个版本,其中过去 12 个月发布了 41 个;首次发布于 2026/03/26。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。