React 与 Next.js

Orbz 不发布 React 组件。React 和 Next.js 与其他框架一样使用 <orb-z> 元素。

React

在客户端应用入口或浏览器运行的组件模块中导入一次浏览器入口：


import "@neongate-ai/orbz/react-types";
import "@neongate-ai/orbz/browser";
import { useState } from "react";
import type { OrbzState } from "@neongate-ai/orbz";
 
export function AssistantPresence() {
  const [state, setState] = useState<OrbzState>("idle");
 
  return (
    <div role="status" aria-live="polite">
      <orb-z state={state} size="300px" />
      <span>Assistant is {state}</span>
      <button type="button" onClick={() => setState("listening")}>
        Listen
      </button>
    </div>
  );
}

Next.js App Router

将注册和交互状态放在客户端边界内。服务器组件仍可正常渲染该客户端组件。


"use client";
 
import "@neongate-ai/orbz/react-types";
import "@neongate-ai/orbz/browser";
 
export function AssistantPresence() {
  return <orb-z state="thinking" size="300px" />;
}

浏览器入口支持安全 SSR：customElements 不可用时不执行操作，在客户端包执行时定义元素。

为自定义标签提供类型

在 React 或 Next.js TypeScript 应用中导入一次可选 JSX 类型扩展：


import '@neongate-ai/orbz/react-types'

这让 TypeScript 识别原生 <orb-z>，不会在 Orbz 运行时中创建 React 组件、包装器、运行时适配器或 React 依赖。

设置结构化属性

语音引擎、对话流程和智能提供器是 JavaScript 对象，不是 HTML 属性。首次安排对话运行前，通过 ref 赋值：


"use client";
 
import "@neongate-ai/orbz/react-types";
import "@neongate-ai/orbz/browser";
import { useCallback } from "react";
import type {
  OrbzElement,
  OrbzVoiceEnginePort
} from "@neongate-ai/orbz";
 
interface ProductPresenceProps {
  voiceEngine: OrbzVoiceEnginePort;
}
 
export function ProductPresence(props: ProductPresenceProps) {
  const setElement = useCallback(
    (element: HTMLElement | null) => {
      if (element) {
        (element as OrbzElement).voiceEngine = props.voiceEngine;
      }
    },
    [props.voiceEngine]
  );
 
  return <orb-z ref={setElement} state="idle" />;
}

仓库中的 React 和 Next.js 示例采用此原生元素方式。