VGTable
API и настройки
Data API, JavaScript-конфигурация, методы, события, Remote-контракт, i18n и CSS-переменные.
HTML и Data API
VGTable инициализируется по data-vg-table. Вложенные параметры записываются через дефис: stickyHeader.maxHeight становится data-sticky-header-max-height, request.cache.ttl — data-request-cache-ttl.
<form id="orders-filters">
<input type="search" id="orders-search">
<select data-filter-field="status">
<option value="">Все статусы</option>
<option value="active">Активные</option>
</select>
<button type="button" data-filter-reset>Сбросить</button>
</form>
<div class="vg-table-wrapper orders-table">
<div class="vg-table-container">
<table
id="orders-table"
class="vg-table vg-table-hovered"
data-vg-table
data-locale="ru"
data-sort-multiple="true"
data-search-enable="true"
data-search-input="#orders-search"
data-filters-enable="true"
data-filters-form="#orders-filters"
data-pagination-enable="true"
data-pagination-per-page="25"
data-pagination-show-per-page="true"
data-sticky-header-enable="true"
data-sticky-header-mode="container"
data-sticky-header-max-height="28rem"
data-fixed-columns="left:id;right:actions"
data-url-state-enable="true"
>
<thead>
<tr>
<th data-field="id" data-sort-type="number">ID</th>
<th data-field="name">Название</th>
<th data-field="status">Статус</th>
<th data-field="actions" data-sort-enabled="false">Действия</th>
</tr>
</thead>
<tbody>...</tbody>
</table>
</div>
</div>
JavaScript API и группы настроек
Ручная конфигурация объединяется с Data API. Именованные группы подходят для одинаковых таблиц, а i18n позволяет расширять встроенные ru/en словари.
import {VGTable} from 'vgapp';
const element = document.querySelector('#orders-table');
const table = VGTable.getOrCreateInstance(element, {
sort: {enabled: true, multiple: true, multipleWithShift: true},
stickyHeader: {enabled: true, mode: 'container', maxHeight: '28rem'},
fixedColumns: {columns: {left: ['id'], right: ['actions']}},
pagination: {
enabled: true,
per: 25,
size: {enabled: true, options: [10, 25, 50, 100]},
},
search: {enabled: true, input: '#orders-search'},
filters: {enabled: true, form: '#orders-filters'},
urlState: {enabled: true},
}).init();
table.setSorts([
{field: 'status', direction: 'asc'},
{field: 'name', direction: 'desc'},
]);
table.setPage(2);
table.refreshStickyHeader();
table.dispose();
// Общая конфигурация подключается одним data-group-params="orders".
VGTable.registerParamsGroup('orders', {
pagination: {enabled: true, per: 25, size: {enabled: true}},
search: {enabled: true, input: '#orders-search'},
filters: {enabled: true, form: '#orders-filters'},
});
const table = VGTable.getOrCreateInstance(element, {
locale: 'en-US', // региональный код использует fallback en
i18n: {
en: {
pagination: {size: {label: 'Items per page'}},
state: {labels: {empty: 'No orders'}},
},
},
}).init();
table.setLocale('ru');
table.getLocale();
VGTable.unregisterParamsGroup('orders');
DOM-события
Все публичные события всплывают от исходного table, а полезная нагрузка находится в event.detail. Это единый интеграционный контракт вместо внутренних callbacks.
const table = document.querySelector('#orders-table');
table.addEventListener('sortchange.vg.table', ({detail}) => console.log(detail.sorts));
table.addEventListener('pagechange.vg.table', ({detail}) => console.log(detail.page));
table.addEventListener('filterschange.vg.table', ({detail}) => console.log(detail.filters));
table.addEventListener('selectionchange.vg.table', ({detail}) => console.log(detail.keys));
table.addEventListener('columnresize.vg.table', ({detail}) => console.log(detail.widths));
table.addEventListener('rowreorder.vg.table', ({detail}) => console.log(detail.order));
table.addEventListener('requesterror.vg.table', ({detail}) => console.error(detail.error));
table.addEventListener('localechange.vg.table', ({detail}) => console.log(detail.locale));
Remote-контракт
Remote режим включается непустым request.route. data читает объекты по data-field, view принимает готовый tbody, auto выбирает доступный вариант; meta управляет серверной пагинацией.
// GET /api/orders?page=2&per_page=25&sort=status,name&direction=asc,desc
const dataResponse = {
data: [
{id: 101, name: 'Заказ 101', status: 'active'},
],
meta: {page: 2, per_page: 25, total: 84, pages: 4},
};
// responsemode: 'view' или 'auto'
const viewResponse = {
view: {tbody: '<tr><td>101</td><td>Заказ 101</td><td>active</td></tr>'},
meta: {page: 1, per_page: 25, total: 1, pages: 1},
};
const table = VGTable.getInstance(document.querySelector('#orders-table'));
table.setRequestParams({customer: 17});
table.reload({force: true});
table.exportRemote('xlsx');
CSS-переменные
Переменные задаются на .vg-table-wrapper или конкретной таблице. Размерные классы vg-table-xs/sm/lg/xl меняют базовую геометрию, vg-table без модификатора использует md.
.orders-table {
--vg-table-container-radius: 12px;
--vg-table-cell-padding-block: .75rem;
--vg-table-cell-padding-inline: 1rem;
--vg-table-thead-bg: var(--vg-surface-muted-bg);
--vg-table-tbody-bg-hovered: color-mix(in srgb, var(--vg-primary) 6%, transparent);
--vg-table-sticky-top: 4rem;
--vg-table-sticky-max-height: 32rem;
--vg-table-fixed-shadow-color: rgb(0 0 0 / 18%);
--vg-table-pagination-active-bg: var(--vg-primary);
--vg-table-row-reorder-indicator-color: var(--vg-primary);
}
Таблица и контейнер
--vg-table-container-border-width- внешняя граница
--vg-table-container-border-color- цвет внешней границы
--vg-table-container-radius- радиус scroll-контейнера
--vg-table-container-bg- фон контейнера
--vg-table-cell-padding-block- вертикальный отступ ячейки
--vg-table-cell-padding-inline- горизонтальный отступ
--vg-table-font-size- размер шрифта
--vg-table-border-color- разделители строк
--vg-table-bg- фон таблицы
--vg-table-thead-bg- фон заголовка
--vg-table-thead-text- текст заголовка
--vg-table-tbody-bg-hovered- hover строки
Сортировка и управление
--vg-table-sort-column-background- фон отсортированной колонки
--vg-table-sort-chevron-opacity- неактивный шеврон
--vg-table-columns-resize-line-color- линия изменения ширины
--vg-table-columns-drag-outline-color- контур drop колонки
--vg-table-row-reorder-handle-size- размер drag-handle
--vg-table-row-reorder-indicator-color- индикатор позиции строки
--vg-table-row-reorder-drag-opacity- прозрачность переносимой строки
--vg-table-selection-row-background- фон выбранной строки
--vg-table-expandable-indent- отступ уровня дерева
--vg-table-expandable-toggle-size- размер плюс/минус
Sticky и Fixed
--vg-table-sticky-top- offset от верха окна
--vg-table-sticky-max-height- высота container-режима
--vg-table-sticky-z-index- слой заголовка
--vg-table-sticky-shadow- разделитель заголовка
--vg-table-fixed-z-index- слой body-ячейки
--vg-table-fixed-header-z-index- слой фиксированного th
--vg-table-fixed-cell-bg- непрозрачный фон ячейки
--vg-table-fixed-shadow-color- цвет краевой тени
Пагинация и состояния
--vg-table-pagination-control-size- размер кнопки
--vg-table-pagination-gap- зазор групп
--vg-table-pagination-active-bg- активная страница
--vg-table-pagination-size-width- ширина VGDropdown
--vg-table-skeleton-duration- скорость shimmer
--vg-table-skeleton-content-height- высота полосы
--vg-table-state-min-height- минимальная высота состояния
--vg-table-state-bg- фон состояния
--vg-table-state-action-bg-hover- hover кнопки retry/reset
--vg-table-state-icon-color- цвет иконки
Настройки
Значения ниже соответствуют текущему DEFAULT_OPTIONS. Почти все скалярные параметры имеют одноимённый Data API; объекты, функции и пользовательские i18n-словари передаются через JavaScript.
Базовое поведение
localeru- Локаль интерфейса; data-locale. Встроены ru/en и fallback регионального кода.
i18n{}- Пользовательские словари; задаются только через JavaScript.
sort.enabled / hovertrue / true- Локальная или Remote-сортировка и видимость неактивных шевронов.
sort.multiple / multipleWithShiftfalse / true- Мультисортировка и режим добавления колонки с Shift.
pan.enabledtrue- Горизонтальная прокрутка с Shift и перетаскиванием.
selection.enabled / click / multiplefalse / true / false- Одиночный или множественный выбор строк.
state.enabledtrue- Состояния empty, filtered-empty и error.
Заголовок и колонки
stickyHeader.enabled / modefalse / container- Sticky Header в container или page режиме.
stickyHeader.top / maxHeightnull / 24rem- Верхний offset и высота внутреннего viewport.
fixedColumns.columns''- left/right по data-field или индексу; data-fixed-columns.
fixedColumns.mode / stackGapfixed / 0- Постоянная или stack-фиксация и расстояние между колонками.
columnResize.enabled / minWidth / maxWidthfalse / 80 / 600- Изменение ширины заголовка и ограничения в px.
columnResize.persist / storageKeyfalse / ''- Сохранение ширин в localStorage.
columnReorder.enabled / persistfalse / false- Native drag-and-drop колонок и сохранение порядка.
columnVisibility.enabled / controlsfalse / ''- Внешние checkbox data-vg-table-column.
columnVisibility.minVisible / persist1 / false- Минимум видимых колонок и сохранение скрытых полей.
Строки и дерево
rowReorder.enabled / modefalse / handle- Самостоятельная перестановка строк; handle или вся строка.
rowReorder.handleSelector[data-row-reorder-handle]- Область начала drag-and-drop.
rowReorder.keyAttr / persistdata-row-key / false- Стабильный ключ и сохранение локального порядка.
expandable.enabled / collapsedfalse / true- Многоуровневые раскрывающиеся строки.
expandable.idAttr / parentAttrdata-expand-id / data-expand-parent-id- Атрибуты связи дерева.
Поиск, фильтры и URL
search.enabled / input / paramfalse / '' / q- Внешнее поле локального или Remote-поиска.
search.debounce / resetPage / fields300 / true / []- Задержка, сброс страницы и разрешённые поля.
filters.enabled / formfalse / ''- Внешняя форма фильтров.
filters.apply / debounceauto / 300- Автоматическое или ручное применение.
filters.defaultOperatoreq- eq, neq, contains, starts, ends, gt/gte/lt/lte, in/notin.
urlState.enabled / modefalse / replace- Общий query string для page, perPage, sort, search и filters.
urlState.include.*true- Выбор частей состояния, участвующих в URL.
Пагинация и Remote
pagination.enabled / page / per / maxfalse / 1 / 10 / 100- Стартовая страница и количество строк.
pagination.position / alignbottom / right- top, bottom, both и выравнивание панели.
pagination.size.enabled / optionsfalse / [10,25,50,100]- VGDropdown количества строк с произвольным вводом.
pagination.quick.enabledfalse- Быстрый переход: true, false или auto.
pagination.persist.page / pertrue / true- Сохранение локальной страницы и размера.
loading.enabled / minDelay / skeletontrue / 500 / 5- Skeleton Remote-загрузки.
request.route / method'' / GET- Endpoint; непустой route включает Remote режим.
request.responsemodedata- data, view или auto.
request.datapath / metapath / viewpathdata / meta / view.tbody- Dot-path частей ответа.
request.params / parammap{} / {}- Базовые параметры и переименование backend-ключей.
request.cache.enable / ttl / maxtrue / 30000 / 30- Cache одинаковых Remote-запросов.
request.export.route''- Отдельный endpoint экспорта; иначе используется основной.
Публичные методы
Методы возвращают текущее состояние или false/null, если соответствующая подсистема не включена.
Экземпляр и конфигурация
getInstance(element) / getOrCreateInstance(element, params)- Получить существующий экземпляр или создать один экземпляр.
init() / dispose()- Инициализировать все включённые подсистемы или полностью снять их.
registerParamsGroup(name, params)- Зарегистрировать общую конфигурацию для data-group-params.
getParamsGroup(name) / unregisterParamsGroup(name)- Прочитать или удалить именованную группу.
isRemote() / isComplex()- Проверить Remote режим или неоднородную сетку colspan/rowspan.
getLocale() / setLocale(locale)- Прочитать или динамически переключить локаль.
Состояние и данные
setSort() / setSorts() / getSorts() / clearSort()- Управление одиночной и множественной сортировкой.
setPage() / setPerPage() / getPagination()- Управление пагинацией.
setSearch() / resetSearch() / getSearch()- Управление глобальным поиском.
setFilters() / resetFilters() / getFilters()- Управление фильтрами. Сброс фильтров также очищает поиск.
showTableState() / clearTableState() / getTableState()- Показать или снять empty/error state.
getUrlState() / refreshUrlState()- Прочитать и повторно применить query string.
Строки и колонки
selectRow() / toggleRow() / getSelectedRows() / clearSelection()- Управление выбранными строками.
expandRow() / collapseRow() / toggleExpanded()- Управление ветвями expandable.
getColumns() / setColumnWidth() / moveColumn()- Состояние, ширина и порядок колонок.
setColumnVisible() / resetColumns() / refreshColumns()- Видимость, сброс и обновление колонок.
getRowOrder() / moveRow() / resetRows()- Порядок строк и программное перемещение.
refreshStickyHeader() / refreshFixedColumns()- Ручной пересчёт sticky-геометрии; refreshStickyHeader() повторно измеряет текущее содержимое после стороннего AJAX/DOM-обновления.
Remote
reload(options)- Повторить загрузку; force: true обходит cache.
setRequestParams(params, reload, replace)- Добавить или заменить параметры и при необходимости перезагрузить.
getRequestState() / clearRequestCache()- Получить состояние запроса или очистить cache.
exportRemote(format, options)- Сформировать URL экспорта csv/xlsx и открыть его.
Справочник событий
Имена сгруппированы по подсистемам, но каждое событие является отдельным CustomEvent с суффиксом .vg.table.
DOM-события
sortchange.vg.tablesort, sorts- Изменение сортировки и её приоритетов.
pagechange.vg.tablepage, perPage, totalPages, source- Переход на другую страницу.
perpagechange.vg.tablepage, perPage, totalRows, source- Изменение количества строк.
searchchange.vg.tablevalue, param, source- Изменение поиска.
filterschange.vg.tablefilters, params, fields, meta- Изменение фильтров.
selectionchange.vg.tablerow, rows, keys, selected- Изменение выбранных строк.
rowtoggle / rowexpand / rowcollapse.vg.tablerow, id, expanded- Изменение ветви expandable.
columnresize.vg.tablefield, width, widths- Изменение ширины колонки.
columnreorder.vg.tablefield, fromIndex, toIndex, order- Новый порядок колонок.
columnvisibilitychange.vg.tablefield, visible, hidden- Изменение видимости колонки.
rowreorder.vg.tablerow, key, fromIndex, toIndex, order- Изменение порядка строк.
statechange.vg.tabletype, message- Показ или очистка состояния таблицы.
beforeload.vg.tablerequest, params- Перед Remote-запросом.
requestsuccess / requesterror.vg.tableresponse либо error- Результат HTTP-запроса.
dataloaded / afterrender.vg.tablerows, view, meta- Получение и отображение Remote-строк.
urlstateread / urlstatewrite / urlstateerror.vg.tablestate, url либо error- Синхронизация query string.
localechange.vg.tablelocale- Динамическое переключение локали.