Calendar Calendar

introduce

Calendar component is used to select dates or date ranges.

Code Demo

Select a single date

The following demonstrates the use of the calendar component in combination with cells. The confirm event will be triggered after the date selection is completed.

<z-cell title="Select a single date" :value="date" @click="show = true" />
<z-calendar v-model:show="show" @confirm="onConfirm" />
import { ref } from 'vue';

export default {
   setup() {
     const date = ref('');
     const show = ref(false);

     const formatDate = (date) => `${date.getMonth() + 1}/${date.getDate()}`;
     const onConfirm = (value) => {
       show.value = false;
       date.value = formatDate(value);
     };

     return {
       date,
       show,
       onConfirm,
     };
   },
};

Select multiple dates

After setting type to multiple, you can select multiple dates. At this time, the date returned by the confirm event is an array structure, and the array contains several selected dates.

<z-cell title="Select multiple dates" :value="text" @click="show = true" />
<z-calendar v-model:show="show" type="multiple" @confirm="onConfirm" />
import { ref } from 'vue';

export default {
   setup() {
     const text = ref('');
     const show = ref(false);

     const onConfirm = (dates) => {
       show.value = false;
       text.value = `${dates.length} dates selected`;
     };

     return {
       text,
       show,
       onConfirm,
     };
   },
};

Select date range

After setting type to range, you can select a date range. At this time, the date returned by the confirm event is an array structure. The first item in the array is the start time and the second item is the end time.

<z-cell title="Select date range" :value="date" @click="show = true" />
<z-calendar v-model:show="show" type="range" @confirm="onConfirm" />
import { ref } from 'vue';

export default {
   setup() {
     const date = ref('');
     const show = ref(false);

     const formatDate = (date) => `${date.getMonth() + 1}/${date.getDate()}`;
     const onConfirm = (values) => {
       const [start, end] = values;
       show.value = false;
       date.value = `${formatDate(start)} - ${formatDate(end)}`;
     };

     return {
       date,
       show,
       onConfirm,
     };
   },
};

Tips: By default, the start and end times of the date range cannot be on the same day. You can set the allow-same-day attribute to allow the selection of the same day.

Quick selection

Set show-confirm to false to hide the confirm button, in which case the confirm event will be triggered immediately after the selection is completed.

<z-calendar v-model:show="show" :show-confirm="false" />

Custom color

The color of the calendar can be customized through the color attribute, which takes effect on the selected date and bottom button.

<z-calendar v-model:show="show" color="#ee0a24" />

Custom date range

Define the calendar range via min-date and max-date.

<z-calendar v-model:show="show" :min-date="minDate" :max-date="maxDate" />
import { ref } from 'vue';

export default {
   setup() {
     const show = ref(false);

     return {
       show,
       minDate: new Date(2010, 0, 1),
       maxDate: new Date(2010, 0, 31),
     };
   },
};

Custom button text

Set the button text through confirm-text, and set the text when the button is disabled through confirm-disabled-text.

<z-calendar
   v-model:show="show"
   type="range"
   confirm-text="Complete"
   confirm-disabled-text="Please select an end time"
/>

Custom date copywriting

Format the content of each cell on the calendar by passing in the formatter function.

<z-calendar v-model:show="show" type="range" :formatter="formatter" />
export default {
   setup() {
     const formatter = (day) => {
       const month = day.date.getMonth() + 1;
       const date = day.date.getDate();

       if (month === 5) {
         if (date === 1) {
           day.topInfo = 'Labor Day';
         } else if (date === 4) {
           day.topInfo = 'Youth Day';
         } else if (date === 11) {
           day.text = 'Today';
         }
       }

       if (day.type === 'start') {
         day.bottomInfo = 'Check-in';
       } else if (day.type === 'end') {
         day.bottomInfo = 'Departure';
       }

       return day;
     };

     return {
       formatter,
     };
   },
};

Custom popup position

Customize the pop-up position of the pop-up layer through the position attribute. The optional values are top, left, and right.

<z-calendar v-model:show="show" :round="false" position="right" />

Maximum date range

When selecting a date range, you can specify the maximum number of optional days through the max-range attribute. When the selected range exceeds the maximum number of optional days, the corresponding prompt copy will pop up.

<z-calendar type="range" :max-range="3" />

Customize the starting day of the week

Set the day the week starts with the first-day-of-week property.

<z-calendar first-day-of-week="1" />

Tiled display

Set poppable to false, and the calendar will be displayed directly on the page instead of appearing as a pop-up layer.

<z-calendar
   title="Calendar"
   :poppable="false"
   :show-confirm="false"
   :custom-style="{ height: '500px' }"
/>

API

Props

ParametersDescriptionTypeDefault value
typeSelection type:
single means selecting a single date,
multiple means selecting multiple dates,
range means selecting a date range
stringsingle
titleCalendar titlestringDate selection
colorTheme color, effective for bottom button and selected datestring#1989fa
min-dateSelectable minimum dateDateCurrent date
max-dateThe maximum date that can be selectedDateSix months after the current date
default-dateThe date selected by default, it is an array when type is multiple or range, passing in null means not selected by defaultDate | Date | nullToday
row-heightDate row heightnumber | string64
formatterDate formatting function(day: Day) => Day-
poppableWhether to display the calendar as a pop-up layerbooleantrue
show-markWhether to display the month background watermarkbooleantrue
show-titleWhether to display the calendar titlebooleantrue
show-subtitleWhether to display the calendar subtitle (year and month)booleantrue
show-confirmWhether to display the confirmation buttonbooleantrue
readonlyWhether it is in read-only state. Date cannot be selected in read-only statebooleanfalse
confirm-textConfirm button textstringOK
confirm-disabled-textText when confirm button is disabledstringOK
first-day-of-weekSet the starting day of the week0-60

