Available only in PRO Edition

Расширение Formatters

Расширение gantt.ext.formatters предоставляет два способа форматирования значений:

• durationFormatter()
• linkFormatter()

Вы также можете создать пользовательский форматтер, используя существующие в качестве основы.

Форматтер длительности

Метод gantt.ext.formatters.durationFormatter(config) создает новый экземпляр DurationFormatter.

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

• durationFormatter (config): DurationFormatter — создает форматтер длительности
  • config? — (object) — необязательный объект конфигурации с такими опциями:
    • enter? — (string) — устанавливает формат по умолчанию, используемый методом parse, если во входном значении отсутствуют единицы измерения. По умолчанию "day".
    • store? — (string) — определяет формат хранения значений длительности в Gantt. Это влияет на результат метода parse. По умолчанию "hour".
    • format? — (string | Array <string>) — задает формат вывода. Поддерживаются значения: "auto", "minute", "hour", "day", "week", "month", "year" или массив из этих значений. "auto" означает, что форматтер сам выбирает подходящую единицу в зависимости от размера значения (для больших значений — дни/месяцы/годы, для меньших — минуты/часы).
    • short? — (boolean) — включает короткие обозначения (аббревиатуры) для единиц времени. По умолчанию false.
    • minutesPerHour? — (number) — задает соотношение минут в часе. По умолчанию 60.
    • hoursPerDay? — (number) — задает соотношение часов в дне. По умолчанию 8.
    • hoursPerWeek? — (number) — задает соотношение часов в неделе. По умолчанию 40.
    • daysPerMonth? — (number) — задает соотношение дней в месяце. По умолчанию 30.
    • daysPerYear? — (number) — задает соотношение дней в году. По умолчанию 365.
    • labels? — (object) — задает текстовые подписи для разных единиц времени, используемые при разборе и форматировании:
      • minute? — (object) — подписи для минут
        • full? — (string) — полное название для минут
        • plural? — (string) — множественное число для минут
        • short? — (string) — короткое название для минут
      • hour? — (object) — подписи для часов
        • full? — (string) — полное название для часов
        • plural? — (string) — множественное число для часов
        • short? — (string) — короткое название для часов
      • day? — (object) — подписи для дней
        • full? — (string) — полное название для дней
        • plural? — (string) — множественное число для дней
        • short? — (string) — короткое название для дней
      • week? — (object) — подписи для недель
        • full? — (string) — полное название для недель
        • plural? — (string) — множественное число для недель
        • short? — (string) — короткое название для недель
      • month? — (object) — подписи для месяцев
        • full? — (string) — полное название для месяцев
        • plural? — (string) — множественное число для месяцев
        • short? — (string) — короткое название для месяцев
      • year? — (object) — подписи для лет
        • full? — (string) — полное название для лет
        • plural? — (string) — множественное число для лет
        • short? — (string) — короткое название для лет

Примеры:

Создание форматтера длительности с настройками по умолчанию:

const formatter = gantt.ext.formatters.durationFormatter();
// экземпляр форматтера создается с помощью фабричного метода

• enter:

formatter.parse("1"); // интерпретируется как 1 день, если enter:"day" (по умолчанию)
formatter.parse("1"); // интерпретируется как 1 час, если enter:"hour"

• store:

formatter.parse("1 day"); // сохраняется как 8, если store:"hour"
formatter.parse("1 day"); // сохраняется как 480, если store:"minute"

• format

gantt.ext.formatters.durationFormatter({
    format: ["hour", "minute"],     store:"minute"
}).format(260); // результат: "4 hours 20 minutes"
 
gantt.ext.formatters.durationFormatter({
    format: "hour",     store:"minute"  
}).format(260);// результат: "4.33 hours"

• short

gantt.ext.formatters.durationFormatter({
    format: ["week", "hour", "minute"],
    store:"minute",
    short: false   }).format(10021); //"4 weeks 7 hours 1 minute"
 
gantt.ext.formatters.durationFormatter({
    format: ["week", "hour", "minute"],
    store:"minute",
    short: true  }).format(10021); //"4wk 7h 1min"

Пример с полной конфигурацией:

