This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).
Expo 日历
一个提供用于与设备的系统日历、事件、提醒及相关记录交互的 API 的库。
重要 为了更快地提供更新，
expo-calendar目前不支持在 Expo Go 和 Snack 中使用。要使用它，请创建一个开发构建。
expo-calendar 提供了用于与设备的系统日历、事件、提醒事项及相关记录进行交互的 API。
此外，它还提供了启动系统提供的日历 UI 的方法，以便允许用户查看或编辑事件。在 iOS 上，它们会以模态方式呈现 EKEventViewController 或 EKEventEditViewController。
安装
If you are installing this in an existing React Native app, make sure to install expo in your project.
在 app 配置中进行配置
如果你在项目中使用配置插件（Continuous Native Generation (CNG)），你可以使用 expo-calendar 内置的配置插件来进行配置。该插件允许你配置一些无法在运行时设置、且需要重新构建新的应用二进制文件才会生效的属性。如果你的应用不使用 CNG，那么你需要手动配置该库。
Example app.json with config plugin
Configurable properties
要本地化 iOS 日历或提醒事项权限消息，请将匹配的用途说明键添加到每个语言环境文件中的 ios 对象。calendarPermission 属性同时设置 NSCalendarsUsageDescription 和 NSCalendarsFullAccessUsageDescription，而 remindersPermission 同时设置 NSRemindersUsageDescription 和 NSRemindersFullAccessUsageDescription。Expo 会在预构建期间将本地化值写入 InfoPlist.strings。
Are you using this library in an existing React Native app?
如果你不使用 Continuous Native Generation (CNG)（即手动使用原生 ios 项目），则需要在原生项目中配置以下权限：
-
对于 iOS，请将
NSCalendarsUsageDescription、NSCalendarsFullAccessUsageDescription和NSRemindersUsageDescription添加到项目的 ios/[app]/Info.plist 中：<key>NSCalendarsUsageDescription</key> <string>允许 $(PRODUCT_NAME) 访问你的日历</string> <key>NSCalendarsFullAccessUsageDescription</key> <string>允许 $(PRODUCT_NAME) 访问你的日历</string> <key>NSRemindersUsageDescription</key> <string>允许 $(PRODUCT_NAME) 访问你的提醒事项</string>当在 iOS 17+ 上请求仅写入日历访问权限时，请添加
NSCalendarsWriteOnlyAccessUsageDescription，而不是NSCalendarsFullAccessUsageDescription：<key>NSCalendarsWriteOnlyAccessUsageDescription</key> <string>允许 $(PRODUCT_NAME) 向你的日历添加事件</string>
用法
import * as Calendar from 'expo-calendar'; import { useEffect } from 'react'; import { StyleSheet, View, Text, Button } from 'react-native'; const BasicUsage = () => { useEffect(() => { (async () => { const { status } = await Calendar.requestCalendarPermissions(); if (status === 'granted') { const calendars = Calendar.getCalendars(Calendar.EntityTypes.EVENT); console.log('Here are all your calendars:'); console.log(JSON.stringify(calendars)); } })(); }, []); return ( <View style={styles.container}> <Text>日历模块示例</Text> <Button title="创建一个新日历" onPress={createCalendar} /> </View> ); }; async function createCalendar() { const newCalendar = await Calendar.createCalendar({ title: 'Expo Calendar', color: 'blue', entityType: Calendar.EntityTypes.EVENT, }); console.log(`Your new calendar: ${JSON.stringify(newCalendar)}`); } const styles = StyleSheet.create({ container: { flex: 1, backgroundColor: '#fff', alignItems: 'center', justifyContent: 'space-around', }, });
API
import * as Calendar from 'expo-calendar';
除非另有说明，所有日期都以 ISO 8601 格式返回。
Hooks
Check or request permissions to access the user's calendars.
This uses both getCalendarPermissions and requestCalendarPermissions to interact
with the permissions.
On iOS, writeOnly requests permission to create calendar events without reading
existing calendars or events. It does not grant permission to create, update, or delete calendars.
[PermissionResponse | null, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]Example
const [status, requestPermission] = Calendar.useCalendarPermissions();
Check or request permissions to access the user's reminders.
This uses both getRemindersPermissions and requestRemindersPermissions to interact
with the permissions.
[PermissionResponse | null, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]Example
const [status, requestPermission] = Calendar.useRemindersPermissions();
Classes
Type: Class extends ExpoCalendar
Represents a calendar object that can be accessed and modified using the Expo Calendar Next API.
This class provides properties and methods for interacting with a specific calendar on the device, such as retrieving its events, updating its details, and accessing its metadata.
ExpoCalendar Properties
CalendarAccessLevelLevel of access that the user has for the calendar.
AttendeeType[]Attendee types that this calendar supports.
booleanBoolean value that determines whether this calendar can be modified.
EntityTypesWhether the calendar is used in the Calendar or Reminders OS app.
booleanBoolean value indicating whether this is the device's primary calendar.
booleanIndicates whether this calendar is synced and its events stored on the device.
Unexpected behavior may occur if this is not set to true.
unionInternal system name of the calendar.
Acceptable values are: string | null
stringID of the source to be used for the calendar. Likely the same as the source for any other locally stored calendars.
ExpoCalendar Methods
Presents the system-provided dialog to create a new event in this calendar, pre-filled with the provided data. Requires at minimum write-only calendar permission.
Promise<DialogEventResult>Creates a new event in the calendar.
Promise<ExpoCalendarEvent>An instance of the created event.
Creates a new reminder in the calendar.
Promise<ExpoCalendarReminder>An instance of the created reminder.
Deletes the calendar.
Promise<void>Gets a calendar by its ID. Throws an error if the calendar with the given ID does not exist.
Promise<ExpoCalendar>An ExpoCalendar object representing the calendar.
Returns a list of reminders matching the provided criteria. If startDate and endDate are defined,
returns all reminders that overlap at all with the [startDate, endDate] interval, that is, all reminders
that end after the startDate or begin before the endDate.
Promise<ExpoCalendarReminder[]>An array of ExpoCalendarReminder objects matching the search criteria.
Updates the provided details of an existing calendar stored on the device. To remove a property,
explicitly set it to null in details.
Promise<void>Type: Class extends ExpoCalendarAttendee
Represents a calendar attendee object.
ExpoCalendarAttendee Properties
booleanIndicates whether or not this attendee is the current OS user.
ExpoCalendarAttendee Methods
Deletes the attendee.
Promise<void>Type: Class extends ExpoCalendarEvent
Represents a calendar event object that can be accessed and modified using the Expo Calendar Next API.
ExpoCalendarEvent Properties
unionDate when the event record was created.
Acceptable values are: string | Date
unionDate object or string representing the time when the event ends.
Acceptable values are: string | Date
booleanWhether invited guests can modify the details of the event.
stringFor instances of recurring events, volatile ID representing this instance. Not guaranteed to always refer to the same instance.
booleanBoolean value indicating whether or not the event is a detached (modified) instance of a recurring event.
unionDate when the event record was last modified.
Acceptable values are: string | Date
unionLocation field of the event.
Acceptable values are: string | null
OrganizerOrganizer of the event. This property is only available on events associated with calendars that are managed by a service such as Google Calendar or iCloud. The organizer is read-only and cannot be set.
stringFor detached (modified) instances of recurring events, the ID of the original recurring event.
unionFor recurring events, the start date for the first (original) instance of the event.
Acceptable values are: string | Date
unionObject representing rules for recurring or repeating events. Set to null for one-time events.
It is either endDate or occurrence based.
Acceptable values are: RecurrenceRule | null
unionDate object or string representing the time when the event starts.
Acceptable values are: string | Date
stringTime zone the event is scheduled in.
When set to null, the event is scheduled to the device's time zone.
ExpoCalendarEvent Methods
Deletes the event.
Promise<void>Launches the calendar UI provided by the OS to edit or delete an event.
Promise<DialogEventResult>A promise which resolves with information about the dialog result.
Gets an event by its ID. Throws an error if the event with the given ID does not exist.
Promise<ExpoCalendarEvent>An ExpoCalendarEvent object representing the event.
Gets all attendees for a given event (or instance of a recurring event).
Promise<ExpoCalendarAttendee[]>An array of Attendee associated with the specified event.
Returns an event instance for a given event (or instance of a recurring event).
ExpoCalendarEventAn event instance.
Launches the calendar UI provided by the OS to preview an event.
Promise<OpenEventDialogResult>A promise which resolves with information about the dialog result.
Updates the provided details of an existing calendar stored on the device. To remove a property,
explicitly set it to null in details.
Promise<void>Type: Class extends ExpoCalendarReminder
Represents a calendar reminder object that can be accessed and modified using the Expo Calendar Next API.
ExpoCalendarReminder Properties
Alarm[]Array of Alarm objects which control automated alarms to the user about the task.
unionDate object or string representing the date of completion, if completed is true.
Setting this property of a nonnull Date will automatically set the reminder's completed value to true.
Acceptable values are: string | Date
unionDate when the reminder record was created.
Acceptable values are: string | Date
unionDate object or string representing the time when the reminder task is due.
Acceptable values are: string | Date
unionDate when the reminder record was last modified.
Acceptable values are: string | Date
unionObject representing rules for recurring or repeated reminders. null for one-time tasks.
Acceptable values are: RecurrenceRule | null
unionDate object or string representing the start date of the reminder task.
Acceptable values are: string | Date
ExpoCalendarReminder Methods
Deletes the reminder.
Promise<void>Gets a reminder by its ID. Throws an error if the reminder with the given ID does not exist.
Promise<ExpoCalendarReminder>An ExpoCalendarReminder object representing the reminder.
Methods
Deprecated: Use
event.createAttendee()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<string>Creates a new calendar on the device, allowing events to be added later and displayed in the OS Calendar app.
Promise<ExpoCalendar>An ExpoCalendar object representing the newly created calendar.
Deprecated: Use
createCalendar()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<string>Deprecated: Use
calendar.createEvent()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<string>Deprecated: Use
calendar.addEventWithForm()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<DialogEventResult>Deprecated: Use
calendar.createReminder()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<string>Deprecated: Use
attendee.delete()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<void>Deprecated: Use
calendar.delete()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<void>Deprecated: Use
event.delete()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<void>Deprecated: Use
reminder.delete()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<void>Deprecated: Use
event.editInCalendar()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<DialogEventResult>Deprecated: Use
event.getAttendees()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<Attendee[]>Deprecated: Use
getCalendarPermissions()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<PermissionResponse>Gets an array of ExpoCalendar shared objects with details about the different calendars stored on the device.
Promise<ExpoCalendar[]>An array of ExpoCalendar shared objects matching the provided entity type (if provided).
Deprecated: Use
getCalendars()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<Calendar[]>Deprecated: Use
getDefaultCalendarSync()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<Calendar>Gets an instance of the default calendar object.
Android: This function is not available on Android. Android does not expose a single system-managed default calendar. Use
getCalendars()and choose an appropriate writable calendar for your app;isPrimarycan help identify per-account primary calendars.
ExpoCalendarAn ExpoCalendar object that is the user's default calendar.
Deprecated: Use
ExpoCalendarEvent.get()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Deprecated: Use
listEvents()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Deprecated: Use
ExpoCalendarReminder.get()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Deprecated: Use
calendar.listReminders()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<Reminder[]>Checks user's permissions for accessing user's reminders.
Promise<PermissionResponse>A promise that resolves to an object of type PermissionResponse.
Deprecated: Use
getRemindersPermissions()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<PermissionResponse>Deprecated: Import this method from
expo-calendar/legacy. This method will throw in runtime.
Deprecated: Use
getSourcesSync()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Gets an array of Source objects with details about the different sources stored on the device.
Android: This function is not available on Android. Android does not expose a first-class calendar sources API. If you need account-like source information, call
getCalendars()and inspect each calendar'ssourcefield.
Source[]An array of Source objects representing the sources found.
Deprecated: Import this method from
expo-calendar/legacy. This method will throw in runtime.
Promise<boolean>Lists events from the device's calendar. It can be used to search events in multiple calendars.
Note: If you want to search events in a single calendar, you can use
ExpoCalendar.listEventsinstead.
Promise<ExpoCalendarEvent[]>An array of ExpoCalendarEvent objects representing the events found.
Deprecated: Use
event.openInCalendar()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
voidDeprecated: Use
event.openInCalendar()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<OpenEventDialogResult>Presents the OS calendar picker and returns the selected calendar.
Promise<ExpoCalendar | null>An ExpoCalendar object or null when the picker is cancelled.
Asks the user to grant permissions for accessing user's calendars.
Promise<PermissionResponse>Deprecated: Use
requestCalendarPermissions()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<PermissionResponse>Deprecated: Use
requestCalendarPermissions()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<PermissionResponse>Asks the user to grant permissions for accessing user's reminders.
Promise<PermissionResponse>A promise that resolves to an object of type PermissionResponse.
Deprecated: Use
requestRemindersPermissions()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<PermissionResponse>Deprecated: Use
attendee.update()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<string>Deprecated: Use
calendar.update()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<string>Deprecated: Use
event.update()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<string>Deprecated: Use
reminder.update()or import this method fromexpo-calendar/legacy. This method will throw in runtime.
Promise<string>Types
The result of presenting a calendar dialog for creating or editing an event.
Type: Pick<ExpoCalendar, 'color' | 'title'>
Type: Pick<ExpoCalendarEvent, 'title' | 'location' | 'timeZone' | 'url' | 'notes' | 'alarms' | 'recurrenceRule' | 'availability' | 'startDate' | 'endDate' | 'allDay'>
Type: Pick<ExpoCalendarReminder, 'title' | 'location' | 'timeZone' | 'url' | 'notes' | 'alarms' | 'recurrenceRule' | 'startDate' | 'dueDate' | 'completed' | 'completionDate'>
The result of presenting the calendar dialog for opening (viewing) an event.
Literal type: union
Permission expiration time. Currently, all permissions are granted permanently.
Acceptable values are: 'never' | number
Literal type: union
Acceptable values are: PermissionHookBehavior | Options
A recurrence rule for events or reminders, allowing the same calendar item to recur multiple times. This type is based on the iOS interface which is in turn based on the iCal RFC so you can refer to those to learn more about this potentially complex interface.
Not all the combinations make sense. For example, when frequency is DAILY, setting daysOfTheMonth makes no sense.
Options for specifying a particular instance of a recurring event. This type is used in various methods that operate on recurring events, such as updating or deleting a single occurrence or a set of future occurrences.
A source account that owns a particular calendar. Expo apps will typically not need to interact with Source objects.
Enums
Enum containing all possible user responses to the calendar UI dialogs. Depending on what dialog is presented, a subset of the values applies.
CalendarDialogResultActions.canceled ＝ "canceled"The user canceled or dismissed the dialog.
CalendarDialogResultActions.done ＝ "done"On Android, this is the only possible result because the OS doesn't provide enough information to determine the user's action - the user may have canceled the dialog, modified the event, or deleted it.
On iOS, this means the user simply closed the dialog.
CalendarDialogResultActions.responded ＝ "responded"The user responded to and saved a pending event invitation.
权限
Android
如果你只打算使用系统提供的日历 UI，则不需要请求任何权限。
否则，你必须将以下权限添加到 app.json 中 expo.android.permissions 数组里。
iOS
如果只想添加事件而不读取现有的日历数据，请在配置插件中启用 writeOnlyAccess 选项，并通过向 requestCalendarPermissions 传入 true 来请求仅写入权限。对于 ExpoCalendar.createEvent 等方法，这样的权限就足够了。读取日历数据的方法，例如 getCalendars、listEvents 或 presentPicker，则需要完整的日历访问权限。
该库使用以下用途说明键：