首页
/ 5个核心功能解决方案：react-native-calendars从入门到精通

5个核心功能解决方案：react-native-calendars从入门到精通

2026-03-16 03:47:59作者：郁楠烈Hubert
react-native-calendars
React Native Calendar Components 🗓️ 📆
项目地址：https://gitcode.com/gh_mirrors/re/react-native-calendars

核心功能解析

1. 日期标记系统

场景说明：在日程管理应用中，需要直观展示不同类型的日程事件，如会议、休假、截止日期等。react-native-calendars提供了灵活的日期标记功能，支持多种视觉展示方式。

基础实现：

<Calendar
  markingType={'multi-dot'}
  markedDates={{
    '2023-10-01': { 
      dots: [
        { key: 'work', color: '#007AFF', selectedDotColor: '#FFFFFF' },
        { key: 'personal', color: '#34C759' }
      ],
      selected: true,
      selectedColor: '#007AFF'
    },
    '2023-10-05': { 
      startingDay: true, 
      color: '#FF9500',
      textColor: '#FFFFFF' 
    },
    '2023-10-06': { color: '#FF9500' },
    '2023-10-07': { 
      endingDay: true, 
      color: '#FF9500',
      textColor: '#FFFFFF' 
    }
  }}
  onDayPress={(day) => console.log('Selected day:', day)}
/>

日历日期标记效果

常见误区：

  • 忘记设置markingType属性，导致标记不显示
  • 直接修改markedDates对象而不是创建新对象，导致UI不更新
  • 同时使用多种标记类型而未正确配置

专家提示：对于动态更新的标记数据，建议使用不可变数据结构（如Immer或Immutable.js）来确保组件正确重渲染。标记数据应仅包含当前可见月份的日期，以提高性能。

2. 可扩展日历视图

场景说明：在有限的屏幕空间内，需要同时展示月历概览和当日详细日程，可扩展日历视图允许用户通过滑动展开或折叠日程列表。

基础实现：

<ExpandableCalendar
  style={{ borderRadius: 10 }}
  current={'2023-10-01'}
  markedDates={markedDates}
  disabledOpacity={0.6}
  hideKnob={false}
  calendarWidth={320}
  renderItem={(item) => (
    <View style={styles.item}>
      <Text style={styles.itemText}>{item.title}</Text>
      <Text style={styles.itemTime}>{item.time}</Text>
    </View>
  )}
  data={[
    { title: '团队周会', time: '10:00-11:30', date: '2023-10-03' },
    { title: '产品评审', time: '14:00-15:30', date: '2023-10-03' },
    { title: '客户演示', time: '09:30-10:30', date: '2023-10-05' },
  ]}
/>

可扩展日历视图

常见误区：

  • 未正确设置calendarWidth导致布局错乱
  • 数据更新时未处理空状态，导致列表闪烁
  • 自定义renderItem时未保持一致的高度

专家提示：使用calendarWidth属性时，建议结合DimensionsAPI动态计算宽度，以适配不同屏幕尺寸。对于大量数据，考虑实现虚拟列表优化渲染性能。

3. 时间线日程视图

场景说明：需要以时间轴形式展示一天内的详细日程安排，直观显示事件的时间重叠和持续时长。

基础实现：

<Timeline
  data={[
    {
      id: '1',
      title: '晨间会议',
      start: '2023-10-03T09:00:00',
      end: '2023-10-03T10:00:00',
      summary: '每日站会，讨论当日计划',
      color: '#4CAF50'
    },
    {
      id: '2',
      title: '产品设计评审',
      start: '2023-10-03T10:30:00',
      end: '2023-10-03T12:00:00',
      summary: '讨论新功能原型',
      color: '#2196F3'
    },
    {
      id: '3',
      title: '午餐',
      start: '2023-10-03T12:00:00',
      end: '2023-10-03T13:00:00',
      color: '#FF9800'
    }
  ]}
  timeIntervals={60}
  format24h={true}
  showNowIndicator={true}
  onEventPress={(event) => console.log('Event pressed:', event)}
/>

时间线日程视图

常见误区：

  • 事件时间格式不正确导致渲染异常
  • 未处理事件重叠情况，导致UI混乱
  • 未设置适当的timeIntervals导致时间刻度显示不当

专家提示：对于跨天事件，建议在数据处理阶段拆分到不同日期。使用showNowIndicator时，可配合定时器定期更新指示器位置，保持实时性。