const formatter = gantt.ext.formatters.durationFormatter({
    // значения по умолчанию
    enter: "day",
    store: "hour",
    format: "auto",
    short: false,
    minutesPerHour: 60,
    hoursPerDay: 8,
    hoursPerWeek: 40,
    daysPerMonth: 30,
    daysPerYear: 365,
    labels: {
        minute: {
            full: "minute",
            plural: "minutes",
            short: "min"
        },
        hour: {
            full: "hour",
            plural: "hours",
            short: "h"
        },
        day: {
            full: "day",
            plural: "days",
            short: "d"
        },
        week: {
            full: "week",
            plural: "weeks",
            short: "wk"
        },
        month: {
            full: "month",
            plural: "months",
            short: "mon"
        },
        year: {
            full: "year",
            plural: "years",
            short: "y"
        }
    }
});

API

Экземпляр DurationFormatter предоставляет следующие методы:

• canParse (value): boolean — проверяет, может ли строка быть преобразована в значение длительности; возвращает true, если да, иначе false
  • value — (string) — строка для проверки

const formatter = gantt.ext.formatters.durationFormatter();
console.log(formatter.canParse("1 day"));
// true
 
console.log(formatter.canParse("abc"));
// false

• format (value): string — преобразует значение длительности в форматированную строку
  • value — (number) — значение длительности для преобразования

const formatter = gantt.ext.formatters.durationFormatter();
console.log(formatter.format(24));
// результат: 3 days

• parse (value): number — преобразует строку в значение длительности или возвращает ‘null’, если преобразование невозможно
  • value — (string) — строка для разбора

const formatter = gantt.ext.formatters.durationFormatter();
console.log(formatter.parse("1 day"));
// результат: 8

Подробнее о durationFormatter можно узнать в статье Расчёт рабочего времени.

Форматтер связей

Метод gantt.ext.formatters.linkFormatter(config) создает новый экземпляр LinkFormatter. Он имеет схожие методы и параметры конфигурации с форматтером длительности.

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

• linkFormatter (config): LinkFormatter — создает форматтер связей
  • config? — (object) — необязательный объект конфигурации с такими опциями:
    • durationFormatter? — (DurationFormatter) — экземпляр, созданный с помощью gantt.ext.formatters.durationFormatter(), который влияет на разбор и форматирование значений лагов/опережения.
    • labels? — (object) — подписи для различных типов связей:
      • finish_to_start? — (string) — подпись для связей "Finish to Start"
      • start_to_start? — (string) — подпись для связей "Start to Start"
      • finish_to_finish? — (string) — подпись для связей "Finish to Finish"
      • start_to_finish? — (string) — подпись для связей "Start to Finish"

Примеры:

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

const formatter = gantt.ext.formatters.linkFormatter();
// экземпляр форматтера создается с помощью фабричного метода

• short:

gantt.ext.formatters.linkFormatter()
   .format({id:1, type:"1", source: 1, target: 2, lag: 5});
// результат: "1SS+5 days"
 
var durationFormatter = gantt.ext.formatters.durationFormatter({
    short: true
});
gantt.ext.formatters.linkFormatter({durationFormatter: durationFormatter})
    .format({id:1, type:"2", source: 1, target: 2, lag: -1});
// результат: "1FF-1d"

• labels:

const formatter = gantt.ext.formatters.linkFormatter({
    // значения по умолчанию
    durationFormatter: gantt.ext.formatters.durationFormatter(),
    labels: {
        finish_to_start: "FS",
        start_to_start: "SS",
        finish_to_finish: "FF",
        start_to_finish: "SF"
    }
});

API

Экземпляр LinkFormatter предоставляет следующие методы:

• canParse (value): boolean — проверяет, может ли строка быть преобразована в объект связи; возвращает true, если да, иначе false
  • value — (string) — строка для проверки

const formatter = gantt.ext.formatters.linkFormatter();
console.log(formatter.canParse("1FS + 1 day"));
// true
 
console.log(formatter.canParse("abc"));
// false

• format (link): string — преобразует объект связи в строку
  • link — (Link) — объект связи для преобразования

const formatter = gantt.ext.formatters.linkFormatter();
 
