Class CalendarApp

“日历”应用

允许脚本读取和更新用户的 Google 日历。此类可直接访问用户的默认日历,还可以检索用户拥有或订阅的其他日历。

属性

属性类型说明
ColorColor一个枚举,表示 Google 日历服务中提供的命名颜色。
EventColorEventColor表示日历服务中提供的命名活动颜色的枚举。
EventTransparencyEventTransparencyEventTransparency 枚举。
EventTypeEventTypeEventType 枚举。
GuestStatusGuestStatus一个枚举,表示访客对活动的状态。
MonthMonth表示一年中的月份的枚举。
VisibilityVisibility表示事件公开范围的枚举。
WeekdayWeekday表示星期几的枚举。

方法

方法返回类型简介
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()}`);

参数

名称类型说明
titleString活动的标题。
dateDate活动的日期(仅使用日期;时间会被忽略)。

返回

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()}`);

参数

名称类型说明
titleString活动的标题。
startDateDate活动的开始日期(仅使用日期,时间会被忽略)。
endDateDate活动的结束日期(仅使用日期,时间会被忽略)。结束日期不包含在内。

返回

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()}`);

参数

名称类型说明
titleString活动的标题。
startDateDate活动的开始日期(仅使用日期,时间会被忽略)。
endDateDate活动的结束日期(仅使用日期,时间会被忽略)。结束日期不包含在内。
optionsObject用于指定高级参数的 JavaScript 对象,如下所列。

高级参数

名称类型说明
descriptionString事件说明。
locationString活动的地点。
guestsString应添加为访客的电子邮件地址的逗号分隔列表。
sendInvitesBoolean是否发送邀请电子邮件(默认值: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()}`);

参数

名称类型说明
titleString活动的标题。
dateDate活动的日期(仅使用日期;时间会被忽略)。
optionsObject用于指定高级参数的 JavaScript 对象,如下所列。

高级参数

名称类型说明
descriptionString事件说明。
locationString活动的地点。
guestsString应添加为访客的电子邮件地址的逗号分隔列表。
sendInvitesBoolean是否发送邀请电子邮件(默认值: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()}`);

参数

名称类型说明
titleString系列活动的标题
startDateDate系列中第一个事件的日期(仅使用日期,时间会被忽略)
recurrenceEventRecurrence活动系列的重复设置

返回

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()}`);

参数

名称类型说明
titleString系列活动的标题
startDateDate系列中第一个事件的日期(仅使用日期,时间会被忽略)
recurrenceEventRecurrence活动系列的重复设置
optionsObject用于指定高级参数的 JavaScript 对象,如下所列

高级参数

名称类型说明
descriptionString系列活动的说明
locationString系列活动的地点
guestsString应作为访客添加到系列活动的电子邮件地址的英文逗号分隔列表
sendInvitesBoolean是否发送邀请电子邮件(默认: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(),
);

参数

名称类型说明
nameString新日历的名称

返回

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(),
);

参数

名称类型说明
nameString新日历的名称
optionsObject用于指定高级参数的 JavaScript 对象,如下所列

高级参数

名称类型说明
locationString日历的位置
descriptionString日历的说明
timeZoneString要将日历设置为的时区,采用“长”格式指定(例如“America/New_York”(Joda.org 上所列)
colorString十六进制颜色字符串(“#rrggbb”)或 CalendarApp.Colors 中的值
hiddenBoolean日历是否在界面中隐藏(默认:false
selectedBoolean日历活动是否显示在界面中(默认值: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()}`);

参数

名称类型说明
titleString活动的标题
startTimeDate活动的开始日期和时间
endTimeDate活动的结束日期和时间

返回

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()}`);

参数

名称类型说明
titleString活动的标题
startTimeDate活动的开始日期和时间
endTimeDate活动的结束日期和时间
optionsObject用于指定高级参数的 JavaScript 对象,如下所列

高级参数

名称类型说明
descriptionString事件说明
locationString活动地点
guestsString应添加为访客的电子邮件地址的逗号分隔列表
sendInvitesBoolean是否发送邀请电子邮件(默认:false

返回

CalendarEvent - 创建的事件

授权

使用此方法的脚本需要具有以下一项或多项范围相关 REST API 中的适当范围的授权:

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

createEventFromDescription(description)

根据自由形式的说明创建事件。

说明应采用与界面的“快速添加”功能相同的格式。

// 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()}`);

参数

名称类型说明
descriptionString事件的自由形式说明

返回

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()}`);

参数

名称类型说明
titleString系列活动的标题
startTimeDate系列活动中第一个活动的开始日期和时间
endTimeDate系列中第一个事件的结束日期和时间
recurrenceEventRecurrence活动系列的重复设置

返回

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()}`);

参数

名称类型说明
titleString系列活动的标题
startTimeDate系列活动中第一个活动的开始日期和时间
endTimeDate系列中第一个事件的结束日期和时间
recurrenceEventRecurrence活动系列的重复设置
optionsObject用于指定高级参数的 JavaScript 对象,如下所列

高级参数

名称类型说明
descriptionString系列活动的说明
locationString系列活动的地点
guestsString应作为访客添加到系列活动的电子邮件地址的英文逗号分隔列表
sendInvitesBoolean是否发送邀请电子邮件(默认: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());

参数

名称类型说明
idString日历 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);

