本頁面由 Cloud Translation API 翻譯而成。

Class CalendarApp

允許指令碼讀取及更新使用者的 Google 日曆。這個類別可直接存取使用者的預設日曆，以及擷取使用者擁有或訂閱的其他日曆。

屬性

屬性	類型	說明
`Color`	`Color`	代表日曆服務中可用的命名顏色的列舉。
`EventColor`	`EventColor`	代表日曆服務中可用的命名活動顏色的列舉。
`EventType`	`EventType`	`EventType` 列舉。
`GuestStatus`	`GuestStatus`	列舉項目，代表邀請對象在活動中的狀態。
`Month`	`Month`	代表一年中月份的列舉。
`Visibility`	`Visibility`	代表事件可見度的列舉。
`Weekday`	`Weekday`	代表一週各日的列舉。

方法

方法	傳回類型	簡短說明
`createAllDayEvent(title, date)`	`CalendarEvent`	建立新的全天活動。
`createAllDayEvent(title, startDate, endDate)`	`CalendarEvent`	建立可跨越多天的全天活動。
`createAllDayEvent(title, startDate, endDate, options)`	`CalendarEvent`	建立可跨越多天的全天活動。
`createAllDayEvent(title, date, options)`	`CalendarEvent`	建立新的全天活動。
`createAllDayEventSeries(title, startDate, recurrence)`	`CalendarEventSeries`	建立新的全天活動系列。
`createAllDayEventSeries(title, startDate, recurrence, options)`	`CalendarEventSeries`	建立新的全天活動系列。
`createCalendar(name)`	`Calendar`	建立使用者擁有的新日曆。
`createCalendar(name, options)`	`Calendar`	建立使用者擁有的新日曆。
`createEvent(title, startTime, endTime)`	`CalendarEvent`	建立新事件。
`createEvent(title, startTime, endTime, options)`	`CalendarEvent`	建立新事件。
`createEventFromDescription(description)`	`CalendarEvent`	根據任意形式說明建立事件。
`createEventSeries(title, startTime, endTime, recurrence)`	`CalendarEventSeries`	建立新的事件系列。
`createEventSeries(title, startTime, endTime, recurrence, options)`	`CalendarEventSeries`	建立新的事件系列。
`getAllCalendars()`	`Calendar[]`	取得使用者擁有或訂閱的所有日曆。
`getAllOwnedCalendars()`	`Calendar[]`	取得使用者擁有的所有日曆。
`getCalendarById(id)`	`Calendar`	取得具有指定 ID 的日曆。
`getCalendarsByName(name)`	`Calendar[]`	取得使用者擁有或訂閱的所有指定名稱日曆。
`getColor()`	`String`	取得日曆的顏色。
`getDefaultCalendar()`	`Calendar`	取得使用者的預設日曆。
`getDescription()`	`String`	取得日曆的說明。
`getEventById(iCalId)`	`CalendarEvent`	取得具有指定 ID 的事件。
`getEventSeriesById(iCalId)`	`CalendarEventSeries`	取得具有指定 ID 的系列活動。
`getEvents(startTime, endTime)`	`CalendarEvent[]`	取得指定時間範圍內發生的所有事件。
`getEvents(startTime, endTime, options)`	`CalendarEvent[]`	取得在指定時間範圍內發生且符合指定條件的所有事件。
`getEventsForDay(date)`	`CalendarEvent[]`	取得特定日期發生的所有事件。
`getEventsForDay(date, options)`	`CalendarEvent[]`	取得在特定日期發生且符合指定條件的所有事件。
`getId()`	`String`	取得日曆的 ID。
`getName()`	`String`	取得日曆名稱。
`getOwnedCalendarById(id)`	`Calendar`	取得使用者擁有的指定 ID 日曆。
`getOwnedCalendarsByName(name)`	`Calendar[]`	取得使用者擁有的所有指定名稱日曆。
`getTimeZone()`	`String`	取得日曆的時區。
`isHidden()`	`Boolean`	決定日曆是否會在使用者介面中隱藏。
`isMyPrimaryCalendar()`	`Boolean`	判斷日曆是否為有效使用者的主要日曆。
`isOwnedByMe()`	`Boolean`	判斷日曆是否由您擁有。
`isSelected()`	`Boolean`	決定是否要在使用者介面中顯示日曆的活動。
`newRecurrence()`	`EventRecurrence`	建立新的週期物件，可用於建立事件週期規則。
`setColor(color)`	`Calendar`	設定日曆的顏色。
`setDescription(description)`	`Calendar`	設定日曆的說明。
`setHidden(hidden)`	`Calendar`	設定日曆是否會顯示在使用者介面中。
`setName(name)`	`Calendar`	設定日曆的名稱。
`setSelected(selected)`	`Calendar`	設定是否要在使用者介面中顯示日曆活動。
`setTimeZone(timeZone)`	`Calendar`	設定日曆的時區。
`subscribeToCalendar(id)`	`Calendar`	如果使用者獲准訂閱，系統會使用指定 ID 訂閱日曆。
`subscribeToCalendar(id, options)`	`Calendar`	如果使用者獲准訂閱，系統會使用指定 ID 訂閱日曆。

