# vue-effort-slider 教程：带 WebGL 火焰拖尾的 Vue 3 滑块组件

## 这是什么

`vue-effort-slider` 是一个**高度可定制**的 Vue 3 滑块组件，最大特点是带**实时 WebGL 火焰拖尾特效**——灵感来自 Claude Code 的 effort slider。当滑块拖到阈值（默认满值）时，会激活 GPU 加速的火焰拖尾；同时具备平滑的「吸附到刻度」动画、动态配色以及零运行时依赖。

简单说，它把一个普通的 `0–100` 滑块，做成了一个有科技感、可随手调外观的 AI「思考深度」选择器。

## 效果预览

拉到最大档位时的火焰拖尾效果：

![Max 档位的火焰拖尾效果](https://cdn.sanity.io/images/z4mv7hi8/production/4a8782e50a181ee841ac99f74bbba36e0b575afa-1500x700.webp)

常规拖动的实时演示（动图）：

<img src="/images/vue-effort-slider/slider.webp" alt="vue-effort-slider 拖动演示" style="border-radius:12px;max-width:800px;width:100%" />

## 核心特性

- **WebGL2 火焰拖尾**：滑块达到阈值时激活 GPU 实时渲染的火焰效果。
- **吸附刻度动画**：以 cubic ease-out 平滑吸附到最近的 25% 档位。
- **完全可主题化**：10+ 颜色属性，可定制滑块、拖尾、轨道、标签、辉光等每个视觉元素。
- **v-model 支持**：标准 Vue 双向绑定（`modelValue`）。
- **圆角裁切（Squircle）**：卡片与轨道采用 Apple 风格超椭圆裁切路径。
- **响应式**：宽度接受像素值或 CSS 字符串（如 `'100%'`）。
- **帮助气泡**：内置帮助图标 + teleport tooltip。
- **轻量**：零运行时依赖，仅需 Vue 3 作为 peerDependency。

## 安装

```bash
npm install vue-effort-slider
```

## 快速开始

### 从零创建项目

```bash
# 1. 创建项目
npm create vite@latest my-slider -- --template vue
cd my-slider
npm install vue-effort-slider
```

修改 `src/App.vue`：

```vue
<script setup>
import { ref } from 'vue'
import { EffortSlider } from 'vue-effort-slider'
import 'vue-effort-slider/style.css'

const value = ref(75)
</script>

<template>
  <EffortSlider v-model="value" />
  <p style="color:#71717a;text-align:center;margin-top:16px">Current value: {{ value }}</p>
</template>
```

```bash
# 2. 运行
npm run dev
```

打开 `http://localhost:5173`，即可看到带火焰拖尾的滑块。

### 全局注册

```js
// main.js
import { createApp } from 'vue'
import App from './App.vue'
import VueEffortSlider from 'vue-effort-slider'
import 'vue-effort-slider/style.css'

const app = createApp(App)
app.use(VueEffortSlider)
app.mount('#app')
```

```vue
<template>
  <EffortSlider v-model="value" />
</template>

<script setup>
import { ref } from 'vue'
const value = ref(75)
</script>
```

### 局部引入

```vue
<template>
  <EffortSlider v-model="value" label="思考深度" />
</template>

<script setup>
import { ref } from 'vue'
import { EffortSlider } from 'vue-effort-slider'
import 'vue-effort-slider/style.css'

const value = ref(50)
</script>
```

### 子模块按需引入（Tree-shaking）

```js
// 完整组件
import { EffortSlider } from 'vue-effort-slider'
import 'vue-effort-slider/style.css'

// 仅组件
import { EffortSlider } from 'vue-effort-slider/EffortSlider'

// 单独引入 composable
import { useSliderState } from 'vue-effort-slider/useSliderState'
import { useWebglFire } from 'vue-effort-slider/useWebglFire'

// 或批量从 composables 引入
import { useSliderState, useWebglFire } from 'vue-effort-slider/composables'

// 仅着色器（GLSL 源字符串）
import { VERT, FRAG_SIM, FRAG_BLUR, FRAG_COMP } from 'vue-effort-slider/shaders'
```

### 独立火焰 Canvas

用 `useWebglFire` 可以把火焰拖尾效果加到任意 canvas 上：

```vue
<template>
  <canvas ref="canvasRef" width="400" height="60"
    style="width:400px;height:60px;border-radius:10px;background:#0c0c0c" />
</template>

<script setup>
import { ref } from 'vue'
import { useWebglFire } from 'vue-effort-slider/useWebglFire'

const canvasRef = ref(null)
const sliderValue = ref(100)
const isActive = ref(true)

useWebglFire(canvasRef, sliderValue, isActive, () => '#a857f7')
</script>
```

## 在线配置面板

组件配套一个在线配置面板 **[slider.qiyuan.icu](https://slider.qiyuan.icu)**，可以实时调整每个 prop、预览火焰拖尾效果，并一键复制生成的代码（动图）：

<img src="/images/vue-effort-slider/slider_27c_site_opt.webp" alt="vue-effort-slider 实时配置面板" style="border-radius:12px;max-width:800px;width:100%" />

想直接上手调参，打开 [slider.qiyuan.icu](https://slider.qiyuan.icu) 即可。

## Props

### 基础 Props

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` | `Number` | `75` | 当前值，支持 `v-model`，范围 `0`–`100` |
| `width` | `String \| Number` | `376` | 组件宽度，像素数字或 CSS 字符串（如 `'100%'`） |
| `label` | `String` | `'Slider'` | 顶部标签文字 |
| `threshold` | `Number` | `100` | 激活 WebGL 火焰效果的阈值，设 `100` 即仅满值激活 |
| `scaleLabels` | `String[]` | `['Faster', 'Smarter']` | 轨道两端的刻度标签 |
| `statusLabels` | `Object` | `{ level1:'Minimal', level2:'Low', level3:'Medium', level4:'High', level5:'Max' }` | 5 档状态文字 |
| `background` | `String` | `'#000000'` | 卡片背景色（任意 CSS 颜色） |
| `borderRadius` | `String \| Number` | `20` | 卡片圆角（像素） |
| `showHelp` | `Boolean` | `true` | 是否显示帮助图标 |
| `helpText` | `String` | `'Drag the slider to adjust AI thinking depth'` | 点击帮助图标弹出的提示内容 |

### 颜色 Props

所有颜色属性均接受任意合法 CSS 颜色值（hex / rgb / hsl 等）。

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `labelColor` | `String` | `'#b0b0c7'` | 顶部标签文字颜色 |
| `statusColor` | `String` | `'#a1a1aa'` | 未达阈值时的状态文字颜色 |
| `activeColor` | `String` | `'#c084fc'` | 达阈值时状态文字颜色（带辉光） |
| `highlightColor` | `String` | `'#c084fc'` | 达阈值时滑块辉光颜色 |
| `scaleLabelColor` | `String` | `'#b0b0b8'` | 端点标签颜色 |
| `helpIconColor` | `String` | `'#a1a1aa'` | 帮助图标颜色 |
| `trailColor` | `String` | `'#a857f7'` | WebGL 火焰拖尾颜色 |
| `thumbColor` | `String` | `'#ffffff'` | 滑块拖柄颜色 |
| `trackColor` | `String` | `'#0c0c0c'` | 轨道背景色 |
| `dotColor` | `String` | `'#494950'` | 轨道上 5 个装饰圆点颜色 |

## Events

| 事件 | 回调参数 | 说明 |
| --- | --- | --- |
| `update:modelValue` | `Number` | 拖动过程中持续触发，供 `v-model` 使用 |
| `change` | `Number` | 拖动结束、吸附动画完成后触发一次，参数为最终吸附值 |
| `help` | — | 点击帮助图标时触发 |