wx calendar
v1.8.0
微信小程式日曆
· 年月周日程视图 · 支持skyline和webview渲染 · 支持插件扩展
小程式基礎庫SDKVersion >= 3.0.0
npm i @lspriv/wx-calendar -S微信小程式開發工具功能表列：工具-->构建npm官方文檔
在頁面或全域設定檔中配置
{
"usingComponents" : {
"calendar" : " @lspriv/wx-calendar "
}
}在頁面wxml檔案中使用
< calendar id =" calendar " bindload =" handleLoad " /> const { WxCalendar } = require ( '@lspriv/wx-calendar/lib' ) ;
const { LunarPlugin } = require ( '@lspriv/wc-plugin-lunar' ) ;
// 使用农历插件
WxCalendar . use ( LunarPlugin ) ;
Page ( {
handleLoad ( detail ) {
conosle . log ( 'calendar load' , detail ) ;
}
} ) Important
請在bindload 事件後執行selectComponent('#calendar') 操作。
alpha分支是我的工作分支也是進度最新的分支，issue/*分支是解決issue裡提到的問題，develop分支相當SIT，發pr到master打tag，拉取哪個分支自行考慮
npm install
# 启动，默认skyline配置
npm run dev
# 设置webview
# npm run dev @webview 或者 npm run dev @W npm run buildnpm run packageNote
這個發包指令執行了打包、發包和推送倉庫三部分，所以不必重複執行打包指令
測驗尚未寫完，等我抽空就寫?
需要開啟以下選項，開發工具右上角-> 詳情-> 本機設置
pages.json的globalStyle中配置usingComponents {
"globalStyle" : {
"wx-calendar" : " /components/wx-calendar "
}
}注意事項請參考UniApp小程式自訂元件支持
參考Taro 使用原生模块
Note
如果在Taro 專案中引用了小程式原生的元件，那麼該專案將不再具備多端轉換的能力。
以下出現的類型定義：
type CalendarDay = {
year : number ; // 年
month : number ; // 月
day : number ; // 日
} ;以下所有屬性都是可選填屬性
| 屬性 | 類型 | 說明 | 預設值 |
|---|---|---|---|
| view | string | 視圖 | month [week|schedule] |
| marks | array | 日程、角標和假日標記 | [] |
| vibrate | boolean | 點選日期是否震動 | true |
| darkmode | boolean | 深色模式（跟隨系統） | true |
| date | string|number | 選取日期 | xxxx-xx-xx|timestamp |
| weekstart | number | 週首日，0|1|2|3|4|5|6 | 0 |
| style | string | 設定主題樣式變數 | '' |
| font | string | 設定字體 | '' |
| areas | array | 自訂佈局區域 | ['header', 'title', 'subinfo', 'today', 'viewbar', 'dragbar'] |
| viewGesture | boolean | 是否滑動手勢控制視圖 | true |
| sameChecked | boolean | 保持選取日期樣式一致 | false |
| customNavBar | boolean | 元件所在頁面是否自訂導覽列 | true |
| alignDate | string | 日期排布（居中｜基線對齊） | center [center|baseline] |
| showRest | boolean | 非本月日期是否顯示 | true |
Tip
1.7.0+版本已經移除了固定視圖屬性，新增手勢控制屬性viewGesture ，用以下方式實現固定視圖，有更高的自由度
固定視圖的新方式
<!-- 固定为周视图 -->
<!-- view 默认初始视图 -->
<!-- view-gesture 取消手势控制 -->
<!-- areas 只保留四个区域，将viewbar和dragbar移除 -->
< calendar
view =" week "
view-gesture =" {{ false }} "
areas =" {{ ['header', 'title', 'subinfo', 'today'] }} "
/> Tip
關於屬性marks
// 标记里的日期，要么输入年月日year｜month｜day，要么输入日期 date
type Mark = {
year ?: number ; // 年
month ?: number ; // 月
day ?: number ; // 日
date ?: string | number | Date ; // 日期 yyyy-mm-dd | timestamp | Date
type : 'schedule' | 'corner' | 'festival' | 'solar' ; // 日程｜角标｜节假日 | 日期文字
text : string ; // 内容
style ?: string | Record < string , string | number > ; // 标记样式
}
// 样式标记
type StyleMark = {
year ?: number ; // 年
month ?: number ; // 月
day ?: number ; // 日
date ?: string | number | Date ; // 日期 yyyy-mm-dd | timestamp |
style : string | Record < string , string | number > ;
}角標內容最好一個字元長度，只對一個字元校正了位置，多出的請自行調整位置
Important
如果組件所在頁面未開啟自訂導覽列，請設定屬性customNavBar為false
bindload日曆載入完成
type LoadEventDetail = {
checked : CalenderDay ; // 当前选择日期
view : 'week' | 'month' | 'schedule' ; // 当前视图
range : [ start : CalenderDay , end : CalenderDay ] ; // 当前渲染的月份范围
}取得組件實例
< calendar id =" calendar " bindload =" handleLoad " /> import { CalendarExport } from '@lspriv/wx-calendar/lib' ;
Page ( {
handleLoad ( ) {
const calendar = this . selectComponent ( '#calendar' ) as CalendarExport ;
// 如果你使用了其他插件，比如 WxCalendar.use(AnyPlugin)，则可以
// const calendar = ... as CalendarExport<[typeof AnyPlugin]>;
}
} ) ; bindclick日期點擊
type LoadEventDetail = {
checked : CalenderDay ; // 当前点击日期
view : 'week' | 'month' | 'schedule' ; // 当前视图
} Note
日期點選事件，若有必要請自行防手震處理
bindchange日期選取變化
type ChangeEventDetail = {
checked : CalenderDay ; // 当前选择日期
view : 'week' | 'month' | 'schedule' ; // 当前视图
range : [ start : CalenderDay , end : CalenderDay ] ; // 当前渲染的月份范围
} bindviewchange面板視圖變化
type ViewChangeEventDetail = {
checked : CalenderDay ; // 当前选择日期
view : 'week' | 'month' | 'schedule' ; // 当前视图
} bindschedule點擊日程觸發
type ScheduleEventDetail = {
schedules ?: Array < ScheduleEventDetail > ; // 所有日程
schedule ?: ScheduleEventDetail ; // 当前点击日程
all : boolean ; // 是否所有日程
}checked選取日期
{
/**
* @param date 选中日期
* yyyy-mm-dd | timestamp | Date | CalendarDay
*/
( date : string | number | Date | CalendarDay ) : Promise < void > ;
} toggleView切換視圖
{
/**
* @param [view] 要切换的视图
* 当view未指定时，会在周月视图之间切换
*/
( view ?: 'month' | 'week' | 'schedule' ) : void ;
} openAnuual開啟年度面板
{
( ) : Promise < void > ;
} getMarks取得完整的日期標記
{
/**
* @param date 获取日期
*/
( date : CalendarDay ) : PluginEntireMarks ;
} getPlugin取得插件實例
{
/**
* @param key 插件的KEY
*/
( key : string ) : InstanceType < PluginConstructor > ;
} updateDates更新日期數據
{
/**
* 若不指定哪些日期更新，默认刷新全部
*/
( dates ?: Array < CalendarDay > ) : Promise < void > ;
}元件開啟了樣式隔離，僅可調整字體大小和色號，可透過傳入style屬性修改以下css變數調整主題
. wcc {
/* 浅色主题 */
--wc-bg-light : # FFF ; /* 主背景色 */
--wc-title-color-light : # 333 ; /* 左上角日期标题 */
--wc-title-sub-color-light : # 7A7A7A ; /* 左上角日期标题的右侧描述 */
--wc-opt-bg-light : # D9ECFF ; /* 视图控制背景色 */
--wc-opt-checked-bg-light : # 409EFF ; /* 视图控制按钮背景色 */
--wc-opt-color-light : # 409EFF ; /* 视图控制字体 */
--wc-opt-checked-color-light : # FFF ; /* 视图控制选中字体 */
--wc-week-color-light : # ABABAB ; /* 星期 */
--wc-date-color-light : # 333 ; /* 日期 */
--wc-mark-color-light : # ABABAB ; /* 日期下方信息 */
--wc-dot-color-light : # ABABAB ; /* 日期上方‘･’ */
--wc-schedule-color-light : # 409EFF ; /* 日程默认 */
--wc-schedule-bg-light : # EAEEF2 ; /* 日程默认背景 */
--wc-today-color-light : # 409EFF ; /* 日期（今日） */
--wc-solar-color-light : # 409EFF ; /* 日期下方信息默认（节气，节假日） */
--wc-checked-color-light : # 333 ; /* 被选日期 */
--wc-checked-mark-color-light : # ABABAB ; /* 被选日期下方信息 */
--wc-checked-dot-color-light : # ABABAB ; /* 被选日期上方‘･’ */
--wc-checked-today-color-light : # FFF ; /* 被选日期（今日） */
--wc-checked-bg-light : # F5F5F5 ; /* 被选日期背景圆圈 */
--wc-checked-today-bg-light : # 409EFF ; /* 被选日期背景圆圈（今日） */
--wc-control-bg-light : # DFDFDF ; /* 底部控制条背景 */
--wc-annual-bg-light : # FFF ; /* 年面板背景 */
--wc-annual-title-color-light : # 333 ; /* 年面板左上角标题 */
--wc-annual-title-sub-color-light : # 7A7A7A ; /* 年面板左上角标题右侧信息 */
/* 深色主题，以下和浅色主题一一对应 */
--wc-bg-dark : # 000 ;
--wc-title-color-dark : # E5E5E5 ;
--wc-title-sub-color-dark : # 7A7A7A ;
--wc-opt-bg-dark : # 332D2D80 ;
--wc-opt-checked-bg-dark : # 409EFF ;
--wc-opt-color-dark : # 409EFF ;
--wc-opt-checked-color-dark : # FFF ;
--wc-week-color-dark : # ABABAB ;
--wc-date-color-dark : # E5E5E5 ;
--wc-mark-color-dark : # 5F5F5F ;
--wc-dot-color-dark : # ABABAB ;
--wc-schedule-color-dark : # 66B1FF ;
--wc-schedule-bg-dark : # 332D2D80 ;
--wc-today-color-dark : # 409EFF ;
--wc-solar-color-dark : # 409EFF ;
--wc-checked-color-dark : # E5E5E5 ;
--wc-checked-mark-color-dark : # 5F5F5F ;
--wc-checked-dot-color-dark : # ABABAB ;
--wc-checked-today-color-dark : # E5E5E5 ;
--wc-checked-bg-dark : # 262626 ;
--wc-checked-today-bg-dark : # 409EFF ;
--wc-control-bg-dark : # 262626 ;
--wc-annual-bg-dark : # 000 ;
--wc-annual-title-color-dark : # E5E5E5 ;
--wc-annual-title-sub-color-dark : # 3F3F3F ;
/** 字号 */
--wc-title-size : 46 rpx ; /** 左上角日期标题字号 */
--wc-title-sub-size : 20 rpx ; /** 左上角日期标题右侧描述信息字号 */
--wc-operator-size : 22 rpx ; /** 视图控制按钮字号 */
--wc-week-size : 20 rpx ; /** 星期字号 */
--wc-date-size : 36 rpx ; /** 日期字体字号 */
--wc-mark-size : 20 rpx ; /** 日期下方信息字体字号 */
--wc-corner-size : 16 rpx ; /** 日期角标字体字号 */
--wc-schedule-size : 16 rpx ; /** 日程字体字号 */
--wc-annual-title-size : 50 rpx ; /** 年面板左上角年份标题字体字号 */
--wc-annual-title-sub-size : 18 rpx ; /** 年面板左上角年份标题右侧信息字体字号 */
}修改樣式
< calendar style =" --wc-bg-light: #000; " />由於小程式建構npm的特殊性，本元件又是非純js函式庫，為了得到正確的型別提示，需要在小程式根目錄的jsconfig.json或是tsconfig.json檔案中指明路徑。
{
"compilerOptions" : {
"paths" : {
"@lspriv/wx-calendar/*" : [
" ./node_modules/@lspriv/wx-calendar/dist/* "
]
}
}
} const { WxCalendar } = require ( '@lspriv/wx-calendar/lib' ) ;
const { YourPlugin } = require ( 'anywhere' ) ;
// WxCalendar.clearPlugin(); 清理预设插件
WxCalendar . use ( YourPlugin , options ) ; // options 插件选项
Component ( {
...
} ) import { Plugin } from '@lspriv/wx-calendar/lib' ;
class MyPlugin implements Plugin {
/**
* 插件的 KEY 是必须的，没有此插件会被过滤掉
*/
static KEY = 'my-plugin' as const ;
/**
* 构造函数，参数为用户传入的插件选项。
* 此构造器可选择实现，如果没有提供选项配置或是其他初始化过程的话。
*/
constructor ( options ?: Record < string , any > ) {
// options 引入时的插件选项
}
} 註冊日曆組件的三個生命週期鉤子created attached detacched 。
import { Plugin , PluginService , CalendarData } from '@lspriv/wx-calendar/lib' ;
class MyPlugin implements Plugin {
/**
* 插件初始化，可选择实现该方法
* 在日历组件 created 阶段最后，在插件实例化后
* @param service PliginService实例
*/
PLUGIN_INITIALIZE ( service : PluginService ) : void {
// 获取日历组件实例
const component = service . component ;
}
/**
* 组件挂载，可选择实现该方法
* 在日历组件 attached 阶段中，此时组件的所有工具类已完成实例化，视图数据即将更新。
* 你可以在此方法里修改视图更新数据 sets，还可以调整一些工具实例的初始值。
* @param service PliginService实例
* @param sets 视图数据
*/
PLUGIN_ON_ATTACH ( service : PluginService , sets : Partial < CalendarData > ) : void {
}
/**
* 组件销毁，可选择实现该方法
* 在日历组件 detacched 阶段中
* @param service PliginService实例
*/
PLUGIN_ON_DETACHED ( service : PluginService ) : void {
}
} 新增修改和刪除日期標記，以及完善補充日程資料。
import {
Plugin ,
WcYear ,
CalendarDay ,
TrackDateResult ,
TrackYearResult ,
WcScheduleInfo ,
getMarkKey ,
getAnnualMarkKey
} from '@lspriv/wx-calendar/lib' ;
class MyPlugin implements Plugin {
/**
* 捕获日期，可选择实现该方法
* 在此添加修改和删除【周/月/日程视图面板】的日期标记
* @param date 日期
*/
PLUGIN_TRACK_DATE ( date : CalendarDay ) : TrackDateResult | null {
// do something...
return {
schedule : [ { text : '' , color : '' , bgColor : '' , key : getMarkKey ( 'id' , MyPlugin . KEY ) } ] , // 设置日程数组，可选
corner : { text : '' , color : '' } , // 设置角标，可选
festival : { text : '' , color : '' } , // 设置节假日，可选
style : { backgroundColor : '' , color : '' } // 设置日期样式，也可传字符串形式（如 'background-color: #409EFF;color: #fff;'），可选
} ;
} ;
/**
* 捕获年份，可选择实现该方法
* 在此添加修改和删除【年面板】的日期标记
* @param year 年
*/
PLUGIN_TRACK_YEAR ( year : WcYear ) : TrackYearResult | null {
// do something...
return {
subinfo : [
{ text : '乙巳蛇年' , color : '#F56C6C' } ,
{ text : '农历初一' , color : '#409EFF' }
] ,
marks : new Map ( [
[ getAnnualMarkKey ( { month : 10 , day : 6 } ) , { rwtype : 'rest' } ] , // 休息日，置灰
[ getAnnualMarkKey ( { month : 10 , day : 7 } ) , { rwtype : 'work' } ] , // 工作日，正常
[ getAnnualMarkKey ( { month : 10 , day : 12 } ) , { sub : '#F56C6C' } ] // 自定义颜色下标
[ getAnnualMarkKey ( { month : 10 , day : 20 } ) , {
style : {
color : { light : '#fff' , dark : '#000' } , // 日期字体颜色, light浅色模式下，dark深色模式下
bgColor : { light : '#409EFF' , dark : '#409EFF' } , // 日期背景颜色
opacity : { light : 1 , dark : 1 } , // 不支持 0
bgTLRadius : { light : 50 , dark : 50 } , // 日期背景左上圆角半径
bgTRRadius : { light : 0 , dark : 0 } , // 日期背景右上圆角半径
bgBLRadius : { light : 0 , dark : 0 } , // 日期背景左下圆角半径
bgBRRadius : { light : 50 , dark : 50 } , // 日期背景右下圆角半径
bgWidth : { light : 'dateCol' , dark : 'dateCol' } // 日期背景宽度，deteCol为列宽
}
} ]
] )
}
} ;
/**
* 捕获日程信息（点击日程时执行），可选择实现该方法
* @param date 日期
* @param id 插件内标记, 由 getMarkKey 生成 key 时传入的 id，详见 PLUGIN_TRACK_DATE
*/
PLUGIN_TRACK_SCHEDULE ( date : CalendarDay , id :? string ) : WcScheduleInfo {
}
} 擷取使用者的手勢動作，此時動作已完成，但在日曆元件預設行為之前。
import { Plugin , PluginService , EventIntercept } from '@lspriv/wx-calendar/lib' ;
class MyPlugin implements Plugin {
/**
* 拦截日期点击动作，可选择实现该方法
* @param service PliginService实例
* @param event 事件参数
* @param intercept 拦截器
*/
PLUGIN_CATCH_TAP ( service : PluginService , event : TouchEvent , intercept : EventIntercept ) : void {
// 获取日历组件实例
const component = service . component ;
// 若不想事件继续传播
if ( ... ) intercept ( ) ;
// intercept(0) 直接退出
// intercept(1) 继续向其他插件传播，但不会执行日历组件默认行为
}
/**
* 拦截日期跳转动作（如跳转到今日或者调用toDate方法），可选择实现该方法
* @param service PliginService实例
* @param date 要跳转的日期
* @param intercept 拦截器
*/
PLUGIN_CATCH_MANUAL ( service : PluginService , date : CalendarDay , intercept : EventIntercept ) : void { }
} Note
本日曆統計共有七個主要的動作，目前僅提供日期點擊動作和日期跳轉動作的捕獲，七個動作分別是
回應日曆元件事件load click change viewChange 。
import { Plugin , PluginService , CalendarEventDetail , OnceEmiter } from '@lspriv/wx-calendar/lib' ;
class MyPlugin implements Plugin {
/**
* 日历加载完成，可选择实现该方法
* @param service PliginService实例
* @param detail 响应数据
* @param emiter 事件触发器
*/
PLUGIN_ON_LOAD ( service : PluginService , detail : CalendarEventDetail , emiter : OnceEmiter ) : void {
// 获取日历组件实例
const component = service . component ;
emiter . cancel ( ) ; // 取消日历组件触发 bindload 事件。
// emiter.emit(detail); 劫持触发 bindload 事件，和 emiter.cancel 只能二选一。
}
/**
* 日期点击事件，可选择实现该方法
* @param service PliginService实例
* @param detail 响应数据
* @param emiter 事件触发器
*/
PLUGIN_ON_CLICK ( service : PluginService , detail : CalendarEventDetail , emiter : OnceEmiter ) : void {
}
/**
* 日期选中变化，可选择实现该方法
* @param service PliginService实例
* @param detail 响应数据
* @param emiter 事件触发器
*/
PLUGIN_ON_CHANGE ( service : PluginService , detail : CalendarEventDetail , emiter : OnceEmiter ) : void {
}
/**
* 视图变化，可选择实现该方法
* @param service PliginService实例
* @param detail 响应数据
* @param emiter 事件触发器
*/
PLUGIN_ON_VIEWCHANGE ( service : PluginService , detail : CalendarEventDetail , emiter : OnceEmiter ) : void {
}
} import { Plugin , CalendarDay , PluginService , DateRange } from '@lspriv/wx-calendar/lib' ;
class MyPlugin implements Plugin {
/**
* 日期过滤器（提供给其他组件调用的），可选择实现该方法
* @param service PliginService实例
* @param dates 待过滤的日期数组
*/
PLUGIN_DATES_FILTER ( service : PluginService , dates : Array < CalendarDay | DateRange > ) : Array < Calendar | DateRange > {
// 获取日历组件实例
const component = service . component ;
return [
[ { year : 2024 , month : 6 , day : 1 } , { year : 2024 , month : 6 , day : 28 } ] , // 日期范围
{ year : 2024 , month : 7 , day : 1 } // 单点日期
]
}
} 数据标记後引入的插件數據覆蓋先引入的插件數據动作捕捉後引入的先執行响应事件依插件的引入順序響應事件，先引入的先響應有任何问题或是需求请到 `Issues` 面板提交 忙的时候还请见谅 有兴趣开发维护的道友加微信
