calendar-core

Calendar Core

一个计算日历视图数据的核心算法。数据驱动，插件设计，轻量高效

安装

npm i calendar-core -S

演示

import CalendarCore from 'calendar-core'

const calendar = new CalendarCore(new Date(), {
  weekly: false,
  full: false,
  firstDayOfWeek: 0,
  plugins: [
    {
      name: 'myPlugin',
      handler (data, index) {
        const date = new Date(data.value)
        return {
          localeDate: date.toLocaleDateString(),
          localeTime: date.toLocaleTimeString()
        }
      }
    }
  ]
})

参数和类型描述

配置选项

interface Options {
  // 是否按周计算，计算结果只有 7 个元素，就是一周的数据
  weekly?: boolean

  // 当计算月份视图时，元素数量有 35 个和 42 个两种结果
  // 如果该值为 true，则全部按照 42 个元素计算，以保持所有月份元素数量相同
  full?: boolean

  // 一周的第一天，可选值范围是 0～6，默认为 0 (星期日)
  firstDayOfWeek?: number

  // 插件列表
  plugins?: Plugin[]
}

构造函数

interface CalendarCoreConstructor {
  /**
   * 使用 new CalendarCore 创建实例
   * @param value 基于该值计算当前月份，或者当前周的元素数据列表, 该值为必选项
   * @param options 配置选项
   */
  new (value: Date | string | number, options?: Options)

  /**
   * 根据一周的第一天获取星期数排序值
   * @param firstDayOfWeek 一周的第一天
   */
  getDays (firstDayOfWeek: number): number[]
}

实例对象

interface CalendarCore {
  // 当前实例化的日期对象的 ISO 日期字符串
  readonly value: string

  // 年份值
  readonly year: number

  // 月份值
  readonly month: number

  // 日期值
  readonly date: number

  // 日历元素数据列表
  readonly elements: Data[]

  /**
   * 实例化基于当前实例的上一个实例
   * 如果按周计算则为上一周，否则为上一个月份
   */
  prev (): CalendarCore

  /**
   * 实例化基于当前实例的下一个实例
   * 如果按周计算则为下一周，否则为下一个月份
   */
  next (): CalendarCore

  /**
   * 实例化基于当前实例按照指定步长移动后的实例
   * 上面的 prev 方法和 next 方法就是直接调用的该方法
   * @param step 移动步长，该值可为负数
   */
  move (step: number): CalendarCore
}

元素数据

interface DataBase {
  // 元素在视图中的位置
  // -1 为上一个月份的元素
  // 0 为当前月份的元素
  // 1 为下一个月份的元素
  pos: -1 | 0 | 1

  // 年份值
  year: number

  // 月份值
  month: number

  // 日期值
  date: number

  // 星期值
  day: number

  // ISO 日期字符串
  // 该值可作为唯一值（ID）使用
  // 如果该值与 CalendarCore 实例的 value 值相等，则为当前选中元素
  value: string
}

interface Extends {
  [key: string]: any
}

interface Data extends DataBase {
  // 数据扩展对象
  // 如果使用了插件，那么插件返回的数据结果将会以插件的名称作为 key 存储于此对象中
  // 该字段只有使用了插件的时候才会存在
  extends?: Extends
}

插件

像节日，农历，事件日程，黄道吉日等的功能扩展，都可通过插件实现

interface Plugin {
  // 插件名称，该值同时作为存储数据的键值，必选项
  name: string

  /**
   * 插件处理器，通过此方法返回的扩展的数据
   * @param data 当前循环的的元素数据对象，注意该对象为只读，不可修改
   * @param index 当前循环的索引
   */
  handler (data: Readonly<DataBase>, index: number): any
}