4. 周视图日历

场景说明：在需要关注短期日程的应用中，周视图提供了比月视图更详细的日程展示，同时比日视图能看到更多日期范围。

基础实现：

<WeekCalendar
  onDayPress={(day) => console.log('Selected day:', day)}
  markedDates={markedDates}
  weekStartsOn={1} // 1表示周一为一周的第一天
  numberOfDays={7}
  horizontal={true}
  pagingEnabled={true}
  style={{ height: 400 }}
  renderDayContent={(day) => (
    <View style={styles.dayContent}>
      {day.marking?.dots && day.marking.dots.map((dot, index) => (
        <View 
          key={index} 
          style={[styles.dot, { backgroundColor: dot.color }]} 
        />
      ))}
    </View>
  )}
/>

周视图日历

常见误区：

  • 未正确设置horizontal和pagingEnabled属性导致滑动体验不佳
  • 自定义renderDayContent时未考虑日期选择状态
  • 未处理不同屏幕尺寸下的布局适配

专家提示：结合onWeekChange事件实现周数据的懒加载，只加载当前可见周的事件数据，显著提升性能。

5. 议程视图

场景说明：以列表形式按日期分组展示日程，适合需要快速浏览多个日期事件的场景，如会议安排、课程表等。

基础实现：

<Agenda
  items={{
    '2023-10-03': [
      { name: '团队周会', time: '10:00', duration: '1h' },
      { name: '产品评审', time: '14:00', duration: '1.5h' }
    ],
    '2023-10-05': [
      { name: '客户演示', time: '09:30', duration: '1h' },
      { name: '技术分享', time: '15:00', duration: '1h' }
    ]
  }}
  renderItem={(item, firstItemInDay) => (
    <View style={[styles.agendaItem, firstItemInDay && styles.firstItem]}>
      <Text style={styles.itemTime}>{item.time}</Text>
      <Text style={styles.itemName}>{item.name}</Text>
      <Text style={styles.itemDuration}>{item.duration}</Text>
    </View>
  )}
  renderEmptyDate={() => (
    <View style={styles.emptyDate}>
      <Text style={styles.emptyDateText}>当天没有安排</Text>
    </View>
  )}
  rowHasChanged={(r1, r2) => r1.name !== r2.name}
  pastScrollRange={1}
  futureScrollRange={3}
  onLoadMoreItems={(day) => {
    // 加载更多日期数据
    console.log('加载日期:', day);
  }}
/>

常见误区：

  • 数据更新时未实现rowHasChanged方法，导致列表渲染异常
  • 未设置pastScrollRange和futureScrollRange导致初始加载数据过多
  • 自定义renderItem时未处理firstItemInDay状态

专家提示：启用infiniteScroll属性并实现onLoadMoreItems方法，实现日程数据的无限滚动加载，提升大数据量下的性能表现。

典型场景应用

场景一：会议室预订系统

需求分析：开发一个企业会议室预订系统，需要展示会议室占用情况，允许用户查看不同日期的可用时段并进行预订。

实现步骤：

  1. 设置基础日历组件：
const MeetingRoomCalendar = () => {
  const [selectedDate, setSelectedDate] = useState('2023-10-03');
  const [markedDates, setMarkedDates] = useState({});
  const [reservations, setReservations] = useState({});
  
  // 初始化标记数据
  useEffect(() => {
    fetchReservations().then(data => {
      setReservations(data);
      // 处理标记数据
      const marks = {};
      Object.keys(data).forEach(date => {
        marks[date] = { marked: true, dotColor: '#FF3B30' };
      });
      setMarkedDates(marks);
    });
  }, []);
  
  return (
    <View style={styles.container}>
      <Calendar
        current={selectedDate}
        markedDates={markedDates}
        onDayPress={(day) => {
          setSelectedDate(day.dateString);
          // 加载选中日期的预订数据
          fetchDayReservations(day.dateString).then(data => {
            setReservations(prev => ({...prev, [day.dateString]: data}));
          });
        }}
        theme={{
          selectedDayBackgroundColor: '#007AFF',
          todayTextColor: '#007AFF',
          arrowColor: '#007AFF'
        }}
      />
      
      <Timeline
        data={reservations[selectedDate] || []}
        style={styles.timeline}
        timeIntervals={60}
        format24h={true}
        showNowIndicator={true}
        onEventPress={(event) => {
          // 显示预订详情或编辑界面
          navigation.navigate('ReservationDetail', { event });
        }}
        renderEventContent={(event) => (
          <View style={[styles.eventContainer, { backgroundColor: event.color }]}>
            <Text style={styles.eventTitle}>{event.roomName}</Text>
            <Text style={styles.eventDesc}>{event.title}</Text>
          </View>
        )}
      />
      
      <FAB
        style={styles.fab}
        icon="plus"
        onPress={() => navigation.navigate('NewReservation', { date: selectedDate })}
      />
    </View>
  );
};
  1. 样式配置：
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#F5F5F5',
  },
  timeline: {
    flex: 1,
    marginTop: 10,
    paddingHorizontal: 10,
  },
  eventContainer: {
    padding: 8,
    borderRadius: 6,
  },
  eventTitle: {
    color: 'white',
    fontWeight: 'bold',
    fontSize: 14,
  },
  eventDesc: {
    color: 'white',
    fontSize: 12,
  },
  fab: {
    position: 'absolute',
    margin: 16,
    right: 0,
    bottom: 0,
    backgroundColor: '#007AFF',
  },
});
  1. 数据处理：
