Конфигурация

Настройте таблицу Pivot и панель конфигурации с помощью следующего API:

• config - определяет структуру таблицы Pivot и способ агрегации данных
• render-table - изменяет конфигурацию таблицы на лету
• tableShape - настраивает внешний вид таблицы Pivot
• columnShape - настраивает внешний вид и поведение столбцов
• headerShape - настраивает внешний вид и поведение заголовков
• configPanel - управляет видимостью панели конфигурации
• setLocale - применяет локаль (см. Локализация)
• data, fields - загружают данные и метаданные полей
• predicates - предварительно обрабатывают данные перед агрегацией
• methods - определяют пользовательские методы агрегации
• limits - ограничивают количество строк и столбцов в итоговом наборе данных

Инструкции по работе с данными см. в разделе Работа с данными.

Вы можете настроить следующие элементы таблицы Pivot:

• столбцы и строки
• заголовки и подвалы
• ячейки
• размеры таблицы

Изменение размеров таблицы

Используйте свойство tableShape, чтобы изменить размер строк, столбцов, заголовка и подвала.

Следующий фрагмент кода показывает размеры по умолчанию:

const sizes = {
    rowHeight: 34,
    headerHeight: 30,
    footerHeight: 30,
    columnWidth: 150
};

Следующий фрагмент кода переопределяет размеры по умолчанию:

const table = new pivot.Pivot("#root", {
    fields,
    data,
    tableShape: {
        sizes: {
            rowHeight: 44,
            headerHeight: 60,
            footerHeight: 30,
            columnWidth: 170
        }
    },
    config: {
        rows: ["studio", "genre"],
        columns: [],
        values: [
            {
                field: "title",
                method: "count"
            },
            {
                field: "score",
                method: "max"
            }
        ]
    }
});

К сведению

Чтобы задать ширину конкретных столбцов, используйте параметр width свойства columnShape.

Автоматическое изменение ширины столбцов по содержимому

Используйте параметр autoWidth свойства columnShape, чтобы вычислять ширину столбцов автоматически. Все подпараметры autoWidth являются необязательными. Полные описания см. в справочнике columnShape.

Объект autoWidth принимает следующие параметры:

• columns - объект, определяющий, для каких полей вычисляется ширина автоматически
• auto - подстраивает ширину под заголовок, содержимое ячейки или под оба варианта
• maxRows - количество строк данных, анализируемых для определения размера столбца (по умолчанию: 20)
• firstOnly - если true (по умолчанию), каждое поле анализируется только один раз. Когда несколько столбцов основаны на одном поле (например, oil с count и oil с sum), анализируется только первый столбец, а остальные наследуют его ширину

Следующий фрагмент кода включает autoWidth для четырёх полей и отключает firstOnly, чтобы каждый столбец получил собственное измерение:

const table = new pivot.Pivot("#root", {
    fields,
    data,
    config: {
        rows: ["studio", "genre"],
        columns: [],
        values: [
            {
                field: "title",
                method: "count"
            },
            {
                field: "score",
                method: "max"
            }
        ]
    },
    columnShape: {
        autoWidth: {
            // вычислять ширину столбца для этих полей
            columns: {
                studio: true,
                genre: true,
                title: true,
                score: true
            },
            // анализировать все поля
            firstOnly: false
        }
    }
});

Применение шаблонов к ячейкам

Добавление шаблонов через tableShape

Используйте параметр templates свойства tableShape, чтобы отображать значения ячеек через функцию. Каждый ключ — это идентификатор поля, а каждое значение — функция, возвращающая строку. Все столбцы, основанные на указанном поле, получают этот шаблон.

В примере ниже к ячейкам state применяется шаблон, который отображает объединённое название штата (полное название и аббревиатура):

const states = {
  "California": "CA",
  "Colorado": "CO",
  "Connecticut": "CT",
  "Florida": "FL",
  // другие значения
};

const table = new pivot.Pivot("#root", {
    tableShape: {
        templates: {
            // настроить значения ячеек "state"
            state: v => v + ` (${states[v]})`,
        }
    },
    fields,
    data,
    config: {
        rows: ["state", "product_type"],
        columns: [],
        values: [
            {
                field: "profit",
                method: "sum"
            },
            {
                field: "sales",
                method: "sum"
            },
            // другие значения
        ],
    },
    fields,
});

Добавление шаблона через хелпер template

Чтобы вставить HTML-содержимое в ячейки тела таблицы, используйте хелпер pivot.template и присвойте результат свойству cell объекта столбца. Применяйте шаблон непосредственно перед отрисовкой таблицы, перехватывая событие render-table с помощью метода api.intercept.

