sard-uniapp 1.19.5 → 1.20.0

package/utils/date.d.ts

@@ -1,15 +1,58 @@
+/**
+ * 判断是否为闰年。
+ */
 export declare function isLeapYear(year: number): boolean;
-export declare function getMonthDays(year: number, month: number): number;
-export declare function getDaysInYear(date: Date): number;
-export declare function getWeekOfMonthStart(year: number, month: number): number;
-export declare function getDaysInDate(date: Date): number;
+/**
+ * 获取某月的天数，月份从0开始。
+ */
+export declare function getDaysInMonth(year: number, month: number): number;
+/**
+ * 获取当前日期是一年中的第几天。
+ */
+export declare function getDayOfYear(date: Date): number;
+/**
+ * 获取指定月份第一天是星期几，月份从0开始。
+ */
+export declare function getFirstDayWeekday(year: number, month: number): number;
+/**
+ * 获取从基准日期（如1970-01-01）到指定日期的总天数。
+ */
+export declare function getDaysSinceUnixEpoch(date: Date): number;
+/**
+ * 把日期转换为年月日数值，例如：2025年7月1号 -> 20250601。
+ */
 export declare function toDateNumber(date: Date): number;
+/**
+ * 把日期转换为年月日字符串，，例如：2025年7月1号 -> 2025-7-1。
+ */
 export declare function toDateString(date: Date): string;
+/**
+ * 把日期转换为年月数值，例如：2025年7月1号 -> 20250600。
+ */
 export declare function toMonthNumber(date: Date): number;
-export declare function getPadStartDays(year: number, month: number, amount: number): Date[];
-export declare function getPadEndDays(year: number, month: number, amount: number): Date[];
-export declare function getOffsetDaysFromMonthStart(weekOnMonthStart: number, weekStartsOn: number): number;
+/**
+ * 计算当前月份1号前面需要显示的上个月末尾的天数。
+ */
+export declare function getDaysBeforeFirstDay(year: number, month: number, weekStartsOn?: number): number;
+/**
+ * 获取当前月份最后一天之后需要显示的下个月开始的天数。
+ */
+export declare function getDaysAfterLastDay(year: number, month: number, weekStartsOn?: number): number;
+/**
+ * 获取当前月份1号之前需要显示的上个月末尾的日期。
+ */
+export declare function getPrevMonthTailDays(year: number, month: number, weekStartsOn?: number): Date[];
+/**
+ * 获取当前月份最后一天之后需要显示的下个月开始的日期。
+ */
+export declare function getNextMonthHeadDays(year: number, month: number, weekStartsOn?: number): Date[];
+/**
+ * 根据传入的占位符返回格式化后的日期。
+ */
 export declare function formatDate(date: Date, format?: string): string;
+/**
+ * 解析日期的字符串表示形式，并返回 Date 实例对象。
+ */
 export declare function parseDate(value: string, format?: string): Date;
 export declare function toDate(date: Date | string, valueFormat?: string): Date;
 export declare function minmaxDate(date: Date, minDate: Date, maxDate: Date): Date;
@@ -21,26 +64,56 @@ export declare function getNextMonthDate(date: Date): Date;
 export declare const lunarInfo: number[];
 export declare const springFestivals: number[][];
 export declare const baseLunarYear = 1900;
+/**
+ * 获取农历某年闰月的月份，月份从1开始（0表示无闰月）。
+ */
 export declare function getLunarLeapMonth(year: number): number;
-export declare function getLunarLeapMonthDays(year: number): 0 | 30 | 29;
+/**
+ * 获取农历某年闰月的天数。
+ */
+export declare function getLunarLeapMonthDays(year: number): number;
+/**
+ * 获取农历某年的总天数。
+ */
 export declare function getLunarYearDays(year: number): number;