Calendar Poppable Props

When Calendar's poppable is true, the following props are supported:

ParametersDescriptionTypeDefault value
v-model:showWhether to display the calendar pop-up windowbooleanfalse
positionPop-up position, optional values are top right leftstringbottom
roundWhether to display rounded pop-upsbooleantrue
close-on-popstateWhether to automatically close when the page is rolled backbooleantrue
close-on-click-overlayWhether to close the overlay after clicking itbooleantrue
safe-area-inset-topWhether to enable top safe area adaptationbooleanfalse
safe-area-inset-bottomWhether to enable bottom safe area adaptationbooleantrue

Calendar Range Props

When Calendar's type is range, the following props are supported:

ParametersDescriptionTypeDefault value
max-rangeThe maximum number of optional days in the date rangenumber | stringUnlimited
range-promptPrompt text when the range selection exceeds the maximum number of optional daysstringMaximum selection of xx days
show-range-promptWhen the range selection exceeds the maximum selectable number of days, whether to display the prompt textbooleantrue
allow-same-dayWhether to allow the date range to start and end on the same daybooleanfalse

Calendar Multiple Props

When Calendar's type is multiple, the following props are supported:

ParametersDescriptionTypeDefault value
max-rangeThe maximum number of days that can be selected for a datenumber | stringUnlimited
range-promptPrompt text when selecting more than the maximum number of optional daysstringSelect at most xx days

Day data structure

Each date in the calendar corresponds to a Day object, and the content of the Day object can be customized through the formatter attribute.

Key nameDescriptionType
dateDate object corresponding to dateDate
typeDate type, optional values are selected, start, middle, end, disabledstring
textThe text displayed in the middlestring
topInfoThe prompt information abovestring
bottomInfoPrompt information belowstring
classNameAdditional class namestring

Events

Event nameDescriptionCallback parameters
selectTriggered when any date is clicked and selectedvalue: Date | Date
confirmTriggered after date selection is completed. If show-confirm is true, it will be triggered after clicking the confirm buttonvalue: Date | Date
openTriggered when the popup layer is opened-
closeTriggered when closing the popup layer-
openedTriggered after the popup layer is opened and the animation ends-
closedTriggered after the popup layer is closed and the animation ends-
unselectWhen the type of the calendar component is multiple, triggered when the date is unselectedvalue: Date
month-showTriggered when a month enters the visible area{ date: Date, title: string }
over-rangeTriggered when the range selection exceeds the maximum selectable number of days-
click-subtitleTriggered when the calendar subtitle is clickedevent: MouseEvent
click-disabled-dateTriggered when a disabled date is clickedvalue: Date | Date

Slots

NameDescriptionParameters
titleCustom title-
subtitleCustom calendar subtitle{ text: string, date?: Date }
month-titleCustomize the subtitle of each month{ text: string, date: Date }
footerCustomize bottom area content-
confirm-textCustomize the content of the confirm button
top-infoCustomize the prompt information above the dateday: Day
bottom-infoCustomize the prompt information below the dateday: Day

method

Calendar instances can be obtained through ref and instance methods can be called.

Method nameDescriptionParametersReturn value
resetResets the selected date to the specified date. If no parameters are passed, it will be reset to the default datedate?: Date | Date-
scrollToDateScroll to a certain datedate: Date-
getSelectedDateGet the selected date-Date | Date | null

Theme customization

Style variables

The component provides the following CSS variables, which can be used to customize styles. For usage, please refer to ConfigProvider component.

NameDefaultDescription
--z-calendar-backgroundvar(--z-background-2)-
--z-calendar-popup-height80%-
--z-calendar-header-shadow0 4rpx 20rpx rgba(125, 126, 128, 0.16)-
--z-calendar-header-title-height88rpx-
--z-calendar-header-title-font-sizevar(--z-font-size-lg)-
--z-calendar-header-subtitle-font-sizevar(--z-font-size-md)-
--z-calendar-weekdays-height60rpx-
--z-calendar-weekdays-font-sizevar(--z-font-size-sm)-
--z-calendar-month-title-font-sizevar(--z-font-size-md)-
--z-calendar-month-mark-colorfade(var(--z-gray-2), 80%)-
--z-calendar-month-mark-font-size320rpx-
--z-calendar-day-height128rpx-
--z-calendar-day-font-sizevar(--z-font-size-lg)-
--z-calendar-day-margin-bottom8rpx-
--z-calendar-range-edge-colorvar(--z-white)-
--z-calendar-range-edge-backgroundvar(--z-primary-color)-
--z-calendar-range-middle-colorvar(--z-primary-color)-
--z-calendar-range-middle-background-opacity0.1-
--z-calendar-selected-day-size108rpx-
--z-calendar-selected-day-colorvar(--z-white)-
--z-calendar-info-font-sizevar(--z-font-size-xs)-
--z-calendar-info-line-heightvar(--z-line-height-xs)-
--z-calendar-selected-day-backgroundvar(--z-primary-color)-
--z-calendar-day-disabled-colorvar(--z-text-color-3)-
--z-calendar-confirm-button-height72rpx-
--z-calendar-confirm-button-margin14rpx 0-

common problem

How to use asynchronously returned data in formatter?

If you need to use asynchronously returned data in a formatter, you can use computed properties to dynamically create a formatter function. The example is as follows:

const asyncData = ref();

const formatter = computed(() => {
   if (!asyncData.value) {
     return (day) => day;
   }
   return (day) => {
     day.bottomInfo = asyncData.value;
     return day;
   };
});

setTimeout(() => {
   asyncData.value = 'Backend copywriting';
}, 3000);