npm package: @fish-render/separator
Description: Fish Render separator component for Vue 3
Author: fish-render
Latest version: 0.1.3

# @fish-render/separator

Vue 3 separator 组件，提供现代化的用户界面体验。

## 安装

```bash
npm install @fish-render/separator
# 或
yarn add @fish-render/separator
# 或
pnpm add @fish-render/separator
```

## 使用方法

### 方式一：自动引入样式（推荐）

当你引入组件时，样式会自动加载：

```vue
<template>
  <Separator>
    <!-- 组件内容 -->
  </Separator>
</template>

<script setup>
import { Separator } from '@fish-render/separator'
// 样式会自动加载，无需额外引入
</script>
```

### 方式二：手动引入样式

如果你想要手动控制样式的引入时机：

```vue
<template>
  <Separator>
    <!-- 组件内容 -->
  </Separator>
</template>

<script setup>
import { Separator } from '@fish-render/separator'
</script>

<style lang="scss">
/* 手动引入样式（SCSS） */
@import '@fish-render/separator/styles';
</style>
```

### 方式三：在 main.js 中全局引入

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import { Separator } from '@fish-render/separator'
import '@fish-render/separator/styles'

const app = createApp(App)

app.component('Separator', Separator)

app.mount('#app')
```

### 方式四：使用插件方式

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import SeparatorPlugin from '@fish-render/separator'

const app = createApp(App)
app.use(SeparatorPlugin)
app.mount('#app')
```

## 示例

### 基础用法

```vue
<template>
  <Separator>
    <SeparatorPanel>
      <div>左侧内容</div>
    </SeparatorPanel>
    <SeparatorPanel>
      <div>右侧内容</div>
    </SeparatorPanel>
  </Separator>
</template>
```

### 尺寸双向绑定（v-model:size）

```vue
<template>
  <Separator layout="horizontal">
    <SeparatorPanel v-model:size="left" :min="120" />
    <SeparatorPanel v-model:size="right" :min="120" />
  </Separator>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const left = ref(240)
const right = ref(240)
</script>
```

### 隐藏静默灰线（showLine）

```vue
<template>
  <Separator :show-line="false">
    <SeparatorPanel :size="280" />
    <SeparatorPanel />
  </Separator>
</template>
```

### 分割线样式（lineType）

```vue
<template>
  <Separator :line-type="'dashed'">
    <SeparatorPanel :size="240" />
    <SeparatorPanel :size="240" />
  </Separator>
</template>
```

### 吸附阈值（snapThreshold）

```vue
<template>
  <Separator :snap-threshold="16">
    <SeparatorPanel :size="200" />
    <SeparatorPanel :size="200" />
  </Separator>
</template>
```

### 拖拽事件（resize-start / resize / resize-end）

```vue
<template>
  <Separator @resize-start="onStart" @resize="onResize" @resize-end="onEnd">
    <SeparatorPanel :size="240" />
    <SeparatorPanel :size="240" />
  </Separator>
</template>

<script setup lang="ts">
function onStart(index: number) { console.log('resize-start', index) }
function onResize(index: number) { console.log('resize', index) }
function onEnd(index: number) { console.log('resize-end', index) }
</script>
```

### 键盘与双击交互
- 双击分割线：均分相邻两个面板尺寸。
- 键盘微调：分割线获得焦点时，`ArrowLeft/ArrowRight` 或 `ArrowUp/ArrowDown` 以 8px 步长微调相邻面板尺寸（随布局方向变化）。

### 懒拖拽（lazy）

```vue
<template>
  <Separator :lazy="true" @resize-end="onEnd">
    <SeparatorPanel :size="260" />
    <SeparatorPanel />
  </Separator>
</template>
```

### 垂直布局

```vue
<template>
  <Separator layout="vertical">
    <SeparatorPanel :size="200" />
    <SeparatorPanel />
  </Separator>
</template>
```

## API

### Separator Props

| 参数 | 类型 | 默认值 | 说明 |
| ---- | ---- | ------ | ---- |
| layout | `'horizontal' | 'vertical'` | `horizontal` | 布局方向（水平/垂直）。 |
| lazy | `boolean` | `false` | 拖拽期间是否延迟触发内部与容器事件；为 `true` 时仅在结束时统一触发。 |
| snapThreshold | `number` | `8` | 分割线吸附阈值（px）；靠近相邻分割线时自动吸附。 |
| showLine | `boolean` | `true` | 是否显示静默灰线；为 `false` 时仅在 hover 或拖拽时显示彩色线。 |
| lineType | `'solid' | 'dashed' | 'dotted' | 'double'` | `solid` | 分割线样式：实线、虚线、点线、双线。 |

### Separator Events

| 事件名 | 参数 | 说明 |
| ---- | ---- | ---- |
| resize-start | `(index: number)` | 开始拖拽某分割线时触发。 |
| resize | `(index: number)` | 拖拽过程中触发（`lazy=false` 时连续）。 |
| resize-end | `(index: number)` | 结束拖拽时触发。 |
| collapse | `(index: number)` | 将面板折叠到最小值时触发（程序化调用）。 |

### SeparatorPanel Props

| 参数 | 类型 | 默认值 | 说明 |
| ---- | ---- | ------ | ---- |
| size | `string | number` | `-` | 面板初始尺寸；支持像素值（数字）或百分比字符串（如 `'50%'`）。 |
| min | `string | number` | `0` | 面板最小尺寸；支持像素值或百分比。 |
| max | `string | number` | `不限` | 面板最大尺寸；支持像素值或百分比。 |
| resizable | `boolean` | `true` | 是否参与拖拽；为 `false` 时不显示该侧分割线且不可拖拽。 |
| collapsible | `boolean` | `false` | 控制是否显示展开/闭合按钮（待开发）。 |

### SeparatorPanel 事件

| 事件名 | 参数 | 说明 |
| ---- | ---- | ---- |
| update:size | `(val: string | number)` | 与 `v-model:size` 对应的双向绑定事件。 |

### 类型定义

```typescript
export interface SeparatorProps {
  layout?: 'horizontal' | 'vertical'
  lazy?: boolean
  snapThreshold?: number
  showLine?: boolean
  lineType?: 'solid' | 'dashed' | 'dotted' | 'double'
}

export interface SeparatorPanelProps {
  size?: string | number
  min?: string | number
  max?: string | number
  resizable?: boolean
  collapsible?: boolean // 待开发
}

export type SeparatorEmits = {
  (e: 'resize-start', index: number): void
  (e: 'resize', index: number): void
  (e: 'resize-end', index: number): void
  (e: 'collapse', index: number): void
}
```
## 样式自定义

组件使用 CSS 类名，你可以通过覆盖这些类名来自定义样式：

```css
/* separator 组件样式 */
.fish-separator {
  /* 自定义组件样式 */
}
```

## 注意事项

1. **浏览器兼容性**：组件使用了现代 CSS 特性，确保在现代浏览器中使用
2. **样式加载**：样式是全局的，会在应用启动时自动加载
3. **Tree Shaking**：如果你使用 Tree Shaking，建议使用手动引入样式的方式
4. **TypeScript 支持**：组件完全支持 TypeScript，提供完整的类型定义

## 许可证

MIT License