formatter.format({id:1, type:"1", source: 1, target: 2, lag: 5});
// результат: "1SS+5 days"

• parse (value): object — преобразует строку в объект связи или возвращает ‘null’, если разбор невозможен. Обратите внимание, что link.target в разобранном объекте будет установлен в "null".
  • value — (string) — строка для разбора

const formatter = gantt.ext.formatters.linkFormatter();
 
formatter.parse("1SS+5 days");
// результат: {id:1, type:"1", source: 1, target: null, lag: 5}

Информация о форматах

LinkFormatter работает с двумя форматами ссылок:

• ${WBS} – короткий формат
  • ${WBS} – код WBS задачи

const formatter = gantt.ext.formatters.linkFormatter();
 
console.log(formatter.parse("1.1"));
// {id:1, type:"0", source: 2, target: 3, lag: 0}
 
console.log(formatter.format({id:2, type:"0", source: 1, target: 3, lag: 0}));
// 1.1

• ${WBS}${TYPE}${LAG} – полный формат
  • ${WBS} – код WBS задачи
  • ${TYPE} – тип связи. Поддерживаемые значения: 'FF', 'FS', 'SS', 'SF', либо как определено в конфигурации labels для LinkFormatter.
  • ${LAG} – лаг связи. Может быть положительным или отрицательным, например, +1 day или -1 day. Поддерживаемый формат зависит от параметра durationFormatter, переданного в конструктор LinkFormatter.

const formatter = gantt.ext.formatters.linkFormatter();
 
console.log(formatter.parse("1.1SS + 1 day"));
// {id:1, type:"1", source: 2, target: null, lag: 1}
 
console.log(formatter.format({id:1, type:"1", source: 2, target: 3, lag: 1}));
// 1.1SS + 1 day

Связи типа Finish-To-Start без лага или опережения будут отображаться в коротком формате, остальные связи – в полном формате. Аналогично, если в метод parse передан только код WBS задачи, форматтер предполагает тип Finish-to-Start с нулевым лагом.

Более подробно о методе linkFormatter можно узнать в статье Редактирование "на месте" в гриде.

Пользовательский форматтер

В Gantt можно создавать пользовательские форматтеры на основе встроенных. Эти пользовательские форматтеры можно подключать к редактору inline. Внутри грид Gantt хранит данные в своем ожидаемом формате, но при открытии редактора пользователю отображается значение в нужном формате.

Пользовательский форматтер — это объект с двумя функциями: format() и parse().

Функция format() преобразует число (для пользовательского форматтера длительности) или ссылку (для пользовательского форматтера ссылок) в нужное отображаемое значение. Функция parse() преобразует отформатированное значение обратно в число или объект ссылки.

Пример пользовательских форматтеров:

const customDurationFormatter = {
    format: function (duration) {
        let formattedDuration;
        // код преобразования числа в нужное значение
        return formattedDuration;
    },
    parse: function (formattedValue) {
        let duration;
        // код преобразования значения в число
        return duration;
    }
};
 
const customLinkFormatter = {
    format: function (link) {
        let formattedLink;
        // код преобразования объекта ссылки в нужное значение
        return formattedLink;
    },
    parse: function (formattedValue) {
        let link;
        // код преобразования значения в объект `link`
        return link
    }
};

Можно использовать существующие форматтеры внутри пользовательских и при необходимости изменять их вывод.

Пользовательские форматтеры назначаются редакторам так же, как и стандартные. Например:

const durationEditor = { 
    type: "duration", map_to: "duration", formatter: customDurationFormatter 
};

Ниже приведён пример с пользовательскими форматтерами для длительности и ссылок:

Related sample:  Custom duration and link formatters

Пользовательские правила для форм множественного числа

Стандартный Duration Formatter предназначен для работы с английскими формами множественного числа, где обычно достаточно добавить суффикс или немного изменить существительное.

В других языках часто есть несколько форм множественного числа и разные правила их использования. Для этого можно создать пользовательский форматтер, реализующий нужные правила для вашего языка. Пример ниже показывает, как реализовать такие правила для японского языка:

Related sample:  Custom duration formatter with different plural values for Japanese locale

К началу