CalendarService API の使用

カレンダーベースの機能を持つ Lightning Web コンポーネントを開発するには、デバイスの標準のカレンダー機能にアクセスする方法として CalendarService API を使用します。

CalendarService をコンポーネント定義にインポートして、CalendarService API 関数をコードで使用できるようにします。
カレンダー関連の関数をコールする前に CalendarService が使用できることをテストして確認します。
カレンダー機能は、行動の作成、参照、更新、削除を行うために使用します。

コンポーネントの JavaScript ファイルで、標準 JavaScript import ステートメントを使用して CalendarService をインポートします。具体的には、次のように lightning/mobileCapabilities モジュールから getCalendarService() ファクトリ関数をインポートします。

コンポーネントにインポートされたら、ファクトリ関数を使用して CalendarService のインスタンスを取得します。CalendarService インスタンスでは、ユーティリティ関数と定数を使用して、可用性を確認します。次に、カレンダー関連の関数を使用して、関連する機能を実行します。

CalendarService は、物理デバイスのハードウェアおよびプラットフォーム機能に連動します。CalendarService を使用するコンポーネントは、デスクトップコンピュータやモバイルブラウザでエラーなく表示されますが、カレンダー関連の機能は動作しません。このようなエラーを回避するには、使用する前に CalendarService 機能を使用できるかどうかをテストします。

CalendarService を使用すれば、デバイスのカレンダーを Lightning Web コンポーネントに簡単にインポートできます。まず、getCalendars() を使用して、コンポーネント内から利用可能なデバイスのカレンダーにアクセスできるようにします。次に、カレンダーのデータを目的の方法で処理します。

次に例を示します。

getEvents() 関数を使用して、指定した日付範囲のすべての行動を取得します。まず、getEvents() 関数を必要なパラメータを指定してコールします。次に、行動データを目的の方法で処理または表示します。

たとえば、カレンダーコンポーネントに「週表示」と「月表示」がある場合、startDateSecondsUTC と endDateSecondsUTC パラメータを調整して、表示する日付範囲を適切に指定する必要があります。いずれかのモバイルデバイスのカレンダーの行動を表示したくない場合は、calendars[] 配列で使用するカレンダーを指定します。

次に例を示します。

addEvent() 関数を使用して、モバイルデバイスに新しい行動を作成し、追加します。まず、addEvent() 関数を必要なパラメータを指定してコールします。コールに成功した場合は、成功メッセージで処理するか、任意の方法で処理します。addEvent() 関数の戻り値の詳細については、「暗黙のデータ設定」参照してください。

次に例を示します。

updateEvent() 関数を使用して、モバイルデバイスの行動を更新します。まず、updateEvent() 関数を必要なパラメータを指定してコールします。コールに成功した場合は、成功メッセージで処理するか、任意の方法で処理します。updateEvent() 関数の戻り値の詳細については、「暗黙のデータ設定」参照してください。

次に例を示します。

updateEvent() を使用することは、行動データの元に戻せない変更が可能なため、本質的に危険なアクションです。この機能をコンポーネントで使用する場合には注意が必要です。最低でも、ユーザに対して、アクションの結果を明確に示す確認ウィンドウを追加し、必要な場合にキャンセルできるオプションを提供することを検討してください。

removeEvent() 関数を使用して、モバイルデバイスの行動を削除します。まず、removeEvent() 関数を必要なパラメータを指定してコールします。コールに成功した場合は、成功メッセージで処理するか、任意の方法で処理します。

次に例を示します。

removeEvent() を使用することは、行動データの元に戻せない変更が可能なため、本質的に危険なアクションです。この機能をコンポーネントで使用する場合には注意が必要です。最低でも、ユーザに対して、アクションの結果を明確に示す確認ウィンドウを追加し、必要な場合にキャンセルできるオプションを提供することを検討してください。

行動データを CalendarService の関数 (すなわち addEvent() および updateEvent() 関数) に渡すとき、CalendarService では行動データの一部を変更してから返すことができます。この動作をここでは暗黙のデータ設定と呼びます。これは、ユーザが他のプロパティを変更したことにより、CalendarService がプロパティの値を調整する場合に発生します。

たとえば、終日の行動を新しく追加する場合 (または既存の行動を終日に更新する場合)、開始時刻または終了時刻を指定すると、CalendarService がそれらの時刻を拒否します。代わりに、開始時刻は 00:00:00 (12:00:00 AM) に、終了時刻は 23:59:59 (11:59:59 PM) に設定されます。

暗黙のデータ設定は、定期的な行動の詳細を変更する場合にも発生します。定期的な行動が変更されるたびに、古い ID が上書きされ、新しく生成された ID に置き換えられます。

addEvent() および updateEvent() 関数を使用する際には、この点を考慮してください。コードでは、常に CalendarService が返す行動データの設定を使用してください。コンポーネントで未加工 (未設定) の行動データを使用すると、エラーや不正な動作につながることがあります。