Разделитель панелей
Splitter делит область на панели, размер которых меняют, перетаскивая ручку между ними или с клавиатуры.
Folders
Messages
<tk-splitter style="block-size: 160px"> <tk-splitter-panel size="30" min="15" max="60"><p>Folders</p></tk-splitter-panel> <tk-splitter-handle label="Resize folders"></tk-splitter-handle> <tk-splitter-panel><p>Messages</p></tk-splitter-panel> </tk-splitter>
Анатомия
| Часть | Что это |
|---|---|
tk-splitter |
группа; раскладывает панели по одной оси и хранит их размеры |
tk-splitter-panel |
одна панель; вмещает что угодно и обрезает то, что не помещается |
tk-splitter-handle |
линия между двумя панелями с зоной захвата 12px; одна остановка Tab |
Панели и ручки — прямые потомки группы, по порядку: панель, ручка, панель и так далее. Ручка меняет размер только двух соседних панелей.
Направление и вложенность
orientation="horizontal" (по умолчанию) ставит панели рядом. orientation="vertical"
ставит их друг под другом. Для раскладки в обе стороны вложите группу в панель.
Files
Editor
Console
<tk-splitter style="block-size: 240px">
<tk-splitter-panel size="25" min="15"><p>Files</p></tk-splitter-panel>
<tk-splitter-handle label="Resize files"></tk-splitter-handle>
<tk-splitter-panel><tk-splitter orientation="vertical" style="block-size: 100%">
<tk-splitter-panel size="70"><p>Editor</p></tk-splitter-panel>
<tk-splitter-handle label="Resize console"></tk-splitter-handle>
<tk-splitter-panel min="10"><p>Console</p></tk-splitter-panel>
</tk-splitter></tk-splitter-panel>
</tk-splitter>Размер группе задаёте вы, например block-size или дорожкой grid; панели делят его между
собой.
Размеры
Размеры задаются в процентах от группы.
size: начальная доля панели. Панели без неё поровну делят остаток. Дальше splitter сам хранит размеры, пока их перетаскивают.minиmax: доля, меньше или больше которой панель не станет. Перетаскивание останавливается, когда любой из соседей упирается в предел, и пределы держатся при изменении размера окна. По умолчаниюminравен 0, поэтому задайте нижний предел там, где содержимое должно оставаться пригодным.- Двойной щелчок по ручке возвращает её двум панелям начальное деление.
Сохранение раскладки
После каждого изменения, сделанного человеком, группа вызывает tk-resize с
detail.sizes. Текущие размеры читайте из sizes, а восстанавливайте через
setSizes(): он удерживает каждую панель в её пределах и не вызывает tk-resize.
const splitter = document.querySelector('tk-splitter');
splitter.addEventListener('tk-resize', debounce(() => {
localStorage.setItem('layout', JSON.stringify(splitter.sizes));
}, 200));
const saved = localStorage.getItem('layout');
if (saved) splitter.setSizes(JSON.parse(saved));Состояния
Fixed sidebar
Content
<tk-splitter style="block-size: 120px"> <tk-splitter-panel size="30"><p>Fixed sidebar</p></tk-splitter-panel> <tk-splitter-handle label="Resize sidebar" disabled></tk-splitter-handle> <tk-splitter-panel><p>Content</p></tk-splitter-panel> </tk-splitter>
При наведении и перетаскивании на линии появляется акцентная полоса 2px. При фокусе с клавиатуры вокруг зоны захвата появляется рамка.
disabled: фиксирует обе панели. Ручка становится простой линией, её нельзя перетащить и на неё нельзя перейти фокусом.
Когда использовать
- Splitter нужен, когда удобное деление зависит от человека и задачи: навигация и содержимое, редактор и предпросмотр, список и подробности, основная область и консоль.
- Если деление никто не меняет, обойдитесь обычной раскладкой. Каждая ручка — ещё один элемент управления, в котором надо разобраться.
- Не используйте его, чтобы показывать и скрывать область. Панель, сжатая до нуля, не закрыта; нужен настоящий переключатель.
Текст
- Называйте ручку по тому, что она меняет: «Изменить ширину боковой панели», «Изменить высоту консоли». Имя по умолчанию — «Resize», и по нему несколько ручек не различить.
- Прокрутку делайте внутри содержимого панели, если оно может не поместиться,
например через
Scroll area ; сама панель обрезает лишнее. - Не ставьте элементы управления вплотную к ручке. Её зона захвата заходит примерно на 5px на край каждой панели.
Можно / нельзя
| ✅ Можно | ❌ Нельзя |
|---|---|
| Там, где людям нужно разное деление | Ручки в раскладке, которую никто не меняет |
| Называть ручку по тому, что она меняет | Несколько ручек с именем «Resize» |
min там, где содержимое перестаёт работать |
Позволять панели случайно сжаться до нуля |
| Вложенные группы для раскладки в обе стороны | Ждать, что ручка сдвинет больше двух панелей |
Сохранять по tk-resize, восстанавливать через setSizes() |
Считать панель, сжатую до нуля, закрытой |
Связанные
Slider : задаёт значение на шкале, а splitter делит место.Divider : линия, которая не двигается.Scroll area : прокрутка содержимого внутри панели.
API
Атрибуты tk-splitter
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
orientation |
horizontal | vertical |
horizontal |
панели рядом или друг под другом |
Атрибуты tk-splitter-panel
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
size |
number | поровну от остатка | начальная доля, % |
min |
number | 0 |
наименьшая доля, % |
max |
number | 100 |
наибольшая доля, % |
Атрибуты tk-splitter-handle
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
label |
string | Resize |
доступное имя; у каждой ручки своё |
disabled |
boolean | false |
фиксирует пару; ручка становится простой линией |
Слоты
| Элемент | Слот | Содержимое |
|---|---|---|
tk-splitter |
по умолчанию | панели и ручки, по порядку |
tk-splitter-panel |
по умолчанию | что угодно, включая вложенный tk-splitter |
Свойства и методы
| Член | Что делает |
|---|---|
tk-splitter.sizes |
только для чтения; текущие доли в %, по порядку |
tk-splitter.setSizes(sizes) |
задаёт доли в пределах каждой панели; не вызывает tk-resize |
События
tk-splitter вызывает tk-resize после каждого шага перетаскивания, нажатия клавиши или
сброса двойным щелчком, с detail.sizes. Событие всплывает. setSizes() его не вызывает.
CSS
--tk-splitter-handle-hitуtk-splitter-handle: ширина зоны захвата, по умолчанию 12px. Она лежит поверх панелей и не занимает места.
Токены
| Элемент | Токен |
|---|---|
| линия | border/default, 1px |
| полоса при наведении и перетаскивании | border/accent, 2px |
| рамка фокуса | border/accent/focus, с radius-2 |
| отключённая линия | border/subtle |
Курсор — col-resize в горизонтальной группе и row-resize в вертикальной. Значения по
темам:
Доступность
Встроено:
- Ручка — разделитель, на который можно перейти фокусом. Скринридер называет её имя и размер панели перед ней: «Resize sidebar, разделитель, 30%». Каждый шаг озвучивается.
- Отключённая ручка выпадает из порядка Tab и озвучивается как простой разделитель.
- Перетаскивание ручки пальцем не прокручивает страницу.
На вашей стороне:
- Дайте каждой ручке своё имя в
label. - Задайте
min, чтобы с клавиатуры нельзя было сжать панель до непригодного размера. - На сенсорных экранах расширьте зону захвата через
--tk-splitter-handle-hit.
| Клавиша | Действие |
|---|---|
Tab |
переводит фокус на ручку |
Right / Down |
увеличивает панель перед ручкой на 1% |
Left / Up |
уменьшает её на 1% |
Shift + стрелка |
то же, на 10% |
Home / End |
сжимает её до наименьшего или растягивает до наибольшего размера |