@fxshelf/word-tunnel/docs/使用说明.md

3D keyword tunnel word-cloud for React and Vue — perspective fly-through text. Zero animation-lib deps. Copy-as-source friendly.

# 使用说明

## 安装

```bash
npm install @fxshelf/word-tunnel
```

```ts
import '@fxshelf/word-tunnel/styles.css'
```

## React

```tsx
import { WordTunnel } from '@fxshelf/word-tunnel'
import '@fxshelf/word-tunnel/styles.css'

<WordTunnel style={{ height: 420, background: '#0c081e' }} />
```

## Vue

```vue
<script setup lang="ts">
import { WordTunnel } from '@fxshelf/word-tunnel/vue'
import '@fxshelf/word-tunnel/styles.css'
</script>

<template>
  <WordTunnel :style="{ height: '420px', background: '#0c081e' }" />
</template>
```

## CDN（React 18 UMD）

需先加载 React 18 UMD，再加载 IIFE，并引入 CSS。完整页面见 [CDN示例.html](./CDN示例.html)。

```html
<link rel="stylesheet" href="https://unpkg.com/@fxshelf/word-tunnel/dist/index.css" />
<script crossorigin src="https://unpkg.com/react@18.3.1/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.production.min.js"></script>
<script src="https://unpkg.com/@fxshelf/word-tunnel/dist/word-tunnel.iife.js"></script>
<script>
  ReactDOM.createRoot(document.getElementById('app')).render(
    React.createElement(WordTunnel.WordTunnel, {
      style: { height: 420, background: '#0c081e' },
    }),
  )
</script>
```

## 复制源码

拷贝 `src/core`（含 `styles.css`）与 `src/react` 或 `src/vue`，保持同级目录即可。

## Props

| 属性 | 说明 | 默认 |
|------|------|------|
| `words` | 词条数组 | 内置搞笑词 |
| `count` | 固定词数；不传则按宽度自适应 | — |
| `seed` | 随机种子（同值布局可复现，换值换分布） | `20250913` |
| `perspective` | CSS perspective | `900` |
| `innerRadius` | 中心空洞半径 | `8` |
| `outerRadius` | 外圈采样半径 | `52` |
| `travelMin` | z 最短飞行距离 | `480` |
| `travelRange` | z 额外随机飞行距离 | `560` |
| `fadeIn` / `fadeOut` | 淡入完成 / 开始淡出进度 0–100 | `10` / `88` |
| `color` / `fontSize` | 文字样式 | — |
| `children` / slot | 叠在词云上的内容 | — |

## 参考文章

- [我用 CSS 3D 做了个星空隧道 Loading，没有 Three.js](https://juejin.cn/post/7684547172777246766)（掘金）
- [知乎专栏 · 星空隧道词云 Loading](https://zhuanlan.zhihu.com/p/2082492419061330179)
- [CSDN · 星空隧道词云 Loading](https://blog.csdn.net/paopao_pop/article/details/165232859)