参数

名称类型说明
nameString日历名称

返回

Calendar[] - 用户可以访问的所有名称为此的 Google 日历

授权

使用此方法的脚本需要具有以下一项或多项范围相关 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());

参数

名称类型说明
iCalIdString事件的 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 的 ID,则系统会返回一个包含系列中单个事件的 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());

参数

名称类型说明
iCalIdString活动系列的 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}`);

参数

名称类型说明
startTimeDate时间范围的开始时间
endTimeDate时间范围的结束时间(不含)

返回

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)

获取在指定时间范围内发生且符合指定条件的所有事件。

此方法会返回在给定时间范围内开始、结束或涵盖该时间范围的事件。如果未指定时区,系统会在脚本时区的上下文中解读时间值,该时区可能与日历的时区不同。

请注意,对 authorsearchstatusFilters 进行过滤是在应用 startmax 之后进行的。这意味着,即使有其他事件符合条件,返回的事件数量也可能少于 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}`);

参数

名称类型说明
startTimeDate时间范围的开始时间
endTimeDate时间范围的结束时间(不含)
optionsObject用于指定高级参数的 JavaScript 对象,如下所列

高级参数

名称类型说明
startInteger要返回的第一个事件的索引
maxInteger要返回的事件数量上限
authorString用于按活动创建者过滤结果的电子邮件地址
searchString用于过滤结果的全文搜索查询
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}`);

参数

名称类型说明
dateDate要检索事件的日期(仅使用日期;时间会被忽略)

返回

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 对象的日期部分,并会忽略时间部分。日期的解读是指从日历所在时区当天零点到次日零点。

请注意,对 authorsearchstatusFilters 进行过滤是在应用 startmax 之后进行的。这意味着,即使有其他事件符合条件,返回的事件数量也可能少于 max

// 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}`);

参数

名称类型说明
dateDate要检索事件的日期(仅使用日期;时间会被忽略)
optionsObject高级过滤选项

高级参数

名称类型说明
startInteger要返回的第一个事件的索引
maxInteger要返回的事件数量上限
authorString用于按活动创建者过滤结果的电子邮件地址
searchString用于过滤结果的全文搜索查询
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());

参数

名称类型说明
idString日历 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);

参数

名称类型说明
nameString日历名称

返回

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);

参数

名称类型说明
colorStringCalendarApp.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.');

参数

名称类型说明
descriptionString此日历的说明

返回

Calendar - 用于链式调用的日历

授权

使用此方法的脚本需要具有以下一项或多项范围相关 REST API 中的适当范围的授权:

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

setHidden(hidden)

设置日历在界面中是否可见。

参数

名称类型说明
hiddenBooleantrue 用于在界面中隐藏日历;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');

参数

名称类型说明
nameString新名称

返回

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);

参数

名称类型说明
selectedBooleantrue 以在界面中显示日历的活动;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');

参数

名称类型说明
timeZoneString时区,采用“长”格式指定(例如“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());

参数

名称类型说明
idString要订阅的日历的 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());

参数

名称类型说明
idString要订阅的日历的 ID。
optionsObject用于指定高级参数的 JavaScript 对象,如下所列。

高级参数

名称类型说明
colorString十六进制颜色字符串(“#rrggbb”)或 CalendarApp.Colors 中的值。
hiddenBoolean日历是否在界面中隐藏(默认:false)。
selectedBoolean日历的活动是否显示在界面中(默认:如果同时指定了 color,则为 true;否则为 false)。

返回

Calendar - 新订阅的日历。

抛出

Error - 如果不存在具有此 ID 的日历

授权

使用此方法的脚本需要具有以下一项或多项范围相关 REST API 中的适当范围的授权:

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