# @realsee/vapor

> Vapor 是如视 VR 业务组件库（React），提供面向 VR 看房等业务场景的 UI 组件与多风格 SVG 图标库。
> 包名 `@realsee/vapor`，支持 React >= 16.12.0。

需要完整的组件/Hooks/图标详细列表？→ 阅读 [ai_guides/README.md](./ai_guides/README.md)

## 安装

```bash
npm install @realsee/vapor
```

## 快速开始

所有组件需在 `<Vapor>` 全局容器内使用，该容器提供主题管理、响应式断点、设备信息、弹层管理、Toast 通知、错误边界等全局能力。

```tsx
import { Vapor, Button, Icon, HomeSymbol } from '@realsee/vapor';

function App() {
  return (
    <Vapor theme="arc_beauty">
      <Button
        appearance="solid"
        color="primary"
        icon={<Icon symbol={HomeSymbol} type="solid" />}
      >
        首页
      </Button>
    </Vapor>
  );
}
```

详见 [安装指南](./ai_guides/installation.md) · [快速上手](./ai_guides/quick-start.md)

## 场景化查找

根据你要做的事情，快速定位文档：

| 我想要… | 去看 |
| :--- | :--- |
| 搭建页面布局 | [Stack](./ai_guides/components/stack.md) · [Block](./ai_guides/components/block.md) · [Box](./ai_guides/components/box.md) · [Grid](./ai_guides/components/grid.md) |
| 做弹窗 / 浮层 | [Dialog](./ai_guides/components/dialog.md) · [Modal](./ai_guides/components/modal.md) · [BottomSheet](./ai_guides/components/bottom-sheet.md) · [Drawer](./ai_guides/components/drawer.md) · [Overlay](./ai_guides/components/overlay.md) |
| 命令式弹出弹窗（不写 visible 状态） | [命令式弹层 Recipe](./ai_guides/recipes/dispatch-overlay.md) |
| 做导航栏 / 工具栏 | [TitleBar](./ai_guides/components/title-bar.md) · [BottomBar](./ai_guides/components/bottom-bar.md) · [Toolbar](./ai_guides/components/toolbar.md) · [TabView](./ai_guides/components/tab-view.md) |
| 播放音视频 / 轮播 | [Video](./ai_guides/components/video.md) · [Audio](./ai_guides/components/audio.md) · [MediaSlider](./ai_guides/components/media-slider.md) |
| 用图标 | [Icon 组件](./ai_guides/components/icon.md) · [图标列表](./ai_guides/symbols/symbol-list.md) |
| 做表单输入 | [FloatingInput](./ai_guides/components/floating-input.md) · [Checkbox](./ai_guides/components/checkbox.md) · [Switch](./ai_guides/components/switch.md) · [SelectCircle](./ai_guides/components/select-circle.md) |
| 做响应式适配 | [响应式布局 Recipe](./ai_guides/recipes/responsive-layout.md) |
| 跨组件传内容（不用 props） | [Slot/Plug Recipe](./ai_guides/recipes/slot-plug.md) |
| 做主题切换 | [Theme](./ai_guides/components/theme.md) · [Vapor 容器](./ai_guides/components/vapor.md) |
| 做轻提示 / Toast | [Toast](./ai_guides/components/toast.md) |
| 做卡片 / 瀑布流 | [Card](./ai_guides/components/card.md) |
| 做浮动按钮 | [Fab](./ai_guides/components/fab.md) · [FoldableFab](./ai_guides/components/foldable-fab.md) |
| 搭建完整应用布局 | [综合布局实战 Recipe](./ai_guides/recipes/app-layout.md) |
| 做错误边界 | [Error Boundary Recipe](./ai_guides/recipes/error-boundary.md) |

## 组件分类速查

按分类浏览，每项附带关键词 tag 便于搜索。

### 全局配置
- [Vapor](./ai_guides/components/vapor.md) — `config` `provider` `dimension` `responsive` `slot` `overlay` `error-boundary`
- [Theme](./ai_guides/components/theme.md) — `theme` `dark` `light` `skin`

### 布局
- [Block](./ai_guides/components/block.md) — `block` `layout` `absolute` `position`
- [Stack](./ai_guides/components/stack.md) — `flex` `horizontal` `vertical` `stack` `divide`
- [Box](./ai_guides/components/box.md) — `box` `container` `wrapper`
- [Grid](./ai_guides/components/grid.md) — `grid` `columns` `rows` `responsive`
- [Layer](./ai_guides/components/layer.md) — `layer` `shadow` `gradient` `vignetting`

### 基础组件
- [Button](./ai_guides/components/button.md) — `action` `click` `popup` `trigger`
- [Icon](./ai_guides/components/icon.md) — `icon` `symbol` `svg` `badge`
- [Text](./ai_guides/components/text.md) — `text` `typography` `number` `ellipsis`
- [Font](./ai_guides/components/font.md) — `font` `size` `weight` `opacity`
- [Image](./ai_guides/components/image.md) — `image` `photo` `picture`
- [Avatar](./ai_guides/components/avatar.md) — `avatar` `user` `profile` `badge`
- [Badge](./ai_guides/components/badge.md) — `badge` `dot` `count` `notification`

