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.

HTML
<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();
Группы и i18n
// Общая конфигурация подключается одним 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.

JavaScript
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 управляет серверной пагинацией.

HTTP / JSON
// 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.

CSS
.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
Динамическое переключение локали.