component-rendering

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Component Rendering

组件渲染

Handles streaming props and persistent component state.

处理流式属性与组件持久化状态。

Quick Start

快速开始

tsx

const { streamStatus, propStatus } = useTamboStreamStatus<Props>();

if (streamStatus.isPending) return <Skeleton />;
if (streamStatus.isStreaming) return <LoadingIndicator />;

tsx

const { streamStatus, propStatus } = useTamboStreamStatus<Props>();

if (streamStatus.isPending) return <Skeleton />;
if (streamStatus.isStreaming) return <LoadingIndicator />;

Stream Status

流式状态

Track overall and per-prop streaming status:

tsx

import { useTamboStreamStatus } from "@tambo-ai/react";

function MyComponent({ title, items }: Props) {
  const { streamStatus, propStatus } = useTamboStreamStatus<Props>();

  // Global status
  if (streamStatus.isPending) return <Skeleton />;
  if (streamStatus.isStreaming) return <LoadingIndicator />;
  if (streamStatus.isError) return <Error message={streamStatus.streamError} />;

  // Per-prop status
  return (
    <h2 className={propStatus.title?.isStreaming ? "animate-pulse" : ""}>
      {title}
    </h2>
  );
}

跟踪全局及单个属性的流式传输状态：

tsx

import { useTamboStreamStatus } from "@tambo-ai/react";

function MyComponent({ title, items }: Props) {
  const { streamStatus, propStatus } = useTamboStreamStatus<Props>();

  // 全局状态
  if (streamStatus.isPending) return <Skeleton />;
  if (streamStatus.isStreaming) return <LoadingIndicator />;
  if (streamStatus.isError) return <Error message={streamStatus.streamError} />;

  // 单个属性状态
  return (
    <h2 className={propStatus.title?.isStreaming ? "animate-pulse" : ""}>
      {title}
    </h2>
  );
}

StreamStatus Properties

StreamStatus 属性

Property	Description
`isPending`	No tokens received yet
`isStreaming`	Active streaming in progress
`isSuccess`	All props finished without error
`isError`	Fatal error occurred
`streamError`	Error object if failed

属性	描述
`isPending`	尚未接收任何令牌
`isStreaming`	正在进行主动流式传输
`isSuccess`	所有属性已完成传输且无错误
`isError`	发生致命错误
`streamError`	传输失败时的错误对象

PropStatus (per-prop)

PropStatus（单个属性）

Property	Description
`isPending`	No tokens for this prop yet
`isStreaming`	Prop has partial content
`isSuccess`	Prop finished streaming
`error`	Error for this prop (if any)

属性	描述
`isPending`	尚未接收该属性的任何令牌
`isStreaming`	该属性已有部分内容
`isSuccess`	该属性已完成流式传输
`error`	该属性的错误信息（如有）

Component State

组件状态

Make state visible to AI and persist across sessions:

tsx

import { useEffect } from "react";
import { useTamboComponentState, useTamboStreamStatus } from "@tambo-ai/react";

interface Props {
  title?: string;
}

function EditableCard({ title: streamedTitle }: Props) {
  const [title, setTitle, setFromProp] = useTamboComponentState("title", "");
  const { streamStatus } = useTamboStreamStatus();

  // Sync streamed prop to state
  useEffect(() => {
    if (streamedTitle !== undefined) {
      setFromProp(streamedTitle);
    }
  }, [streamedTitle, setFromProp]);

  return (
    <input
      value={title}
      onChange={(e) => setTitle(e.target.value)}
      disabled={streamStatus.isStreaming}
    />
  );
}

使状态对AI可见并在会话间持久化：

tsx

import { useEffect } from "react";
import { useTamboComponentState, useTamboStreamStatus } from "@tambo-ai/react";

interface Props {
  title?: string;
}

function EditableCard({ title: streamedTitle }: Props) {
  const [title, setTitle, setFromProp] = useTamboComponentState("title", "");
  const { streamStatus } = useTamboStreamStatus();

  // 将流式属性同步到状态
  useEffect(() => {
    if (streamedTitle !== undefined) {
      setFromProp(streamedTitle);
    }
  }, [streamedTitle, setFromProp]);

  return (
    <input
      value={title}
      onChange={(e) => setTitle(e.target.value)}
      disabled={streamStatus.isStreaming}
    />
  );
}

useTamboComponentState API

tsx

const [value, setValue, setFromProp] = useTamboComponentState(
  key,
  initialValue,
);

Return	Description
`value`	Current state value
`setValue`	Update state (marks as user-edited)
`setFromProp`	Update from streaming props (doesn't mark as user-edited)

tsx

const [value, setValue, setFromProp] = useTamboComponentState(
  key,
  initialValue,
);

返回值	描述
`value`	当前状态值
`setValue`	更新状态（标记为用户编辑）
`setFromProp`	通过流式属性更新状态（不标记为用户编辑）

When to Use Component State

何时使用组件状态

User-editable content AI should see
Form inputs requiring persistence
State that survives page reloads
Streaming props that user can modify after generation

AI需要可见的用户可编辑内容
需要持久化的表单输入
页面刷新后仍保留的状态
用户可在生成后修改的流式属性

Streaming Best Practices

流式传输最佳实践

Make props optional in Zod schema:

tsx

z.object({
  title: z.string().optional().describe("Card title"),
  items: z.array(z.string()).optional(),
});

Show skeletons for missing data, not errors
Use optional chaining:
```
items?.map(...)
```
Disable interactions until
```
streamStatus.isSuccess
```

在Zod schema中设置属性为可选：

tsx

z.object({
  title: z.string().optional().describe("Card title"),
  items: z.array(z.string()).optional(),
});

为缺失数据显示骨架屏，而非错误提示
使用可选链操作：
```
items?.map(...)
```
在
streamStatus.isSuccess
前禁用交互