# bs-ui-date

[Base Readme](./base/README.md)
> 这个项目是从bs-ui-seed基础创建出来的. 请查看`base/README.md` 来了解其基础内容.

## 功能介绍

### 本组件主要是日期选择组件，它提供下面两种功能
- 基础的时间选择功能
- 用户可还可使用页面级时间选择（通过特定属性切换）

## 使用方法

### 特别说明（！！！重要）

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


1. 安装

```js
npm i bs-ui-date -s
```

2. json

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

```
3. wxml

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

```xml
<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引入组件全局样式

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

5. js

``` 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. 对象类型参数

#### 例如, 参数格式为

``` js
{
    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 	| 组件必备的回调函数（不配置此项组件会发生意想不到的后果） |