توضّح هذه الصفحة ماهية التصنيفات وكيفية إدارتها في التقاويم وكيفية تعيينها للأحداث باستخدام واجهة برمجة التطبيقات Google Calendar API.
يتيح لك "تقويم Google" تخصيص مظهر أحداثك من خلال منحها ألوانًا وأسماء مخصّصة. في السابق، كانت الأحداث تقتصر على مجموعة ثابتة من الألوان المستندة إلى الفهرس (colorId). باستخدام التصنيفات، يمكنك تحديد لوحة ألوان مرنة ومخصّصة لكل تقويم وتطبيق هذه التصنيفات مباشرةً على الأحداث.
إدارة التصنيفات في تقويم
يمكنك تحديد ما يصل إلى 200 تصنيف مخصّص لكل تقويم باستخدام السمة labelProperties في مورد التقاويم.
لإدارة التصنيفات، استخدِم الطريقتَين 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"
}
]
}
}
مثال: إضافة تصنيفات إلى تقويم وإزالتها منه
لإضافة تصنيفات أو إزالتها، عليك أولاً قراءة التقويم للحصول على قائمة التصنيفات الحالية، وتعديل القائمة في الرمز، ثم تعديل التقويم باستخدام القائمة المعدَّلة لتجنُّب الكتابة فوق التصنيفات الأخرى.
تعرض الأمثلة التالية كيفية استرداد تقويم وإزالة تصنيف يحمل رقم التعريف 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)
جافا
// 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"
}
]
}
}
تعيين تصنيفات للأحداث
بعد تحديد التصنيفات في التقويم، يمكنك تعيينها لأحداث فردية من خلال ضبط السمة 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)
جافا
// 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.