Расширение Zoom

Вы можете ознакомиться с подробностями об расширении Zoom в статье Zooming. В текущей статье приведена API-справка по объекту zoom:

Уровни масштабирования

Расширение Zoom использует набор настроек масштаба и позволяет быстро переключаться между ними.

ZoomLevel — это объект, который содержит настройки масштаба. Он имеет следующие свойства:

• name - (string) - имя уровня
• scale_height? - (number) - высота шкалы
• height? - (number) - высота шкалы
• min_column_width? - (number) - минимальная ширина столбца. Он имеет больший приоритет, чем minColumnWidth и maxColumnWidth
• scales - (Scales) - массив шкал, между которыми можно переключаться во время зума вверх/вниз на этом уровне

Методы

• init(zoomConfig): void - инициализирует расширение с заданной конфигурацией.
  • zoomConfig? - (object) - объект конфигурации, который содержит массив levels зум-уровней и ряд дополнительных свойств:
    • levels? - (ZoomLevel[]) - массив зум-уровней. Необязателен — если пропущен, используется набор default named levels ("hour", "day", "week", "month", "year")
    • handler? - (Function): void - позволяет задать пользовательский обработчик колёсика мыши для ручного управления зумированием
      • e - (Event) - нативный объект события.
    • startDate? - (Date) - начальное значение масштабирования временной шкалы
    • endDate? - (Date) - конечное значение масштабирования временной шкалы
    • activeLevelIndex? - (number) - номер дефолтного активного уровня
    • widthStep? - (number) - шаг увеличения/уменьшения ширины шкалы при переходе к следующему/предыдущему уровню масштабирования
    • minColumnWidth? - (number) - минимальная ширина столбца, позволяющая перейти на предыдущий уровень масштабирования
    • maxColumnWidth? - (number) - максимальная ширина столбца, позволяющая перейти на следующий уровень масштабирования
    • useKey? - (string) - клавиша, которая включает зумирование прокручиванием колёсика мыши:"ctrlKey" | "altKey" | "shiftKey"
    • trigger? - (string | null | undefined) - триггер зумирования: "wheel" | null | undefined
    • element? - (HTMLElement | Function): HTMLElement - DOM-элемент, над которым активируется зумирование, или функция, возвращающая DOM-элемент
    • fit? - (object) - настройки по умолчанию для zoom-to-fit. Вместе с опциями zoomToFit, перечисленными ниже, она принимает levels (посвящённый набор шкал, используемых только для подгонки) и handler (функция, переопределяющая выбор уровня)

Это два примера настройки конфигурации zoom:

const zoomConfig = {
    levels: [
        {
            name: "day",
            scale_height: 27,
            min_column_width: 80,
            scales: [{ unit: "day", step: 1, format: "%d %M" }]
        },
        {
            name: "week",
            scale_height: 50,
            min_column_width: 50,
            scales: [
                {
                    unit: "week",
                    step: 1,
                    format: (date) => {
                        const dateToStr = gantt.date.date_to_str("%d %M");
                        const endDate = gantt.date.add(date, 6, "day");
                        const weekNumber = gantt.date.date_to_str("%W")(date);

                        return `#${weekNumber}, ${dateToStr(date)} - ${dateToStr(endDate)}`;
                    }
                },
                { unit: "day", step: 1, format: "%j %D" }
            ]
        },
        {
            name: "month",
            scale_height: 50,
            min_column_width: 120,
            scales: [{ unit: "month", format: "%F, %Y" }, { unit: "week", format: "Week #%W" }]
        },
        {
            name: "quarter",
            height: 50,
            min_column_width: 90,
            scales: [
                { unit: "month", step: 1, format: "%M" },
                {
                    unit: "quarter",
                    step: 1,
                    format: (date) => {
                        const dateToStr = gantt.date.date_to_str("%M");
                        const endDate = gantt.date.add(gantt.date.add(date, 3, "month"), -1, "day");

                        return `${dateToStr(date)} - ${dateToStr(endDate)}`;
                    }
                }
            ]
        },
        {
            name: "year",
            scale_height: 50,
            min_column_width: 30,
            scales: [{ unit: "year", step: 1, format: "%Y" }]
        }
    ]
};

gantt.ext.zoom.init(zoomConfig);


// or, in a more simple way levels can be presented as scale arrays
const hourToStr = gantt.date.date_to_str("%H:%i");
const hourRangeFormat = (step) => {
    return (date) => {
        const intervalEnd = new Date(gantt.date.add(date, step, "hour") - 1);

        return `${hourToStr(date)} - ${hourToStr(intervalEnd)}`;
    };
};
const simpleZoomConfig = {
    levels: [
        [
            { unit: "month", format: "%M %Y", step: 1 }
        ],
        [
            { unit: "month", format: "%M %Y", step: 1 },
            { unit: "day", format: "%d %M", step: 1 }
        ],
        [
            { unit: "day", format: "%d %M", step: 1 },
            { unit: "hour", format: hourRangeFormat(12), step: 12 }
        ],
        [
            { unit: "day", format: "%d %M", step: 1 },
            { unit: "hour", format: hourRangeFormat(6), step: 6 }
        ],
        [
            { unit: "day", format: "%d %M", step: 1 },
            { unit: "hour", format: "%H:%i", step: 1 }
        ]
    ]
};

gantt.ext.zoom.init(simpleZoomConfig);

• getCurrentLevel(): number - возвращает номер (индекс) текущего уровня масштабирования

gantt.ext.zoom.getCurrentLevel();

