日付・日時フィールドの処理

kintone には日付・時刻に関する複数のフィールドタイプがあり、それぞれ値のフォーマットが異なります。JavaScript カスタマイズで日付の計算や比較を行う際、フォーマットやタイムゾーンの扱いを誤ると、意図しない動作やバグの原因になります。

この記事では、各フィールドタイプのデータ形式を整理し、日付操作の実装パターンを紹介します。

日付系フィールドのデータ形式

kintone の日付系フィールドは 4 種類あり、それぞれ値のフォーマットが異なります。

値の取得と設定

基本的な取得

(() => {
  'use strict';

  kintone.events.on(['app.record.detail.show'], (event) => {
    const record = event.record;

    // 日付フィールド
    const dateValue = record['開始日'].value; // "2026-02-24"

    // 日時フィールド（UTC）
    const datetimeValue = record['作成日時'].value; // "2026-02-24T00:30:00Z"

    // 時刻フィールド
    const timeValue = record['開始時刻'].value; // "09:30"

    console.log('日付:', dateValue);
    console.log('日時:', datetimeValue);
    console.log('時刻:', timeValue);

    return event;
  });
})();

値の設定

(() => {
  'use strict';

  kintone.events.on(['app.record.create.show', 'app.record.edit.show'], (event) => {
    const record = event.record;

    // 日付フィールド: YYYY-MM-DD 形式
    record['開始日'].value = '2026-02-24';

    // 日時フィールド: ISO 8601 (UTC) 形式
    record['申請日時'].value = '2026-02-24T00:30:00Z';

    // 時刻フィールド: HH:mm 形式
    record['開始時刻'].value = '09:30';

    // 現在の日時を設定する場合
    const now = new Date();
    record['更新日付'].value = formatDate(now);
    record['更新日時'].value = now.toISOString().replace(/\.\d{3}Z$/, 'Z');

    return event;
  });

  /**
   * Date オブジェクトを YYYY-MM-DD 形式の文字列に変換する
   * @param { Date } date
   * @returns { string }
   */
  const formatDate = (date) => {
    const year = date.getFullYear();
    const month = String(date.getMonth() + 1).padStart(2, '0');
    const day = String(date.getDate()).padStart(2, '0');
    return `${year}-${month}-${day}`;
  };
})();

日付の計算

日数の差を計算する

2 つの日付フィールドの差（日数）を計算する例です。

(() => {
  'use strict';

  kintone.events.on(
    ['app.record.create.show', 'app.record.edit.show'],
    (event) => {
      const record = event.record;
      const startDate = record['開始日'].value;
      const endDate = record['終了日'].value;

      if (startDate && endDate) {
        const days = calcDaysDiff(startDate, endDate);
        record['期間（日）'].value = String(days);
      }

      return event;
    }
  );

  /**
   * 2 つの日付文字列の差を日数で返す
   * @param { string } startDateStr - 開始日 (YYYY-MM-DD)
   * @param { string } endDateStr - 終了日 (YYYY-MM-DD)
   * @returns { number } 日数差（終了日 - 開始日）
   */
  const calcDaysDiff = (startDateStr, endDateStr) => {
    const start = new Date(startDateStr);
    const end = new Date(endDateStr);
    const diffMs = end.getTime() - start.getTime();
    return Math.floor(diffMs / (1000 * 60 * 60 * 24));
  };
})();

営業日数を計算する

土日を除いた営業日数を計算する関数です。

/**
 * 2 つの日付間の営業日数（土日を除く）を計算する
 * @param { string } startDateStr - 開始日 (YYYY-MM-DD)
 * @param { string } endDateStr - 終了日 (YYYY-MM-DD)
 * @returns { number } 営業日数
 */
const calcBusinessDays = (startDateStr, endDateStr) => {
  const start = new Date(startDateStr);
  const end = new Date(endDateStr);
  let count = 0;
  const current = new Date(start);

  while (current <= end) {
    const dayOfWeek = current.getDay();
    // 0 = 日曜, 6 = 土曜
    if (dayOfWeek !== 0 && dayOfWeek !== 6) {
      count++;
    }
    current.setDate(current.getDate() + 1);
  }

  return count;
};

N 日後の日付を求める

指定日から N 日後の日付を計算する例です。

/**
 * 日付に指定日数を加算する
 * @param { string } dateStr - 基準日 (YYYY-MM-DD)
 * @param { number } days - 加算する日数
 * @returns { string } 加算後の日付 (YYYY-MM-DD)
 */
const addDays = (dateStr, days) => {
  const date = new Date(dateStr);
  date.setDate(date.getDate() + days);
  return formatDate(date);
};

const formatDate = (date) => {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const day = String(date.getDate()).padStart(2, '0');
  return `${year}-${month}-${day}`;
};

// 使用例
// addDays('2026-02-24', 30)  => "2026-03-26"
// addDays('2026-02-24', -7)  => "2026-02-17"

日時フィールドのタイムゾーン変換

日時フィールドの UTC 値を日本時間（JST）に変換して表示する方法です。

/**
 * UTC の日時文字列を日本時間の表示用文字列に変換する
 * @param { string } utcDateStr - UTC 日時 (YYYY-MM-DDTHH:mm:ssZ)
 * @returns { string } JST の表示用文字列 (YYYY/MM/DD HH:mm)
 */
