Перейти к основному содержимому

addTaskLayer

информация

Эта функция доступна только в PRO-версии.

Description​

Отображает дополнительный слой с пользовательскими элементами для задач в области timeline

addTaskLayer: (func: AdditionalTaskLayer['TaskLayerRender'] | AdditionalTaskLayer['TaskLayerConfig']) => string

Parameters​

  • func - (required) TaskLayerRender | TaskLayerConfig - функция рендеринга или объект конфигурации

Returns​

  • layerId - (string) - DOM-элемент, который будет отображён в слое

Example​

gantt.init("gantt_here");
gantt.addTaskLayer(function draw_deadline(task) {
    if (task.deadline) {
        var el = document.createElement('div');
        el.className = 'deadline';
        var sizes = gantt.getTaskPosition(task, task.deadline);

        el.style.left = sizes.left + 'px';
        el.style.top = sizes.top + 'px';

        el.setAttribute('title', gantt.templates.task_date(task.deadline));
        return el;
    }
    return false;
});

Details​

Аргумент может быть одного из следующих типов:

  • taskLayerRender (task, timeline, config, viewport): HTMLElement|boolean|void - функция, которая получает объект задачи и возвращает DOM-элемент для отображения в слое.

    • task - (Task) - объект задачи
    • timeline? - (any) - вид timeline
    • config? - (GanttConfigOptions) - объект конфигурации Gantt
    • viewport? - (LayerViewport) - объект viewport слоя

  • taskLayerConfig - (object) - объект конфигурации дополнительного слоя задач, который включает:

    • id? - (string | number) - необязательный ID слоя
    • renderer - (object) - обязательный объект, отвечающий за рендеринг элементов слоя
      • render - (TaskLayerRender) - функция, возвращающая HTML-элемент для рендеринга
      • update? - (Function): void - необязательная функция для обновления отрендеренных HTML-элементов
        • task - (Task) - объект задачи
        • node - (HTMLElement) - контейнер отрендеренного узла
        • timeline? - (any) - вид timeline
        • config? - (GanttConfigOptions) - объект конфигурации Gantt
        • viewport? - (LayerViewport) - объект viewport слоя
      • onrender? - (Function): void - необязательный коллбек, вызываемый после завершения рендеринга, полезен для рендеринга нативных компонентов (например, с использованием ReactDOM.render)
        • task - (Task) - объект задачи
        • node - (HTMLElement) - контейнер отрендеренного узла
        • view? - (any) - ячейка layout, куда добавлен слой (по умолчанию timeline)
      • getRectangle? - (Function): { left: number, top: number, height: number, width: number } | void - необязательная функция, возвращающая координаты прямоугольника viewport
        • task - (Task) - объект задачи
        • view? - (any) - ячейка layout, куда добавлен слой (по умолчанию timeline)
        • config? - (GanttConfigOptions) - объект конфигурации Gantt
        • gantt? - (GanttStatic) - объект Gantt
      • getVisibleRange - (Function): {start: number, end: number} | undefined | void - необязательная функция, возвращающая объект видимого диапазона
        • gantt? - (GanttStatic) - объект Gantt
        • view? - (any) - ячейка layout, куда добавлен слой (по умолчанию timeline)
        • config? - (GanttConfigOptions) - объект конфигурации Gantt
        • datastore? - (any) - объект хранилища задач
        • viewport? - (LayerViewport) - объект viewport слоя
    • container? - (HTMLElement) - необязательный контейнер для слоя
    • topmost? - (boolean) - необязательный флаг, если true, элемент будет отображаться поверх задачи
    • filter? - (Function): boolean - необязательная функция, принимающая объект задачи и возвращающая false для пропуска рендеринга этой задачи
      • task - (Task) - объект задачи

Viewport слоя включает следующие свойства:

  • viewport - (object) - объект viewport для слоя

    • x - (number) - левая позиция прямоугольника
    • x_end - (number) - правая позиция прямоугольника
    • y - (number) - верхняя позиция прямоугольника
    • y_end - (number) - нижняя позиция прямоугольника
    • width - (number) - ширина прямоугольника
    • height - (number) - высота прямоугольника

  • Учтите, что пользовательские слои будут очищены после следующего вызова gantt.init

  • Также вызов gantt.resetLayout() сбрасывает пользовательские слои. Чтобы пользовательские слои оставались видимыми, нужно переопределять gantt.addTaskLayer после вызова resetLayout.

Умный рендеринг для пользовательских слоёв​

Умный рендеринг направлен на отображение только тех HTML-элементов, которые видны пользователю, избегая отрисовки скрытых за скроллбаром.

