当前位置：首页 > news >正文

Dayzed API完全参考：解锁React日期选择器的全部潜能

news 2026/8/9 18:17:12

Dayzed API完全参考：解锁React日期选择器的全部潜能

【免费下载链接】dayzedPrimitives to build simple, flexible, WAI-ARIA compliant React date-picker components.项目地址: https://gitcode.com/gh_mirrors/da/dayzed

Dayzed是一个为React开发者打造的灵活日期选择器组件库，提供了构建简单、灵活且符合WAI-ARIA标准的日期选择器组件所需的基础组件。本文将全面解析Dayzed的API，帮助开发者快速掌握如何利用这个强大的工具创建自定义日期选择器。

快速入门：Dayzed安装与基础使用

安装步骤

要开始使用Dayzed，首先需要通过npm或yarn安装：

npm install --save dayzed

或者

yarn add dayzed

注意：Dayzed依赖react@>=16.8.0和prop-types，请确保这些依赖已安装。此外，Dayzed也支持preact@>=10，Preact用户可以从dayzed/preact导入。

基础示例

Dayzed提供了两种使用方式：自定义Hook和渲染属性函数。以下是一个简单的单日期选择器示例：

import React from 'react'; import { useDayzed } from 'dayzed'; function Datepicker(props) { const { calendars, getBackProps, getForwardProps, getDateProps } = useDayzed(props); // 渲染日历的代码 return ( <div> <button {...getBackProps({ calendars })}>Back</button> <button {...getForwardProps({ calendars })}>Next</button> {/* 日历网格渲染 */} </div> ); }

核心API详解

Dayzed Props

Dayzed组件接受多种属性来定制日期选择器的行为和外观。以下是主要属性的详细说明：

date

date| 默认为new Date()

用于计算初始渲染时显示的月份。

maxDate 和 minDate

date| 可选

用于限制可选日期的范围。maxDate设置最大可选日期，minDate设置最小可选日期。

monthsToDisplay

number| 默认为1

指定要显示的月份数量，基于date和offset属性计算。

firstDayOfWeek

number| 默认为0

设置每周的第一天，可能的值为0-6（周日到周六），默认为周日。

showOutsideDays

boolean| 默认为 false

标志是否用相邻月份的日期填充前后几周。

selected

any| 可选

已选择的日期，可以是单个Date对象或Date对象数组。

onDateSelected

function(selectedDate: Date, event: Event)|必需

当用户选择日期时调用的函数。接收两个参数：selectedDate（被选中的日期）和event（触发选择的事件）。

render

function({})|必需

用于渲染日历的函数，接收一个包含日历数据和工具函数的对象。

offset

number|控制属性| 默认为0（如果不受控）

相对于date属性的月份偏移量。

onOffsetChanged

function(offset: number)|控制属性

当用户选择前进或后退时调用的函数。如果提供了offset属性，则此函数必需。

控制属性（Control Props）

Dayzed内部管理自己的offset状态，并在偏移量变化时调用onOffsetChanged处理函数。通过将offset作为属性传递，可以将状态变为受控状态，从而获得更多控制权。这类似于React中的受控组件概念，如<input />。

自定义Hook：useDayzed

useDayzed是Dayzed提供的自定义Hook，相比渲染属性函数，它不会在渲染树中添加额外的子节点。使用方式如下：

function Datepicker(props) { const { calendars, getBackProps, getForwardProps, getDateProps } = useDayzed(props); return <div>{/* 日历元素渲染 */}</div>; }

渲染属性函数

渲染属性函数是通过render属性或作为子组件传递给Dayzed的函数。它接收一个包含以下两类属性的对象：

Prop Getters

Prop Getters是用于将属性应用到渲染元素的函数，提供了最大的灵活性。主要包括：

getDateProps({}): 返回应应用于日期按钮元素的属性
getBackProps({}): 返回应应用于"后退"按钮元素的属性
getForwardProps({}): 返回应应用于"前进"按钮元素的属性

使用示例：

<button {...getDateProps({ onClick: (e) => console.log('Date clicked', e) })}> {date.getDate()} </button>

State

状态值表示Dayzed组件的当前状态，主要包括calendars数组，其中每个元素包含月份数据：

month: 月份的从零开始的数字（0-11）
year: 月份的年份
firstDayOfMonth: 月份的第一天
lastDayOfMonth: 月份的最后一天
weeks: 包含每月每周日期对象的数组

每个日期对象包含以下属性：

date: 该星期几的Date对象
selected: 该日期是否被选中
selectable: 该日期是否可选择
today: 该日期是否是今天
prevMonth: 该日期是否属于上一个月
nextMonth: 该日期是否属于下一个月

实战技巧：充分利用Dayzed API

多日期选择实现

要实现多日期选择，只需将selected属性设置为日期数组，并在onDateSelected处理函数中管理选中状态：

function MultiDatePicker() { const [selectedDates, setSelectedDates] = useState([]); const handleDateSelected = (date) => { setSelectedDates(prev => prev.includes(date) ? prev.filter(d => d !== date) : [...prev, date] ); }; return ( <Dayzed selected={selectedDates} onDateSelected={handleDateSelected} render={/* 渲染函数 */} /> ); }

日期范围选择

日期范围选择可以通过维护开始和结束日期状态来实现：

function RangeDatePicker() { const [range, setRange] = useState({ start: null, end: null }); const handleDateSelected = (date) => { setRange(prev => prev.start === null ? { start: date, end: null } : prev.end === null ? { ...prev, end: date } : { start: date, end: null } ); }; return ( <Dayzed selected={[range.start, range.end].filter(Boolean)} onDateSelected={handleDateSelected} render={/* 渲染函数 */} /> ); }

自定义日期显示

利用calendars状态中的日期信息，可以完全自定义日期的显示方式，包括样式、内容和交互：

{calendar.weeks.map((week, weekIndex) => week.map((dateObj, index) => { if (!dateObj) return <div key={index} />; const { date, selected, today } = dateObj; const style = { background: today ? 'cornflowerblue' : '', background: selected ? 'purple' : background, // 更多样式... }; return ( <button style={style} key={index} {...getDateProps({ dateObj })} > {date.getDate()} </button> ); }) )}