标签

本页介绍了标签是什么、如何在日历中管理标签，以及如何使用 Google 日历 API 将标签分配给活动。

Google 日历可让您为活动分配自定义颜色和名称，从而自定义活动的外观。以前，活动只能使用一组固定的基于索引的颜色 (colorId)。现在，您可以使用标签为每个日历定义灵活的自定义调色板，并将这些标签直接应用于活动。

管理日历中的标签

您可以使用 Calendars 资源中的 labelProperties 属性，为每个日历定义最多 200 个自定义标签。

如需管理标签，请使用 Calendars.insert 或 Calendars.update 方法。每个标签都需要一个 id、一个十六进制格式的 backgroundColor 和一个可选的 name。

日历资源表示法

{
  "kind": "calendar#calendar",
  "id": "primary",
  "summary": "My Team Calendar",
  "labelProperties": {
    "eventLabels": [
      {
        "id": "42617328-8756-4291-8273-192837465647",
        "backgroundColor": "#039be5",
        "name": "Important Project"
      },
      {
        "id": "19283746-9182-4736-8271-918273645261",
        "backgroundColor": "#33b679",
        "name": "Team Meeting"
      }
    ]
  }
}

示例：在日历中添加和移除标签

如需添加或移除标签，您应先读取日历以获取当前标签列表，然后在代码中修改该列表，并使用更新后的列表更新日历，以免覆盖其他标签。

以下示例展示了如何检索日历、移除 ID 为 11111111-2222-3333-4444-555555555555 的标签、添加两个新标签（22222222-3333-4444-5555-666666666666 和 33333333-4444-5555-6666-777777777777）以及更新日历：

Go

// Refer to the Go quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/go

// 1. Read the calendar to get existing labels
calendar, err := srv.Calendars.Get("primary").Do()
if err != nil {
    log.Fatalf("Unable to retrieve calendar: %v", err)
}

if calendar.LabelProperties == nil {
    calendar.LabelProperties = &calendar.LabelProperties{}
}
labels := calendar.LabelProperties.EventLabels

// 2. Remove a label with a specific ID (UUID format)
targetIdToRemove := "11111111-2222-3333-4444-555555555555"
var updatedLabels []*calendar.EventLabel
for _, label := range labels {
    if label.Id != targetIdToRemove {
        updatedLabels = append(updatedLabels, label)
    }
}
labels = updatedLabels

// 3. Add 2 new labels with UUID IDs
labels = append(labels, &calendar.EventLabel{
    Id:              "22222222-3333-4444-5555-666666666666",
    BackgroundColor: "#8e24aa",
    Name:            "Design Work",
})
labels = append(labels, &calendar.EventLabel{
    Id:              "33333333-4444-5555-6666-777777777777",
    BackgroundColor: "#f4511e",
    Name:            "Urgent Review",
})

// 4. Update the calendar with the new list
calendar.LabelProperties.EventLabels = labels
updatedCalendar, err := srv.Calendars.Update("primary", calendar).Do()
if err != nil {
    log.Fatalf("Unable to update calendar: %v", err)
}
fmt.Printf("Calendar updated: %s\n", updatedCalendar.Summary)

Java

// Refer to the Java quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/java

// 1. Read the calendar to get existing labels
Calendar calendar = service.calendars().get("primary").execute();

LabelProperties labelProperties = calendar.getLabelProperties();
if (labelProperties == null) {
  labelProperties = new LabelProperties();
}
List<EventLabel> labels = labelProperties.getEventLabels();
if (labels == null) {
  labels = new ArrayList<>();
} else {
  // Create a mutable copy since the returned list might be immutable
  labels = new ArrayList<>(labels);
}

// 2. Remove a label with a specific ID (UUID format)
String targetIdToRemove = "11111111-2222-3333-4444-555555555555";
labels.removeIf(label -> targetIdToRemove.equals(label.getId()));

// 3. Add 2 new labels with UUID IDs
labels.add(new EventLabel()
    .setId("22222222-3333-4444-5555-666666666666")
    .setBackgroundColor("#8e24aa")
    .setName("Design Work"));

labels.add(new EventLabel()
    .setId("33333333-4444-5555-6666-777777777777")
    .setBackgroundColor("#f4511e")
    .setName("Urgent Review"));

// 4. Update the calendar with the new list
labelProperties.setEventLabels(labels);
calendar.setLabelProperties(labelProperties);

Calendar updatedCalendar = service.calendars().update("primary", calendar)
    .execute();

System.out.printf("Calendar updated: %s\n", updatedCalendar.getSummary());

JavaScript

// Refer to the Node.js quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/nodejs

// 1. Retrieve the calendar resource
calendar.calendars.get({
  calendarId: 'primary'
}, (err, res) => {
  if (err) return console.log('The API returned an error: ' + err);

  // Extract existing labels from the calendar resource
  const cal = res.data;
  if (!cal.labelProperties) {
    cal.labelProperties = {};
  }
  if (!cal.labelProperties.eventLabels) {
    cal.labelProperties.eventLabels = [];
  }

  // 2. Remove a label with a specific ID (UUID format)
  const targetIdToRemove = '11111111-2222-3333-4444-555555555555';
  cal.labelProperties.eventLabels = cal.labelProperties.eventLabels.filter(
    label => label.id !== targetIdToRemove
  );

  // 3. Add 2 new labels with UUID IDs
  cal.labelProperties.eventLabels.push({
    id: '22222222-3333-4444-5555-666666666666',
    backgroundColor: '#8e24aa',
    name: 'Design Work'
  });
  cal.labelProperties.eventLabels.push({
    id: '33333333-4444-5555-6666-777777777777',
    backgroundColor: '#f4511e',
    name: 'Urgent Review'
  });

  // 4. Update the calendar with the new list
  calendar.calendars.update({
    calendarId: 'primary',
    resource: cal
  }, (updateErr, updateRes) => {
    if (updateErr) return console.log('Update failed: ' + updateErr);
    console.log(`Calendar updated: ${updateRes.data.summary}`);
  });
});