// 模拟API调用
const fetchReservations = async () => {
  // 实际应用中替换为真实API调用
  return {
    '2023-10-03': [
      {
        id: '1',
        roomName: '会议室A',
        title: '产品规划会议',
        start: '2023-10-03T09:00:00',
        end: '2023-10-03T10:30:00',
        color: '#FF3B30'
      },
      {
        id: '2',
        roomName: '会议室B',
        title: '技术评审',
        start: '2023-10-03T14:00:00',
        end: '2023-10-03T15:00:00',
        color: '#5856D6'
      }
    ],
    // 更多日期数据...
  };
};

效果展示： 时间线日程视图

场景二：健身课程预约系统

需求分析：开发一个健身课程预约应用，用户可以查看每周课程安排，标记已预约课程，并能查看详细课程信息。

实现步骤：

  1. 实现周视图日历：
const FitnessClassCalendar = () => {
  const [selectedDate, setSelectedDate] = useState(moment().format('YYYY-MM-DD'));
  const [classes, setClasses] = useState({});
  const [userBookings, setUserBookings] = useState({});
  
  useEffect(() => {
    // 加载课程数据
    fetchWeeklyClasses().then(data => setClasses(data));
    // 加载用户预约
    fetchUserBookings().then(data => setUserBookings(data));
  }, []);
  
  // 生成标记数据
  const markedDates = useMemo(() => {
    const marks = {};
    Object.keys(classes).forEach(date => {
      // 有课程的日期标记为蓝色
      marks[date] = { marked: true, dotColor: '#007AFF' };
      
      // 用户已预约的日期标记为绿色
      if (userBookings[date]) {
        marks[date].dots = [
          { key: 'available', color: '#007AFF' },
          { key: 'booked', color: '#34C759' }
        ];
        marks[date].markingType = 'multi-dot';
      }
    });
    return marks;
  }, [classes, userBookings]);
  
  return (
    <View style={styles.container}>
      <WeekCalendar
        onDayPress={(day) => {
          setSelectedDate(day.dateString);
        }}
        markedDates={markedDates}
        weekStartsOn={1}
        horizontal={true}
        pagingEnabled={true}
        style={styles.weekCalendar}
        renderDayContent={(day) => (
          <View style={styles.dayContent}>
            <Text style={styles.dayText}>{day.day}</Text>
            {day.marking?.dots && day.marking.dots.map((dot, index) => (
              <View 
                key={index} 
                style={[styles.dot, { backgroundColor: dot.color }]} 
              />
            ))}
          </View>
        )}
      />
      
      <View style={styles.classListContainer}>
        <Text style={styles.dateHeader}>{moment(selectedDate).format('MMMM Do, YYYY')}</Text>
        
        {classes[selectedDate]?.length > 0 ? (
          <FlatList
            data={classes[selectedDate]}
            keyExtractor={(item) => item.id}
            renderItem={({ item }) => (
              <ClassItem 
                item={item}
                isBooked={!!userBookings[selectedDate]?.includes(item.id)}
                onBookToggle={(id, isBooked) => handleBookingToggle(selectedDate, id, isBooked)}
              />
            )}
          />
        ) : (
          <View style={styles.emptyState}>
            <Text style={styles.emptyText}>当天没有课程安排</Text>
          </View>
        )}
      </View>
    </View>
  );
};
  1. 课程项组件：
