@fish-render/separator

Vue 3 separator 组件，提供现代化的用户界面体验。

安装

npm install @fish-render/separator
# 或
yarn add @fish-render/separator
# 或
pnpm add @fish-render/separator

使用方法

方式一：自动引入样式（推荐）

当你引入组件时，样式会自动加载：

<template>
  <Separator>
    <!-- 组件内容 -->
  </Separator>
</template>

<script setup>
import { Separator } from '@fish-render/separator'
// 样式会自动加载，无需额外引入
</script>

方式二：手动引入样式

如果你想要手动控制样式的引入时机：

<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 中全局引入

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')

方式四：使用插件方式

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')

示例

基础用法

<template>
  <Separator>
    <SeparatorPanel>
      <div>左侧内容</div>
    </SeparatorPanel>
    <SeparatorPanel>
      <div>右侧内容</div>
    </SeparatorPanel>
  </Separator>
</template>

尺寸双向绑定（v-model:size）

<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）

<template>
  <Separator :show-line="false">
    <SeparatorPanel :size="280" />
    <SeparatorPanel />
  </Separator>
</template>

分割线样式（lineType）

<template>
  <Separator :line-type="'dashed'">
    <SeparatorPanel :size="240" />
    <SeparatorPanel :size="240" />
  </Separator>
</template>

吸附阈值（snapThreshold）

<template>
  <Separator :snap-threshold="16">
    <SeparatorPanel :size="200" />
    <SeparatorPanel :size="200" />
  </Separator>
</template>

拖拽事件（resize-start / resize / resize-end）

<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）

<template>
  <Separator :lazy="true" @resize-end="onEnd">
    <SeparatorPanel :size="260" />
    <SeparatorPanel />
  </Separator>
</template>

垂直布局

<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 对应的双向绑定事件。 |

类型定义

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 类名，你可以通过覆盖这些类名来自定义样式：

/* separator 组件样式 */
.fish-separator {
  /* 自定义组件样式 */
}

注意事项

1. 浏览器兼容性：组件使用了现代 CSS 特性，确保在现代浏览器中使用
2. 样式加载：样式是全局的，会在应用启动时自动加载
3. Tree Shaking：如果你使用 Tree Shaking，建议使用手动引入样式的方式
4. TypeScript 支持：组件完全支持 TypeScript，提供完整的类型定义

许可证

MIT License