### 导航
- [TitleBar](./ai_guides/components/title-bar.md) — `header` `navigation` `top` `bar`
- [BottomBar](./ai_guides/components/bottom-bar.md) — `footer` `navigation` `bottom` `launcher`
- [TabView](./ai_guides/components/tab-view.md) — `tab` `panel` `switch` `navigation`
- [Toolbar](./ai_guides/components/toolbar.md) — `toolbar` `actions` `above` `hidden`
- [Segmented](./ai_guides/components/segmented.md) — `segmented` `toggle` `switch`

### 数据录入
- [FloatingInput](./ai_guides/components/floating-input.md) — `input` `floating` `text` `form`
- [Checkbox](./ai_guides/components/checkbox.md) — `checkbox` `check` `select` `form`
- [Switch](./ai_guides/components/switch.md) — `switch` `toggle` `on` `off`
- [SelectCircle](./ai_guides/components/select-circle.md) — `select` `circle` `picker`

### 反馈
- [Dialog](./ai_guides/components/dialog.md) — `dialog` `modal` `confirm` `popup`
- [Modal](./ai_guides/components/modal.md) — `modal` `overlay` `popup` `route`
- [Toast](./ai_guides/components/toast.md) — `toast` `notification` `message` `tip`
- [Drawer](./ai_guides/components/drawer.md) — `drawer` `slide` `panel` `side`
- [Mask](./ai_guides/components/mask.md) — `mask` `backdrop` `overlay`
- [Overlay](./ai_guides/components/overlay.md) — `overlay` `portal` `float`
- [Progress](./ai_guides/components/progress.md) — `progress` `bar` `loading` `percent`

### 容器与面板
- [BottomSheet](./ai_guides/components/bottom-sheet.md) — `bottom-sheet` `panel` `snap` `drag` `scroll`
- [Card](./ai_guides/components/card.md) — `card` `slider` `flow` `carousel`
- [Fieldset](./ai_guides/components/fieldset.md) — `fieldset` `group` `legend` `section`

### 媒体
- [MediaSlider](./ai_guides/components/media-slider.md) — `media` `slider` `carousel` `gallery`
- [Video](./ai_guides/components/video.md) — `video` `player` `media`
- [Audio](./ai_guides/components/audio.md) — `audio` `player` `sound`
- [Wave](./ai_guides/components/wave.md) — `wave` `animation` `audio`

### 交互增强
- [ClickAway](./ai_guides/components/click-away.md) — `click-away` `outside` `dismiss`
- [Fab](./ai_guides/components/fab.md) — `fab` `float` `action` `button`
- [FoldableFab](./ai_guides/components/foldable-fab.md) — `fab` `fold` `expand` `menu`

## 图标
- [图标总览与 API](./ai_guides/symbols/README.md) — `icon` `symbol` `svg`
- [图标完整列表](./ai_guides/symbols/symbol-list.md) — 全部图标名称、描述、tags

## Hooks 速查
- `useDimension` — `responsive` `breakpoint` `match` `orientation`
- `useDevice` — `device` `ua` `platform` `window`
- `usePlug` / `useSlot` / `Slot` — `slot` `plug` `inject` `portal`
- `useDispatchOverlayComponent` — `dispatch` `imperative` `popup`
- `useScrollable` — `scroll` `scrollTo` `scrollIntoView`
- `useRemPx` — `rem` `px` `convert` `fontSize`
- `useSaveAreaInsets` — `safe-area` `notch` `insets`
- `useToast` — `toast` `message` `notification`
- `usePopup` — `popup` `dismiss` `hover`
- `useOverlayManager` / `useOverlayVisible` / `useOverlayRegister` — `overlay` `visible` `z-index`
- `useBasePath` — `static` `cdn` `asset`
- `useTheme` — `theme` `dark` `light`
- `useFont` — `font` `size` `weight`
- `useModalRouter` / `useModalPadding` — `modal` `router` `navigate`

所有 Hooks 详细用法见 [Vapor 全局容器文档](./ai_guides/components/vapor.md)

## Recipes（实战用例）
- [响应式布局](./ai_guides/recipes/responsive-layout.md) — `responsive` `breakpoint` `rem` `adaptive`
- [Slot/Plug 跨组件通信](./ai_guides/recipes/slot-plug.md) — `slot` `plug` `inject` `cross-component`
- [Error Boundary](./ai_guides/recipes/error-boundary.md) — `error` `boundary` `fallback` `catch`
- [命令式弹层](./ai_guides/recipes/dispatch-overlay.md) — `dispatch` `imperative` `modal` `dynamic`
- [综合布局实战](./ai_guides/recipes/app-layout.md) — `layout` `ZStack` `Layer` `safe-area` `RouterModal`
