# 组件参考 (/docs/cloud/services/agent/embed/component-reference) `` 是一个 Web Component，把智能体对话界面嵌入你的页面。本页列出它的选项、方法和事件，以及对应的 React 组件。 ## 选项 [#选项] 通过 `setOptions` 传入。首次调用必须包含 `api.url`、`api.getToken` 和 `agent.name`，缺任何一项会抛出 `TypeError`。 | 选项 | 类型 | 说明 | | ------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------- | | `api.url` | `string` | 接口地址，必填。初始化后不能更改，否则抛出 `TypeError`；换后端请新建元素。 | | `api.getToken` | `(current: string \| null) => Promise` | 必填。返回嵌入令牌。`current` 是当前令牌，首次为 `null`；令牌到期前会再次调用。 | | `agent.name` | `string` | 必填。显示的智能体名称。 | | `agent.avatar` | `string` | 头像地址。 | | `layout` | `"inline" \| "sidebar" \| "popup" \| "modal"` | 默认 `inline`。 | | `launcher` | 见下表 | 默认：`inline` 为 `none`，其余布局为 `bubble`。 | | `header` | 见下表 | 顶栏内容。 | | `history.enabled` | `boolean` | 默认开启。设为 `false` 后隐藏历史会话入口，`showHistory()` 不再生效。 | | `width` | `number` | `sidebar` 布局的宽度，单位 CSS 像素，默认 400。 | | `theme` | 见下表 | 外观。 | | `startScreen` | 见下表 | 空会话时的开场。 | | `composer.placeholder` | `string` | 输入框占位文字，默认「发送消息」。 | | `composer.attachments.enabled` | `boolean` | 默认开启。设为 `false` 后不能选择、粘贴或拖入文件。 | | `disclaimer` | `string` | 对话区的免责声明。 | | `footer` | `string` | 对话区底部的文字。 | | `autoScroll` | `boolean` | 控制新内容到达时是否自动滚动。 | | `locale` | `"zh" \| "en"` | 界面语言。未指定时先取宿主页面的 `lang`，再取浏览器语言；`zh` 开头的语言标签使用中文，其余使用英文，无语言信息时使用英文。 | ### launcher [#launcher] | 字段 | 类型 | 说明 | | ---------- | --------------------------------- | ------- | | `type` | `"none" \| "bubble" \| "mascot"` | 必填。 | | `image` | `string` | 图片地址。 | | `position` | `"bottom-right" \| "bottom-left"` | 启动按钮位置。 | | `label` | `string` | 按钮文字。 | ### header [#header] | 字段 | 类型 | 说明 | | ---------- | ----------------------------------------------- | --------------------------------------------------------- | | `title` | `string` | 标题。 | | `subtitle` | `string` | 副标题。 | | `icon` | `string` | 受支持的 Lucide 图标名，或图片地址。 | | `actions` | `{ id: string; icon: string; label: string }[]` | 自定义顶栏按钮。点击时触发 `praxis.header.action`，`detail` 为 `{ id }`。 | ### theme [#theme] | 字段 | 类型 | 说明 | | ------------- | ------------------------------------------ | ------------------------------------------------------------------------------- | | `colorScheme` | `"light" \| "dark" \| "system"` | `system` 跟随浏览器的深浅色设置。 | | `accent` | `string` | 主色。必须是不透明的明确 CSS 颜色；含 `var()`、`currentcolor` 等不被接受，会抛出 `TypeError`。前景色按对比度自动选择。 | | `surface` | `string` | 背景色，限制同 `accent`。 | | `grayscale` | `"neutral" \| "warm" \| "cool"` | 灰阶色板。 | | `radius` | `"none" \| "sm" \| "md" \| "lg" \| "full"` | 圆角，分别对应 0、4、10、18、9999 像素。 | | `density` | `"compact" \| "normal" \| "spacious"` | 间距，基础单位分别为 3、4、5 像素。 | | `fontFamily` | `string` | 字体族。空字符串或含 `; { } < >` 会抛出 `TypeError`。 | | `fontSize` | `number` | 基础字号，单位像素，必须为正的有限数，否则抛出 `RangeError`。 | 未设置 `accent` 时使用默认绿色（浅色 `#167A43`，深色 `#30a46c`）。 ### startScreen [#startscreen] | 字段 | 类型 | 说明 | | ---------- | ------------------------------------- | -------------------------------- | | `greeting` | `string` | 问候语。 | | `prompts` | `{ label: string; prompt: string }[]` | 推荐问题。最多显示前 4 个；点击后立即发送 `prompt`。 | ## 更新选项 [#更新选项] `setOptions(partial)` 把传入的字段合并进当前配置：嵌套对象逐层合并，数组整体替换，显式传 `undefined` 会重置该字段。`api.url` 不能改。 ## 方法 [#方法] 在元素上直接调用。 | 方法 | 说明 | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `setOptions(partial)` | 初始化或更新选项。 | | `sendUserMessage(text)` | 以用户身份发送一条消息，返回 `Promise`，值为 `"accepted"`、`"rejected"` 或 `"unknown"`。文本为空或超长、有待处理的审批、历史仍在加载、输入框不可用时返回 `rejected`。 | | `setComposerValue(text)` | 替换输入框中的草稿。 | | `focusComposer()` | 聚焦输入框。历史面板打开时不生效。 | | `setThreadId(id)` | 切换到指定会话；传 `null` 回到空会话。同时关闭历史面板，会话变化时触发 `praxis.thread.change`。 | | `showHistory()` / `hideHistory()` | 打开或关闭历史面板。 | | `open()` / `close()` / `toggle()` | 展开或收起面板。`inline` 布局下没有效果。 | ## 事件 [#事件] 事件都是冒泡、可穿过 Shadow DOM 的 `CustomEvent`。 | 事件 | `detail` | 何时触发 | | ---------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `praxis.ready` | 无 | 界面已挂载。不代表网络认证已成功。 | | `praxis.error` | `KitError` 或 `{ message: string }` | 传输失败时为 `KitError`（含 `code`、`status`、`retryable`、`message`）；会话加载或发送失败时为 `{ message }`。错误码见[限制与错误](/docs/cloud/services/agent/embed/limits-and-errors)。 | | `praxis.thread.change` | `{ threadId: string \| null }` | 当前会话变化，包括首条消息创建出新会话。 | | `praxis.response.start` | 无 | 智能体开始回复。 | | `praxis.response.end` | 无 | 回复结束。 | | `praxis.open` / `praxis.close` | 无 | 面板展开或收起。 | | `praxis.history.open` / `praxis.history.close` | 无 | 历史面板打开或关闭。 | | `praxis.header.action` | `{ id: string }` | 点击了 `header.actions` 中的按钮。 | ```js const agent = document.querySelector("praxis-agent"); agent.addEventListener("praxis.thread.change", event => { console.log(event.detail.threadId); }); ``` ## React [#react] React 组件来自 `@deepractice-ai/praxis-kit-react`，需要 React 18 或 19。 ```tsx import { PraxisAgent, usePraxisAgent } from "@deepractice-ai/praxis-kit-react"; export function Chat({ options, getToken }) { const { ref, control } = usePraxisAgent(); return ( control.open()} /> ); } ``` ### 属性 [#属性] | 属性 | 类型 | 说明 | | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------- | | `getToken` | `(current: string \| null) => Promise` | 必填。作用同 `api.getToken`。 | | `options` | 与上文选项相同，但去掉 `api.getToken` | 提供 `api.url` 和 `agent.name` 后才会初始化。不传则渲染一个未配置的元素。 | | `layout` | 同 `layout` 选项 | 优先于 `options.layout`。 | | `launcher` | `"none" \| "bubble" \| "mascot"` | 优先于 `options.launcher.type`，其余启动按钮字段保留。 | | `className`、`style` | | 作用于宿主元素。 | | `onReady`、`onError`、`onThreadChange`、`onResponseStart`、`onResponseEnd`、`onOpen`、`onClose`、`onHistoryOpen`、`onHistoryClose`、`onHeaderAction` | 回调，参数为原始 `CustomEvent` | 对应上表事件，`detail` 相同。 | `layout` 和 `launcher` 请通过属性或 `options` 设置，不要写成 HTML 属性。更新 `options` 时请保持嵌套对象引用稳定（例如 `useMemo`），否则每次渲染都会触发更新。 ### 控制句柄 [#控制句柄] `ref` 暴露的句柄包含 `sendUserMessage`、`setThreadId`、`setComposerValue`、`showHistory`、`hideHistory`、`focusComposer`、`open`、`close`、`toggle`，参数与上文方法一致。在 `onReady` 之前，以及组件卸载之后调用，会同步抛出 `Error("PraxisAgent is not ready. Wait for onReady before calling control methods.")`，调用不会排队。 `usePraxisAgent()` 返回稳定的 `{ ref, control }`：把 `ref` 传给组件，在组件外用 `control` 调用方法。 ### 前端工具与页面上下文 [#前端工具与页面上下文] `usePraxisTool`、`usePraxisReadable`、`PraxisProvider` 和 `onClientTool`、`onToolChange`、`onLog` 见[前端工具与页面上下文](/docs/cloud/services/agent/embed/client-tools)。 ## iframe 加载器 [#iframe-加载器] 加载器负责令牌请求和跨窗口通信。属性与接入示例见[嵌入方式](/docs/cloud/services/agent/embed/methods)。加载后可用 `window.PraxisKit.get("ABC123")` 取得句柄（换成智能体短号），调用 `open()`、`close()`、`toggle()`；远程组件方法返回 Promise。前端工具通过句柄的 `onClientTool(handler)` 注册。