bs-ui-date

Base Readme

这个项目是从bs-ui-seed基础创建出来的. 请查看base/README.md 来了解其基础内容.

功能介绍

本组件主要是日期选择组件，它提供下面两种功能

• 基础的时间选择功能
• 用户可还可使用页面级时间选择（通过特定属性切换）

使用方法

特别说明（！！！重要）

使用本组件时需配置bs-utils,否则相关moment功能无法使用

1. 安装

npm i bs-ui-date -s

2. json

// 使用页面级时间选择器时必须注册这个页面，否则页面级时间选择无法正常使用
"pages": [
  "miniprogram_npm/bs-ui-date/datepicker/index", // 页面级选择器主页
],
// 配置该组件
"usingComponents": {
    "bs-date": "miniprogram_npm/bs-ui-date/index"
  }

3. wxml

使用时建议在外部使用一个view进行包装，并设置宽度和高度

<bs-date date='{{dateTimeStamp}}'
        start='{{946656000000}}'
        end= '2035-12-30'
        slot-icon=""
        is-picker="{{true}}"
        date-type-name="{{dateTypeName}}"
        limit="{{limit}}" 
        binddatechange="dateChange">
    <view slot="...">"自定义结构"</view>
    <!-- <view slot="date">日历小图标</view>
    <view slot="prev">前箭头</view>
    <view slot="next">后箭头</view> -->
</bs-date>
<!-- 区域选择的Date设置 -->
<view class='dateview'>
    <bs-date date='{{range_dateTimestamp}}' is-picker="{{false}}" date-format="{{range_dateFormat}}"
        show-week="{{prop_showWeek}}" date-type-name="{{dateRangeName}}" date-types="days"
        binddatechange="daterangechange" start="{{range_startTimestamp}}" end="range_endTimestamp" callback-func="daterangechange" 
        slot-icon="prev,next" disabled-before-day="range_disabledBeforeDay" disabled-after-day="range_disabledAfterDay">
        <view slot="prev"></view>
        <view slot="next"></view>

    </bs-date>
</view>

4. wxss

在app.wxss引入组件全局样式

@import "miniprogram_npm/bs-ui-date/default.wxss";

5. js

Page({
    data: {
        dateTypeName: 'day',
        dateTimeStamp: new Date().valueOf(),
        //时间范围的参数
        dateRangeName: 'days',
        range_dateTimestamp: [moment().startOf('day').valueOf(), moment.endOf('day').valueOf()], //时间范围选择的Date初始值，必须两个都有或者两个都没值
        range_startTimestamp: utils.moment('2018-1-1','YYYY-M-D').valueOf(),//组件往后渲染的截止日期
        range_endTimestamp:utils.moment().valueOf(),//组件往前渲染的截止日期
        range_disabledBeforeDay:28,//组件往前可以选择多少天 如果往后的时间大于结束时间则只能选择到结束时间 一般适用于区间选择
        range_disabledAfterDay:20,//组件往后可以选择多少天 一般适用于区间选择 
        range_dateFormat: 'YYYY-M-D',//日期范围的显示格式
        limit: {//不同dateType的start和end不一样
            day: {
                startTime: utils.moment('2019-1-1', 'YYYY-M-D').valueOf(),
                endTime: utils.moment().add(-2,'day').endOf().valueOf()
            },
            week: {
                startTime: utils.moment('2019-1-1', 'YYYY-M-D').valueOf(),
                endTime: utils.moment().valueOf()
            },
            month: {
                startTime: utils.moment('2019-1-1', 'YYYY-M-D').valueOf(),
                endTime: utils.moment().valueOf()
            },
            year: {
                startTime: utils.moment('2019-1-1', 'YYYY-M-D').valueOf(),
                endTime: utils.moment().valueOf()
            },
        }
    },
    // 时间改变后的默认回调函数,要自定义函数名请用'callback-func'
    datechange(event) {
        // 这里是返给使用者的参数
        const {
            dateTypeName, // 日期的类型
            dateStr, // 组件内部处理后的字符串
            dateTimestamp // 选择后的时间戳；
            startTimestamp, //开始时间的时间戳 主要用于周的返回时间
            endTimestamp,//结束时间的时间戳 主要用于周的返回时间
        } = event.detail
        this.setData({
            dateTimestamp: dateTimestamp,
            dateTypeName: dateTypeName
        })
    },
    /**时间范围选择 */
    daterangechange(event) {
        const {
            dateTypeName,
            dateStr,
            dateTimestamp
        } = event.detail
        this.setData({
            range_dateTimestamp: dateTimestamp,//区域选择时，该字段返回是时间戳数组
            dateRangeName: dateTypeName
        })
    },
})

