日历和活动

本指南介绍了日历、活动及其相互之间的关系。

日历

一个日历 是相关事件的集合 如摘要、默认时区、地点等。 通过 ID(电子邮件地址)指定日历可以有多个所有者。

事件

事件 是与特定日期或时间范围相关联的对象。事件通过唯一 ID 进行标识。除了开始 结束日期时间,则事件包含其他数据,例如摘要、说明、 位置、状态、提醒、附件等

事件类型

Google 日历支持单次活动和周期性活动:

  • 单个事件表示唯一事件。
  • 周期性事件会定义多次发生,

您还可以为活动设置计时全天时间:

  • 定时事件发生在两个特定时间点之间。计时事件 使用 start.dateTimeend.dateTime 字段指定 。
  • 全天活动会持续一整天或连续的一系列天数。全天 事件使用 start.dateend.date 字段指定发生的时间。 请注意,对于全天活动,时区字段没有意义。

组织者

活动只有一个组织者,也就是包含主副本的日历 事件。事件还可以包含多个 参加者。 参加者通常是受邀用户的主日历。

下图显示了日历与 事件和其他相关元素:

主日历和其他日历

主日历是一种与单个日历关联的特殊日历 用户账号。系统会自动为每个新用户账号创建此日历 并且其 ID 通常与用户的主电子邮件地址匹配。只要 账户已存在,则其主日历不可删除或“取消拥有”由 用户。不过,仍然可以与其他用户共享。

除主日历外,您还可以明确创建任意数量的 其他日历;用户可以修改、删除和共享这些日历 多个用户之间的会话

日历和日历列表

日历集合 代表所有现有日历。它可用于创建和删除 日历。您还可以检索或设置在所有 有权访问某个日历的用户。例如,日历的标题和默认 时区是全局属性。

CalendarList 是 用户已添加到其列表的所有日历条目的集合(显示 )。您可以使用它添加和移除现有的 日历与用户列表之间的双向同步。您还可以使用它来检索和设置 用户特定日历属性的值(例如默认提醒)。另一个 因为不同的用户可能会有不同的颜色 。

下表比较了这两个集合的操作的含义:

操作 日历 CalendarList
insert 创建新的辅助日历。默认情况下,此日历也处于 已添加到创建者的日历列表中。 在用户的列表中插入现有日历。
delete 删除辅助日历。 从用户的列表中移除日历。
get 检索日历元数据,例如标题、时区。 检索元数据以及特定于用户的自定义设置 例如颜色或覆盖提醒。
patch/update 修改日历元数据。 修改用户特定的日历属性。

周期性活动

有些活动会固定安排多次,例如每周会议、 生日和节假日除了设置不同的开始时间和结束时间之外 这些重复的事件通常都是相同的。

如果活动按照指定的时间表重复,则称为“周期性活动”。 “单次”活动不是周期性活动,只发生一次。

重复规则

周期性活动的时间表分为两个部分:

  • 其开始和结束字段(定义第一次出现,就好像 只是一个独立的单个事件),并且

  • 其重复规则字段(用于定义事件随时间的重复方式)。

重复规则字段包含一个字符串数组,该数组代表一个或多个 RFC 中定义的 RRULERDATEEXDATE 属性 5545

RRULE 属性最为重要,因为它定义了 重复活动它由几个组件组成。其中包括:

  • FREQ - 事件的重复频率(例如 DAILYWEEKLY)。必填。

  • INTERVAL - 与 FREQ 搭配使用,用于指定事件的频率 。例如,FREQ=DAILY;INTERVAL=2 表示每 。

  • COUNT - 此事件应重复的次数。

  • UNTIL - 活动应一直重复到哪个日期或日期时间(含此日期或日期时间)。

  • BYDAY - 应在一周的哪几天(SUMOTU 等)。其他类似的组件包括 BYMONTHBYYEARDAYBYHOUR

RDATE 属性用于指定事件的其他日期或日期时间 应发生的所有情况。例如 RDATE;VALUE=DATE:19970101,19970120。 使用此方法可添加 RRULE 未涵盖的额外事件。