const utcToJst = (utcDateStr) => {
  if (!utcDateStr) return '';

  const date = new Date(utcDateStr);

  return date.toLocaleString('ja-JP', {
    year: 'numeric',
    month: '2-digit',
    day: '2-digit',
    hour: '2-digit',
    minute: '2-digit',
    timeZone: 'Asia/Tokyo',
  });
};

// 使用例
// utcToJst('2026-02-24T00:30:00Z')  => "2026/02/24 09:30"

現在の日時を JST で設定する

日時フィールドの値は UTC で設定する必要がありますが、JavaScript の new Date() はブラウザのタイムゾーンに基づく時刻を返すため、toISOString() で UTC に変換できます。

// 現在の JST 時刻を UTC に変換して日時フィールドに設定
const now = new Date();
record['登録日時'].value = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
// JST で 2026/02/24 09:30 の場合 => "2026-02-24T00:30:00Z"

期間の判定

期限切れ判定

(() => {
  'use strict';

  kintone.events.on(['app.record.index.show'], (event) => {
    const records = event.records;

    records.forEach((record) => {
      const deadline = record['期限'].value;
      const status = record['ステータス'].value;

      if (isOverdue(deadline) && status !== '完了') {
        // 期限切れのレコードに対する処理
        console.log(`期限切れ: レコード ${record['$id'].value}`);
      }
    });

    return event;
  });

  /**
   * 指定した日付が過去かどうかを判定する
   * @param { string } dateStr - 日付 (YYYY-MM-DD)
   * @returns { boolean }
   */
  const isOverdue = (dateStr) => {
    if (!dateStr) return false;
    const deadline = new Date(dateStr);
    const today = new Date();
    today.setHours(0, 0, 0, 0);
    return deadline < today;
  };
})();

期間内の判定

/**
 * 指定した日付が期間内かどうかを判定する
 * @param { string } dateStr - 判定する日付 (YYYY-MM-DD)
 * @param { string } startStr - 期間の開始日 (YYYY-MM-DD)
 * @param { string } endStr - 期間の終了日 (YYYY-MM-DD)
 * @returns { boolean }
 */
const isInRange = (dateStr, startStr, endStr) => {
  if (!dateStr || !startStr || !endStr) return false;
  const date = new Date(dateStr);
  const start = new Date(startStr);
  const end = new Date(endStr);
  return date >= start && date <= end;
};

// 使用例
// isInRange('2026-02-24', '2026-02-01', '2026-02-28')  => true
// isInRange('2026-03-01', '2026-02-01', '2026-02-28')  => false

change イベントでの日付計算

フィールドの値が変更されたときに自動で日付計算を実行する例です。

(() => {
  'use strict';

  const events = [
    'app.record.create.change.開始日',
    'app.record.edit.change.開始日',
    'app.record.create.change.終了日',
    'app.record.edit.change.終了日',
  ];

  kintone.events.on(events, (event) => {
    const record = event.record;
    const startDate = record['開始日'].value;
    const endDate = record['終了日'].value;

    if (startDate && endDate) {
      const start = new Date(startDate);
      const end = new Date(endDate);
      const diffMs = end.getTime() - start.getTime();
      const days = Math.floor(diffMs / (1000 * 60 * 60 * 24));

      if (days >= 0) {
        record['期間（日）'].value = String(days);
      } else {
        record['期間（日）'].value = '';
      }
    } else {
      record['期間（日）'].value = '';
    }

    return event;
  });
})();

REST API クエリでの日付指定

REST API のクエリで日付・日時を条件に指定する場合のフォーマットを整理します。

// 日付フィールドの条件指定
const query1 = '開始日 = "2026-02-24"';
const query2 = '開始日 >= "2026-01-01" and 開始日 <= "2026-12-31"';

// 日時フィールドの条件指定（UTC で指定する）
const query3 = '作成日時 > "2026-02-24T00:00:00Z"';

// 組み込み関数の使用
const query4 = '開始日 = TODAY()';           // 今日
const query5 = '開始日 < TODAY()';           // 今日より前
const query6 = '作成日時 > NOW()';           // 現在日時以降
const query7 = '開始日 >= THIS_MONTH()';     // 今月以降
const query8 = '開始日 >= LAST_MONTH()';     // 先月以降
const query9 = '開始日 < FROM_TODAY(7, DAYS)'; // 7 日前より後

まとめ

• 日付（DATE）フィールドは YYYY-MM-DD 形式、日時（DATETIME）フィールドは UTC の YYYY-MM-DDTHH:mm:ssZ 形式
• 日時フィールドの値は常に UTC で保存されるため、表示時にはタイムゾーン変換が必要
• toLocaleString の timeZone オプションで特定のタイムゾーンでの表示が可能
• 日数の差、営業日数、N 日後の日付など、よく使う計算パターンをユーティリティ関数化しておくと便利
• change イベントで日付フィールドの変更を検知して自動計算を実装できる（ただし async/await は不可）
• REST API のクエリでは TODAY()、NOW()、FROM_TODAY() などの組み込み関数を活用できる

練習問題