Splitter | Tuff Docs

Usage

Give the splitter a real width and height through its parent. Its compact 6px separator has a slim grip; the two panes share the remaining space, so their ratio never adds separator-width overflow.

Loading demo...

Best Practices

Always wrap TxSplitter in a container with explicit height. Without a bounded box the panes cannot resize predictably.
Keep min and max far enough apart for both panes to remain usable; avoid letting one pane collapse to unreadable content.
Use snap for inspector/sidebar layouts where stable ratios matter; leave it 0 for free-form editing canvases.
Put scroll containers inside pane slots, not around the splitter root, so resizing does not fight page scroll.
Disable the splitter while modal interactions or drag-and-drop flows are active to avoid competing pointer capture.

API Reference

Props

Prop	Type	Default	Description
`modelValue`	`number`	`0.5`	Ratio for pane A. Non-finite values fall back to `0.5`; rendered values are clamped between `0` and `1`.
`direction`	`'horizontal' \| 'vertical'`	`'horizontal'`	`horizontal` splits left/right; `vertical` splits top/bottom. Invalid values fall back to horizontal.
`min`	`number`	`0.1`	Minimum emitted ratio during pointer or keyboard resizing.
`max`	`number`	`0.9`	Maximum emitted ratio during pointer or keyboard resizing.
`disabled`	`boolean`	`false`	Disables pointer and keyboard resizing. If enabled while dragging, it ends the active drag.
`barSize`	`number`	`6`	Separator track size in pixels. Runtime floor is `6px`; the visible grip is 2px thick.
`snap`	`number`	`0`	Optional ratio step. `0` disables snapping; positive values snap emitted ratios to the nearest step.

Slots

Slot	Props	Description
`a`	-	First pane: left in horizontal mode, top in vertical mode.
`b`	-	Second pane: right in horizontal mode, bottom in vertical mode.

Events

Event	Payload	Description
`update:modelValue`	`number`	Emitted with the next clamped and snapped ratio.
`change`	`number`	Emitted with the same ratio for change listeners.
`drag-start`	`()`	Emitted when pointer resizing starts.
`drag-end`	`()`	Emitted when pointer resizing ends or is cancelled by disabling/unmounting.

Overview

Pointer drag reads the splitter root bounding box: horizontal uses clientX / width, vertical uses clientY / height.
Keyboard resizing uses ArrowLeft / ArrowRight in horizontal mode and ArrowUp / ArrowDown in vertical mode, stepping by 0.02 before clamp / snap.
The separator renders role="separator" with aria-label="Resize"; aria-orientation is vertical for horizontal panes and horizontal for vertical panes. It reports the current split through aria-valuenow and the min/max bounds through aria-valuemin/aria-valuemax, all as integer percentages (0..100).
When disabled, the separator uses tabindex="-1", pointer/keyboard changes are ignored, and active dragging is ended.
The component does not persist layout. Store the v-model ratio in the caller if users should keep their pane size.

Technologies

Accessibility note: The separator is keyboard-focusable with role="separator", aria-label="Resize", and arrow-key resizing, and it exposes aria-valuenow / aria-valuemin / aria-valuemax as integer percentages (the current ratio and the min/max bounds scaled to 0..100) so assistive tech can announce the split position. Visible ratio/size feedback is still helpful when precision matters.
Layout note: Rendered ratios are clamped to 0..1, while emitted pointer/keyboard changes are clamped by min/max and then snapped. Keep min <= max in caller code; the component does not normalize inverted bounds.
Verified coverage: splitter.test.ts checks horizontal and vertical rendering, separator orientation, aria-valuenow/aria-valuemin/aria-valuemax, slot content, ratio/bar CSS variables, pointer drag with clamp/snap, vertical pointer math, keyboard resizing, disabled blocking, and drag-end emission when disabled mid-drag.
Component source: packages/tuffex/packages/components/src/splitter/src/TxSplitter.vue.
Types: packages/tuffex/packages/components/src/splitter/src/types.ts exports SplitterProps, SplitterEmits, and SplitterDirection.
Export alias: packages/tuffex/packages/components/src/splitter/index.ts exports Splitter, TxSplitter, splitter types, and TxSplitterInstance.
Coverage: packages/tuffex/packages/components/src/splitter/__tests__/splitter.test.ts verifies rendering, pointer/keyboard resizing, snapping, disabled behavior, and drag lifecycle.

查看源码

packages/tuffex/packages/components/src/splitter/index.ts