В примере ниже в ячейки тела добавляются иконки (звезда или флаг) в зависимости от поля (id, user_score):

function cellTemplate(value, method, row, column) {
    const field = column.fields ? column.fields[row.$level] : column.field;

    if (field === "id") {
        return idTemplate(value);
    }

    if (field === "user_score") {
        return scoreTemplate(value);
    }

    return value;
}

function idTemplate(value) {
    const name = value?.toString().split("-")[0];
    return `<span className="cell-id flag-${name}"></span> ${value}`;
}

function scoreTemplate(value) {
    return `<i className="cell-score wxi-star"></i> ${value}`;
}

widget.api.intercept("render-table", ({ config: tableConfig }) => {
    tableConfig.columns = tableConfig.columns.map((c) => {
        if (c.area === "rows") {
            // применить шаблон к ячейкам столбца из области "rows"
            c.cell = pivot.template(({ value, method, row, column }) => cellTemplate(value, method, row, column));
        }
        return c;
    });
});

Применение шаблонов к заголовкам

Добавление шаблонов через headerShape

Чтобы управлять форматом текста в заголовках, используйте параметр template свойства headerShape. Параметр представляет собой функцию, которая:

• принимает метку поля, его ID и подпись (название метода, если есть)
• возвращает обработанное значение

Шаблон по умолчанию:

template: (label, id, subLabel) =>
    label + (subLabel ? ` (${subLabel})` : "")

Без пользовательского шаблона поля области values отображают метку и метод (например, Oil(count)), а поля других областей отображают значение label. Шаблон predicates переопределяет шаблон headerShape.

В примере ниже текст заголовка преобразуется в нижний регистр, давая такие метки, как profit (sum):

new pivot.Pivot("#pivot", {
    data,
    headerShape: {
        // пользовательский шаблон для текста заголовка
        template: (label, id, subLabel) => (label + (subLabel ? ` (${subLabel})` : "")).toLowerCase(),
        },
    config: {
        rows: ["state", "product_type"],
        columns: [],
        values: [
            {
                field: "profit",
                method: "sum"
            },
            {
                field: "sales",
                method: "sum"
            },
            // другие значения
        ],
    },
    fields,
});

Добавление шаблонов через хелпер template

Чтобы вставить HTML-содержимое в ячейки заголовков, используйте хелпер pivot.template и присвойте результат свойству cell объекта ячейки заголовка. Применяйте шаблон непосредственно перед отрисовкой таблицы, перехватывая событие render-table с помощью метода api.intercept.

В примере ниже иконки добавляются к:

• меткам заголовков на основе имени поля (например, id получает иконку глобуса)
• заголовкам столбцов на основе значения ячейки (цветные стрелки-индикаторы в зависимости от значения status)

function rowsHeaderTemplate(value, field) {
    let icon = "";
    if (field === "id") icon = "<i className='icon wxi-earth'></i>";
    if (field === "user_score") icon = "<i className='icon wxi-star'></i>";
    return `${value} ${icon}`;
}

function statusTemplate(value) {
    let icon = "";
    if (value === "Up") icon = "<i style='color:green' className='icon wxi-arrow-up'></i>";
    if (value === "Down") icon = "<i style='color:red' className='icon wxi-arrow-down'></i>";
    return `${value} ${icon}`;
}

widget.api.intercept("render-table", ({ config: tableConfig }) => {
    tableConfig.columns = tableConfig.columns.map((c) => {
        if (c.area === "rows") {
            // применить шаблон к первой строке заголовка столбцов из области "rows"
            c.header[0].cell = pivot.template(({ value, field }) => rowsHeaderTemplate(value, field));
        } else {
            // ячейки заголовка, отображающие значения из поля "status"
            const headerCell = c.header.find((h) => h.field === "status");
            if (headerCell) {
                headerCell.cell = pivot.template(({ value }) => statusTemplate(value));
            }
        }
        return c;
    });
});

Сворачиваемые столбцы

Чтобы пользователи могли сворачивать и разворачивать столбцы под общим заголовком, установите параметр collapsible свойства headerShape в true.

Следующий фрагмент кода включает сворачиваемые заголовки столбцов:

const table = new pivot.Pivot("#root", {
    fields,
    data,
    headerShape: {
        collapsible: true,
    },
    config: {
        rows: ["studio", "genre"],
        columns: [],
        values: [
            {
                field: "title",
                method: "count"
            },
            {
                field: "score",
                method: "max"
            }
        ]
    }
});

Фиксация столбцов