內容詳盡的說明文件

`createAllDayEvent(title, date)`

建立新的全天活動。

// Creates an all-day event for the moon landing and logs the ID.
const event = CalendarApp.getDefaultCalendar().createAllDayEvent(
    'Apollo 11 Landing',
    new Date('July 20, 1969'),
);
Logger.log(`Event ID: ${event.getId()}`);

參數

名稱	類型	說明
`title`	`String`	事件的名稱。
`date`	`Date`	活動日期 (只使用日期，系統會忽略時間)。

回攻員

CalendarEvent：已建立的事件。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`createAllDayEvent(title, startDate, endDate)`

建立可跨越多天的全天活動。

// Creates an all-day event for the Woodstock festival (August 15th to 17th) and
// logs the ID.
const event = CalendarApp.getDefaultCalendar().createAllDayEvent(
    'Woodstock Festival',
    new Date('August 15, 1969'),
    new Date('August 18, 1969'),
);
Logger.log(`Event ID: ${event.getId()}`);

參數

名稱	類型	說明
`title`	`String`	事件的名稱。
`startDate`	`Date`	活動開始的日期 (只會使用日期，系統會忽略時間)。
`endDate`	`Date`	活動結束的日期 (只會使用日期，系統會忽略時間)。結束日期不包含在內。

回攻員

CalendarEvent：已建立的事件。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`createAllDayEvent(title, startDate, endDate, options)`

建立可跨越多天的全天活動。

// Creates an all-day event for the Woodstock festival (August 15th to 17th) and
// logs the ID.
const event = CalendarApp.getDefaultCalendar().createAllDayEvent(
    'Woodstock Festival',
    new Date('August 15, 1969'),
    new Date('August 18, 1969'),
    {location: 'Bethel, White Lake, New York, U.S.', sendInvites: true},
);
Logger.log(`Event ID: ${event.getId()}`);

參數

名稱	類型	說明
`title`	`String`	事件的名稱。
`startDate`	`Date`	活動開始的日期 (只會使用日期，系統會忽略時間)。
`endDate`	`Date`	活動結束的日期 (只會使用日期，系統會忽略時間)。結束日期不包含在內。
`options`	`Object`	指定進階參數的 JavaScript 物件，如下所列。

進階參數

名稱	類型	說明
`description`	`String`	事件的說明。
`location`	`String`	活動的地點。
`guests`	`String`	以半形逗號分隔的電子郵件地址清單，這些電子郵件地址應新增為訪客。
`sendInvites`	`Boolean`	是否要傳送邀請電子郵件 (預設值：`false`)。

回攻員

CalendarEvent：已建立的事件。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`createAllDayEvent(title, date, options)`

建立新的全天活動。

// Creates an all-day event for the moon landing and logs the ID.
const event = CalendarApp.getDefaultCalendar().createAllDayEvent(
    'Apollo 11 Landing',
    new Date('July 20, 1969'),
    {location: 'The Moon'},
);
Logger.log(`Event ID: ${event.getId()}`);

參數

名稱	類型	說明
`title`	`String`	事件的名稱。
`date`	`Date`	活動日期 (只使用日期，系統會忽略時間)。
`options`	`Object`	指定進階參數的 JavaScript 物件，如下所列。

進階參數

名稱	類型	說明
`description`	`String`	事件的說明。
`location`	`String`	活動的地點。
`guests`	`String`	以半形逗號分隔的電子郵件地址清單，這些電子郵件地址應新增為訪客。
`sendInvites`	`Boolean`	是否要傳送邀請電子郵件 (預設值：`false`)。

回攻員

CalendarEvent：已建立的事件。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`createAllDayEventSeries(title, startDate, recurrence)`

建立新的全天活動系列。

// Creates an event series for a no-meetings day, taking place every Wednesday
// in 2013.
const eventSeries = CalendarApp.getDefaultCalendar().createAllDayEventSeries(
    'No Meetings',
    new Date('January 2, 2013 03:00:00 PM EST'),
    CalendarApp.newRecurrence()
        .addWeeklyRule()
        .onlyOnWeekday(CalendarApp.Weekday.WEDNESDAY)
        .until(new Date('January 1, 2014')),
);
Logger.log(`Event Series ID: ${eventSeries.getId()}`);

參數