const ClassItem = ({ item, isBooked, onBookToggle }) => {
  return (
    <View style={styles.classItem}>
      <View style={styles.classInfo}>
        <Text style={styles.className}>{item.title}</Text>
        <Text style={styles.classTime}>{item.time}</Text>
        <Text style={styles.classInstructor}>教练: {item.instructor}</Text>
      </View>
      
      <Button
        title={isBooked ? "取消预约" : "预约"}
        color={isBooked ? "#FF3B30" : "#34C759"}
        onPress={() => onBookToggle(item.id, isBooked)}
        style={styles.bookButton}
      />
    </View>
  );
};

效果展示： 周视图日历

进阶优化方案

性能优化

  1. 虚拟列表实现： 对于包含大量事件的议程视图，使用FlatList替代ScrollView实现虚拟列表：
<Agenda
  renderItem={renderItem}
  // 使用自定义FlatList实现虚拟列表
  listProps={{
    renderScrollComponent: (props) => (
      <FlatList {...props} removeClippedSubviews={true} />
    ),
    maxToRenderPerBatch: 5,
    windowSize: 7,
  }}
/>
  1. 数据分片加载： 实现日历数据的按需加载，只加载当前可见区域的数据：
const CalendarWithLazyLoading = () => {
  const [visibleMonths, setVisibleMonths] = useState([]);
  const [markedDates, setMarkedDates] = useState({});
  
  const handleMonthChange = (month) => {
    const monthStr = moment(month.dateString).format('YYYY-MM');
    
    // 避免重复加载
    if (!visibleMonths.includes(monthStr)) {
      setVisibleMonths(prev => [...prev, monthStr]);
      
      // 加载该月份的数据
      fetchMonthData(monthStr).then(data => {
        setMarkedDates(prev => ({
          ...prev,
          ...data
        }));
      });
    }
  };
  
  return (
    <Calendar
      onMonthChange={handleMonthChange}
      markedDates={markedDates}
      // 其他属性...
    />
  );
};
  1. 避免不必要的重渲染： 使用React.memo和useCallback优化组件性能：
const MemoizedDayComponent = React.memo(({ day, onPress }) => {
  // 组件实现...
}, (prevProps, nextProps) => {
  // 自定义比较函数，只有当关键属性变化时才重渲染
  return (
    prevProps.day.dateString === nextProps.day.dateString &&
    prevProps.day.marking === nextProps.day.marking &&
    prevProps.day.selected === nextProps.day.selected
  );
});

兼容性优化

  1. 跨平台样式统一： 针对iOS和Android平台实现统一的视觉效果：
// 使用Platform API适配不同平台
const getPlatformStyles = () => {
  if (Platform.OS === 'ios') {
    return {
      dayTextFontFamily: 'Helvetica Neue',
      dayTextFontSize: 16,
    };
  }
  return {
    dayTextFontFamily: 'Roboto',
    dayTextFontSize: 14,
  };
};

// 在组件中使用
const platformStyles = useMemo(() => getPlatformStyles(), []);

<Calendar
  theme={{
    ...platformStyles,
    // 其他主题属性
  }}
/>
  1. Android硬件加速： 在AndroidManifest.xml中启用硬件加速提升性能：
<application
  android:hardwareAccelerated="true"
  ...>
  <!-- 其他配置 -->
</application>
  1. 日期库兼容性处理： 使用内置的dateutils或自定义日期处理函数确保跨平台一致性：
import { getDateString, addDays } from '../src/dateutils';

// 代替直接使用moment或其他日期库
const tomorrow = addDays(new Date(), 1);
const tomorrowStr = getDateString(tomorrow);

扩展性优化

  1. 自定义主题系统： 实现可定制的主题系统，允许应用整体风格调整：
// 主题上下文
const CalendarThemeContext = React.createContext(defaultTheme);

export const CalendarThemeProvider = ({ children, theme }) => {
  return (
    <CalendarThemeContext.Provider value={theme}>
      {children}
    </CalendarThemeContext.Provider>
  );
};

// 自定义日历组件
export const ThemedCalendar = (props) => {
  const theme = useContext(CalendarThemeContext);
  
  return (
    <Calendar
      theme={{ ...defaultTheme, ...theme }}
      {...props}
    />
  );
};