Зафиксируйте столбцы слева или справа, чтобы они оставались видимыми при прокрутке остальной части таблицы. Используйте параметр split свойства tableShape и установите left или right в true.

Фиксация столбцов слева

Когда split.left равно true, количество зафиксированных столбцов соответствует количеству полей rows в свойстве config. В древовидном режиме фиксируется только один столбец независимо от количества полей rows.

Следующий фрагмент кода фиксирует один столбец слева (определено одно поле rows):

const table = new pivot.Pivot("#root", {
    fields,
    data,
    config: {
        rows: ["studio"],
        columns: ["genre"],
        values: [
            {
                field: "title",
                method: "count"
            },
            {
                field: "score",
                method: "max"
            }
        ]
    },
    tableShape: { 
        split: {left: true } 
    }
});

Чтобы задать пользовательское количество фиксированных столбцов, подпишитесь на событие render-table и переопределите tableConfig.split. Избегайте разделения столбцов с объединёнными ячейками (colspan).

Следующий фрагмент кода фиксирует слева все столбцы rows плюс удвоенное количество полей values:

const table = new pivot.Pivot("#root", {
    fields,
    data,
    config: {
        rows: ["continent", "name"],
        columns: ["year"],
        values: [
            {
                field: "oil",
                method: "sum"
            },
            {
                field: "oil",
                method: "count"
            }
        ]
    }
});
table.api.on("render-table", ({ config: tableConfig }) => {
    const { config } = table.api.getState();

    tableConfig.split = {
        left: config.rows.length + config.values.length * 2
    };
});

Фиксация столбцов справа

Установите split.right в true, чтобы зафиксировать итоговые столбцы справа.

Следующий фрагмент кода фиксирует итоговый столбец справа:

const widget = new pivot.Pivot("#pivot", {
    fields,
    data: dataset,
    tableShape:{
        split: {right: true},
        totalColumn: true,
    },
    config:  {
        rows: ["hobbies"],
        columns: ["relationship_status"],
        values: [
            {
                field: "age",
                method: "min"
            },
            {
                field: "age",
                method: "max"
            }
        ]
    }
});

Чтобы зафиксировать произвольное количество столбцов справа, подпишитесь на событие render-table и переопределите tableConfig.split. Избегайте разделения столбцов с объединёнными ячейками (colspan).

Следующий фрагмент кода фиксирует справа столько столбцов, сколько полей в values:

const widget = new pivot.Pivot("#pivot", {
    fields,
    data: dataset,
    config:  {
        rows: ["hobbies"],
        columns: ["relationship_status"],
        values: [
            {
                field: "age",
                method: "min"
            },
            {
                field: "age",
                method: "max"
            }
        ]
    }
});

widget.api.on("render-table", ({ config: tableConfig }) => {
    const { config } = widget.api.getState();
    tableConfig.split = {
        right: config.values.length,
    }
})

Сортировка в столбцах

Сортировка в интерфейсе включена по умолчанию: пользователи нажимают на заголовок столбца для сортировки. Чтобы отключить её, установите параметр sort свойства columnShape в false.

Следующий фрагмент кода отключает сортировку в интерфейсе:

const table = new pivot.Pivot("#root", {
    fields,
    data,
    config: {
        rows: ["studio", "genre"],
        columns: [],
        values: [
            {
                field: "title",
                method: "count"
            },
            {
                field: "score",
                method: "max"
            }
        ]
    },
    columnShape: {
        sort: false
    }
});

Подробнее о сортировке по умолчанию, пользовательских компараторах и обновлениях во время выполнения см. в разделе Сортировка данных.

Включение древовидного режима

Древовидный режим отображает данные иерархически с раскрываемыми строками. Установите параметр tree свойства tableShape в true (по умолчанию false). Первое поле массива rows в config становится родительской строкой.

Следующий фрагмент кода включает древовидный режим с studio в качестве родителя и genre в качестве вложенных строк:

const table = new pivot.Pivot("#root", {
    tableShape: {
        tree: true
    },
    fields,
    data: dataset,
    config: {
        rows: ["studio", "genre"],
        values: [
            {
                field: "title",
                method: "count"
            },
            {
                field: "score",
                method: "max"
            },
            {
                field: "episodes",
                method: "count"
            },
            {
                field: "rank",
                method: "min"
            },
            {
                field: "members",
                method: "max"
            }
        ]
    }
});

Развёртывание и свёртывание всех строк

Чтобы программно развернуть или свернуть все строки, включите древовидный режим через свойство tableShape. Затем получите экземпляр виджета Table с помощью метода getTable и вызовите событие open-row или close-row через метод api.exec таблицы.