名稱	類型	說明
`title`	`String`	系列叢書中的事件名稱
`startDate`	`Date`	系列中第一個事件的日期 (只使用日期，時間部分會遭到忽略)
`recurrence`	`EventRecurrence`	活動系列的重複設定

回攻員

CalendarEventSeries：已建立的活動系列

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`createAllDayEventSeries(title, startDate, recurrence, options)`

建立新的全天活動系列。

// Creates an event series for a no-meetings day, taking place every Wednesday
// in 2013.
const eventSeries = CalendarApp.getDefaultCalendar().createAllDayEventSeries(
    'No Meetings',
    new Date('January 2, 2013 03:00:00 PM EST'),
    CalendarApp.newRecurrence()
        .addWeeklyRule()
        .onlyOnWeekday(CalendarApp.Weekday.WEDNESDAY)
        .until(new Date('January 1, 2014')),
    {guests: 'everyone@example.com'},
);
Logger.log(`Event Series ID: ${eventSeries.getId()}`);

參數

名稱	類型	說明
`title`	`String`	系列叢書中的事件名稱
`startDate`	`Date`	系列中第一個事件的日期 (只使用日期，時間部分會遭到忽略)
`recurrence`	`EventRecurrence`	活動系列的重複設定
`options`	`Object`	指定進階參數的 JavaScript 物件，如下所列：

進階參數

名稱	類型	說明
`description`	`String`	系列活動的說明
`location`	`String`	系列活動的位置
`guests`	`String`	以半形逗號分隔的電子郵件地址清單，這些電子郵件地址應新增為系列活動的邀請對象
`sendInvites`	`Boolean`	是否傳送邀請電子郵件 (預設值：`false`)

回攻員

CalendarEventSeries：已建立的活動系列

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`createCalendar(name)`

建立使用者擁有的新日曆。

// Creates a new calendar named "Travel Plans".
const calendar = CalendarApp.createCalendar('Travel Plans');
Logger.log(
    'Created the calendar "%s", with the ID "%s".',
    calendar.getName(),
    calendar.getId(),
);

參數

名稱	類型	說明
`name`	`String`	新日曆的名稱

回攻員

Calendar - 新建立的日曆

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`createCalendar(name, options)`

建立使用者擁有的新日曆。

// Creates a new calendar named "Travel Plans" with a description and color.
const calendar = CalendarApp.createCalendar('Travel Plans', {
  description: 'A calendar to plan my travel schedule.',
  color: CalendarApp.Color.BLUE,
});
Logger.log(
    'Created the calendar "%s", with the ID "%s".',
    calendar.getName(),
    calendar.getId(),
);

參數

名稱	類型	說明
`name`	`String`	新日曆的名稱
`options`	`Object`	指定進階參數的 JavaScript 物件，如下所列：

進階參數

