2020年11月16日 FullCalendar v5.0.0を使いこなす（v4からの変更点まとめ）

UI開発者橋本

今月の11月12日からv5.4.0になったFullCalendarですが、v5.0.0（以下「v5」）が今年の6月にリリースされて以来、このバージョンの日本語記事がまだあまり出回っていないと感じました。
そのため今回はv5からの機能の追加や変更について、過去のバージョンと比較していくつかご紹介します。
v5には破壊的変更が多数含まれていますので、これからFullCalenderを使用される方はぜひご一読ください。

主な変更

v5での変更点については公式ドキュメントの「v5 Release Notes and Upgrade Guide」にまとまっています。
※v3からアップデートする方は「V4 Release Notes and Upgrade Guide」もご覧ください。

以下、個人的に重要だと思った点のまとめとなります。

ライブラリ読み込みに必要なファイル数の削減

以下は公式のダウンロードリンクからダウンロードしたFullCalendarを使い、HTMLファイルからlink要素とscript要素を使って読み込む場合の記述です。

v4までのFullCalendar

<link href='fullcalendar/core/main.css' rel='stylesheet'>
<link href='fullcalendar/daygrid/main.css' rel='stylesheet'>
<link href='fullcalendar/timegrid/main.css' rel='stylesheet'>

<script src='fullcalendar/core/main.js'></script>
<script src='fullcalendar/daygrid/main.js'></script>
<script src='fullcalendar/timegrid/main.js'></script>
<script>
  var calendarEl = document.getElementById('calendar');

  var calendar = new FullCalendar.Calendar(calendarEl, {
    plugins: [ 'dayGrid', 'timeGrid' ],
    defaultView: 'dayGridMonth'
  });

  calendar.render();
</script>

v5のFullCalendar

<link href='fullcalendar/main.css' rel='stylesheet'>

<script src='fullcalendar/main.js'></script>
<script>
  var calendarEl = document.getElementById('calendar');

  var calendar = new FullCalendar.Calendar(calendarEl, {
    defaultView: 'dayGridMonth'
  });

  calendar.render();
</script>

CSSファイルとJSファイルの読み込みが1つでよくなりました。
1つのファイルで全機能を読み込むためファイルサイズは大きくなり、pluginsの記述無しで公式で定義されている各タイプのカレンダーが活用できるようになりました。

ファイルサイズが気になる場合は、以下のようにESモジュールからFullCalendarを使用すれば今まで通り必要なカレンダータイプのみ読み込むのでこちらを使いましょう。
また、こちらはv5からCSSを読み込む記述が不要になっています。

import { Calendar } from '@fullcalendar/core';
import timeGridPlugin from '@fullcalendar/timegrid';

// import '@fullcalendar/core/main.css'; // 不要
// import '@fullcalendar/daygrid/main.css'; // 不要
// import '@fullcalendar/timegrid/main.css'; // 不要

let calendar = new Calendar(calendarEl, {
  plugins: [ timeGridPlugin ]
});

CSSおよびDOM構造の単純化

v4まではtable要素の中に複数のtable要素が入っていたりと複雑なDOM構造をしていたカレンダーでしたが、かなり単純化され要素の入れ子が少なくなりました。
また、CSSはv4から完全に書き直されており、セレクターの記述が以下の通り、よりフラットになったため、CSSが上書きしやすくなっています。

.fc-event .fc-title　→　.fc-event-title

そのため以前のバージョンでCSSをカスタマイズしていた場合はすべてv5用に書き換えるか、後述するclassNameオプションを使用する必要があります。

classNameオプションの追加

FullCalendarのカレンダーではさまざまな場所でfc-〇〇といったクラスがデフォルトで付けられていますが、そこに固有のクラス名を追加で付与することができるオプションです。
以下のように〇〇ClassNamesという形でオプションが複数追加されました。

dayHeaderClassNames
dayCellClassNames
slotLabelClassNames
slotLaneClassNames
weekNumberClassNames
allDayClassNames
eventClassNames
moreLinkClassNames
resourceLabelClassNames
resourceLaneClassNames
resourceGroupLabelClassNames
resourceGroupLaneClassNames
resourceAreaHeaderClassNames
headerClassNames
cellClassNames
noEventsClassNames
nowIndicatorClassNames

上記の中でeventClassNamesを例にとって実際にクラス名を付与する方法を以下に記述しました。
関数を用いることで、付けるクラス名を分岐できたりもします。

eventClassNames: [ 'free', 'work' ];

// 条件によってクラス名を分岐させる場合
eventClassNames: function(data) {
  if (data.event.extendedProps.holiday) {
    return [ 'free' ];
  } else {
    return [ 'work' ];
  }
}

オプション名の命名変更

Unknown option 'オプション名'というエラーが出る場合は、この変更によるものです。
既存のオプションの名前がv5にていくつか変更されたため、以前のオプション名を用いたままだとエラーが出てオプションが反映されません。
よく使われるオプションでいうと、「defaultView」が「initialView」、「defaultDate」が「initialDate」に命名が変更されています。
その他のオプション名の変更について、詳細はV5 Release Notes and Upgrade Guideの「Toolbar」からご確認ください。

印刷用レンダリングの最適化

有料のプレミアムプラグインのみの機能になりますが、カレンダーのページで右クリックからの印刷を行うとき、印刷用に特化したレンダリングをしてくれるようになりました。
こちらの機能は、前述したHTMLファイルからFullCalendarを読み込む場合は自動的に含まれていますが、ESモジュールから読み込む場合は以下の通り、プラグインをインストールする必要があります。

1.@fullcalendar/adaptiveをインストール

npm install --save @fullcalendar/adaptive

2.プラグインリストに追加

import adaptivePlugin from '@fullcalendar/adaptive';

let calendar = new Calendar({
  plugins: [ adaptivePlugin ]
});

この機能名は「adaptive」、つまり適応型と命名されているのですが、その理由としては今後のアップデートで印刷のみではなく、スマホやタブレットサイズの画面にも対応するカレンダーをレンダリングできるようになる予定だからです！
FullCalendarがレスポンシブ対応になる日もそう遠くなさそうですね！

再レンダリングメソッドの削除

これまではCalendar.rerenderEventsメソッド、Calendar.rerenderResourcesメソッドでのみカレンダーの再レンダリングを行っていました。
v5からはその2つが削除され、カレンダーのレンダリングに使用するCalendar.renderを再度使用することで、任意のタイミングでいつでも再レンダリングできるようになりました。

あとがき

今回はFullCalendar v5の変更点をまとめてみました。

FullCalendarは開発者が意欲的にアップデートを続けているため、利用されている方やこれから利用を考えている方は必ず公式ドキュメントおよび使用するバージョンのリリースノートを確認しましょう。
主観にはなりますが、Web上にあるFullCalendarの日本語記事は投稿日が古いものも多く、参考にしても最新バージョンではエラーを引き起こしてしまう可能性が高いです。
どのライブラリやツールにもいえることですが、公式ドキュメントに情報で勝るものはありません。