EXDATE 属性与 RDATE 类似,但指定日期或日期时间。 事件不应发生的时间。也就是说,这些事件应该 已排除。它必须指向由重复规则生成的有效实例。

EXDATERDATE 可以设置时区,并且必须是日期(而非日期时间) 。

每个属性都可以在重复规则字段中多次出现。 重复规则定义为所有 RRULERDATE 规则的并集减去 被全部 EXDATE 条规则排除的那些。

下面是周期性事件的一些示例:

  1. 每周二和周五上午 6 点至 7 点举行的活动,开始时间为 并在 9 月 29 日第五次发生后停止:

    ...
    "start": {
     "dateTime": "2015-09-15T06:00:00+02:00",
     "timeZone": "Europe/Zurich"
    },
    "end": {
     "dateTime": "2015-09-15T07:00:00+02:00",
     "timeZone": "Europe/Zurich"
    },
    "recurrence": [
     "RRULE:FREQ=WEEKLY;COUNT=5;BYDAY=TU,FR"
    ],
    …
    
  2. 从 2015 年 6 月 1 日开始的全天活动,每 3 天重复一次 在整个月内(不包括 6 月 10 日,但包括 6 月 9 日和 11 日):

    ...
    "start": {
     "date": "2015-06-01"
    },
    "end": {
     "date": "2015-06-02"
    },
    "recurrence": [
     "EXDATE;VALUE=DATE:20150610",
     "RDATE;VALUE=DATE:20150609,20150611",
     "RRULE:FREQ=DAILY;UNTIL=20150628;INTERVAL=3"
    ],
    …
    

实例和异常

周期性活动由若干“实例”组成:即特定发生的实例 。这些实例本身就是事件。

周期性事件修改可能影响整个 周期性活动(及其所有实例)或仅单个实例。 不同于父级周期性活动的实例称为例外情况。

例如,某项例外情况可能会包含不同的摘要、不同的开始时间或 或仅邀请更多参加者加入该实例。您也可以取消 而不必移除周期性活动 (实例取消会反映在 status)。

如何通过 您可以在此处找到 Google Calendar API。

时区

时区用于指定采用统一标准时间的区域。 在 Google 日历 API 中,您可以使用 IANA 时区标识符。

您可以为日历和活动设置时区。以下部分 描述这些设置的影响

日历时区

日历的时区也称为默认时区,因为 对查询结果的影响。日历时区会影响 由 events.get()events.list()events.instances() 方法。

查询结果时区转换
get(), list()instances() 方法会按您在 timeZone 中指定的时区返回 参数。如果省略此参数,则这些方法都将使用日历 默认时区。
将全天活动与带时间范围的查询相匹配
list()instances() 方法,用于指定开始时间和结束时间过滤器,方法是使用 返回实例。日历时区 用于计算全天活动的开始和结束时间,以确定 它们是否符合过滤规范

活动时区

事件实例有开始和结束时间;这些时间的规范 可能包含时区。您可以通过以下几种方式指定时区: 以下所有项目都指定了相同的时间:

  • dateTime 字段中添加时区偏移量,例如 2017-01-25T09:00:00-0500
  • 指定无时差的时间,例如 2017-01-25T09:00:00,将 timeZone 字段留空(这将隐式使用默认时区)。
  • 请指定无时差的时间(例如 2017-01-25T09:00:00),并使用 timeZone 字段指定时区。

如果您愿意,也可以指定采用世界协调时间 (UTC) 的活动时间:

  • 请以世界协调时间 (UTC) 2017-01-25T14:00:00Z 指定时间,或使用零偏移 2017-01-25T14:00:00+0000

在上述所有情况下,事件时间的内部表示形式都相同, 但设置 timeZone 字段会为事件附加时区,就像 当您使用 Google 日历设置活动时区时 界面

显示活动时区的屏幕截图 fragment

周期性活动时区

对于周期性活动,必须始终指定一个时区。 为了延长事件的重复发生,必须使用它。