名稱	類型	說明
`location`	`String`	日曆的位置
`description`	`String`	日曆的說明
`timeZone`	`String`	要將日曆設為的時區，以「long」格式指定 (例如「America/New_York」(如 Joda.org 所列)
`color`	`String`	十六進位顏色字串 ("#rrggbb") 或 `CalendarApp.Colors` 中的值
`hidden`	`Boolean`	是否在使用者介面中隱藏日曆 (預設值：`false`)
`selected`	`Boolean`	是否在使用者介面中顯示日曆活動 (預設值：`true`)

回攻員

Calendar - 新建立的日曆

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`createEvent(title, startTime, endTime)`

建立新事件。

如果未指定時區，系統會根據指令碼的時區解讀時間值，而這個時區可能與日曆的時區不同。

// Creates an event for the moon landing and logs the ID.
const event = CalendarApp.getDefaultCalendar().createEvent(
    'Apollo 11 Landing',
    new Date('July 20, 1969 20:00:00 UTC'),
    new Date('July 21, 1969 21:00:00 UTC'),
);
Logger.log(`Event ID: ${event.getId()}`);

參數

名稱	類型	說明
`title`	`String`	活動名稱
`startTime`	`Date`	事件開始的日期和時間
`endTime`	`Date`	活動結束的日期和時間

回攻員

CalendarEvent：已建立的事件

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`createEvent(title, startTime, endTime, options)`

建立新事件。

如果未指定時區，系統會根據指令碼的時區解讀時間值，而這個時區可能與日曆的時區不同。

// Creates an event for the moon landing and logs the ID.
const event = CalendarApp.getDefaultCalendar().createEvent(
    'Apollo 11 Landing',
    new Date('July 20, 1969 20:00:00 UTC'),
    new Date('July 20, 1969 21:00:00 UTC'),
    {location: 'The Moon'},
);
Logger.log(`Event ID: ${event.getId()}`);

參數

名稱	類型	說明
`title`	`String`	活動名稱
`startTime`	`Date`	事件開始的日期和時間
`endTime`	`Date`	活動結束的日期和時間
`options`	`Object`	指定進階參數的 JavaScript 物件，如下所列：

進階參數

名稱	類型	說明
`description`	`String`	事件說明
`location`	`String`	活動地點
`guests`	`String`	以半形逗號分隔的電子郵件地址清單，這些電子郵件地址應新增為訪客
`sendInvites`	`Boolean`	是否傳送邀請電子郵件 (預設值：`false`)

回攻員

CalendarEvent：已建立的事件

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`createEventFromDescription(description)`

根據任意形式的說明建立事件。

說明的格式應與 UI 的「快速新增」功能相同。

// Creates a new event and logs its ID.
const event = CalendarApp.getDefaultCalendar().createEventFromDescription(
    'Lunch with Mary, Friday at 1PM',
);
Logger.log(`Event ID: ${event.getId()}`);

參數

名稱	類型	說明
`description`	`String`	事件的說明 (格式不限)

回攻員

CalendarEvent：已建立的事件

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`createEventSeries(title, startTime, endTime, recurrence)`

建立新的事件系列。

// Creates an event series for a team meeting, taking place every Tuesday and
// Thursday in 2013.
const eventSeries = CalendarApp.getDefaultCalendar().createEventSeries(
    'Team Meeting',
    new Date('January 1, 2013 03:00:00 PM EST'),
    new Date('January 1, 2013 04:00:00 PM EST'),
    CalendarApp.newRecurrence()
        .addWeeklyRule()
        .onlyOnWeekdays(
            [CalendarApp.Weekday.TUESDAY, CalendarApp.Weekday.THURSDAY])
        .until(new Date('January 1, 2014')),
);
Logger.log(`Event Series ID: ${eventSeries.getId()}`);

參數

名稱	類型	說明
`title`	`String`	系列叢書中的事件名稱
`startTime`	`Date`	系列活動的第一個活動開始的日期和時間
`endTime`	`Date`	系列活動中第一個活動結束的日期和時間
`recurrence`	`EventRecurrence`	活動系列的重複設定

回攻員

CalendarEventSeries：已建立的活動系列

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`createEventSeries(title, startTime, endTime, recurrence, options)`

建立新的事件系列。

// Creates an event series for a team meeting, taking place every Tuesday and
// Thursday in 2013.
const eventSeries = CalendarApp.getDefaultCalendar().createEventSeries(
    'Team Meeting',
    new Date('January 1, 2013 03:00:00 PM EST'),
    new Date('January 1, 2013 04:00:00 PM EST'),
    CalendarApp.newRecurrence()
        .addWeeklyRule()
        .onlyOnWeekdays(
            [CalendarApp.Weekday.TUESDAY, CalendarApp.Weekday.THURSDAY])
        .until(new Date('January 1, 2014')),
    {location: 'Conference Room'},
);
Logger.log(`Event Series ID: ${eventSeries.getId()}`);

參數

名稱	類型	說明
`title`	`String`	系列叢書中的事件名稱
`startTime`	`Date`	系列活動的第一個活動開始的日期和時間
`endTime`	`Date`	系列活動中第一個活動結束的日期和時間
`recurrence`	`EventRecurrence`	活動系列的重複設定
`options`	`Object`	指定進階參數的 JavaScript 物件，如下所列：

進階參數

名稱	類型	說明
`description`	`String`	系列活動的說明
`location`	`String`	系列活動的位置
`guests`	`String`	以半形逗號分隔的電子郵件地址清單，這些電子郵件地址應新增為系列活動的邀請對象
`sendInvites`	`Boolean`	是否傳送邀請電子郵件 (預設值：`false`)

回攻員

CalendarEventSeries：已建立的活動系列

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`getAllCalendars()`

取得使用者擁有或訂閱的所有日曆。

// Determines how many calendars the user can access.
const calendars = CalendarApp.getAllCalendars();
Logger.log(
    'This user owns or is subscribed to %s calendars.',
    calendars.length,
);

回攻員

Calendar[]：使用者可存取的所有日曆

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getAllOwnedCalendars()`

取得使用者擁有的所有日曆。

// Determines how many calendars the user owns.
const calendars = CalendarApp.getAllOwnedCalendars();
Logger.log('This user owns %s calendars.', calendars.length);

回攻員

Calendar[]：使用者擁有的所有日曆

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getCalendarById(id)`

取得具有指定 ID 的日曆。

// Gets the public calendar "US Holidays" by ID.
const calendar = CalendarApp.getCalendarById(
    'en.usa#holiday@group.v.calendar.google.com',
);
Logger.log('The calendar is named "%s".', calendar.getName());

參數

名稱	類型	說明
`id`	`String`	日曆 ID

回攻員

Calendar：具有指定 ID 的日曆，如果日曆不存在、使用者無法存取，或未訂閱該日曆，則為 null

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getCalendarsByName(name)`

取得使用者擁有或訂閱的所有指定名稱日曆。名稱不區分大小寫。

// Gets the public calendar named "US Holidays".
const calendars = CalendarApp.getCalendarsByName('US Holidays');
Logger.log('Found %s matching calendars.', calendars.length);

參數

名稱	類型	說明
`name`	`String`	日曆名稱

回攻員

Calendar[]：使用者可存取的所有同名日曆

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getColor()`

取得日曆的顏色。

// Opens the calendar by its ID.
// TODO(developer): Replace the ID with your own.
const calendar = CalendarApp.getCalendarById('222larabrown@gmail.com');

// Gets the color of the calendar and logs it to the console.
// For the default calendar, you can use CalendarApp.getColor() instead.
const calendarColor = calendar.getColor();
console.log(calendarColor);

回攻員

String：十六進位顏色字串 ("#rrggbb")。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getDefaultCalendar()`

取得使用者的預設日曆。

// Determines the time zone of the user's default calendar.
const calendar = CalendarApp.getDefaultCalendar();
Logger.log(
    'My default calendar is set to the time zone "%s".',
    calendar.getTimeZone(),
);

回攻員

Calendar：使用者的預設日曆

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getDescription()`

取得日曆的說明。

// Opens the calendar by its ID.
// TODO(developer): Replace the ID with your own.
const calendar = CalendarApp.getCalendarById('222larabrown@gmail.com');

// Sets the description of the calendar to 'Test description.'
calendar.setDescription('Test description');

// Gets the description of the calendar and logs it to the console.
// For the default calendar, you can use CalendarApp.getDescription() instead.
const description = calendar.getDescription();
console.log(description);

回攻員

String：這個日曆的說明。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getEventById(iCalId)`

取得具有指定 ID 的事件。如果系列叢書屬於預設日曆以外的日曆，則必須從該日曆呼叫這個方法。呼叫 getEventById(iCalId) 只會傳回預設日曆中的活動。

如果多個事件屬於同一系列，則可能會使用相同的 ID。在這種情況下，這個方法只會傳回該系列的第一個事件。

// Opens the calendar by its ID.
// TODO(developer): Replace the ID with your own.
const calendar = CalendarApp.getCalendarById('222larabrown@gmail.com');

// Creates an event for the moon landing.
const event = calendar.createEvent(
    'Apollo 11 Landing',
    new Date('July 20, 1969 20:05:00 UTC'),
    new Date('July 20, 1969 20:17:00 UTC'),
);

// Gets the calendar event ID and logs it to the console.
const iCalId = event.getId();
console.log(iCalId);

// Gets the event by its ID and logs the title of the event to the console.
// For the default calendar, you can use CalendarApp.getEventById(iCalId)
// instead.
const myEvent = calendar.getEventById(iCalId);
console.log(myEvent.getTitle());

參數

名稱	類型	說明
`iCalId`	`String`	事件 ID。

回攻員

CalendarEvent：具有指定 ID 的事件，如果事件不存在或使用者無法存取，則為 null。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getEventSeriesById(iCalId)`

取得具有指定 ID 的系列活動。如果提供的 ID 是單一 CalendarEvent，系統會傳回 CalendarEventSeries 和一系列中的單一事件。請注意，如果活動系列屬於預設日曆以外的日曆，則必須從該 CalendarApp 呼叫這個方法；直接呼叫 getEventSeriesById(iCalId) 只會傳回預設日曆中存在的活動系列。

// Opens the calendar by its ID.
// TODO(developer): Replace the ID with your own.
const calendar = CalendarApp.getCalendarById('222larabrown@gmail.com');

// Creates an event series for a daily team meeting from 1 PM to 2 PM.
// The series adds the daily event from January 1, 2023 through December 31,
// 2023.
const eventSeries = calendar.createEventSeries(
    'Team meeting',
    new Date('Jan 1, 2023 13:00:00'),
    new Date('Jan 1, 2023 14:00:00'),
    CalendarApp.newRecurrence().addDailyRule().until(new Date('Jan 1, 2024')),
);

// Gets the ID of the event series.
const iCalId = eventSeries.getId();

// Gets the event series by its ID and logs the series title to the console.
// For the default calendar, you can use CalendarApp.getEventSeriesById(iCalId)
// instead.
console.log(calendar.getEventSeriesById(iCalId).getTitle());

參數

名稱	類型	說明
`iCalId`	`String`	事件系列的 ID。

回攻員

CalendarEventSeries：具有指定 ID 的系列，如果系列不存在或使用者無法存取，則為 null。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getEvents(startTime, endTime)`

取得在指定時間範圍內發生的所有事件。

這個方法會傳回在指定時間範圍內開始、結束或涵蓋該時間範圍的事件。如果未指定時區，系統會根據指令碼的時區解讀時間值，而這個時區可能與行事曆的時區不同。

// Determines how many events are happening in the next two hours.
const now = new Date();
const twoHoursFromNow = new Date(now.getTime() + 2 * 60 * 60 * 1000);
const events = CalendarApp.getDefaultCalendar().getEvents(now, twoHoursFromNow);
Logger.log(`Number of events: ${events.length}`);

參數

名稱	類型	說明
`startTime`	`Date`	時間範圍的起始時間
`endTime`	`Date`	時間範圍的結束時間 (不包含在內)

回攻員

CalendarEvent[]：在時間範圍內發生的事件

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getEvents(startTime, endTime, options)`

取得在指定時間範圍內發生且符合指定條件的所有事件。

請注意，對 author、search 或 statusFilters 進行篩選的動作會在套用 start 和 max 之後執行。也就是說，即使有其他事件符合條件，傳回的事件數量可能會少於 max。

// Determines how many events are happening in the next two hours that contain
// the term "meeting".
const now = new Date();
const twoHoursFromNow = new Date(now.getTime() + 2 * 60 * 60 * 1000);
const events = CalendarApp.getDefaultCalendar().getEvents(
    now,
    twoHoursFromNow,
    {search: 'meeting'},
);
Logger.log(`Number of events: ${events.length}`);

參數

名稱	類型	說明
`startTime`	`Date`	時間範圍的起始時間
`endTime`	`Date`	時間範圍的結束時間 (不包含在內)
`options`	`Object`	指定進階參數的 JavaScript 物件，如下所列：

進階參數

名稱	類型	說明
`start`	`Integer`	要傳回的第一個事件的索引
`max`	`Integer`	要傳回的事件數量上限
`author`	`String`	活動建立者用來篩選結果的電子郵件地址
`search`	`String`	用於篩選結果的全文搜尋查詢
`statusFilters[]`	`GuestStatus`	用於篩選結果的狀態陣列

回攻員

CalendarEvent[]：在時間範圍內發生且符合條件的事件

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getEventsForDay(date)`

取得特定日期發生的所有事件。

如果事件是在指定日期開始、結束或涵蓋該日期，此方法會傳回該事件。

請注意，系統只會使用 Date 物件的日期部分，而忽略時間部分。日期會根據日曆時區，從當天午夜到隔天午夜算起。

// Determines how many events are happening today.
const today = new Date();
const events = CalendarApp.getDefaultCalendar().getEventsForDay(today);
Logger.log(`Number of events: ${events.length}`);

參數

名稱	類型	說明
`date`	`Date`	要擷取事件的日期 (只會使用日期，系統會忽略時間)

回攻員

CalendarEvent[]：在指定日期發生的事件

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getEventsForDay(date, options)`

取得在特定日期發生且符合指定條件的所有事件。

如果事件是在指定日期開始、結束或涵蓋該日期，此方法會傳回該事件。

請注意，系統只會使用 Date 物件的日期部分，而忽略時間部分。日期會根據日曆時區，從當天午夜到隔天午夜算起。

// Determines how many events are happening today and contain the term
// "meeting".
const today = new Date();
const events = CalendarApp.getDefaultCalendar().getEventsForDay(today, {
  search: 'meeting',
});
Logger.log(`Number of events: ${events.length}`);

參數

名稱	類型	說明
`date`	`Date`	要擷取事件的日期 (只會使用日期，系統會忽略時間)
`options`	`Object`	進階篩選選項

進階參數

名稱	類型	說明
`start`	`Integer`	要傳回的第一個事件的索引
`max`	`Integer`	要傳回的事件數量上限
`author`	`String`	活動建立者用來篩選結果的電子郵件地址
`search`	`String`	用於篩選結果的全文搜尋查詢
`statusFilters[]`	`GuestStatus`	用於篩選結果的狀態陣列

回攻員

CalendarEvent[]：在指定日期發生且符合條件的事件

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getId()`

取得日曆的 ID。使用者的預設日曆 ID 就是電子郵件地址。

// Opens the calendar by its ID.
// To get the user's default calendar, use CalendarApp.getDefaultCalendar().
// TODO(developer): Replace the ID with your own.
const calendar = CalendarApp.getCalendarById('222larabrown@gmail.com');

// Gets the ID of the calendar and logs it to the console.
const calendarId = calendar.getId();
console.log(calendarId);

回攻員

String：日曆 ID。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getName()`

取得日曆的名稱。

// Opens the calendar by its ID.
// TODO(developer): Replace the ID with your own.
const calendar = CalendarApp.getCalendarById('222larabrown@gmail.com');

// Gets the name of the calendar and logs it to the console.
// For the default calendar, you can use CalendarApp.getName() instead.
const calendarName = calendar.getName();
console.log(calendarName);

回攻員

String：這個日曆的名稱。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getOwnedCalendarById(id)`

取得使用者擁有的指定 ID 日曆。

如要找出日曆 ID，請在 Google 日曆中按一下日曆名稱旁的箭頭，然後選取「日曆設定」。ID 會顯示在設定頁面底部附近。

// Gets a (non-existent) private calendar by ID.
const calendar = CalendarApp.getOwnedCalendarById(
    '123456789@group.calendar.google.com',
);
Logger.log('The calendar is named "%s".', calendar.getName());

參數

名稱	類型	說明
`id`	`String`	日曆 ID

回攻員

Calendar：具有指定 ID 的日曆，如果日曆不存在或使用者不擁有該日曆，則為 null

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getOwnedCalendarsByName(name)`

取得使用者擁有的所有指定名稱日曆。名稱不區分大小寫。

// Gets a private calendar named "Travel Plans".
const calendars = CalendarApp.getOwnedCalendarsByName('Travel Plans');
Logger.log('Found %s matching calendars.', calendars.length);

參數

名稱	類型	說明
`name`	`String`	日曆名稱

回攻員

Calendar[]：使用者擁有的所有同名日曆

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`getTimeZone()`

取得日曆的時區。

// Opens the calendar by its ID.
// TODO(developer): Replace the ID with your own.
const calendar = CalendarApp.getCalendarById('222larabrown@gmail.com');

// Gets the time zone of the calendar and logs it to the console.
// For the default calendar, you can use CalendarApp.getTimeZone() instead.
const timeZone = calendar.getTimeZone();
console.log(timeZone);

回攻員

String：時區，以「長」格式指定 (例如「America/New_York」，如 Joda.org 所列)。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`isHidden()`

決定日曆是否會在使用者介面中隱藏。

// Opens the calendar by its ID.
// TODO(developer): Replace the ID with your own.
const calendar = CalendarApp.getCalendarById('222larabrown@gmail.com');

// Determines whether the calendar is hidden in the user interface and logs it
// to the console. For the default calendar, you can use CalendarApp.isHidden()
// instead.
const isHidden = calendar.isHidden();
console.log(isHidden);

回攻員

Boolean：如果日曆在使用者介面中隱藏，則為 true；如果未隱藏，則為 false。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`isMyPrimaryCalendar()`

判斷日曆是否為有效使用者的主日曆。

// Opens the calendar by its ID.
// TODO(developer): Replace the ID with your own.
const calendar = CalendarApp.getCalendarById('222larabrown@gmail.com');

// Determines whether the calendar is the default calendar for
// the effective user and logs it to the console.
// For the default calendar, you can use CalendarApp.isMyPrimaryCalendar()
// instead.
const isMyPrimaryCalendar = calendar.isMyPrimaryCalendar();
console.log(isMyPrimaryCalendar);

回攻員

Boolean：如果日曆是有效使用者的預設日曆，則為 true；如果不是，則為 false。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`isOwnedByMe()`

判斷日曆是否由您擁有。

// Gets a calendar by its ID. To get the user's default calendar, use
// CalendarApp.getDefault() instead.
// TODO(developer): Replace the ID with the calendar ID that you want to use.
const calendar = CalendarApp.getCalendarById(
    'abc123456@group.calendar.google.com',
);

// Determines whether the calendar is owned by you and logs it.
console.log(calendar.isOwnedByMe());

回攻員

Boolean：如果日曆屬於您，則為 true；否則為 false。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`isSelected()`

決定是否在使用者介面中顯示日曆活動。

// Gets the user's default calendar. To get a different calendar,
// use getCalendarById() instead.
const calendar = CalendarApp.getDefaultCalendar();

// Determines whether the calendar's events are displayed in the user interface
// and logs it.
console.log(calendar.isSelected());

回攻員

Boolean：如果日曆活動顯示在使用者介面中，則為 true；如果沒有顯示，則為 false

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`newRecurrence()`

建立新的週期物件，可用於建立事件週期規則。

// Creates an event series for a no-meetings day, taking place every Wednesday
// in 2013.
const recurrence = CalendarApp.newRecurrence()
                       .addWeeklyRule()
                       .onlyOnWeekday(CalendarApp.Weekday.WEDNESDAY)
                       .until(new Date('January 1, 2014'));
const eventSeries = CalendarApp.getDefaultCalendar().createAllDayEventSeries(
    'No Meetings',
    new Date('January 2, 2013 03:00:00 PM EST'),
    recurrence,
);
Logger.log(`Event Series ID: ${eventSeries.getId()}`);

回攻員

EventRecurrence：新的週期性物件，沒有設定規則 (以每週重複為準)

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly
https://www.google.com/calendar/feeds

`setColor(color)`

設定日曆的顏色。

// Opens the calendar by its ID.
// TODO(developer): Replace the ID with your own.
const calendar = CalendarApp.getCalendarById('222larabrown@gmail.com');

// Sets the color of the calendar to pink using the Calendar Color enum.
// For the default calendar, you can use CalendarApp.setColor() instead.
calendar.setColor(CalendarApp.Color.PINK);

參數

名稱	類型	說明
`color`	`String`	`CalendarApp.Color` 或十六進位顏色字串 ("#rrggbb")。

回攻員

Calendar：用於鏈結的這個日曆。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`setDescription(description)`

設定日曆的說明。

// Gets the user's default calendar. To get a different calendar,
// use getCalendarById() instead.
const calendar = CalendarApp.getDefaultCalendar();

// Sets the description of the calendar.
// TODO(developer): Update the string with the description that you want to use.
calendar.setDescription('Updated calendar description.');

參數

名稱	類型	說明
`description`	`String`	這個日曆的說明

回攻員

Calendar：用於鏈結的這個日曆

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`setHidden(hidden)`

設定日曆是否會顯示在使用者介面中。

參數

名稱	類型	說明
`hidden`	`Boolean`	`true` 可隱藏使用者介面中的日曆；`false` 可顯示日曆

回攻員

Calendar：用於鏈結的這個日曆

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`setName(name)`

設定日曆的名稱。

// Gets the user's default calendar. To get a different calendar,
// use getCalendarById() instead.
const calendar = CalendarApp.getDefaultCalendar();

// Sets the name of the calendar.
// TODO(developer): Update the string with the name that you want to use.
calendar.setName('Example calendar name');

參數

名稱	類型	說明
`name`	`String`	新名稱

回攻員

Calendar：用於鏈結的這個日曆

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`setSelected(selected)`

設定是否要在使用者介面中顯示日曆的活動。

// Gets the user's default calendar. To get a different calendar,
// use getCalendarById() instead.
const calendar = CalendarApp.getDefaultCalendar();

// Selects the calendar so that its events are displayed in the user interface.
// To unselect the calendar, set the parameter to false.
calendar.setSelected(true);

參數

名稱	類型	說明
`selected`	`Boolean`	`true` 可在使用者介面中顯示日曆活動；`false` 可隱藏活動

回攻員

Calendar：用於鏈結的這個日曆

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`setTimeZone(timeZone)`

設定日曆的時區。

// Gets the user's default calendar. To get a different calendar,
// use getCalendarById() instead.
const calendar = CalendarApp.getDefaultCalendar();

// Sets the time zone of the calendar to America/New York (US/Eastern) time.
calendar.setTimeZone('America/New_York');

參數

名稱	類型	說明
`timeZone`	`String`	以「長」格式指定的時區 (例如「America/New_York」，如 Joda.org 所列)。

回攻員

Calendar：用於鏈結的這個日曆。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`subscribeToCalendar(id)`

如果使用者獲准訂閱，系統會使用指定 ID 訂閱日曆。

// Subscribe to the calendar "US Holidays".
const calendar = CalendarApp.subscribeToCalendar(
    'en.usa#holiday@group.v.calendar.google.com',
);
Logger.log('Subscribed to the calendar "%s".', calendar.getName());

參數

名稱	類型	說明
`id`	`String`	要訂閱的日曆 ID

回攻員

Calendar：新訂閱的日曆

擲回

Error：如果沒有這個 ID 的日曆

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds

`subscribeToCalendar(id, options)`

如果使用者獲准訂閱，系統會使用指定 ID 訂閱日曆。

// Subscribe to the calendar "US Holidays", and set it to the color blue.
const calendar = CalendarApp.subscribeToCalendar(
    'en.usa#holiday@group.v.calendar.google.com',
    {color: CalendarApp.Color.BLUE},
);
Logger.log('Subscribed to the calendar "%s".', calendar.getName());

參數

名稱	類型	說明
`id`	`String`	要訂閱的日曆 ID。
`options`	`Object`	指定進階參數的 JavaScript 物件，如下所列。

進階參數

名稱	類型	說明
`color`	`String`	十六進位顏色字串 ("#rrggbb") 或 `CalendarApp.Colors` 中的值。
`hidden`	`Boolean`	是否在使用者介面中隱藏日曆 (預設值：`false`)。
`selected`	`Boolean`	是否要在使用者介面中顯示日曆活動 (預設值：如果也指定 `color`，則為 `true`；否則為 `false`)。

回攻員

Calendar：新訂閱的日曆。

擲回

Error：如果沒有這個 ID 的日曆

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權，或是相關 REST API 中的適當範圍：

https://www.googleapis.com/auth/calendar
https://www.google.com/calendar/feeds