• setLevel(level): void - переключает на указанный уровень масштабирования.
  • level - (number | string) - Уровень задаётся либо строковым значением (имя уровня из конфигурации, например "year"), либо его номером в массиве уровней

gantt.ext.zoom.setLevel("year");
// или 
gantt.ext.zoom.setLevel(5);

• getLevels(): ZoomLevel[] - позволяет получить все уровни масштабирования

gantt.ext.zoom.getLevels();

Возвращает массив уровней масштабирования (ZoomLevel[]), переданных в init(), которые инициализируют расширение.

• zoomIn(): void - увеличивает текущий уровень масштабирования

gantt.ext.zoom.zoomIn();

Для той же цели можно также использовать:

gantt.ext.zoom.setLevel(gantt.ext.zoom.getCurrentLevel() - 1);

• zoomOut(): void - уменьшает текущий уровень масштабирования

gantt.ext.zoom.zoomOut();

Для той же цели можно также использовать:

gantt.ext.zoom.setLevel(gantt.ext.zoom.getCurrentLevel() + 1);

• zoomToFit(options?): boolean - подбирает наиболее детальный уровень зума, на котором целевые задачи помещаются в ширину временной шкалы без горизонтальной прокрутки, и применяет его. См. Подгонка под диапазон для списка опций. Метод идемпотентен и возвращает true, если применён уровень подгонки, false в противном случае.

gantt.ext.zoom.zoomToFit();
// или подгонять только текущие видимые (развернутые) строки
gantt.ext.zoom.zoomToFit({ scope: "visible" });

• resetZoom(): boolean - восстанавливает уровень зума и временную шкалу, которые были активны до первого вызова zoomToFit(). Возвращает true, если сохранённый масштаб был восстановлен, false — если восстанавливать нечего.

gantt.ext.zoom.resetZoom();

• attachEvent(name, handler): string - прикрепляет обработчик события

  • name - (string) - имя обработчика события
  • handler - (Function) - функция, которая будет вызываться при срабатывании события

• detachEvent(id): void - отсоединяет обработчик от события

  • id - (string) - идентификатор прикрепленного обработчика события

• callEvent(name, params): boolean - вызывает внутреннее событие

  • name - (string) - имя события, регистронезависимо
  • params - (Array<any>) - необязательный набор данных, связанных с этим событием
  • Возвращает true, если для события указан обработчик.

• checkEvent(name): boolean - проверяет, имеется ли обработчик(и) для данного события

  • name - (string) - имя события

Возвращает true, если для события указан обработчик.

Подгонка под диапазон

zoomToFit(options) и настройка fit в init() принимают следующие опции:

• scope? - ("all" | "visible") - какие задачи подгонять: "all" (по умолчанию) подгоняет каждую загруженную задачу, включая задачи под свёрнутыми ветвями; "visible" подгоняет только текущие развёрнутые строки
• taskId? - (string | number) - подгоняет одну задачу вместе с её поддеревом
• range? - (object) - подгоняет явный диапазон дат со свойствами start_date и end_date (Date)
• rangeMode? - ("auto" | "preserve" | "target") - перезаписывать ли отображаемые start_date/end_date на подогнанный диапазон. "target" всегда устанавливает подогнанный диапазон, "preserve" сохраняет текущие границы, "auto" (по умолчанию) сохраняет явные границы, если они заданы, и устанавливает подогнанный диапазон в противном случае
• padding? - (number) - количество дополнительных столбцов, добавляемых перед первым и после последнего подобранного диапазона дат. По умолчанию: 1
• minLevel? - (string | number) - наиболее детальный уровень масштабирования, который допускается выбрать у zoomToFit
• maxLevel? - (string | number) - наиболее грубый уровень масштабирования, который допускается выбрать у zoomToFit

Если задать через свойство fit в init(), конфигурация дополнительно принимает:

• levels? - (ZoomLevel[]) - специальный набор уровней масштаба, учитываемый только для zoomToFit. Если опущен, используются интерактивные уровни зума
• handler? - (Function): string | number | boolean | void - переопределяет выбор уровня. Он получает объект контекста и должен вернуть имя/индекс уровня, чтобы применить его, вернуть false чтобы прервать подбор, или вернуть ничего, чтобы сохранить вычисленный уровень
  • context - (object) - объект { range, viewportWidth, levels, padding, defaultLevel }, где defaultLevel — индекс уровня, выбранный встроенным алгоритмом

Опции, переданные напрямую в zoomToFit(), переопределяют значения по умолчанию, заданные в init({ fit }).

gantt.ext.zoom.init({
    fit: {
        scope: "all",
        // специализированный набор шкал, используемых только для подгонки
        levels: [
            { name: "weeks", scale_height: 50, scales: [{ unit: "week", step: 1, format: "Week #%W" }] },
            { name: "months", scale_height: 50, scales: [{ unit: "month", step: 1, format: "%F, %Y" }] }
        ],
        handler: (context) => {
            // вернуть имя/индекс уровня, false для отмены, или ничего чтобы оставить уровень по умолчанию
            return context.defaultLevel;
        }
    }
});

gantt.ext.zoom.zoomToFit();

Связанный пример: Подгонка под диапазон

События

• onAfterZoom - срабатывает во время переключения уровня масштабирования. Аргументы:

• level - (number | string) - номер уровня
• config - (ZoomLevel) - конфигурация уровня

gantt.ext.zoom.attachEvent("onAfterZoom", (level, config) => {
    document.querySelector(`.gantt_radio[value='${config.name}']`).checked = true;
});