Skip to content

Latest commit

 

History

History
233 lines (170 loc) · 8.44 KB

README.md

File metadata and controls

233 lines (170 loc) · 8.44 KB

cxCalendar

cxCalendar 是基于 JavaScript 的日期选择器插件,支持日期、时间、月份、年份等多种类型。

它灵活自由,你可以自定义外观,日期的范围,返回的格式等。

优点

  • 无第三方依赖
  • 支持单日期、日期范围
  • 支持 CSS 自定义样式
  • 支持多语言扩展
  • 全局仅有一个选择器,减少 DOM 污染

Demo: https://ciaoca.github.io/cxCalendar/

从 v3.0 开始,已移除 jQuery 的依赖,如果需要使用旧版,可查看 v2 分支

preview

安装方法

浏览器端引入

<link rel="stylesheet" href="cxcalendar.css">
<script src="cxcalendar.js"></script>

从 NPM 安装,作为模块引入

npm install cxcalendar3
import 'cxcalendar.css';
import cxCalendar from 'cxcalendar3';

使用

// 绑定到输入框
cxCalendar.attach(document.getElementById('input'));

// 动态调用,适合 input 可能会新增或删除的情况
document.body.addEventListener('focus', (e) => {
  if (e.target.nodeName.toLowerCase() === 'input') {
    cxCalendar(e.target);
  };
});

设置默认参数

cxCalendar.defaults.type = 'datetime';
cxCalendar.defaults.language = {
  monthList: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'], 
  weekList: ['Sun', 'Mon', 'Tur', 'Wed', 'Thu', 'Fri', 'Sat'] 
};

API 接口

cxCalendar(document.getElementById('input')); // 立即显示日期选择器
cxCalendar.attach(document.getElementById('input'));
cxCalendar.detach(document.getElementById('input'));
名称 说明
attach(element, options) 绑定日期选择器
detach(element) 解除绑定

实例 API 接口

var input = document.getElementById('input');

// 获取实例
var api = cxCalendar.attach(input);
api.show();

// 销毁实例
cxCalendar.detach(input);
名称 说明
show() 显示面板
hide() 隐藏面板
getDate(format) 获取当前选择的日期
setDate(value) 设置日期值(时间戳或日期字符串)
clearDate() 清除日期值
setOptions(options) 设置参数

options 参数说明