Python

# Refer to the Python quickstart on how to setup the service:
# https://developers.google.com/workspace/calendar/quickstart/python

# 1. Read the calendar to get existing labels
calendar = service.calendars().get(calendarId='primary').execute()

label_properties = calendar.setdefault('labelProperties', {})
labels = label_properties.setdefault('eventLabels', [])

# 2. Remove a label with a specific ID (UUID format)
target_id_to_remove = "11111111-2222-3333-4444-555555555555"
labels = [l for l in labels if l.get('id') != target_id_to_remove]

# 3. Add 2 new labels with UUID IDs
labels.append({
    'id': '22222222-3333-4444-5555-666666666666',
    'backgroundColor': '#8e24aa',
    'name': 'Design Work'
})
labels.append({
    'id': '33333333-4444-5555-6666-777777777777',
    'backgroundColor': '#f4511e',
    'name': 'Urgent Review'
})

# 4. Update the calendar with the new list
label_properties['eventLabels'] = labels
calendar['labelProperties'] = label_properties

updated_calendar = service.calendars().update(
    calendarId='primary',
    body=calendar
).execute()

print(f"Calendar updated: {updated_calendar.get('summary')}")

HTTP

以下原始 HTTP 示例展示了用于更新日历（使用新的标签列表）的最终 PUT 请求。请确保您已先将这些标签与所有现有标签合并。

PUT https://www.googleapis.com/calendar/v3/calendars/primary
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Content-Type: application/json

{
  "summary": "Updated Team Calendar",
  "labelProperties": {
    "eventLabels": [
      {
        "id": "22222222-3333-4444-5555-666666666666",
        "backgroundColor": "#8e24aa",
        "name": "Design Work"
      },
      {
        "id": "33333333-4444-5555-6666-777777777777",
        "backgroundColor": "#f4511e",
        "name": "Urgent Review"
      }
    ]
  }
}

为活动分配标签

在日历中定义标签后，您可以通过在 Events 资源中设置 eventLabelId 属性，将标签分配给各个活动。

您可以在调用 insert、update 或 patch 方法时设置或更改此属性。

活动资源表示法

{
  "kind": "calendar#event",
  "id": "sample-event-id",
  "summary": "Review Design Specs",
  "start": {
    "dateTime": "2026-07-01T10:00:00Z"
  },
  "end": {
    "dateTime": "2026-07-01T11:00:00Z"
  },
  "eventLabelId": "22222222-3333-4444-5555-666666666666"
}

示例：创建带有标签的活动

以下示例展示了如何创建带有自定义标签的事件：

Go

// Refer to the Go quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/go

event := &calendar.Event{
    Summary: "Design Sync",
    Start: &calendar.EventDateTime{
        DateTime: "2026-07-02T14:00:00Z",
    },
    End: &calendar.EventDateTime{
        DateTime: "2026-07-02T15:00:00Z",
    },
    EventLabelId: "22222222-3333-4444-5555-666666666666",
}

createdEvent, err := srv.Events.Insert("primary", event).EventLabelVersion(1).Do()
if err != nil {
    log.Fatalf("Unable to create event: %v", err)
}
fmt.Printf("Event created: %s\n", createdEvent.HtmlLink)

Java

// Refer to the Java quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/java

Event event = new Event()
    .setSummary("Design Sync")
    .setStart(new EventDateTime().setDateTime(new DateTime("2026-07-02T14:00:00Z")))
    .setEnd(new EventDateTime().setDateTime(new DateTime("2026-07-02T15:00:00Z")))
    .setEventLabelId("22222222-3333-4444-5555-666666666666");

Event createdEvent = service.events().insert("primary", event)
    .setEventLabelVersion(1L)
    .execute();

System.out.printf("Event created: %s\n", createdEvent.getHtmlLink());

JavaScript

// Refer to the Node.js quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/nodejs

const event = {
  summary: 'Design Sync',
  start: {
    dateTime: '2026-07-02T14:00:00Z',
  },
  end: {
    dateTime: '2026-07-02T15:00:00Z',
  },
  eventLabelId: '22222222-3333-4444-5555-666666666666',
};

calendar.events.insert({
  calendarId: 'primary',
  resource: event,
  eventLabelVersion: 1,
}, (err, res) => {
  if (err) return console.log('The API returned an error: ' + err);
  console.log(`Event created: ${res.data.htmlLink}`);
});

Python

# Refer to the Python quickstart on how to setup the service:
# https://developers.google.com/workspace/calendar/quickstart/python

event = {
    'summary': 'Design Sync',
    'start': {
        'dateTime': '2026-07-02T14:00:00Z',
    },
    'end': {
        'dateTime': '2026-07-02T15:00:00Z',
    },
    'eventLabelId': '22222222-3333-4444-5555-666666666666'
}

event = service.events().insert(
    calendarId='primary',
    body=event,
    eventLabelVersion=1
).execute()

print(f"Event created: {event.get('htmlLink')}")

HTTP

POST https://www.googleapis.com/calendar/v3/calendars/primary/events?eventLabelVersion=1
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Content-Type: application/json

{
  "summary": "Design Sync",
  "start": {
    "dateTime": "2026-07-02T14:00:00Z"
  },
  "end": {
    "dateTime": "2026-07-02T15:00:00Z"
  },
  "eventLabelId": "22222222-3333-4444-5555-666666666666"
}

如需从活动中移除现有标签，请将 eventLabelId 设置为空字符串 ("")，或在 update 请求中完全省略该字段。