イベント
続いて、カレンダーからのイベントの取得を紹介します。図4はそのサンプルアプリのキャプチャです。
イベント一覧の取得
カレンダーに登録されたイベントの一覧を取得する場合、表7のように4つのメソッドがあります。それぞれ制限や結果などが異なるため、少々わかりにくいかと思います。しかし、基本的にはfindEventもしくはfindEventWithOptionsメソッドを使う事をおすすめします。また、AndroidとiOSの双方で利用できるので特別な理由がない限り、その他のメソッドを使う必要はないでしょう。
ちなみに、findEventはfindEventWithOptionsのoptionsが空オブジェクトとしてデフォルト指定されたものと同一なので、実体の処理も同じものです。このカレンダープラグインには、～WithOptionsが追加されたメソッドがfindEvent以外にもありますが、～WithOptionsのついてないメソッドはすべて空のオプションが指定されたものと同じ意味になります。
| メソッド名 | 対応するプラットフォーム |
|---|---|
| findEvent(title, location, notes, startDate, endDate, successCallback, errorCallback) | Android, iOS |
| findEventWithOptions(title, location, notes, startDate, endDate, options, successCallback, errorCallback) | Android, iOS |
| findAllEventsInNamedCalendar(calendarName, successCallback, errorCallback) | iOS |
| listEventsInRange(startDate,endDate,successCallback, errorCallback) | Android |
また、それぞれのメソッドで指定できるパラメータの意味は表8のようになっています。
| パラメータ名 | 型 | 説明 |
|---|---|---|
| title | DOMString | イベントのタイトルとして含まれる文字列 |
| location | DOMString | 場所として含まれる文字列 |
| notes | DOMString | メッセージ（メモ）として含まれる文字列 |
| startDate | Date | イベントの開始日時 |
| endDate | Date | イベントの終了日時 |
| options | Object | カレンダー（calendarName）もしくはイベントのID（id）を指定する場合に指定する |
| successCallback | Function | 取得できたときのコールバック関数 |
| errorCallback | Function | 失敗したときのコールバック関数 |
| calendarName | DOMString | カレンダーの名前 |
また、表9はfindEvent、findEventWithOptions、findAllEventsInNamedCalendarメソッドで一覧を取得したときの各イベントオブジェクトのプロパティです。
| プロパティ名 | 型 | 説明 |
|---|---|---|
| id | DOMString | イベントを識別するためのID |
| title | DOMString | カレンダーの名称 |
| message | DOMString | メッセージ（メモ） |
| location | DOMString | 場所 |
| startDate | DOMString | YYYY-MM-DD HH:MM:SS形式 |
| endDate | DOMString | YYYY-MM-DD HH:MM:SS形式 |
| lastModifiedDate | DOMString | YYYY-MM-DD HH:MM:SS形式 （iOSのみ） |
| calendar | DOMString | イベントが登録されているカレンダー（iOSのみ） |
| allday | Boolean | 全日のイベントかどうか（Androidのみ） |
しかし、Androidの場合にはcalendarが取得できないので、Androidでそのプロパティが必要な場合はlistEventsInRangeメソッドを利用する必要があります。
listEventsInRangeの場合は、他のメソッドと多少異なり表10のようなイベントオブジェクトのプロパティが取得できるので現状ではこちらを使う必要が出てしまいます。
| プロパティ名 | 型 | 説明 |
|---|---|---|
| id | DOMString | イベントを識別するための内部ID（_id） |
| event_id | DOMString | イベントの識別ID |
| calendar_id | DOMString | カレンダーの識別ID |
| title | DOMString | カレンダーの名称 |
| eventLocation | DOMString | 場所 |
| dtstart | Number | 開始日時（ミリ秒）例：1479859200000 |
| dtend | Number | 終了日時（ミリ秒）例：1479859200000 |
| allDay | Boolean | 全日のイベントかどうか |
リスト10は一覧を取得するサンプルコードです。
function EventListController($scope,$state){
// : 省略
$scope.findEventWithOptions = function(){
// : 省略
// （1） 検索時するカレンダーを指定
var options = window.plugins.calendar.getCalendarOptions();
options.calendarName = "Codezine"; // iOSの場合
// （2） 検索する際にオプションを指定
window.plugins.calendar.findEventWithOptions(null,null,null,startDate, endDate, options,function (events) {
// : 省略
});
}
// : 省略
};
iOSでは（1）のようにカレンダーを指定して（2）findEventWithOptionsメソッドを利用できます。
AndroidではcalendarNameを指定しても無視されるので、findEventと同じ振る舞いになります。ただし、双方ともidを指定することができ、その場合には特定のイベントが取得できます。その他の引数は利用されません。
最後に
スマホのカレンダーAPIを使う事で、ユーザが端末間で同期したいイベントを簡単に管理できます。そのため、他のツールで登録したイベントも取得することができ、自動でアラートを出すようなアプリはもちろんの事、他の任意の処理をする仕組みなども簡単に作成できます。Cordovaで自分向けのアプリを試しに作ろうと思っている方にもおすすめのプラグインです。
次回は、カレンダーにイベントを登録する処理や更新、削除する方法を紹介します。
