Skip to main content
Version: Next

Date Time Picker

Table of Contents​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction​

This document comprehensively covers the design and integration of the date time selection components. It highlights how DateTimePickRange implements dual-panel linked selection, shortcut option configuration, and international date format adaptation. It explains the deep integration mechanism with the Vue 3 reactive system, including v-model two-way binding, time range validation, and disabled date logic. It analyzes the encapsulation strategy of DatePicker for underlying Element Plus components, and the adaptation scheme of DyDatePicker in dynamic forms. Practical suggestions on mobile adaptation, time zone handling, and performance optimization are provided, along with solutions for common issues such as time zone confusion and panels not closing.

Project Structure​

The date time selection components are located in the src/components directory and include three main components: DateTimePickRange, DyDatePicker, and DatePicker. These components are unifiedly exported via src/components/index.ts for global use in the project.

Diagram Source

Section Source

Core Components​

This project contains three core date time selection components:

  • DateTimePickRange: A composite component for selecting time ranges.
  • DyDatePicker: A date selector for dynamic forms.
  • DatePicker: A wrapper for the basic date selector.

All these components are encapsulated based on Element Plus's el-date-picker component, providing default configurations and styles that better meet project requirements.

Section Source

Architecture Overview​

The date time selection components adopt a layered architecture design. Upper-layer components encapsulate the Element Plus date selector, providing project-specific default configurations and behaviors. The DateTimePickRange component implements special logic for time range selection, including time range validation and linked selection.

Diagram Source

Detailed Component Analysis​

DateTimePickRange Analysis​

The DateTimePickRange component implements a linked function for dual date selectors, allowing users to select a time range. The component manages two time values through Vue 3's reactive system and performs range validation when the user selects a time.

Diagram Source

Dual Panel Linked Selection Mechanism​

The DateTimePickRange component uses Vue 3's reactive function to create a reactive object times, which contains From and To properties corresponding to the start and end times. When the user selects a start time, the component checks if the selected time is later than the end time; when selecting an end time, it checks if it is earlier than the start time. If the time range is invalid, a warning message is displayed via ElMessage.

Diagram Source

International Date Format Adaptation​

The component implements internationalization support through the _t function, which is imported from @/libs/Language/Language. The _t function returns the corresponding translated text based on the current language environment. Placeholder texts in the component, such as "Please select start time" and "Please select end time", are translated via the _t function.

Diagram Source

DyDatePicker Analysis​

The DyDatePicker component is a simple wrapper component used in dynamic forms. It inherits all properties of the Element Plus date selector and sets the default value-format to "YYYY-MM-DD HH:mm:ss".

Diagram Source

Dynamic Form Adaptation Scheme​

DyDatePicker passes all incoming properties and attribute bindings to the underlying el-date-picker component using JSX syntax and {...props}, {...attrs} spread operators. This allows DyDatePicker to be fully compatible with all functions of the Element Plus date selector while providing project-specific default values.

Diagram Source

DatePicker Analysis​

The DatePicker component is a basic wrapper around the Element Plus date selector, mainly adding custom icons and popup styles.

Diagram Source

Encapsulation Strategy​

The DatePicker component uses Vue 3's v-bind="$attrs" syntax to pass all undeclared properties to the internal el-date-picker component. This achieves property transparency, allowing external setting of all properties supported by el-date-picker. The component also sets a custom CSS class name for the popup layer via the popper-class property to implement themed styles.

Diagram Source

Section Source

Dependency Analysis​

The date time selection components depend on multiple external libraries and internal modules, forming a clear dependency relationship.

Diagram Source

Section Source

Performance Considerations​

The date time selection components have the following performance considerations:

  • Use Vue 3's Composition API and reactive system to ensure efficient update mechanisms.
  • Create reactive objects via reactive to avoid unnecessary re-renders.
  • Use dayjs for date comparison during time range validation, which is performant.
  • Components adopt on-demand import to reduce bundle size.

For large applications, it is recommended to:

  • Consider using virtual scrolling in pages with heavy use of date selectors.
  • Avoid creating too many date selector instances in loops.
  • Use the clearable attribute reasonably to avoid accidental user operations.

Troubleshooting Guide​

Common Issues and Solutions​

Time Zone Confusion​

Problem Description: The time displayed when the user selects a date time in a different time zone is inconsistent with the actually stored time.

Solution:

  1. Ensure unified time zone standards for both frontend and backend.
  2. Explicitly specify time zone information in value-format.
  3. Use the dayjs time zone plugin for time zone conversion.
  4. Uniformly handle time zone conversion on the server side.

Panel Not Closing​

Problem Description: The date selection panel does not close automatically after selecting a date.

Solution:

  1. Check for code preventing event bubbling.
  2. Ensure el-date-picker's popper-append-to-body attribute is set correctly.
  3. Check if CSS styles affect the behavior of the popup layer.
  4. Confirm compatibility between Vue version and Element Plus version.

Time Range Validation Failure​

Problem Description: Time range validation logic does not execute correctly.

Solution:

  1. Check if onChangeFrom and onChangeTo events are bound correctly.
  2. Confirm dayjs library is imported correctly.
  3. Check if date format matches valueFormat setting.
  4. Ensure times reactive object is initialized correctly.

Section Source

Conclusion​

This document details the date time selection components in the project, including the three core components: DateTimePickRange, DyDatePicker, and DatePicker. These components are encapsulated based on Element Plus's el-date-picker, providing default configurations and behaviors that better meet project requirements.

The DateTimePickRange component implements special logic for time range selection, including time range validation and linked selection, achieving efficient time processing through Vue 3's reactive system and the dayjs library. The DyDatePicker component provides a convenient date selector wrapper for dynamic forms, achieving full compatibility through property spread operators. The DatePicker component offers basic style and icon encapsulation.

All components support internationalization, implementing multi-language support through the Language module. In actual usage, developers can choose suitable components according to specific needs and refer to the best practices and troubleshooting guide in this document to resolve common issues.

Last updated on