Available only in PRO Edition

格式化器扩展

此功能仅在 PRO 版本中可用。

gantt.ext.formatters 扩展提供了两种格式化数值的方式：

您也可以通过现有格式化器创建自定义格式化器。

持续时间格式化器

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"); // 如果 enter:"day"（默认），解析为 1 天
formatter.parse("1"); // 如果 enter:"hour"，解析为 1 小时

store:

formatter.parse("1 day"); // 如果 store:"hour"，存储为 8
formatter.parse("1 day"); // 如果 store:"minute"，存储为 480

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) - 完成到开始类型链接的标签
    - start_to_start? - (string) - 开始到开始类型链接的标签
    - finish_to_finish? - (string) - 完成到完成类型链接的标签
    - start_to_finish? - (string) - 开始到完成类型链接的标签

示例：

使用默认设置创建一个链接格式化器：

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'，或者由LinkFormatter的labels配置定义。
- ${LAG} - 链接时差。可以为正或负，例如+1 day或-1 day。支持的格式取决于传递给LinkFormatter构造函数的durationFormatter参数。

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

没有任何时差的“完成-开始”链接将以简短格式显示，其他类型的链接则使用完整格式。同样，如果仅向parse方法提供任务的 WBS 代码，格式化器会默认其为零时差的“完成-开始”类型。

关于linkFormatter方法的更多细节，请参见在网格中进行内联编辑文章。

自定义格式化器

Gantt 工具允许您基于内置格式化器创建自定义格式化器。您可以将这些自定义格式化器添加到内联编辑器中。在内部，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 
};

下面是一个自定义持续时间和链接格式化器的示例：

复数形式的自定义规则

默认的 Duration Formatter 设计用于处理英语的复数形式，通常只需添加后缀或稍作词形变化。

其他语言往往有多种复数形式，并且使用规则各不相同。为此，您可以创建一个自定义格式化器，以应用适合您语言的规则。以下示例展示了如何为日语实现这些规则：