@gmcb/uv-ui 0.2.27 → 0.3.1

package/docs/components/calendar.md

@@ -0,0 +1,398 @@
+## Calendar 日历 <to-api/>
+
+<demo-model url="/pages/componentsB/calendar/calendar"></demo-model>
+
+::: tip ✈
+
+**组件名：uv-calendar**
+
+[点击下载&安装](https://ext.dcloud.net.cn/plugin?name=uv-calendar)
+
+:::
+
+此组件用于单个选择日期，范围选择日期等，日历被包裹在底部弹起的容器中。
+
+**注意：** 此组件与[Picker 选择器](/components/picker.html)的日期选择模式有一定的重合之处，区别在于本组件为更专业的日期选择场景，能选择日期范围等。
+另外`Picker`组件的日期模式可以配置更多的参数，如时、分、秒等，可以根据不同的使用场景进行选择。
+
+
+### 平台兼容性
+
+|App（vue）|App（nvue）|H5|小程序|VUE2|VUE3|
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|√|√|√|√|√|√|
+
+
+### 基本使用
+
+- 通过`ref`调用`open()`和`close()`控制日历的打开和关闭
+- 通过`mode`参数指定选择日期模式，包含单选 / 多选 / 范围选择。
+
+```vue
+<template>
+	<view>
+		<uv-calendar ref="calendar" @confirm="confirm"></uv-calendar>
+		<button @click="open">打开</button>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const calendar = ref(null);
+function open() {
+  calendar.value.open();
+}
+function confirm(e) {
+  console.log('日历选择：', e);
+}
+
+</script>
+```
+
+### 日历模式
+
+- `mode`为`single`只能选择单个日期
+- `mode`为`multiple`可以选择多个日期
+- `mode`为`range`可以选择日期范围
+
+### 单个日期模式
+
+选择日期后，需要点击底部的`确定`按钮才能触发回调事件，回调参数为一个数组，有如下属性：
+
+```js
+["2021-07-01"]
+```
+
+示例代码：
+
+```vue
+<template>
+	<view>
+		<uv-calendar ref="calendar" mode="single" @confirm="confirm"></uv-calendar>
+		<button @click="open">打开</button>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const calendar = ref(null);
+function open() {
+  calendar.value.open();
+}
+function confirm(e) {
+  console.log('日历选择：', e);
+}
+
+</script>
+```
+
+### 多个日期模式
+
+选择日期后，需要点击底部的`确定`按钮才能触发回调事件，回调参数为一个数组，有如下属性：
+
+```js
+ ["2021-07-27", "2021-07-29", "2021-07-30"]
+```
+
+示例代码：
+
+```vue
+<template>
+	<view>
+		<uv-calendar ref="calendar" mode="multiple" @confirm="confirm"></uv-calendar>
+		<button @click="open">打开</button>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const calendar = ref(null);
+function open() {
+  calendar.value.open();
+}
+function confirm(e) {
+  console.log('日历选择：', e);
+}
+
+</script>
+```
+
+### 日期范围模式
+
+此模式用于选择一个日期范围，比如住酒店的入住到离店的日期范围，
+
+
+此模式的返回参数如下：
+
+```js
+["2021-07-27", "2021-07-28", "2021-07-29", "2021-07-30", "2021-07-31"]
+```
+
+示例代码：
+
+```vue
+<template>
+	<view>
+		<uv-calendar ref="calendar" mode="range" @confirm="confirm"></uv-calendar>
+		<button @click="open">打开</button>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const calendar = ref(null);
+function open() {
+  calendar.value.open();
+}
+function confirm(e) {
+  console.log('日历选择：', e);
+}
+
+</script>
+```
+
+### 自定义主题颜色
+
+组件可传入`color`参数，更改组件主题色
+
+示例代码：
+
+```vue
+<template>
+	<view>
+		<uv-calendar ref="calendar" mode="range" color="#f56c6c" @confirm="confirm"></uv-calendar>
+		<button @click="open">打开</button>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const calendar = ref(null);
+function open() {
+  calendar.value.open();
+}
+function confirm(e) {
+  console.log('日历选择：', e);
+}
+
+</script>
+```
+
+### 自定义文案
+
+- 组件可以通过`formatter`以函数的方式定义日期文案
+
+- 可以通过`setFormatter`返回的`day`参数，进行当天的日期参数设置，比如设置日期下方提示`bottomInfo`，禁止点击`disabled`等，具体根据`day`返回的值进行配置，如下示例：
+
+```
+	day: {
+		bottomInfo: "打8折",
+		date: Sat Jul 22 2023 08:00:00 GMT+0800 (中国标准时间) {},
+		day: 22,
+		disabled: true,
+		dot: true,
+		month: 7,
+		topInfo: "",
+		week: 6
+	}
+```
+
+:::warning 注意：
+注意在页面的`onReady`生命周期获取`ref`再操作。
+:::
+
+```vue
+<template>
+	<view>
+		<uv-calendar
+			ref="calendar"
+			mode="range"
+			startText="住店"
+			endText="离店"
+			confirmDisabledText="请选择离店日期"
+		></uv-calendar>
+		<button @click="open">打开</button>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+import { onReady } from '@dcloudio/uni-app';
+
+const calendar = ref(null);
+onReady(() => {
+  calendar.value.setFormatter(formatter);
+});
+function open() {
+  calendar.value.open();
+}
+function confirm(e) {
+  console.log('日历选择：', e);
+}
+function formatter(day) {
+  const d = new Date();
+  let month = d.getMonth() + 1;
+  const date = d.getDate();
+  if (day.month == month && day.day == date + 3) {
+    day.bottomInfo = '打8折';
+    day.dot = true;
+    day.disabled = true;
+    console.log(day);
+  }
+  return day;
+}
+
+</script>
+```
+
+### 日期最大范围
+
+组件可以通过`maxDate`定义日期文案
+
+```vue
+<template>
+	<view>
+		<uv-calendar ref="calendar" :maxDate="maxDate" @confirm="confirm"></uv-calendar>
+		<button @click="open">打开</button>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const d = new Date();
+const year = d.getFullYear();
+let month = d.getMonth() + 1;
+month = month < 10 ? `0${month}` : month;
+const date = d.getDate();
+const calendar = ref(null);
+const maxDate = ref(`${year}-${month}-${date + 10}`);
+function open() {
+  calendar.value.open();
+}
+function confirm(e) {
+  console.log('日历选择：', e);
+}
+
+</script>
+```
+
+### 是否显示农历
+
+组件可以通过`showLunar`定义是否显示农历
+
+```vue
+<template>
+	<view>
+		<uv-calendar ref="calendar" showLunar @confirm="confirm"></uv-calendar>
+		<button @click="open">打开</button>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const calendar = ref(null);
+function open() {
+  calendar.value.open();
+}
+function confirm(e) {
+  console.log('日历选择：', e);
+}
+
+</script>
+
+```
+### 默认日期
+
+组件可以通过`defaultDate`定义默认日期
+
+```vue
+<template>
+	<view>
+		<uv-calendar ref="calendar" mode="multiple" :defaultDate="defaultDateMultiple" @confirm="confirm"></uv-calendar>
+		<button @click="open">打开</button>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const d = new Date();
+const year = d.getFullYear();
+let month = d.getMonth() + 1;
+month = month < 10 ? `0${month}` : month;
+const date = d.getDate();
+const calendar = ref(null);
+const defaultDateMultiple = ref([`${year}-${month}-${date}`, `${year}-${month}-${date + 1}`, `${year}-${month}-${date + 2}`]);
+function open() {
+  calendar.value.open();
+}
+function confirm(e) {
+  console.log('日历选择：', e);
+}
+
+</script>
+```
+
+### 完整示例
+
+::: tip 完整示例下载地址
+
+[https://ext.dcloud.net.cn/plugin?name=uv-ui](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+:::
+
+### API
+---
+
+### Calendar Props
+
+| 参数					| 说明												| 类型								| 默认值		| 可选值											|
+| :-					| :-												| :-								| :-		| :-											|
+| title					| 标题内容											| String							| 日期选择	| -												|
+| showTitle				| 是否显示标题										| Boolean							| true		| true &#124; false											|
+| showSubtitle			| 是否显示副标题										| Boolean							| true		| true &#124; false											|
+| mode					| 日期类型选择										| String							| single	| multiple-可以选择多个日期，range-选择日期范围（多个月需配合`monthNum`属性使用）		|
+| startText				| mode=range时，第一个日期底部的提示文字				| String							| 开始		| -												|
+| endText				| mode=range时，最后一个日期底部的提示文字				| String							| 结束		| -												|
+| customList			| 自定义列表											| Array								| []		|  []											|
+| color					| 主题色，对底部按钮和选中日期有效						| String							| #3c9cff	| -												|
+| minDate				| 最小的可选日期										| Number &#124; String				| 0			| -												|
+| maxDate				| 最大可选日期										| Number &#124; String				| 0			| -												|
+| defaultDate			| 默认选中的日期，mode为multiple或range是必须为数组格式	| Array &#124; String &#124; Date	| null		| -												|
+| maxCount				| mode=multiple时，最多可选多少个日期					| Number &#124; String				| Number.MAX_SAFE_INTEGER	| -								|
+| rowHeight				| 日期行高											| Number &#124;String				| 56		| -												|
+| showLunar				| 是否显示农历										| Boolean							| false		| true	&#124; false									|
+| showMark				| 是否显示月份背景色									| Boolean							| true		| true &#124; false											|
+| confirmText			| 确定按钮的文字										| String							| 确定		| -												|
+| confirmDisabledText	| 确认按钮处于禁用状态时的文字							| String							| 确定		| -												|
+| closeOnClickOverlay	| 是否允许点击遮罩关闭日历	（注意：关闭事件需要自行处理，只会在开启closeOnClickOverlay后点击遮罩层执行close回调）	| Boolean							| false		| true	&#124; false										|
+| closeOnClickConfirm | 是否允许点击确认按钮关闭日历，设置为`false`不影响`confirm`事件返回 | Boolean | true | true	&#124; false |
+| readonly	            | 是否为只读状态，只读状态下禁止选择日期								| Boolean							| false		| true	&#124;  false										|
+| maxRange	            | 日期区间最多可选天数，默认无限制，mode = range时有效				    | Number &#124; String				| 无限制		| -											|
+| rangePrompt	        | 范围选择超过最多可选天数时的提示文案，mode = range时有效				| String &#124; null				| 	选择天数不能超过 xx 天	| -											|
+| showRangePrompt	    | 范围选择超过最多可选天数时，是否展示提示文案，mode = range时有效								| Boolean							| true		| true &#124; false											|
+| allowSameDay	        | 是否允许日期范围的起止时间为同一天，mode = range时有效								| Boolean							| false		| true &#124; false											|
+| round					| 圆角值，默认无圆角																					| String &#124; Number			| 0	| -							|
+| monthNum		 | 最大展示的月份数量																					| String &#124; Number			| 3	| -							|
+
+### Calendar Methods
+| 方法名								| 说明					| 
+| :-								| :-					|
+| open	| 弹出日历组件	 | -| 
+| close	| 关闭日历组件，可能在`:confirmClosePopup = "false"`用到	 | -| 
+| setFormatter	| 日期格式化函数，使用方法及参数配置请参考[自定义文案](/components/calendar.html#%E8%87%AA%E5%AE%9A%E4%B9%89%E6%96%87%E6%A1%88) |
+
+### Calendar Events
+
+| 事件名		| 说明					| 回调参数					|
+| :-		| :-					| :-						|
+| @confirm	| 日期选择完成后触发，若`show-confirm`为`true`，则点击确认按钮后触发	| 选择日期相关的返回参数		|
+| @close		| 日历关闭时触发			| 可定义页面关闭时的回调事件	|
+| @change		| 点击日期触发			| {day:'点击的日期',selected:'选中的日期'}	|
+
+<style scoped>
+h3[id=calendar-methods] + table thead tr th:nth-child(2){
+	width: 70%;
+}
+h3[id=calendar-events] + table thead tr th:nth-child(2){
+	width: 50%;
+}
+</style>

package/docs/components/calendars.md

@@ -0,0 +1,294 @@
+## Calendars 新版日历（推荐） <to-api/>
+
+<demo-model url="/pages/componentsB/calendars/calendars"></demo-model>
+
+::: tip ✈
+
+**组件名：uv-calendars**
+
+[点击下载&安装](https://ext.dcloud.net.cn/plugin?name=uv-calendars)
+
+:::
+
+为了解决老版本`uv-calendar`性能问题，特别是对日期选择范围有很大限制，体验不友好等缺点。于是有了新版日历组件。
+
+新版本`uv-calendars`，不仅拥有老版本的所有功能，还增加了更加适用的插入页面等强大功能，且更加简洁。查看日期、选择单个或多个或任意范围日期，打点操作，自定义文案，自定义主题等强大功能。
+
+常用场景：酒店日期预订、火车机票选择购买日期、上下班打卡等。
+
+### 平台兼容性
+
+|App（vue）|App（nvue）|H5|小程序|VUE2|VUE3|
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|√|√|√|√|√|√|
+
+:::warning 注意事项
+
+> 为了避免错误使用，给大家带来不好的开发体验，请在使用组件前仔细阅读下面的注意事项，可以帮你避免一些错误。
+1. 本组件农历转换使用的js是 [@1900-2100区间内的公历、农历互转](https://github.com/jjonline/calendar.js)
+2. `date`属性传入的应该是一个 String ，如： 2023-08-03 ，而不是 new Date()
+3. 通过 `insert` 属性来确定当前的事件是 @change 还是 @confirm 。理应合并为一个事件，但是为了区分模式，现使用两个事件，这里需要注意
+4. 弹窗模式下无法阻止后面的元素滚动，如有需要阻止，请在弹窗弹出后，手动设置滚动元素为不可滚动，参考[uv-popup等组件怎么禁止滚动穿透
+](https://www.uvui.cn/components/problem.html#%E5%9B%9B%E3%80%81uv-popup%E7%AD%89%E7%BB%84%E4%BB%B6%E6%80%8E%E4%B9%88%E7%A6%81%E6%AD%A2%E6%BB%9A%E5%8A%A8%E7%A9%BF%E9%80%8F)
+:::
+
+### 基本使用
+
+通过 `ref` 调用 `open()` 方法打开日历
+
+```vue
+<template>
+	<view>
+		<uv-calendars ref="calendars" @confirm="confirm" />
+		<button @click="open">打开日历</button>
+	</view>
+</template>
+<script setup>
+import { ref } from "vue";
+const calendars = ref(null);
+function open() {
+  calendars.value.open();
+}
+function confirm(e) {
+  console.log(e);
+}
+
+</script>
+```
+
+### 插入模式
+
+通过设置 `insert` 属性为 `true`
+
+```vue
+<template>
+	<view>
+		<uv-calendars insert @change="change" />
+	</view>
+</template>
+<script setup>
+function change(e) {
+  console.log(e);
+}
+
+</script>
+```
+
+### 多个日期模式
+
+- 通过设置 `mode` 属性为 `multiple`
+- 该模式的默认值可通过 `date` 设置，eg：`['2023-08-26','2023-08-27','2023-08-28']`
+
+```vue
+<template>
+	<view>
+		<uv-calendars ref="calendars" mode="multiple" @confirm="confirm" />
+		<button @click="open">打开日历</button>
+	</view>
+</template>
+<script setup>
+import { ref } from "vue";
+const calendars = ref(null);
+function open() {
+  calendars.value.open();
+}
+function confirm(e) {
+  console.log(e);
+}
+
+</script>
+
+```
+
+### 日期范围模式
+
+- 通过设置 `mode` 属性为 `range`
+- 该模式的默认值可通过 `date` 设置，eg：`['2023-08-26','2023-08-29']`
+
+```vue
+<template>
+	<view>
+		<uv-calendars ref="calendars" mode="range" @confirm="confirm" />
+		<button @click="open">打开日历</button>
+	</view>
+</template>
+<script setup>
+import { ref } from "vue";
+const calendars = ref(null);
+function open() {
+  calendars.value.open();
+}
+function confirm(e) {
+  console.log(e);
+}
+
+</script>
+
+```
+
+### 自定义主题颜色
+
+通过设置 `color` 属性，更改组件主题色，该值建议传16进制颜色值，如：`#ff0000`。
+
+```vue
+<template>
+	<view>
+		<uv-calendars 
+			ref="calendars" 
+			mode="range" 
+			color="#ff0000" 
+			:date="['2023-08-08','2023-08-27']" 
+			@confirm="confirm" />
+		<button @click="open">打开日历</button>
+	</view>
+</template>
+<script setup>
+import { ref } from "vue";
+const calendars = ref(null);
+function open() {
+  calendars.value.open();
+}
+function confirm(e) {
+  console.log(e);
+}
+
+</script>
+
+```
+
+### 自定义文案
+
+通过设置 `selected` 属性，该属性是一个json数组，具体参数参考[selected-options](/components/calendars.html#selected-options)。
+
+```vue
+<template>
+	<view>
+		<uv-calendars 
+			ref="calendars" 
+			mode="range"
+			title="选择日期"
+			start-text="住店"
+			end-text="离店"
+			:selected="selected"
+			@confirm="confirm" 
+		/>
+		<button @click="open">打开日历</button>
+	</view>
+</template>
+<script setup>
+import { ref } from "vue";
+const selected = ref([{
+  date: `${year}-${month}-02`,
+  info: '签到',
+  badge: true,
+  infoColor: '#ff0000'
+}, {
+  date: `${year}-${month}-06`,
+  info: '余10',
+  infoColor: '#19be6b',
+  topinfo: '￥100',
+  topinfoColor: '#19be6b'
+}]);
+const calendars = ref(null);
+function open() {
+  calendars.value.open();
+}
+function confirm(e) {
+  console.log(e);
+}
+
+</script>
+```
+
+### 完整示例
+
+::: tip 完整示例下载地址
+
+[https://ext.dcloud.net.cn/plugin?name=uv-ui](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+:::
+
+### API
+---
+
+### Calendars Props
+
+| 参数 | 类型 | 默认值 | 说明 |
+|:-|:-|:-|:-|
+| date | String | 今天 | 自定义默认选中日期，不传默认为今天。mode="multiple"或mode="range"时，该值为数组，例 `['2023-08-26','2023-08-29']`。mode不传或字符串，例如`2023-08-26`，即为单日期模式 |
+| lunar | Boolean | false | 显示农历 | 
+| mode `1.0.7` | String | - | 日期类型选择，可选值：不填 &#124; multiple &#124; range，分别为单日期选择，多日期选择，范围选择 | 
+| insert | Boolean | false | 插入模式,可选值，ture：插入模式；false：弹窗模式；默认为插入模式 | 
+| clearDate | Boolean | true | 弹窗模式是否清空上次选择内容 | 
+| selected | Array | - | 打点，期待格式[{date: '2019-06-27', info: '签到', disable: false}]，更多设置参考[自定义文案](/components/calendars.html#自定义文案)，更多参数参考[Selected Options](/components/calendars.html#selected-options) | 
+| startDate | String | - | 限制日期选择范围-开始日期，格式如："2023-01-01"，禁用该日期之前的日期 | 
+| endDate | String | - | 限制日期选择范围-结束日期，格式如："2023-02-01"，禁用该日期之后的日期 | 
+| showMonth | Boolean | true | 是否显示月份为背景 | 
+| round | String&#124;Number | 8px | 弹窗模式，圆角 |
+| color | String | #3c9cff | 主题颜色，建议16进制颜色（如：`#ff0000`），否则range模式下区间颜色会显示异常 |
+| confirmColor | String | #3c9cff | 确认按钮颜色 |
+| cancelColor | String | #909193 | 取消按钮颜色 |
+| closeOnClickOverlay | Boolean | true | 点击遮罩是否关闭弹窗 |
+| startText | String | 开始 | range为true时，第一个日期底部的提示文字 |
+| endText | String | 结束 | range为true时，最后一个日期底部的提示文字 |
+| allowSameDay `1.0.11`| Boolean | false | 是否允许日期范围的起止时间为同一天，mode = range时有效 |
+| readonly `1.0.15` | Boolean | false | 是否为只读状态，只读状态下禁止选择日期 |
+
+#### Selected Options
+
+示例参考[自定义文案](/components/calendars.html#自定义文案)
+
+| 属性名 | 说明 |
+|:-|:-|
+| date | 日期，格式：YYYY-mm-dd | 
+| info | 底部文案 |
+| infoColor | 底部文案颜色 |
+| topinfo | 头部文案 |
+| topinfoColor | 头部文案颜色 |
+| badge | 是否显示右上角红点 |
+| disable | 是否禁止点击该日期 |
+
+### Calendars Methods
+| 方法名 | 说明 | 
+| :- | :- |
+| open	| `insert` 为 `false` 时，调用此方法弹出日历组件	 | 
+
+### Calendars Events
+
+| 事件名 | 说明 | 返回参数 |
+| :- | :- | :- |
+| @confirm	| 点击确定按钮触发 | 返回日期相关参数，fulldate - 单日期；multiple - 多日期；range - 范围选择；其他相关参数		|
+| @close | 关闭日历时触发 |  -	|
+| @change | 点击日期时触发 | 返回日期相关参数，fulldate - 单日期；multiple - 多日期；range - 范围选择；其他相关参数；insert为true时生效 |
+| @monthSwitch | 选择年月确认时触发 | `{ year: 2030, month: '08' }` |
+
+:::warning 注意
+示例依赖了 `uv-popup` `uv-toolbar` `uv-ui` 等多个组件，直接拷贝示例代码将无法正常运行。
+请到 [组件下载页面](https://ext.dcloud.net.cn/plugin?name=uv-calendars) ，在页面右侧选择 使用 `HBuilderX导入示例项目` 。
+:::
+
+<style scoped>
+h3[id=calendars-props] + table thead tr th:nth-child(1),
+h3[id=calendars-props] + table thead tr th:nth-child(2),
+h3[id=calendars-props] + table thead tr th:nth-child(3)
+{
+	width: 18%;
+}
+h3[id=calendars-methods] + table thead tr th:nth-child(2)
+{
+	width: 70%;
+}
+h3[id=calendars-events] + table thead tr th:nth-child(2),
+h3[id=calendars-events] + table thead tr th:nth-child(3)
+{
+	width: 40%;
+}
+h4[id=selected-options] + p + table {
+	width: 50%;
+}
+h4[id=selected-options] + p + table thead tr th:nth-child(1),
+h4[id=selected-options] + p + table thead tr th:nth-child(2)
+{
+	width: 50%;
+}
+</style>