# react-ui

**Repository Path**: box3lab/react-ui

## Basic Information

- **Project Name**: react-ui
- **Description**: 适用于神岛的React，完全由React驱动。
当前为实验项目。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-15
- **Last Updated**: 2025-12-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 神奇代码岛 React-UI

适用于 **神岛 Arena 客户端 UI** 的 React 渲染器，基于官方 **React 18** 渲染器实现。

参考文档：

React 18 官网：https://18.react.dev/

神岛react-ui详细教程：https://docs.box3lab.com/arenapro/zh/react/

## 安装

```sh
npm install @dao3fun/react-ui
```

导出结构：

- `@dao3fun/react-ui`  
  内置 UI 元素组件（`Box`、`Text`、`Image`、`Input`、`ScrollBox` 等）
- `@dao3fun/react-ui/dom`  
  渲染入口（`createRoot` 等）
- `@dao3fun/react-ui/hooks`  
  与神岛客户端交互的常用 Hook（`useScreenSize`、`useClientRemoteChannel` 等）

## 快速上手

```tsx
import React, { useState } from 'react';
import { Box, Text } from '@dao3fun/react-ui';
import { createRoot } from '@dao3fun/react-ui/dom';

function App() {
  const [count, setCount] = useState(0);

  return (
    <Box onClick={() => setCount((c: number) => c + 1)}>
      <Text>你好，React！你点我了 {count} 次</Text>
    </Box>
  );
}

// ui 由神岛客户端提供，对应根 UI 节点
const root = createRoot(ui);
root.render(<App />);
```

## 内置元素组件（Intrinsic Elements）

这些组件会通过自定义渲染器映射到对应的 神岛 UI 元素：

- `Box`：基础容器
- `Text`：文本显示（`children` 会自动映射到底层的 `textContent`）
- `Image`：图片元素（支持 `onLoad` 等事件）
- `Input`：输入框（支持 `onFocus` / `onBlur` / `onChange` 等事件）
- `ScrollBox`：可滚动容器

示例：

```tsx
import { Box, Text, Image, Input, ScrollBox } from '@dao3fun/react-ui';
```

## 神岛特有 Hooks

通过 `@dao3fun/react-ui/hooks` 提供了一些与宿主环境交互的 Hook：

- `useScreenSize()`  
  监听屏幕尺寸变化，返回 `{ screenWidth, screenHeight }`。

- `useClientRemoteChannel<T>()`  
  客户端 <-> 服务端通信：

  ```ts
  type ServerEvent =
    | { type: 'chat'; message: string }
    | { type: 'system'; code: number };

  const { lastEvent, send } = useClientRemoteChannel<ServerEvent>();
  ```

- `usePointerLock()`  
  监听并控制指针锁定状态：

  ```ts
  const { isLocked, errorCount, lockPointer, unlockPointer } = usePointerLock();
  ```

- `useAudio(src)`  
  客户端 `Audio`，提供状态机：

  ```ts
  const { audio, status } = useAudio('https://.../bgm.mp3');
  ```

## TypeScript 支持

该包基于 TypeScript 编写，并提供完整的类型信息：

- 组件 props 里会自动推导底层 `UiBox` / `UiText` / `UiInput` / `UiImage` / `UiScrollBox` 类型
- 事件参数类型为 `UiEvent<T>`，可以获得更好的开发体验

在你的项目Client中开启 JSX 支持：

```jsonc
// client/tsconfig.json
{
  "compilerOptions": {
    "jsx": "react",
  },
}
```

## 注意事项

- 仅适用于神岛 Arena 提供的 UI 运行环境，**不能** 在普通浏览器或 Node 环境中直接渲染 DOM