В примере ниже отрисовываются кнопки «Открыть все» и «Закрыть все», которые разворачивают или сворачивают все ветки в древовидном режиме:

const table = new pivot.Pivot("#root", {
    tableShape: {
        tree: true
    },
    fields,
    data: dataset,
    config: {
        rows: ["type", "studio"],
        columns: [],
        values: [
            {
                field: "score",
                method: "max"
            },
            {
                field: "rank",
                method: "min"
            },
            {
                field: "members",
                method: "sum"
            },
            {
                field: "episodes",
                method: "count"
            }
        ]
    }
});

const api = table.api;
const tableInstance = api.getTable();
// держать все ветки таблицы закрытыми при отрисовке
api.intercept("render-table", (ev) => {
    ev.config.data.forEach((r) => (r.open = false));

    // вернуть false здесь, чтобы предотвратить отрисовку таблицы
    // return false;
});

function openAll() {
    tableInstance.exec("open-row", { id: 0, nested: true });
}

function closeAll() {
    tableInstance.exec("close-row", { id: 0, nested: true });
}

const openAllButton = document.createElement("button");
openAllButton.addEventListener("click", openAll);
openAllButton.textContent = "Open all";

const closeAllButton = document.createElement("button");
closeAllButton.addEventListener("click", closeAll);
closeAllButton.textContent = "Close all";

document.body.appendChild(openAllButton);
document.body.appendChild(closeAllButton);

Изменение ориентации текста заголовков

Чтобы повернуть текст заголовков из горизонтального в вертикальное положение, установите параметр vertical свойства headerShape в true.

Следующий фрагмент кода отрисовывает вертикальный текст заголовков:

const table = new pivot.Pivot("#root", {
    fields,
    data,
    headerShape: {
        vertical: true
    },
    config: {
        rows: ["studio"],
        columns: ["type"],
        values: [
            {
                field: "title",
                method: "count"
            },
            {
                field: "score",
                method: "max"
            }
        ]
    }
});

Управление видимостью панели конфигурации

Панель конфигурации отображается по умолчанию. Пользователи могут переключать её с помощью кнопки Скрыть настройки / Показать настройки. Управляйте панелью программно через свойство configPanel, событие show-config-panel или метод showConfigPanel.

Скрыть панель конфигурации

Чтобы скрыть панель при инициализации, установите свойство configPanel в false.

Следующий фрагмент кода инициализирует Pivot со скрытой панелью:

// панель конфигурации скрыта при инициализации
const table = new pivot.Pivot("#root", {
    fields,
    data: dataset,
    configPanel: false,
    config: {
        rows: ["hobbies"],
        columns: ["relationship_status"],
        values: [
            {
                field: "age",
                method: "min"
            },
            {
                field: "age",
                method: "max"
            }
        ]
    }
});

Чтобы переключить панель во время выполнения, вызовите событие show-config-panel с помощью метода api.exec и установите параметр mode в false.

Следующий фрагмент кода скрывает панель после инициализации:

const table = new pivot.Pivot("#root", {
    fields,
    data,
    config: {
        rows: ["studio", "genre"],
        columns: [],
        values: [
            {
                field: "title",
                method: "count"
            },
            {
                field: "score",
                method: "max"
            }
        ]
    }
});
// скрыть панель конфигурации
table.api.exec("show-config-panel", {
    mode: false
});

Отключение переключения по умолчанию

Чтобы полностью заблокировать стандартную кнопку переключения, перехватите событие show-config-panel с помощью метода api.intercept и верните false.

Следующий фрагмент кода отключает кнопку переключения:

const table = new pivot.Pivot("#root", {
    fields,
    data,
    config: {
        rows: ["studio", "genre"],
        columns: [],
        values: [
            {
                field: "title",
                method: "count"
            },
            {
                field: "score",
                method: "max"
            }
        ]
    }
});

table.api.intercept("show-config-panel", () => {
    return false;
});

В качестве альтернативного API используйте метод showConfigPanel.

Действия с полями на панели

Панель конфигурации поддерживает следующие операции с полями:

• add-field - добавить поле в область
• delete-field - удалить поле из области
• update-field - обновить метод или настройки поля
• move-field - изменить порядок полей внутри области

Связанные примеры:

• Pivot 2. Добавление текстовых шаблонов для ячеек таблицы и заголовков
• Pivot 2. Пользовательские фиксированные столбцы (произвольное количество)
• Pivot 2. Развёртывание и свёртывание всех строк
• Pivot 2. Фиксированные столбцы слева и справа
• Pivot 2. Сортировка