Custom time zone designation option specification definition

[jungeun-cho]

Version

1.13

Custom Timezone Setting

AS-IS

const cal = new Calendar(el, {
    ...
    timezones: [
            {
              tooltip: 'Seoul',
              displayLabel: 'GMT+09:00',
              timezoneOffset: 540
            },
            {
              tooltip: 'New York',
              displayLabel: 'GMT-05:00',
              timezoneOffset: -300
            },
    ]
});

The timezones and timezoneOffset will be deprecated.

The system local setting and the default time zone should match.

However, in Calendar 2.0 we have to take into account that the system local settings and user-defined primary time zones may be different.

In order to calculate the offset, timezone info(e.g. 'Asia/Seoul', 'America/New_York') is essential.
A new timezone option is available. Set the list of time zones in the zones property.
Basically, it will calculate the offset using Intl.DateTimeFormat with the value of the timezone property entered.

TO-BE

const cal = new Calendar(el, {
    timezone: {
        zones: [
            {
              timezoneName: 'Asia/Seoul',
              tooltip: 'Seoul',
              displayLabel: 'GMT+09:00'
            },
            {
              timezoneName: 'America/New_York',
              tooltip: 'New York',
              displayLabel: 'GMT-05:00'
            },
        ]
    }
});

If you define the offsetCalculator property, the offset calculation is done with this function.
The offsetCalculator option allows you to set up a function that returns the timezone offset for that time using date libraries like js-joda and moment-timezone.

The offsetCalculator option is useful when your browser does not support Intl.DateTimeFormat and formatToPart, or you want to use the date library you are familiar with.

const cal = new Calendar(el, {
    timezone: {
        zones: [
            {
              timezone: 'Asia/Seoul',
              tooltip: 'Seoul',
              displayLabel: 'GMT+09:00'
            },
            {
              timezone: 'America/New_York',
              tooltip: 'New York',
              displayLabel: 'GMT-05:00'
            },
        ],
        offsetCalculator: function(timezone, timestamp){
            // matches 'getTimezoneOffset()' of Date API
            // e.g. +09:00 => -540, -04:00 => 240
            return moment.tz.zone(timezone).utcOffset(timestamp);
        },
    }
});

If you are using a custom time zone, you need to add a polyfill if all of the following are true.

1. Browser does not support Intl.DateTimeFormat and formatToPart.
2. The offsetCalculator option is not defined.
3. Your service supports Internet Explorer.

UMD

• Intl ployfill
• I copied the node_modules/@formatjs/intl-datetimeformat/polyfill.umd.min.js file and used it.
• You also need node_modules/@formatjs/intl-getcanonicallocales/polyfill.umd.min.js file to support lower versions of Internet Explorer 11.

CommonJS / ES6

• @formatjs/intl
• @formatjs/intl-datetimeformat
• @formatjs/intl-getcanonicallocales
  • This is used to support lower versions of Internet Explorer 11.

  // for IE9, IE10, IE11
  require('es6-set/implement');
  require('weakmap-polyfill');
  require('@formatjs/intl-getcanonicallocales/polyfill');
  require('@formatjs/intl-locale/polyfill');
  require('@formatjs/intl-pluralrules/polyfill');
  require('@formatjs/intl-numberformat/polyfill');
  require('@formatjs/intl-numberformat/locale-data/en');
  require('@formatjs/intl-datetimeformat/polyfill');
  require('@formatjs/intl-datetimeformat/locale-data/en');
  require('@formatjs/intl-datetimeformat/add-all-tz');