cxCalendar(element, options);
cxCalendar.attach(element, options);
名称 类型 默认值 说明
date integer
string
undefined 默认日期(默认获取当前日期)
可使用时间戳或字符串
※ input 的 value 值优先级更高
startDate integer
string
undefined 起始日期(默认获取当前日期的一年前)
可使用时间戳或字符串
若设置值为 4 位数字,则转换为当年的1月1日
如: 2020 => 2020/1/1
endDate integer
string
undefined 结束日期(默认获取当前日期)
可使用时间戳或字符串
若设置值为 4 位数字,则转换为当年的12月31日
如: 2020 => 2020/12/31
type string 'date' 日期类型
'year' 年份
'month' 年份和月份
'date' 日期
'datetime' 日期和时间
'time' 时间
format string 'Y-m-d' 日期值格式
'Y' 年份,完整 4 位数字
'y' 年份,仅末尾 2 位数字
'm' 月份,数字带前导零(01-12)
'n' 月份(1-12)
'd' 月份中的第几天,有前导零(01-31)
'j' 月份中的第几天(1-31)
'H' 小时,24 小时格式,有前导零(00-23)
'G' 小时,24 小时格式(0-23)
'h' 小时,12 小时格式,有前导零(01-12)
'g' 小时,12 小时格式(1-12)
'i' 分钟,数字带前导零(00-59)
's' 秒,数字带前导零(00-59)
'a' 上午或下午名称
'timestamp' 时间戳(毫秒)
weekStart integer 0 星期开始于周几
0 星期日
1 星期一
2 星期二
3 星期三
4 星期四
5 星期五
6 星期六
lockRow boolean false 是否固定行数
每个月的日期数,可能会出现 5 行或 6 行
默认自适应,设为 true 则固定为 6 行
yearNum integer 20 年份每页条数
hourStep integer 1 小时间隔
minuteStep integer 1 分钟间隔
secondStep integer 1 秒间隔
disableWeek array [] 不可选择的日期(星期值)
0 星期日
1 星期一
2 星期二
3 星期三
4 星期四
5 星期五
6 星期六
例:[0,6] 表示所有周六、周日不可选择
disableDay array [] 不可选择的日期
'1' 每月 1 号
'1-5' 每年 1 月 5 日
'2020-1-1' 指定具体日期
※ 不要有前导零
mode string 'single' 选择模式
'single' 单选模式
'range' 范围模式
rangeSymbol string ' - ' 日期范围拼接符号
rangeMaxDay integer 0 日期范围最长间隔
rangeMaxMonth integer 0 月份范围最长间隔
rangeMaxYear integer 0 年份范围最长间隔
button object {} 操作按钮
today 选择现在
clear 清除已选值
默认自适应,若强制不需要可设置为 false,如 today: false
position string undefined 显示位置
'top'
'bottom'
'left'
'right'
'fixed' 自定义,配合 baseClass 使用
默认自适应,可参考:[Demo Position]
baseClass string undefined 追加样式名称
仅在面板容器增加 class,不会覆盖默认的 class
language string
object
undefined 语言配置
若为 string,将在语言配置文件中查找对应键名(需载入 cxcalendar.languages.js

date, startDate, endDate 的优先级与范围

  • date 早于 startDate 时,则为 startDate,晚于 endDate 时,则为 endDate
  • startDate 日期晚于 endDate 时,调整为 endDate 的一年前

date, startDate, endDate 支持的时间格式

日期连接符 - 可替换为 ./
月、日、时、分、秒,可为数字或带有前导零

  • y
  • y-m
  • y-m-d
  • y-m-d h:i
  • y-m-d h:i:s
  • m-d
  • m-d h:i
  • m-d h:i:s
  • h:i
  • h:i:s

data 属性参数

<input type="text" value="2020-12-1" data-start-date="2020" data-end-date="2021" data-format="Y/m/d" data-language="en">

※ data 属性参数优先级要高于调用时的 options 参数

名称 说明
data-start-date 起始日期
data-end-date 结束日期
data-type 日期类型
data-format 日期值格式
data-weekStart 星期开始于周几
data-year-num 年份每页条数
data-hour-step 小时间隔
data-minute-step 分钟间隔
data-second-step 秒间隔
data-lock-row 是否固定行数,值为 1 时视为 true ,例:data-lock-row="1"
data-disable-week 不可选择的日期(星期值),例:data-disable-week="0,6"
data-disable-day 不可选择的日期,例:data-disable-day="1,5-2,2021-2-11"
data-mode 选择模式
data-range-symbol 日期范围拼接符号
data-range-max-day 日期范围最长间隔
data-range-max-month 月份范围最长间隔
data-range-max-year 年份范围最长间隔
data-position 显示位置
data-base-class 追加样式名称
data-language 语言名称(仅支持 languages 已配置的键名)

操作按钮

  • 按钮文字在 css 中设置;
  • today 按钮会根据配置来决定是否存在。例如 startDateendDate 范围不包含当前时间,则不会存在;
  • confirm 按钮在选择时间和选择范围时存在,不支持配置。

多语言配置

cxcalendar.languages.js 文件中进行配置,载入即可根据用户的语言环境,自动显示对应的语言。

名称 默认值 说明
am '上午' 12小时制的上午名称
pm '下午' 12小时制的下午名称
monthList ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12'] 月份的名称
weekList ['日', '一', '二', '三', '四', '五', '六'] 星期的名称(从周日开始排序)
holiday [] 节假日配置
// 自定义语言示例
'zh-cn': {
  am: '上午',
  pm: '下午',
  monthList: ['一月', '二月', '三月', '四月', '五月', '六月', '七月', '八月', '九月', '十月', '十一月', '十二月'],
  weekList: ['日', '一', '二', '三', '四', '五', '六'],
  holiday: [
    {day: '1-1', name: '元旦'},  // 指定每年重复的节日
    {day: '2021-2-12', name: '春节'}  // 指定具体日期的节日
  ]
}