-export declare function getLunarMonthDays(year: number, month: number): 30 | 29;
-export declare function solarToLunar(year: number, _month: number, date: number): {
+/**
+ * 获取农历某年某月的天数，月份从1开始。
+ */
+export declare function getLunarMonthDays(year: number, month: number): number;
+/**
+ * 公历转农历，月份从1开始（返回的闰月为负数）。
+ */
+export declare function solarToLunar(year: number, month: number, day: number): {
     year: number;
     month: number;
     day: number;
 };
-export declare function lunarToSolar(lunarYear: number, lunarMonth: number, lunarDay: number): {
+/**
+ * 农历转公历（闰月需传递负数）。
+ */
+export declare function lunarToSolar(year: number, month: number, day: number): {
     year: number;
     month: number;
     day: number;
 };
 export declare const lunarYearNames: string[];
+/**
+ * 将阿拉伯数字的年份转为汉字数字年份
+ */
 export declare function getLunarYearName(year: number): string;
 export declare const lunarMonthNames: string[];
+/**
+ * 获取农历月份名称，月份从1开始，例如：正月，十月，腊月。
+ */
 export declare function getLunarMonthName(month: number, isLeapMonth?: boolean): string;
 export declare const lunarDayNames: string[];
+/**
+ * 获取农历日期名称，例如：初一，十二，廿一。
+ */
 export declare function getLunarDayName(day: number): string;
 export declare const heavenlyStems: string[];
 export declare const earthlyBranches: string[];
+/**
+ * 获取农历时辰名称，例如：子初、子正、午初，午正。
+ */
 export declare function getLunarHourName(hour: number): string;

package/utils/date.js

@@ -1,70 +1,102 @@
+import { clamp } from './number';
 import { escapeRegExp } from './regexp';
-import { minmax } from './utils';
-// 判断是否为闰年
+/**
+ * 判断是否为闰年。
+ */
 export function isLeapYear(year) {
     return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
 }
 const monthDays = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
-// 获取某月的天数
-export function getMonthDays(year, month) {
-    if (month === 2) {
+/**
+ * 获取某月的天数，月份从0开始。
+ */
+export function getDaysInMonth(year, month) {
+    if (month === 1) {
         return isLeapYear(year) ? 29 : 28;
     }
     else {
-        return monthDays[month - 1];
+        return monthDays[month];
     }
 }
-// 获取当前日期是一年中的第几天
-export function getDaysInYear(date) {
+/**
+ * 获取当前日期是一年中的第几天。
+ */
+export function getDayOfYear(date) {
     const year = date.getFullYear();
     const month = date.getMonth();
     const d = date.getDate();
     let days = 0;
     for (let m = 0; m < month; m++) {
-        days += getMonthDays(year, m + 1);
+        days += getDaysInMonth(year, m);
     }
     return days + d;
 }
-// 获取某月一号对应是星期几
-export function getWeekOfMonthStart(year, month) {
-    return new Date(year, month - 1, 1).getDay();
+/**
+ * 获取指定月份第一天是星期几，月份从0开始。
+ */
+export function getFirstDayWeekday(year, month) {
+    return new Date(year, month, 1).getDay();
 }
-// 获取 Date 中的总天数
-export function getDaysInDate(date) {
+/**
+ * 获取从基准日期（如1970-01-01）到指定日期的总天数。
+ */
+export function getDaysSinceUnixEpoch(date) {
     return Math.floor(date.getTime() / 1000 / 60 / 60 / 24);
 }
-// 把日期转换为年月日数值
+/**
+ * 把日期转换为年月日数值，例如：2025年7月1号 -> 20250601。
+ */
 export function toDateNumber(date) {
     return date.getFullYear() * 10000 + date.getMonth() * 100 + date.getDate();
 }
-// 把日期转换为年月日字符串
+/**
+ * 把日期转换为年月日字符串，，例如：2025年7月1号 -> 2025-7-1。
+ */
 export function toDateString(date) {
     return date.getFullYear() + '-' + (date.getMonth() + 1) + '-' + date.getDate();
 }
-// 把日期转换为年月数值
+/**
+ * 把日期转换为年月数值，例如：2025年7月1号 -> 20250600。
+ */
 export function toMonthNumber(date) {
     return date.getFullYear() * 10000 + date.getMonth() * 100;
 }
-// 获取从开头开始填充的日期
-export function getPadStartDays(year, month, amount) {
+/**
+ * 计算当前月份1号前面需要显示的上个月末尾的天数。
+ */
+export function getDaysBeforeFirstDay(year, month, weekStartsOn = 0) {
+    const week = getFirstDayWeekday(year, month);
+    return (week - weekStartsOn + 7) % 7;
+}
+/**
+ * 获取当前月份最后一天之后需要显示的下个月开始的天数。
+ */
+export function getDaysAfterLastDay(year, month, weekStartsOn = 0) {
+    const daysBefore = getDaysBeforeFirstDay(year, month, weekStartsOn);
+    return 42 - daysBefore - getDaysInMonth(year, month);
+}
+/**
+ * 获取当前月份1号之前需要显示的上个月末尾的日期。
+ */
+export function getPrevMonthTailDays(year, month, weekStartsOn = 0) {
+    const daysBefore = getDaysBeforeFirstDay(year, month, weekStartsOn);
     const dates = [];
-    for (let i = amount - 1; i >= 0; i--) {
-        dates.push(new Date(year, month - 1, -i));
+    for (let i = daysBefore - 1; i >= 0; i--) {
+        dates.push(new Date(year, month, -i));
     }
     return dates;
 }
-// 获取从结尾开始填充的日期
-export function getPadEndDays(year, month, amount) {
+/**
+ * 获取当前月份最后一天之后需要显示的下个月开始的日期。
+ */
+export function getNextMonthHeadDays(year, month, weekStartsOn = 0) {
+    const daysAfter = getDaysAfterLastDay(year, month, weekStartsOn);
     const dates = [];
-    for (let i = 1; i <= amount; i++) {
-        dates.push(new Date(year, month + 1 - 1, i));
+    for (let i = 1; i <= daysAfter; i++) {
+        dates.push(new Date(year, month + 1, i));
     }
     return dates;
 }
-// 获取一号偏移的天数
-export function getOffsetDaysFromMonthStart(weekOnMonthStart, weekStartsOn) {
-    return (weekOnMonthStart - weekStartsOn + 7) % 7;
-}
 const dateTokensReg = /(YYYY|YY|MM|M|DD|D|HH|H|hh|h|mm|m|ss|s|SSS)/g;
 const dateGetters = {
     YYYY: (date) => String(date.getFullYear()).padStart(4, '0'),
@@ -83,7 +115,9 @@ const dateGetters = {
     s: (date) => String(date.getSeconds()),
     SSS: (date) => String(date.getMilliseconds()).padStart(3, '0'),
 };
-// 根据传入的占位符返回格式化后的日期
+/**
+ * 根据传入的占位符返回格式化后的日期。
+ */
 export function formatDate(date, format = 'YYYY-MM-DD HH:mm:ss') {
     return format.replace(dateTokensReg, (match) => {
         return dateGetters[match](date);
@@ -116,7 +150,9 @@ function parseDateWithoutFormat(value) {
     });
     return date;
 }
-// 解析日期的字符串表示形式，并返回 Date 实例对象
+/**
+ * 解析日期的字符串表示形式，并返回 Date 实例对象。
+ */
 export function parseDate(value, format) {
     if (!format) {
         return parseDateWithoutFormat(value);
@@ -139,22 +175,22 @@ export function parseDate(value, format) {
     });
     return date;
 }
-// 确保返回一个Date对象，如果传递字符串，则使用 parseDate 解析
+// 确保返回一个Date对象，如果传递字符串，则使用 parseDate 解析。
 export function toDate(date, valueFormat) {
     if (date instanceof Date) {
         return date;
     }
     return parseDate(date, valueFormat);
 }
-// 限定日期范围
+// 限定日期范围，会返回一个新的日期。
 export function minmaxDate(date, minDate, maxDate) {
-    return new Date(minmax(date.getTime(), minDate.getTime(), maxDate.getTime()));
+    return new Date(clamp(date.getTime(), minDate.getTime(), maxDate.getTime()));
 }
-// 获取上一个月的日期对象
+// 获取上一个月的日期对象。
 export function getPrevMonthDate(date) {
     return new Date(date.getFullYear(), date.getMonth() - 1, 1);
 }
-// 获取下一个月的日期对象
+// 获取下一个月的日期对象。
 export function getNextMonthDate(date) {
     return new Date(date.getFullYear(), date.getMonth() + 1, 1);
 }
@@ -211,18 +247,24 @@ export const springFestivals = [
     [2, 9], // 2100
 ];
 export const baseLunarYear = 1900;
-// 获取农历某年闰月的月份（0表示无闰月）
+/**
+ * 获取农历某年闰月的月份，月份从1开始（0表示无闰月）。
+ */
 export function getLunarLeapMonth(year) {
     return lunarInfo[year - baseLunarYear] & 0xf;
 }
-// 获取农历某年闰月的天数
+/**
+ * 获取农历某年闰月的天数。
+ */
 export function getLunarLeapMonthDays(year) {
     if (getLunarLeapMonth(year)) {
         return lunarInfo[year - baseLunarYear] & 0x10000 ? 30 : 29;
     }
     return 0;
 }
-// 获取农历某年的总天数
+/**
+ * 获取农历某年的总天数。
+ */
 export function getLunarYearDays(year) {
     let sum = 348; // 29天*12个月
     const info = lunarInfo[year - baseLunarYear];
@@ -233,14 +275,18 @@ export function getLunarYearDays(year) {
     // 加上闰月的天数
     return sum + getLunarLeapMonthDays(year);
 }
-// 获取农历某年某月的天数
+/**
+ * 获取农历某年某月的天数，月份从1开始。
+ */
 export function getLunarMonthDays(year, month) {
     return lunarInfo[year - baseLunarYear] & (0x10000 >> month) ? 30 : 29;
 }
-// 公历转农历
-export function solarToLunar(year, _month, date) {
+/**
+ * 公历转农历，月份从1开始（返回的闰月为负数）。
+ */
+export function solarToLunar(year, month, day) {
     // 计算输入日期与基准日期的天数差
-    const offsetDays = Math.floor((Date.UTC(year, _month - 1, date) - Date.UTC(baseLunarYear, 0, 31)) /
+    const offsetDays = Math.floor((Date.UTC(year, month - 1, day) - Date.UTC(baseLunarYear, 0, 31)) /
         (24 * 60 * 60 * 1000));
     // 农历年、月、日初始化
     let lunarYear = baseLunarYear;
@@ -260,25 +306,25 @@ export function solarToLunar(year, _month, date) {
     // 计算农历月和日
     const leapMonth = getLunarLeapMonth(lunarYear);
     let monthDays = 0;
-    let month = 1;
-    for (; month <= 12; month++) {
+    let _month = 1;
+    for (; _month <= 12; _month++) {
         // 处理闰月
-        if (leapMonth > 0 && month === leapMonth + 1) {
+        if (leapMonth > 0 && _month === leapMonth + 1) {
             monthDays = getLunarLeapMonthDays(lunarYear);
             if (daysRemaining < monthDays) {
                 isLeapMonth = true;
-                month--;
+                _month--;
                 break;
             }
             daysRemaining -= monthDays;
         }
-        monthDays = getLunarMonthDays(lunarYear, month);
+        monthDays = getLunarMonthDays(lunarYear, _month);
         if (daysRemaining < monthDays) {
             break;
         }
         daysRemaining -= monthDays;
     }
-    lunarMonth = month;
+    lunarMonth = _month;
     lunarDay = daysRemaining + 1;
     return {
         year: lunarYear,
@@ -286,24 +332,26 @@ export function solarToLunar(year, _month, date) {
         day: lunarDay,
     };
 }
-// 农历转公历（闰月需传递负数）
-export function lunarToSolar(lunarYear, lunarMonth, lunarDay) {
-    const springFestival = springFestivals[lunarYear - baseLunarYear];
-    const solarDate = new Date(lunarYear, springFestival[0] - 1, springFestival[1]);
-    const info = lunarInfo[lunarYear - baseLunarYear];
+/**
+ * 农历转公历（闰月需传递负数）。
+ */
+export function lunarToSolar(year, month, day) {
+    const springFestival = springFestivals[year - baseLunarYear];
+    const solarDate = new Date(year, springFestival[0] - 1, springFestival[1]);
+    const info = lunarInfo[year - baseLunarYear];
     const leapMonth = info & 0xf;
     let totalDays = 0;
-    const absMonth = Math.abs(lunarMonth);
+    const absMonth = Math.abs(month);
     for (let m = 1; m < absMonth; m++) {
         if (m === leapMonth) {
-            totalDays += getLunarLeapMonthDays(lunarYear);
+            totalDays += getLunarLeapMonthDays(year);
         }
-        totalDays += getLunarMonthDays(lunarYear, m);
+        totalDays += getLunarMonthDays(year, m);
     }
-    if (lunarMonth < 0) {
-        totalDays += getLunarMonthDays(lunarYear, absMonth);
+    if (month < 0) {
+        totalDays += getLunarMonthDays(year, absMonth);
     }
-    totalDays += lunarDay - 1;
+    totalDays += day - 1;
     solarDate.setDate(solarDate.getDate() + totalDays);
     return {
         year: solarDate.getFullYear(),
@@ -314,6 +362,9 @@ export function lunarToSolar(lunarYear, lunarMonth, lunarDay) {
 // 农历年份的名称
 // prettier-ignore
 export const lunarYearNames = ['零', '一', '二', '三', '四', '五', '六', '七', '八', '九', '十'];
+/**
+ * 将阿拉伯数字的年份转为汉字数字年份
+ */
 export function getLunarYearName(year) {
     return (String(year)
         .split('')
@@ -323,14 +374,18 @@ export function getLunarYearName(year) {
 // 农历月份的名称
 // prettier-ignore
 export const lunarMonthNames = ['正', '二', '三', '四', '五', '六', '七', '八', '九', '十', '冬', '腊'];
-// 获取农历月份名称
+/**
+ * 获取农历月份名称，月份从1开始，例如：正月，十月，腊月。
+ */
 export function getLunarMonthName(month, isLeapMonth) {
     return (isLeapMonth ? '闰' : '') + lunarMonthNames[month - 1] + '月';
 }
 // 农历日期的名称
 // prettier-ignore
 export const lunarDayNames = ['初一', '初二', '初三', '初四', '初五', '初六', '初七', '初八', '初九', '初十', '十一', '十二', '十三', '十四', '十五', '十六', '十七', '十八', '十九', '二十', '廿一', '廿二', '廿三', '廿四', '廿五', '廿六', '廿七', '廿八', '廿九', '三十'];
-// 获取农历日期名称
+/**
+ * 获取农历日期名称，例如：初一，十二，廿一。
+ */
 export function getLunarDayName(day) {
     return lunarDayNames[day - 1];
 }
@@ -340,7 +395,9 @@ export const heavenlyStems = ['甲', '乙', '丙', '丁', '戊', '己', '庚', '
 // 十二地支
 // prettier-ignore
 export const earthlyBranches = ['子', '丑', '寅', '卯', '辰', '巳', '午', '未', '申', '酉', '戌', '亥'];
-// 获取农历时辰名称
+/**
+ * 获取农历时辰名称，例如：子初、子正、午初，午正。
+ */
 export function getLunarHourName(hour) {
     const index = Math.floor(((hour === 23 ? 0 : hour) + 1) / 2) % 12;
     return earthlyBranches[index] + (hour % 2 === 1 ? '初' : '正');

package/utils/dom.js

@@ -58,6 +58,8 @@ export function toTouchEvent(event, windowTop = 0) {
             {
                 clientX: event.clientX,
                 clientY: event.clientY - windowTop,
+                pageY: event.pageY,
+                pageX: event.pageX,
             },
         ];
         event.changedTouches = touches;

package/utils/geometry.d.ts

@@ -1,9 +1,4 @@
 export type ScrollIntoViewPosition = 'start' | 'center' | 'end' | 'nearest';
-export interface ScrollIntoViewValueOptions {
-    position?: ScrollIntoViewPosition;
-    startOffset?: number;
-    endOffset?: number;
-}
 export interface ScrollIntoViewOptions {
     position?: ScrollIntoViewPosition;
     startOffset?: number;
@@ -11,36 +6,32 @@ export interface ScrollIntoViewOptions {
     duration?: number;
 }
 /**
-```
-                      page
-                     ╱
-    ╭───────────────╮    viewport
-  ╭─│─ ─ ─ ─ ─ ─ ─ ─│─╮ ╱
-  │ │ ╭───────────╮ │ │
-  │ │ │  element  │ │ │
-  │ │ ╰───────────╯ │ │
-  ╰─│─ ─ ─ ─ ─ ─ ─ ─│─╯
-    │               │
-    │               │
-    ╰───────────────╯
-```
-
-# 参数
-- viewportHeight: viewport 高度
-- viewportScrollTop: viewport 垂直滚动值
-- elementHeight: element 高度
-- elementOffsetTop: element 距离页面顶部距离
-
-# 选项
-- position: element 在视窗中的位置(start, center, end, nearest)
-- startOffset: element 距离视窗顶部的偏移量
-- endOffset: element 距离视窗底部的偏移量
-
-# 结果值
-- viewportScrollTop: viewport 新的垂直滚动值
-
-*/
-export declare function getScrollIntoViewValue(viewportHeight: number, viewportScrollTop: number, elementHeight: number, elementOffsetTop: number, options?: ScrollIntoViewValueOptions): number;
+ * 根据最后位置计算 page 滚动到顶部的值。
+ *
+ * 也可计算水平方向的滚动值。
+ *
+ *                      page
+ *                     ╱
+ *    ╭───────────────╮    viewport
+ *  ╭─│─ ─ ─ ─ ─ ─ ─ ─│─╮ ╱
+ *  │ │ ╭───────────╮ │ │
+ *  │ │ │  element  │ │ │
+ *  │ │ ╰───────────╯ │ │
+ *  ╰─│─ ─ ─ ─ ─ ─ ─ ─│─╯
+ *    │               │
+ *    │               │
+ *    ╰───────────────╯
+ *
+ * @param {number} viewportHeight viewport 高度
+ * @param {number} viewportScrollTop viewport 垂直滚动值
+ * @param {number} elementHeight element 高度
+ * @param {number} elementOffsetTop element 距离页面顶部距离
+ * @param {string} options.position element 在 viewport 中的位置，可选：'start' | 'center' | 'end' | 'nearest'
+ * @param {number} options.startOffset element 距离视窗顶部的偏移量
+ * @param {number} options.endOffset element 距离视窗底部的偏移量
+ * @return {number} viewport 新的垂直滚动值
+ */
+export declare function getScrollIntoViewValue(viewportHeight: number, viewportScrollTop: number, elementHeight: number, elementOffsetTop: number, options?: ScrollIntoViewOptions): number;
 export interface NodeRect {
     top: number;
     right: number;
@@ -49,19 +40,46 @@ export interface NodeRect {
     height: number;
     width: number;
 }
-interface MatchScrollVisibleOptions {
+export interface MatchScrollVisibleOptions {
     offset?: number;
     errorValue?: number;
 }
 /**
- * @description: 匹配元素列表中第一个位于滚动盒子可视区域的元素
+ * 匹配元素列表中第一个位于滚动盒子可视区域的元素
+ *
+ * @param {array} rects NodeRect 类型数组
+ * @param {function} callback 匹配成功时调用，会接收匹配的元素的下标
+ * @param {number} options.offset 偏移量
+ * @param {number} options.errorValue 容错值
  */
 export declare function matchScrollVisible(rects: NodeRect[], callback: (index: number) => unknown, options?: MatchScrollVisibleOptions): Promise<unknown>;
+/**
+ * 保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。
+ */
 export declare function getAspectFillSize(origWidth: number, origHeight: number, containerWidth: number, containerHeight: number): [number, number];
+/**
+ * 保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。
+ */
 export declare function getAspectFitSize(origWidth: number, origHeight: number, containerWidth: number, containerHeight: number): [number, number];
-interface Point {
+export interface Point {
     x: number;
     y: number;
 }
+/**
+ * 获取两点间的距离
+ */
 export declare function getTwoPointsDistance(p1: Point, p2: Point): number;
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * @description: 根据原始坐标尺寸和缩放后的坐标尺寸算出转换的原点
+ * @param {Rect} rect
+ * @param {Rect} scaleRect
+ * @return {[number, number]}
+ */
+export declare function getTransformOrigin(rect: Rect, scaleRect: Rect): [number, number];
 export {};