接口说明

Properties

| Property | type | Required | Default Value | Comments | | ---------------- | ------------- | -------- | ---------------- | --------------------------------------------------------------------- | | date | Number/Array | Required | -- | 此参数为必传项，单个日期选择是时间戳，区间选择是时间戳数组； | | start | String, Number | optional | -- | 此参数可定义起始时间，可以传时间戳，也可以传字符串格式为'YYYY-MM-DD' | | end | String, Number | optional | -- | 此参数可定义起始时间，可以传时间戳，也可以传字符串格式为'YYYY-MM-DD' | | slot-icon | string | optional | date, prev, next | 默认都不传, 自定义图标时传date, 自定义前箭头时传prev, 自定义后箭头传next。 在选择时间范围的时候必须填写该项prev、next,slot为空，不显示左右箭头| | is-picker | Boolean | Required | true | true是原生时间选择器模式，false是页面级时间选择器模式 | | date-type-name | String | Required | day、month、year、days、week | 小写字符串，代表设置时间类型（年月日周切换）days为日期范围，无法切换 | | date-format | null | optional | 'CN' | 日期类型参数，支持（CN，EN，日期格式类型，对象类型）周的显示格式为固定的(2020年(05/04-05/10)) | | show-week | Boolean | optional | true | 是否显示周几 周不显示周几 | | callback-func | String | optional | dateChange | 用户可定义的日期变化的回调函数名称 | | date-types | String | optional | day_month_year | 日期包含的类型（仅isPicker=false生效）days代表该组件为日期范围选择组件 | | disabled-before-day | number | optional | -- | 此参数时间区域选择有用，当选择一个日期之后，第二个日期往前可选择多少天 | | disabled-after-day | number | optional | -- | 此参数时间区域选择有用，当选择一个日期之后，第二个日期往后可选择多少天 | |limit | object | optional | -- | 此参数里面可以给日周月年设置不同的start和end，如果设置该属性，则此类型下的start和end取该属性下 |

dateFormat 日期格式化使用详解

1. CN （组件默认参数）

当参数为CN时，时间格式为 YYYY年MM月DD日

2. EN

当参数为EN时，时间格式为 YYYY-MM-DD

3. 可以输入自定义时间格式

例如，当参数为YYYY-MM-DD 对应时间格式显示为 2019-05-31

4. 对象类型参数

例如, 参数格式为

{
    day: 'YYYY-MM-DD',
    month: 'YYYY年MM月',
    year: 'YY',
    days: 'MM-DD'
}

当dateTypeName为days时, 时间格式为 05-31 （只适用于时间范围选择，返回的时间显示为范围）;

当dateTypeName为week时，时间格式为 2020年(05/04-05/10)（该格式为固定的）

当dateTypeName为day时, 时间格式为 2019-05-31 ;

当dateTypeName为month时, 时间格式为 2019年05月 ;

当dateTypeName为year时, 时间格式为 19 ;

dateTypes 日期包含类型详解（只适用于is-Picker为false的时候，也就是页面级选择器）[默认day_month_year表示日、月、年都显示]

当参数为day时, 跳转过去只显示日(不能切换到月和年);

当参数为days时, 跳转过去只显示日(不能切换到月和年)(时间范围);

当参数为month_year时, 跳转过去只显示月和年(不能切换到日);

自定义样式

| Class Name | Comments | | -------------- | ---------------------------------- | | cm-arrow-space | 自定义左右箭头与中间字符串间的间隙 | | cm-icon-size | 自定义左右箭头与日历图标的大小 | | cm-font-style | 自定义组件全局字体大小和颜色 |

系统级别的样式

可直接通过路径 @import "miniprogram_npm/bs-ui-date/default.wxss"; 导入至app.wxss中使用

如果默认样式不符合UED需求，也可自行进行针对其中的样式进行重写

| Class Name | Comments | | -------------------------- | -------------------------- | | sys_bs-date_arrow_space | 与 cm-arrow-space 作用一致 | | sys_bs-date_icon_size | 与 cm-icon-size 作用一致 | | sys_bs-date_font_style | 与 cm-font-style 作用一致 |

样式定义说明

sys_bs-date_arrow_space 和 cm-arrow-space 定义的是中间字符串的左右margin

sys_bs-date_icon_size 和 cm-icon-size 定义的是图片的width和hight

回调函数

| Property | Required | Comments | | ----------------- | ---------- | ---------------------------------------------------- | | binddatechange | Required | 组件必备的回调函数（不配置此项组件会发生意想不到的后果） |