> ## Documentation Index > Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt > Use this file to discover all available pages before exploring further. # OpenUI > 使用 OpenUI 组件库和 openui-lang 生成完整的交互式仪表板和报告 export const ExampleEmbed = ({example, theme, minHeight = 500, maxHeight = 700}) => { var PROD_BASE = "https://ui-patterns.langchain.com"; var iframeCache = (() => { const g = globalThis; if (!g.__lcExampleIframeCache) { g.__lcExampleIframeCache = new Map(); } return g.__lcExampleIframeCache; })(); function detectPageTheme() { if (typeof document === "undefined") return "light"; const root = document.documentElement; if (root.classList.contains("dark") || root.getAttribute("data-theme") === "dark" || root.style.colorScheme === "dark") { return "dark"; } return "light"; } var LOCAL_BASE = "http://localhost"; var LOCAL_PORTS = { "ai-elements": 4600, "assistant-ui": 4500 }; function isLocalhost() { return typeof location !== "undefined" && (location.hostname === "localhost" || location.hostname === "127.0.0.1"); } var EMBED_CSS = ` [data-lc-ee] .lc-border{border-color:#B8DFFF} [data-lc-ee].dark .lc-border{border-color:#1A2740} [data-lc-ee] .lc-bg-surface{background-color:white} [data-lc-ee].dark .lc-bg-surface{background-color:#0B1120} [data-lc-ee] .lc-bg-wash{background-color:#F2FAFF} [data-lc-ee].dark .lc-bg-wash{background-color:#030710} [data-lc-ee] .lc-spinner{border-color:#B8DFFF;border-top-color:#7FC8FF} [data-lc-ee].dark .lc-spinner{border-color:#1A2740;border-top-color:#7FC8FF} `; const slotRef = useRef(null); const [ready, setReady] = useState(() => Boolean(iframeCache.get(example)?.iframe)); const [iframeHeight, setIframeHeight] = useState(minHeight); const [pageTheme, setPageTheme] = useState(detectPageTheme); const effectiveTheme = theme ?? pageTheme; const effectiveThemeRef = useRef(effectiveTheme); effectiveThemeRef.current = effectiveTheme; useEffect(() => { if (document.getElementById("lc-ee-css")) return; const style = document.createElement("style"); style.id = "lc-ee-css"; style.textContent = EMBED_CSS; document.head.appendChild(style); }, []); useEffect(() => { setPageTheme(detectPageTheme()); const observer = new MutationObserver(() => setPageTheme(detectPageTheme())); observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class", "data-theme", "style"] }); return () => observer.disconnect(); }, []); useEffect(() => { const useLocal = isLocalhost(); const localPort = LOCAL_PORTS[example]; const src = useLocal && localPort ? `${LOCAL_BASE}:${localPort}/` : `${PROD_BASE}/${example}/`; let cached = iframeCache.get(example); if (cached?.hideTimer) { clearTimeout(cached.hideTimer); cached.hideTimer = void 0; } if (!cached) { const iframe = document.createElement("iframe"); iframe.src = src; iframe.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms"); iframe.setAttribute("allow", "clipboard-write"); iframe.title = `${example} example`; Object.assign(iframe.style, { position: "fixed", border: "none", visibility: "hidden", pointerEvents: "auto", zIndex: "1", borderRadius: "15px" }); document.body.appendChild(iframe); cached = { iframe }; iframeCache.set(example, cached); window.addEventListener("message", e => { if (e.data?.type === "RESIZE" && iframeCache.get(example)?.iframe === iframe) { const h = Math.min(maxHeight, Math.max(minHeight, e.data.height)); setIframeHeight(h); } }); iframe.addEventListener("load", () => { iframe.style.visibility = "visible"; setReady(true); try { iframe.contentWindow?.postMessage({ type: "CHAT_LC_SET_THEME", theme: effectiveThemeRef.current }, "*"); } catch {} }); } else { cached.iframe.style.visibility = "visible"; setReady(true); } function syncPosition() { const slot = slotRef.current; if (!slot) return; const rect = slot.getBoundingClientRect(); const {style} = cached.iframe; style.top = `${rect.top}px`; style.left = `${rect.left}px`; style.width = `${rect.width}px`; style.setProperty("height", `${rect.height}px`, "important"); } syncPosition(); const ro = new ResizeObserver(syncPosition); if (slotRef.current) ro.observe(slotRef.current); document.addEventListener("scroll", syncPosition, { passive: true, capture: true }); window.addEventListener("resize", syncPosition, { passive: true }); let frameCount = 0; let rafId = 0; function initialSync() { syncPosition(); if (++frameCount < 5) rafId = requestAnimationFrame(initialSync); } rafId = requestAnimationFrame(initialSync); return () => { cancelAnimationFrame(rafId); ro.disconnect(); document.removeEventListener("scroll", syncPosition, { capture: true }); window.removeEventListener("resize", syncPosition); cached.hideTimer = setTimeout(() => { if (cached?.iframe) cached.iframe.style.visibility = "hidden"; }, 200); }; }, [example, minHeight, maxHeight]); useEffect(() => { const cached = iframeCache.get(example); if (!cached?.iframe || !ready) return; try { cached.iframe.contentWindow?.postMessage({ type: "CHAT_LC_SET_THEME", theme: effectiveTheme }, "*"); } catch {} }, [effectiveTheme, ready, example]); return
{}
{!ready &&
}
; }; [OpenUI](https://github.com/openuidev) 是一个生成式 UI 库，它允许语言模型以一种名为 **openui-lang** 的声明式格式生成完整的交互式 UI。代理不是返回聊天消息，而是返回一个包含卡片、图表、表格、选项卡和表单的组件树，然后由 `Renderer` 将其转换为真实的 React UI。 这种集成非常适合数据丰富的输出，如报告、仪表板和数据探索器，其中模型既是数据分析师又是 UI 设计师。 ## 工作原理 1. **生成系统提示：** 在启动时调用一次 `openuiLibrary.prompt()`；它会生成一个完整的 openui-lang 参考，模型使用它来编写有效的组件树 2. **在第一条消息时注入：** 在新对话开始时，将系统提示作为初始系统消息发送 3. **模型编写 openui-lang：** 模型以类似 `root = Stack([header, kpis, chart])` 的程序形式响应，而不是散文 4. **使用 `Renderer` 渲染：** 将文本传递给 OpenUI 的 `Renderer` 和组件库；它会解析并渲染该树 ```mermaid theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} %%{ init: { "fontFamily": "monospace", "flowchart": { "curve": "curve" } } }%% graph LR PROMPT["openuiLibrary.prompt()"] AGENT["createAgent()"] STREAM["useStream()"] RENDERER["Renderer"] PROMPT --"system message"--> AGENT AGENT --"openui-lang text"--> STREAM STREAM --"ai message content"--> RENDERER ``` ## 安装 ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} npm install @langchain/react @openuidev/react-ui @openuidev/react-headless @openuidev/react-lang ``` OpenUI 需要 React 19+ 和 [`zustand`](https://www.npmjs.com/package/zustand)。前端代码仅限 React；LangGraph 代理后端可以用 TypeScript 或 Python 编写。 ## 导入组件样式 在您的 CSS 入口点或直接在根组件中导入 OpenUI 的捆绑样式： ```css theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} @import "@openuidev/react-ui/components.css"; @import "@openuidev/react-ui/styles/index.css"; ``` ## 生成系统提示 OpenUI 提供了一个 `openuiLibrary.prompt()` 函数，用于生成完整的 openui-lang 参考，包含所有组件签名、语法规则、流式传输提示和示例。在模块加载时调用一次： ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { openuiLibrary, openuiPromptOptions } from "@openuidev/react-ui/genui-lib"; // 生成完整的 openui-lang 系统提示。在启动时调用一次， // 而不是在组件内部，以避免在每次渲染时重新计算。 const SYSTEM_PROMPT = openuiLibrary.prompt({ ...openuiPromptOptions, preamble: "You are a report generator. When asked for a report, produce a detailed, " + "data-rich report using openui-lang: executive summary, KPI cards, charts, " + "tables, and multiple sections. Your ENTIRE response must be raw openui-lang " + "— no code fences, no markdown, no prose.", }); ``` `preamble` 会覆盖默认的角色设定。添加 `additionalRules` 以注入特定任务的约束： ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} const SYSTEM_PROMPT = openuiLibrary.prompt({ ...openuiPromptOptions, preamble: "You are a report generator...", additionalRules: [ ...(openuiPromptOptions.additionalRules ?? []), "Always end the report with 3–4 follow-up query buttons using " + "Button({ type: 'continue_conversation' }, 'secondary') inside a " + "Card([CardHeader('Explore Further'), Buttons([...])], 'sunk').", ], }); ``` ## 通过 useStream 注入系统提示 将系统提示作为每个新线程的第一条消息发送。检查 `stream.messages.length === 0` 以检测新线程，并在前面添加一条 `system` 消息： ```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { useCallback } from "react"; import { useStream } from "@langchain/react"; const SYSTEM_PROMPT = openuiLibrary.prompt({ ... }); export function App() { const stream = useStream({ apiUrl: import.meta.env.VITE_LANGGRAPH_API_URL ?? "/api/langgraph", assistantId: "my_agent", reconnectOnMount: true, fetchStateHistory: true, }); const handleSubmit = useCallback( (text: string) => { // 仅在新线程的第一条消息时注入系统提示。 // 后续消息在其持久化历史记录中已包含它。 const isNewThread = stream.messages.length === 0; stream.submit({ messages: [ ...(isNewThread ? [{ type: "system", content: SYSTEM_PROMPT }] : []), { type: "human", content: text }, ], }); }, [stream], ); // ... } ``` ## 使用 Renderer 渲染 将 AI 消息的文本内容直接传递给 `Renderer` 以及 `openuiLibrary`： ```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { Renderer } from "@openuidev/react-lang"; import { openuiLibrary } from "@openuidev/react-ui/genui-lib"; import { AIMessage } from "langchain"; function MessageList({ messages, isLoading }) { const lastAiIdx = messages.reduce( (acc, msg, i) => (AIMessage.isInstance(msg) ? i : acc), -1, ); return messages.map((msg, i) => { if (AIMessage.isInstance(msg)) { const text = typeof msg.content === "string" ? msg.content : ""; return ( ); } // ... 人类消息气泡 }); } ``` 在活动流期间传递 `isStreaming={true}`，以便 Renderer 在定义到达时优雅地处理未解析的引用。 ## openui-lang 格式 模型编写的是程序，而不是 JSON 规范。每条语句都是一个赋值；`root` 是入口点。官方提示会教模型这种格式，包括提升（hoisting）——先编写 `root`，这样 UI 外壳会立即出现： ``` root = Stack([header, execSummary, kpis, marketSection]) header = CardHeader("State of AI in 2025", "Comprehensive Analysis") execSummary = MarkDownRenderer("## Executive Summary\n\nThe AI market reached...") kpi1 = Card([CardHeader("$826B", "Global Market"), TextContent("42% YoY", "small")], "sunk") kpi2 = Card([CardHeader("78%", "Adoption"), TextContent("Fortune 500", "small")], "sunk") kpis = Stack([kpi1, kpi2], "row", "m", "stretch", "start", true) col1 = Col("Segment", "string") col2 = Col("Revenue ($B)", "number") tbl = Table([col1, col2], [["Generative AI", 286], ["ML Infra", 198]]) s1 = Series("Revenue", [286, 198, 147]) ch1 = BarChart(["Gen AI", "ML Infra", "Vision"], [s1]) marketSection = Card([CardHeader("Market Breakdown"), tbl, ch1]) ``` 启用提升（推荐）时，`root` 行会首先编写，这样页面结构会立即出现，并且每个部分会在模型定义它时逐步填充。 ## 渐进式渲染工具 直接将 `useStream` 连接到 `Renderer` 会导致在每个流式令牌上重新渲染，并且每个响应会产生数百次无操作的重新解析。这会导致图表组件在其数据尚未到达时崩溃。以下工具解决了这些问题： | 问题 | 解决方案 | | ------------------ | ----------------------------------------------------------------------- | | **部分字符串字面量** | `truncateAtOpenString` / `closeOrTruncateOpenString` — 在解析前丢弃或关闭不完整的字符串 | | **令牌中间的变动** | `useStableText` — 仅在完整语句边界（`name = Expr(…)`) 而非每个令牌时才允许 Renderer 更新 | | **图表空数据崩溃** | `chartDataRefsResolved` — 在将图表包含在快照中之前，验证其 `Series` 和标签数组已定义 | | **尚无 `root` / 回退** | `buildProgressiveRoot` — 当模型尚未编写 `root` 时，从顶级变量合成一个 `root = Stack([…])` | | **蛇形命名标识符** | `sanitizeIdentifiers` — 解析器仅接受驼峰命名法；转换模型发出的任何 `snake_case` 名称 | 将完整代码块复制到您的项目中，并将 `stable` 传递给 ``： ````tsx expandable theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { useCallback, useEffect, useMemo, useRef, useState, } from "react"; import { type ActionEvent, BuiltinActionType, Renderer, } from "@openuidev/react-lang"; import { openuiLibrary } from "@openuidev/react-ui/genui-lib"; /** 剥离模型可能发出的任何 markdown 代码围栏。 */ function stripCodeFence(text: string): string { return text .replace(/^```[a-z]*\r?\n?/i, "") .replace(/\n?```\s*$/i, "") .trim(); } /** * openui-lang 解析器仅接受驼峰命名标识符。 * 转换模型发出的任何蛇形命名变量名；字符串内容不受影响。 */ function sanitizeIdentifiers(text: string): string { const toCamel = (s: string) => s.replace(/_([a-zA-Z0-9])/g, (_, c: string) => c.toUpperCase()); const snakeVars: string[] = []; for (const m of text.matchAll(/^([a-zA-Z][a-zA-Z0-9]*(?:_[a-zA-Z0-9]+)+)\s*=/gm)) { if (!snakeVars.includes(m[1])) snakeVars.push(m[1]); } if (snakeVars.length === 0) return text; let result = ""; let inStr = false; let i = 0; while (i < text.length) { if (text[i] === "\\" && inStr) { result += text[i] + (text[i + 1] ?? ""); i += 2; continue; } if (text[i] === '"') { inStr = !inStr; result += text[i++]; continue; } if (!inStr) { let replaced = false; for (const v of snakeVars) { if (text.startsWith(v, i) && !/[a-zA-Z0-9_]/.test(text[i + v.length] ?? "")) { result += toCamel(v); i += v.length; replaced = true; break; } } if (!replaced) result += text[i++]; } else { result += text[i++]; } } return result; } /** * 遍历文本，跟踪未关闭的字符串。如果文本在字符串中间结束，则截断到最后一个安全的换行符—— * 这可以防止部分字符串字面量消耗我们稍后合成的任何 `root = Stack(…)` 行。 */ function truncateAtOpenString(text: string): string { let inStr = false; let lastSafeNewline = 0; for (let i = 0; i < text.length; i++) { const ch = text[i]; if (ch === "\\" && inStr) { i++; continue; } if (ch === '"') { inStr = !inStr; continue; } if (ch === "\n" && !inStr) lastSafeNewline = i; } return inStr ? text.slice(0, lastSafeNewline) : text; } /** * 类似于 truncateAtOpenString，但当部分行是 TextContent 语句时，会合成一个闭合的 `")`。 * 这允许文本逐令牌渲染，而所有其他部分字符串行仍被截断。 */ function closeOrTruncateOpenString(text: string): string { let inStr = false; let lastSafeNewline = 0; for (let i = 0; i < text.length; i++) { const ch = text[i]; if (ch === "\\" && inStr) { i++; continue; } if (ch === '"') { inStr = !inStr; continue; } if (ch === "\n" && !inStr) lastSafeNewline = i; } if (!inStr) return text; const safeText = lastSafeNewline > 0 ? text.slice(0, lastSafeNewline) : ""; const partialLine = text.slice(lastSafeNewline > 0 ? lastSafeNewline + 1 : 0); if (/^[a-zA-Z][a-zA-Z0-9]*\s*=\s*TextContent\(/.test(partialLine)) { return (lastSafeNewline > 0 ? safeText + "\n" : "") + partialLine + '")'; } return safeText; } /** 计算以 `)` 或 `]` 结尾的完整赋值语句的行数。 */ function countCompleteStatements(text: string): number { let count = 0; for (const line of text.split("\n")) { const t = line.trimEnd(); if ((t.endsWith(")") || t.endsWith("]")) && /^[a-zA-Z]/.test(t)) count++; } return count; } const CHART_TYPES = new Set([ "BarChart", "LineChart", "AreaChart", "RadarChart", "HorizontalBarChart", "PieChart", "RadialChart", "SingleStackedBarChart", "ScatterChart", ]); const OPENUI_KEYWORDS = new Set([ "true", "false", "null", "grouped", "stacked", "linear", "natural", "step", "pie", "donut", "string", "number", "action", "row", "column", "card", "sunk", "clear", "info", "warning", "error", "success", "neutral", "danger", "start", "end", "center", "between", "around", "evenly", "stretch", "baseline", "small", "default", "large", "none", "xs", "s", "m", "l", "xl", "horizontal", "vertical", ]); /** * 图表组件（recharts）在标签或系列属性未解析时，会因对 null 使用 `.map()` 而崩溃。 * 在提交稳定快照之前，验证文本中的每个图表的所有数据变量都已定义。 */ function chartDataRefsResolved(text: string): boolean { const lines = text.split("\n"); const complete = new Set(); for (const line of lines) { const t = line.trimEnd(); const m = t.match(/^([a-zA-Z][a-zA-Z0-9]*)\s*=/); if (m && (t.endsWith(")") || t.endsWith("]"))) complete.add(m[1]); } for (const line of lines) { const t = line.trimEnd(); const m = t.match(/^([a-zA-Z][a-zA-Z0-9]*)\s*=\s*([A-Z][a-zA-Z0-9]*)\(/); if (!m || !CHART_TYPES.has(m[2]) || !t.endsWith(")")) continue; const rhs = t.slice(t.indexOf("=") + 1).replace(/"(?:[^"\\]|\\.)*"/g, '""'); for (const [, name] of rhs.matchAll(/\b([a-zA-Z][a-zA-Z0-9]*)\b/g)) { if (/^[a-z]/.test(name) && !OPENUI_KEYWORDS.has(name) && !complete.has(name)) return false; } } return true; } /** * 如果模型尚未编写 `root = Stack(…)`，则从顶级变量（那些已定义但未在任何其他表达式内部引用的变量） * 合成一个。即使模型最后编写 root，这也能实现渐进式渲染。 */ function buildProgressiveRoot(text: string): string { if (!text) return text; const safe = truncateAtOpenString(text); if (/^root\s*=/m.test(safe)) return safe; const defs: string[] = []; const seen = new Set(); for (const m of safe.matchAll(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*=/gm)) { if (!seen.has(m[1])) { defs.push(m[1]); seen.add(m[1]); } } if (defs.length === 0) return safe; const referenced = new Set(); for (const line of safe.split("\n")) { const thisVar = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*=/)?.[1]; const stripped = line.replace(/"(?:[^"\\]|\\.)*"/g, '""'); for (const v of defs) { if (v !== thisVar && new RegExp(`\\b${v}\\b`).test(stripped)) referenced.add(v); } } const topLevel = defs.filter((v) => !referenced.has(v)); const rootVars = topLevel.length > 0 ? topLevel : defs; return `${safe.trimEnd()}\nroot = Stack([${rootVars.join(", ")}], "column", "l")`; } /** * 仅在至少有一个新的*完整*语句到达时才允许 Renderer 更新。这消除了流式传输期间数百次无操作的重新解析。 * * 特殊情况：TextContent 行逐令牌更新（通过 closeOrTruncate），因此文本可以渐进式渲染，而无需等待整行完成。 */ function useStableText(raw: string, isStreaming: boolean): string { const [stable, setStable] = useState(""); const lastCount = useRef(0); useEffect(() => { const safe = truncateAtOpenString(raw); // 严格模式 — 仅用于计数 const enhanced = closeOrTruncateOpenString(raw); // 显示模式 — 关闭部分 TextContent if (!isStreaming) { setStable(enhanced); return; } const count = countCompleteStatements(safe); const newComplete = count > lastCount.current && chartDataRefsResolved(safe); const partialTextContent = enhanced !== safe; if (newComplete || partialTextContent) { if (newComplete) lastCount.current = count; setStable(enhanced); } }, [raw, isStreaming]); return stable; } function AIMessageView({ raw, isStreaming, onSubmit, }: { raw: string; isStreaming: boolean; onSubmit: (text: string) => void; }) { const stable = useStableText(raw, isStreaming); const processed = useMemo(() => buildProgressiveRoot(stable), [stable]); const handleAction = useCallback( (event: ActionEvent) => { if (event.type === BuiltinActionType.ContinueConversation) { onSubmit(event.humanFriendlyMessage); } }, [onSubmit], ); if (!processed) return null; return ( ); } export function MessageList({ messages, isLoading, onSubmit }) { const lastAiIdx = messages.reduce( (acc, msg, i) => (msg.getType() === "ai" ? i : acc), -1, ); return messages.map((msg, i) => { if (msg.getType() === "human") { return (
{typeof msg.content === "string" ? msg.content : ""}
); } if (msg.getType() === "ai") { const raw = sanitizeIdentifiers( stripCodeFence(typeof msg.content === "string" ? msg.content : ""), ); if (!raw) return null; return (
); } return null; }); } ```` ## 后续查询 OpenUI 的 `Button` 组件支持 `continue_conversation` 动作类型。当用户点击后续按钮时，`Renderer` 会触发 `onAction`，上面的 `AIMessageView` 会将按钮的标签作为下一条用户消息提交，其代码路径与在输入框中输入完全相同。 通过系统提示中的 `additionalRules` 为每个报告添加“进一步探索”部分： ``` followUp1 = Button("Compare AI leaders 2024 vs 2025", { type: "continue_conversation" }, "secondary") followUp2 = Button("Global AI investment breakdown", { type: "continue_conversation" }, "secondary") followUpBtns = Buttons([followUp1, followUp2], "row") followUpCard = Card([CardHeader("Explore Further"), followUpBtns], "sunk") root = Stack([..., followUpCard]) ``` ## 最佳实践 * **在模块加载时生成系统提示：** 不要在 React 组件内部；提示有几千字节，应该只计算一次 * **仅在新线程时注入系统提示：** 检查 `stream.messages.length === 0`，并在后续轮次跳过注入，以避免在线程历史中重复提示 * **使用提升顺序：** 先编写 `root = Stack([...])`；UI 外壳会立即出现，并且各部分会在模型定义每个部分时逐步填充 * **基于完整语句进行门控：** 避免在每个令牌上重新渲染 Renderer；仅在完整语句（`name = ComponentCall(...)`）到达时才更新 * **渲染前验证图表数据：** 图表组件需要在包含在稳定快照中之前定义其 `Series` 和标签数组 * **保持驼峰命名变量名：** openui-lang 解析器仅接受驼峰命名标识符；在系统提示的 `additionalRules` 中强化这一点 ***
[将这些文档](/use-these-docs)通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。 [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/frontend/integrations/openui.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。