GAS Calendar 操作日曆行程

CalendarApp 服務讓你能夠讀取、建立、修改 Google 日曆中的活動 (Events)。這對於排班系統、會議提醒或自動行程規劃非常有用。

建立與取得行程

你可以手動指定時段來建立活動，或是搜尋一段特定時間內的行程。

/**
 * 在主日曆建立一個新行程
 */
function createCalendarEvent() {
  const calendar = CalendarApp.getDefaultCalendar();
  
  const title = 'GAS 進階課程';
  const startTime = new Date('2024-05-20T14:00:00');
  const endTime = new Date('2024-05-20T16:00:00');
  
  // 建立行程，並加入地點與說明
  const event = calendar.createEvent(title, startTime, endTime, {
    location: 'Google Meet',
    description: '檢視自動化腳本執行進度。'
  });
  
  console.log(`行程已建立：${event.getId()}`);
}

基礎操作函數語法說明

• CalendarApp.getDefaultCalendar()：取得帳戶的主日曆。
• calendar.createEvent(title, startTime, endTime, options)：建立一個定時行程。
• calendar.getEvents(startTime, endTime)：取得特定時間區間內的所有活動陣列。
• calendar.getEventsForDay(date)：取得特定某一天的所有活動。

活動樣式與顏色設定

為了讓日曆看起來更有條理，你可以根據活動性質動態設定顏色。

/**
 * 將所有標題包含「會議」的活動設為紅色
 */
function updateEventColors() {
  const events = CalendarApp.getDefaultCalendar().getEventsForDay(new Date());
  
  events.forEach(event => {
    if (event.getTitle().includes('會議')) {
      // 顏色 ID 1=淺藍, 4=紅, 10=綠 (以此類推)
      event.setColor(CalendarApp.EventColor.RED);
    }
  });
}

顏色與屬性相關函數語法說明

• event.setColor(color)：設定活動在日曆上的顏色。
• event.setTitle(title) / event.setDescription(desc)：動態更新活動內容。
• event.setAllDayDate(date)：將活動轉為「全天活動」。

行程衝突檢查

在自動排程時，檢查該時段是否已有其他工作是非常重要的。

/**
 * 檢查特定時段是否已有行程 (預約系統必備)
 */
function checkAvailability() {
  const start = new Date('2024-06-01T10:00:00');
  const end = new Date('2024-06-01T11:00:00');
  
  const events = CalendarApp.getDefaultCalendar().getEvents(start, end);
  
  if (events.length > 0) {
    console.log('此時段已有行程，無法預約');
    return false;
  }
  
  console.log('此時段目前有空');
  return true;
}

重複性活動 (Recurrence)

你可以建立每週一次、每月一次的循環行程。

/**
 * 建立每週一執行的週會行程
 */
function createRecurringEvent() {
  const calendar = CalendarApp.getDefaultCalendar();
  
  // 建立重複規則：每週執行一次
  const recurrence = CalendarApp.newRecurrence().addWeeklyRule().onlyOnWeekday(CalendarApp.Weekday.MONDAY);
  
  const startTime = new Date('2024-05-01T09:00:00');
  const endTime = new Date('2024-05-01T10:00:00');
  
  calendar.createEventSeries('週會', startTime, endTime, recurrence);
}

重複規則相關函數語法說明

• CalendarApp.newRecurrence()：建立重複規則建構器。
• addWeeklyRule() / addMonthlyRule() / addDailyRule()：設定重複的週期類型。
• calendar.createEventSeries()：傳入重複規則，建立一系列活動。
• eventSeries.deleteEventSeries()：刪除整組重複活動。