> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-pixel-streaming-embed/react-typescript.md).

# React TypeScript

{% embed url="<https://www.npmjs.com/package/@convai/experience-embed>" %}

## 安装说明

要安装 `@convai/experience-embed` 使用您偏好的包管理器，请使用以下命令之一：

#### npm

```bash
npm install @convai/experience-embed
```

#### yarn

```bash
yarn add @convai/experience-embed
```

#### pnpm

```bash
pnpm add @convai
```

## 快速开始（React Ts）

### 1. 导入组件

```tsx
import { PixelStreamComponent } from '@convai/experience-embed';
```

***

### 2. 设置一个 ref 以访问方法

<pre class="language-tsx"><code class="lang-tsx"><strong>import { useRef } from 'react';
</strong>import { PixelStreamComponentHandles } from '@convai/experience-embed';

const pixelStreamRef = useRef&#x3C;PixelStreamComponentHandles>(null);
</code></pre>

### 3. 在 JSX 中使用组件

```tsx
<PixelStreamComponent
  ref={pixelStreamRef}
  expId="您的体验 ID"
  InitialScreen={<div>正在加载您的体验...</div>}
/>
```

{% hint style="info" %}
`expId` 是您在 Convai 仪表板中的唯一体验 ID。
{% endhint %}

### 4. 使用可用方法进行交互

**启用/禁用摄像头**

```tsx
await pixelStreamRef.current?.enableCamera();
await pixelStreamRef.current?.disableCamera();
```

**启用/禁用角色音频**

```tsx
await pixelStreamRef.current?.enableCharacterAudio();
await pixelStreamRef.current?.disableCharacterAudio();
```

**初始化体验**

```tsx
await pixelStreamRef.current?.initializeExperience();
```

### 5. 自定义加载界面（可选）

```tsx
const CustomLoadingScreen = () => (
  <div style={{
    width: '100%',
    height: '100%',
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
    background: '#000',
    color: '#fff',
  }}>
    <h2>正在加载您的体验...</h2>
  </div>
);
```

用法：

```tsx
<PixelStreamComponent
  ref={pixelStreamRef}
  expId="您的体验 ID"
  InitialScreen={<CustomLoadingScreen />}
/>
```

## 完整示例

```tsx
import React, { useRef } from 'react';
import {
  PixelStreamComponent,
  PixelStreamComponentHandles,
} from '@convai/experience-embed';

function App() {
  const pixelStreamRef = useRef<PixelStreamComponentHandles>(null);

  const handleEnableCamera = async () => {
    await pixelStreamRef.current?.enableCamera();
  };

  const handleDisableCamera = async () => {
    await pixelStreamRef.current?.disableCamera();
  };

  return (
    <div>
      <PixelStreamComponent
        ref={pixelStreamRef}
        expId="您的体验 ID"
        InitialScreen={<div>正在加载您的体验...</div>}
      />
      <button onClick={handleEnableCamera}>启用摄像头</button>
      <button onClick={handleDisableCamera}>禁用摄像头</button>
    </div>
  );
}

export default App;
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-pixel-streaming-embed/react-typescript.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.