// 使用方式
<CalendarThemeProvider theme={{ 
  selectedDayBackgroundColor: '#FF5733',
  todayTextColor: '#FF5733'
}}>
  <ThemedCalendar />
</CalendarThemeProvider>
  1. 事件总线系统： 实现事件总线机制，方便组件间通信：
// eventBus.js
import { EventEmitter } from 'events';
export const calendarEventEmitter = new EventEmitter();

// 在日历组件中
useEffect(() => {
  const handleDateChange = (date) => {
    setSelectedDate(date);
  };
  
  calendarEventEmitter.on('dateChanged', handleDateChange);
  
  return () => {
    calendarEventEmitter.off('dateChanged', handleDateChange);
  };
}, []);

// 在其他组件中触发事件
calendarEventEmitter.emit('dateChanged', newDateString);
  1. 插件化功能扩展： 设计插件系统，允许动态添加功能：
// 定义插件接口
const CalendarPlugin = {
  name: 'base-plugin',
  hooks: {
    beforeRenderDay: (day) => day,
    afterRenderDay: (dayElement) => dayElement,
  },
  components: {}
};

// 插件管理器
class PluginManager {
  constructor() {
    this.plugins = [];
  }
  
  registerPlugin(plugin) {
    this.plugins.push(plugin);
  }
  
  applyHook(hookName, ...args) {
    return this.plugins.reduce((result, plugin) => {
      if (plugin.hooks && plugin.hooks[hookName]) {
        return plugin.hookshookName;
      }
      return result;
    }, args[0]);
  }
}

// 使用插件
const pluginManager = new PluginManager();
pluginManager.registerPlugin(holidayPlugin); // 节假日插件
pluginManager.registerPlugin(weatherPlugin); // 天气插件

// 在日历组件中应用插件
const dayToRender = pluginManager.applyHook('beforeRenderDay', day);

问题排查指南

问题描述 可能原因 解决方案
日期标记不显示 未设置markingType属性 确保根据标记类型设置markingType为'dot'、'multi-dot'或'period'
日历滑动卡顿 渲染数据过多或组件复杂度过高 实现数据分片加载，使用虚拟列表，简化渲染组件
事件不触发 事件处理函数未正确绑定 使用useCallback确保函数引用稳定，检查事件名称是否正确
跨平台样式不一致 未针对不同平台进行样式适配 使用Platform API或第三方库统一样式，避免平台特定样式
组件不更新 状态更新不正确或引用未变化 确保使用不可变数据结构更新状态，避免直接修改对象
日期格式错误 日期字符串格式不符合要求 使用标准ISO格式(YYYY-MM-DD)，通过dateutils处理日期
初始渲染空白 数据加载时机不当 在useEffect中正确处理数据加载，添加加载状态提示
议程视图高度计算错误 动态内容未正确处理 使用onLayout回调动态调整高度，或固定itemHeight
时间线事件重叠显示异常 事件排序或定位算法问题 确保事件按开始时间排序，使用Packer算法优化布局
周视图滑动不流畅 渲染项过多或手势处理冲突 减少同时渲染的天数，优化手势响应区域

总结

react-native-calendars提供了丰富的日历组件和功能，通过本文介绍的核心功能解析、典型场景应用和进阶优化方案，你可以构建出高性能、用户体验优秀的日历应用。无论是简单的日期选择器还是复杂的日程管理系统，react-native-calendars都能满足你的需求。

要深入学习更多高级特性，可以参考官方文档：docsRNC/docs/intro.md，以及项目中的示例代码：example/src/screens/。通过不断实践和优化，你可以充分发挥这个强大组件库的潜力，为用户提供出色的日历体验。

react-native-calendars
React Native Calendar Components 🗓️ 📆
项目地址：https://gitcode.com/gh_mirrors/re/react-native-calendars
登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
27
12
docsdocs
OpenHarmony documentation | OpenHarmony开发者文档
Dockerfile
602
4.04 K
leetcodeleetcode
🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解
Java
69
21
pytorchpytorch
Ascend Extension for PyTorch
Python
442
531
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
112
170
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
1.46 K
825
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
922
770
flutter_flutterflutter_flutter
暂无简介
Dart
847
204
ohos_react_nativeohos_react_native
React Native鸿蒙化仓库
JavaScript
321
375
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
174
249