Однако с пользовательскими слоями Gantt не знает, где именно размещены пользовательские элементы, так как логика их рендеринга полностью контролируется пользователем.

Для решения этой задачи умный рендеринг предполагает, что пользовательский элемент расположен в той же строке, что и связанная с ним задача. Пользовательские элементы добавляются в DOM только когда строки их задач видимы на экране. При этом Gantt игнорирует положение горизонтального скроллбара, поэтому элемент может присутствовать в разметке, но быть невидимым на странице, если он прокручен по горизонтали.

Это обычно работает хорошо, но если у вас много слоёв, вы можете дополнительно оптимизировать рендеринг, предоставив Gantt точные координаты пользовательских элементов.

Для этого используйте параметр object метода addTaskLayer() и передайте объект renderer с такими методами:

  • render - функция рендеринга
  • getRectangle - функция, возвращающая координаты пользовательских элементов
gantt.addTaskLayer({
    renderer: {
        render: function(task, timeline, viewport){
            ...
            return  HTMLElement
        },
        getRectangle: function(task, view){
            ....
            return {left, top, height, width};
        }
    }
});

Процесс рендеринга пользовательских элементов работает так:

1. При изменении положения горизонтального скролла умный рендеринг получает координаты текущей видимой области.
2. dhtmlxGantt вызывает getRectangle для каждой задачи/связи, чтобы получить точные координаты пользовательского элемента.
3. Если getRectangle возвращает null, функция render пропускается, и пользовательский элемент не отображается.
4. Если getRectangle возвращает координаты, пересекающиеся с текущим viewport, вызывается функция render для отображения пользовательского элемента.

gantt.addTaskLayer({
    renderer: {
      render: function draw_planned(task) {
        if (task.planned_start && task.planned_end) {
          var sizes = gantt.getTaskPosition(task,task.planned_start,task.planned_end);
          var el = document.createElement('div');
          el.className = 'baseline';
          el.style.left = sizes.left + 'px';
          el.style.width = sizes.width + 'px';
          el.style.top = sizes.top + gantt.config.task_height + 13 + 'px';
          return el;
        }
        return false;
      },
      // определение getRectangle подключает слой к умному рендерингу
      getRectangle: function(task, view){
        return gantt.getTaskPosition(task, task.planned_start, task.planned_end);
      }
    }
});

Рендеринг видимых частей пользовательских элементов​

Объект renderer в addTaskLayer() также поддерживает обновление разметки узла, чтобы показывать только видимую часть пользовательского элемента через метод update:

gantt.addTaskLayer({
    renderer: {
        render: function(task, timeline, viewport){
            ...
            return  HTMLElement
        },
        update: function(task, node, timeline, viewport){
            ...
            // обновить внутренний HTML узла, чтобы показывать только видимые части
        },
        getRectangle: function(task, view){
            ....
            return {left, top, height, width};
        }
    }
});
  • update - позволяет обновлять внутренний HTML пользовательского элемента, например, скрывая части вне видимости и показывая видимые

Метод update вызывается после события onGanttScroll, предоставляя узел задачи, созданный функцией render, и текущий viewport.

Рендеринг видимых строк задач​

Начиная с версии v7.1.8 объект renderer поддерживает функцию getVisibleRange для указания видимого диапазона строк задач:

gantt.addTaskLayer({
    renderer: {
        render: function(task, timeline, viewport){
            ...
            return  HTMLElement
        },
        getVisibleRange: function(){
            ...
            return { 
                  start: indexStart,
                  end: indexEnd
            }
        }
    }
});
  • getVisibleRange - возвращает объект с индексами начала и конца видимых строк задач. Задачи вне этого диапазона не будут иметь дополнительных слоёв.

Если getVisibleRange возвращает false вместо объекта, Gantt считает, что все задачи видимы и рендерит дополнительные слои для всех.

Коллбек рендеринга элемента​

Объект renderer также включает коллбек onrender:

gantt.addTaskLayer({
    renderer: {
        render: function(task, timeline, viewport){
            ...
            return  HTMLElement
        },
        onrender: function(item, node, view){
            console.log("render", item, node)
        }
    }
});

Функция onrender вызывается каждый раз, когда элемент данных отрисовывается в DOM. Она предоставляет доступ к элементу данных, результату DOM-элементу и виду, который вызвал рендер (grid или timeline).

Этот коллбек можно использовать для модификации DOM-элементов после рендеринга или для инициализации сторонних виджетов внутри отрисованных элементов.