WdatePicker日曆控制元件使用方法
一.介紹：
日期控制元件，使用需引入WdatePicker.js檔案
支援的瀏覽器
IE 6.0+ , Firefox 2.0+ , Chrome, Opera 9.5+ , Safari 3.0+
二.功能例項
三.配置說明
1. 屬性配置
屬性表| 屬性 | 型別 | 預設值 | 說明 |
|---|---|---|---|
| 靜態屬性:只能在WdatePicker.js中配置,一般情況下,不建議您修改靜態屬性的值 | |||
| $wdate | bool | true | 是否自動引入Wdate類 設定為true時,可直接在引入WdatePicker.js的頁面裡使用 class="Wdate" Wdate可在skin目錄下的WdatePicker.css檔案中定義 建議使用預設值 |
| $dpPath | string | '' | 是否顯示指定程式包的絕對位置,一般情況下為空即可(程式自動建立),該屬性是為防止極其少數的情況下程式創建出錯而設定的 設定方法: 如果,程式包所在http中的地址為 http://localhost/proName/My97DatePicker/ 則 $dpPath = '/proName/My97DatePicker/'; 建議使用預設值 |
| $crossFrame | bool | true | 是否跨框架,一般設定為true即可,遇到跨域錯誤時可以將此功能關閉 |
| 可配置屬性:可以在WdatePicker方法是配置 | |||
| el | Element 或 String | null | 指定一個控制元件或控制元件的ID,必須具有value或innerHTML屬性(如input,textarea,span,div,p等標籤都可以),使用者儲存日期顯示值(也就是dateFmt格式化後的值) |
| vel | Element 或 String | null | 指定一個控制元件或控制元件的ID,必須具有value屬性(如input),用於儲存真實值(也就是realDateFmt和realTimeFmt格式化後的值) |
| doubleCalendar | bool | false | 是否是雙月模式,如果該屬性為true,則彈出同時顯示2個月的日期框 |
| enableKeyboard | bool | true | 鍵盤控制開關 |
| enableInputMask | bool | true | 文字框輸入啟用掩碼開關 |
| autoUpdateOnChanged | bool | null | 在修改年月日時分秒等元素時,自動更新到el,預設是關閉的(即:需要點選確定或點選日期才更新) 為false時 不自動更新 為true時 自動更新 為null時(預設值) 如果有日元素且不隱藏確定按鈕時 為false,其他情況為true |
| weekMethod | string | ISO8601 | 周演算法不同的地方有一些差異 常見演算法有兩種 1. ISO8601:規定第一個星期四為第一週,預設值 2. MSExcel:1月1日所在的周 相關連結:http://en.wikipedia.org/wiki/ISO_week_date |
| position | object | {} | 日期選擇框顯示位置 注意:座標單位是px,是相對當前框架座標(不受滾動條影響),預設情況下系統根據頁面大小自動選擇 如: {left:100,top:50}表示固定座標[100,50] {top:50}表示橫座標自動生成,縱座標指定為 50 {left:100}表示縱座標自動生成,橫座標指定為 100 請參考示例 |
| lang | string | 'auto' | 當值為'auto'時 自動根據客戶端瀏覽器的語言自動選擇語言 當值為 其他 時 從langList中選擇對應的語言 你可以參考語言配置 |
| skin | string | 'default' | 面板名稱 預設自帶 default和whyGreen兩個面板 另外如果你的css夠強的話,可以自己做面板 你可以參考面板配置 |
| dateFmt | string | 'yyyy-MM-dd' | 日期顯示格式 你可以參考自定義格式 |
| realDateFmt | string | 'yyyy-MM-dd' |
計算機可識別的,真正的日期格式 無效日期設定(disabledDates),最大日期(maxDate),最小日期(minDate)以及快速日期都必須與它們相匹配 建議使用預設值 |
| realTimeFmt | string | 'HH:mm:ss' | |
| realFullFmt | string | '%Date %Time' | |
| minDate | string | '1900-01-01 00:00:00' | 最小日期(注意要與上面的real日期相匹配) |
| maxDate | string | '2099-12-31 23:59:59' | 最大日期(注意要與上面的real日期相匹配) |
| startDate | string | '' | 起始日期,既點選日期框時顯示的起始日期 為空時,使用今天作為起始日期(預設值) 否則使用傳入的日期作為起始日期(注意要與上面的real日期相匹配) 你可以參考起始日期示例 |
| firstDayOfWeek | int | 0 | 周的第一天 0表示星期日 1表示星期一 |
| isShowWeek | bool | false | 是否顯示周 你可以參考周顯示示例 |
| highLineWeekDay | bool | true | 是否高亮顯示 週六 週日 |
| isShowClear | bool | true | 是否顯示清空按鈕 |
| isShowOK | bool | true | 是否顯示確定按鈕 |
| isShowToday | bool | true | 是否顯示今天按鈕 |
| isShowOthers | bool | true | 為true時,第一行空白處顯示上月的日期，末行空白處顯示下月的日期,否則不顯示 |
| readOnly | bool | false | 是否只讀 |
| errDealMode | int | 0 | 糾錯模式設定 可設定3中模式 0 - 提示 1 - 自動糾錯 2 - 標記 |
| autoPickDate | bool | null | 為false時 點日期的時候不自動輸入,而是要通過確定才能輸入 為true時 即點選日期即可返回日期值 為null時(推薦使用) 如果有時間置為false 否則置為true |
| hmsMenuCfg | Object | { H: [1, 6], m: [5, 6], s: [15, 4] } |
4.8beta4新增
使用hmsMenuCfg屬性可以實現時分秒選單的自定義 |
| qsEnabled | bool | true |
是否啟用快速選擇功能 注意:當日期格式中沒有d這個元素時(如yyyy-MM或HH:mm:ss這樣的格式時),該屬性永遠為true |
| autoShowQS | bool | false | 是否預設顯示快速選擇 |
| quickSel | Array | null | 快速選擇資料,可以傳入5個快速選擇日期 注意:日期格式必須與 realDateFmt realTimeFmt realFullFmt 相匹配 你可以參考快速選擇示例 |
| disabledDays | Array | null | 可以使用此功能禁用週日至週六所對應的日期 0至6 分別代表 週日至週六 你可以參考無效天示例 |
| disabledDates | Array | null | 可以使用此功能禁用所指定的一個或多個日期 你可以參考無效日期示例 |
| opposite | bool | false | 預設為false, 為true時,無效日期變成有效日期 注意:該屬性對無效天特殊天不起作用 你可以參考有效日期示例 |
| specialDates | Array | null | 特殊日期,對指定的日期進行高亮顯示 你可以參考特殊天與特殊日期示例 |
| specialDays | Array | null | 特殊天,使用此功能禁用週日至週六所對應的日期進行高亮顯示 0至6 分別代表 週日至週六 你可以參考特殊天與特殊日期示例 |
| onpicking | function | null |
此四個引數為事件引數 你可以參考自定義事件示例 |
| onpicked | function | null | |
| onclearing | function | null | |
| oncleared | function | null | |
|
ychanging ychanged Mchanging Mchanged dchanging dchanged Hchanging Hchanged mchanging mchanged schanging schanged |
function | null | y M d H m s 分別表示年月日時分秒 changing 事件發生在屬性改變之前 changed 事件發生在屬性改變之後 你可以參考示例5-4-1 |
通過配置WdatePicker.js的屬性可以避免每次呼叫都傳入配置值,為變成帶來很多方便.
在預設情況下My97為每個屬性都配置了預設值,這些預設值都可以在WdatePicker.js中修改的
你可以根據你個人的喜好更改這些值
比如你比較不喜歡預設的面板default 而更喜歡 whyGreen 這個面板,
你可以直接在WdatePicker.js把skin值改為 whyGreen
這樣,你就不必每次呼叫控制元件的時候都傳入 skin:'whyGreen' 了
你學會了嗎?
在控制元件裡面你可以使用 onfocus 或 onclick 事件來呼叫WdatePicker函式來觸發日期控制元件
WdatePicker({})其中{}中的內容都是隻對當前例項有效,你可以任意配置屬性表裡有的所有屬性
你可以隨意的組合這些屬性,達到你的需求
My97日期控制元件在這方面是做得非常靈活的.
您可以設定多個WdatePicker.js檔案,如 cn_WdatePicker.js,en_WdatePicker.js,simple_WdatePicker.js等
在不同的頁面引入不同的 WdatePicker.js 達到配置快速切換的目的.
注意:檔案必須以 _WdatePicker.js(大小寫不限制) 為字尾,形如 <yourname>_WdatePicker.js
2. 語言配置
- 語言列表
My97DatePicker目錄下有個config.js(4.8以後在WdatePicker.js中),裡面有段程式碼:
var langList =
[
{name:'en',charset:'UTF-8'},
{name:'zh-cn', charset:'gb2312'},
{name:'zh-tw', charset:'GBK'}
];
這就是語言列表,每個項有name和charset兩個屬性.
name 表示語言的名稱(必須與瀏覽器的語言字串命名相同),在配置的時候,lang屬性只能是配置列表裡面已有的項,否則將自動返回第一項
charset 表示對應語言目錄下的js檔案所對應的編碼格式 - 語言安裝說明
分兩步輕鬆實現:
1 將語言檔案拷貝到 lang 目錄
2 開啟 config.js 配置語言列表
3. 面板配置
- 面板列表
My97DatePicker目錄下有個config.js(4.8以後在WdatePicker.js中),裡面有段程式碼:
var skinList =
[
{name:'default',charset:'gb2312'},
{name:'whyGreen', charset:'gb2312'},
{name:'blue', charset:'gb2312'},
{name:'simple', charset:'gb2312'}
];
這就是面板列表,每個項有name和charset兩個屬性.
name 表示面板的名稱,在配置的時候,skin屬性只能是配置列表裡面已有的項,否則將自動返回第一項
charset 表示對應面板目錄下的css檔案:datepicker.css所對應的編碼格式 - 面板安裝說明
分兩步輕鬆實現:
1 將面板檔案包拷貝到 skin 目錄
2 開啟 config.js 配置面板列表
四.如何使用
1. 在使用該日期控制元件的檔案中加入JS庫(僅這一個檔案即可,其他檔案會自動引入,請勿刪除或改名), 程式碼如下 <script language="javascript" type="text/javascript" src="datepicker/WdatePicker.js"></script>
注:src="datepicker/WdatePicker.js" 請根據你的實際情況改變路徑
2. 加上主調函式 WdatePicker
關於 WdatePicker 的用法:
如果您是新手,對js還不是很瞭解的話一定要多看看這份文件
基本上每一個演示的示例下面都有相關程式碼,並且 關鍵屬性用藍字標出,關鍵值用紅字標出 應該很容易看明白
如果您有一定的水準
希望能從頭到尾把功能介紹好好看一遍,這樣大部分功能你都會用了
如果您是高手
建議您通讀配置說明和內建函式
五. 內建函式和屬性
| 函式名 | 返回值型別 | 作用域 | 引數 | 描述 |
|---|---|---|---|---|
| $dp.show | void | 全域性 | 無 | 顯示日期選擇框 |
| $dp.hide | void | 全域性 | 無 | 隱藏日期選擇框 |
|
$dp.unbind (4.8beta4新增) |
void | 全域性 | el [string/object]:取消繫結的物件,可傳入dom物件或者是物件的ID | 讓傳入的物件取消日期控制元件繫結 |
| $dp.$D | String | 全域性 | id [string]: 物件的ID arg [object]: 日期差量,可以設定成 {y:[值],M:[值],d:[值],H:[值],m:[值],s:[值]} 屬性 y,M,d,H,m,s 分別代表 年月日時分秒 {M:3,d:7} 表示 3個月零7天 {d:1,H:1} 表示1天多1小時 |
將id對應的日期框中的日期字串,加上定義的日期差量,返回使用real格式化後的日期串 參考 示例 4-3-2 |
| $dp.$DV | String | 全域性 | v [string]: 日期字串 arg [object]: 同上例的arg |
將傳入的日期字串,加上定義的日期差量,返回使用real格式化後的日期串 參考 示例 4-3-3 |
| 以下函式只在事件自定義函式中有效 | ||||
| $dp.cal.getP | String | 事件function | p [string]: 屬性名稱 yMdHmswWD分別代表年,月,日,時,分,秒,星期(0-6),周(1-52),星期(一-六) f [string]: format 格式字串 設定方法參考 1.4 自定義格式 |
返回所指定屬性被格式字串格式化後的值[單屬性],在changing,picking,clearing事件中返回選擇前的值 參考 示例 1-2-2 |
| $dp.cal.getDateStr | String | 事件function | f [string]: 格式字串,為空時使用dateFmt |
返回所指定屬性被格式字串格式化後的值[整個值],在changing,picking,clearing事件中返回選擇前的值 |
| $dp.cal.getNewP | String | 事件function | 用法同$dp.cal.getP | 返回所指定屬性被格式字串格式化後的值[單屬性],在changing,picking,clearing事件中返回選擇後的值 |
| $dp.cal.getNewDateStr | String | 事件function | 用法同$dp.cal.getDateStr | 返回所指定屬性被格式字串格式化後的值[整個值],在changing,picking,clearing事件中返回選擇後的值 |
| 屬性名 | 返回值型別 | 作用域 | 引數 | 描述 |
|---|---|---|---|---|
| $dp.cal.date | object | 事件function | $dp.cal.date.y:返回 年 $dp.cal.date.M:返回 月 $dp.cal.date.d:返回 日 $dp.cal.date.H:返回 時 $dp.cal.date.m:返回 分 $dp.cal.date.s:返回 秒 |
在changing,picking,clearing事件中返回選擇前的日期物件 |
| $dp.cal.newdate | object | 事件function | 用法同$dp.cal.date | 在changing,picking,clearing事件中返回選擇後的日期物件 |
1. 跨無限級框架顯示
無論你把日期控制元件放在哪裡,你都不需要擔心會被外層的iframe所遮擋進而影響客戶體驗,因為My97日期控制元件是可以跨無限級框架顯示的
示例2-7 跨無限級框架演示
可無限跨越框架iframe,無論怎麼巢狀框架都不必擔心了,即使有滾動條也不怕
2. 民國年日曆和其他特殊日曆
當年份格式設定為yyy格式時,利用年份差量屬性yearOffset(預設值1911民國元年),可實現民國年日曆和其他特殊日曆
示例2-8 民國年演示
<input type="text" id="d28" onClick="WdatePicker({dateFmt:'yyy/MM/dd'})"/>
注意:年份格式設定成yyy時,真正的日期將會減去一個差量yearOffset(預設值為:1911),如果是民國年使用預設值即可無需另外配置,如果是其他的差量,可以通過引數的形式配置
3. 為程式設計帶來方便
如果el的值是this,可省略,即所有的el:this都可以不寫
日期框設定為disabled時,禁止更改日期(不彈出選擇框)
如果沒有定義onpicked事件,自動觸發文字框的onchange事件
如果沒有定義oncleared事件,清空時,自動觸發onchange事件
4. 其他屬性
設定readOnly屬性,可指定日期框是否只讀
設定highLineWeekDay屬性,可指定是否高亮週末
設定isShowOthers屬性,可指定是否顯示其他月的日期
加上class="Wdate"就會在選擇框右邊出現日期圖示
多語言和自定義面板
1. 多語言支援
通過lang屬性,可以為每個日期控制元件單獨配置語言,當然也可以通過WdatePicker.js配置全域性的語言
語言列表和語言安裝說明詳見語言配置
示例3-1 多語言示例
繁體中文:
<input id="d311" class="Wdate" type="text" onFocus="WdatePicker({lang:'zh-tw'})"/>
英文:
<input id="d312" class="Wdate" type="text" onFocus="WdatePicker({lang:'en'})"/>
簡體中文:
<input id="d313" class="Wdate" type="text" onFocus="WdatePicker({lang:'zh-cn'})"/>
注意:預設情況lang='auto',即根據瀏覽器的語言自動選擇語言.
2. 自定義和動態切換面板
通過skin屬性,可以為每個日期控制元件單獨配置面板,當然也可以通過WdatePicker.js配置全域性的面板
面板列表和面板安裝說明詳見面板配置
示例3-2 面板演示
預設面板default: skin:'default'
<input id="d321" class="Wdate" type="text" onfocus="WdatePicker()"/>
注意:在WdatePicker裡配置了skin='default',所以此處可省略,同理,如果你把WdatePicker裡的skin配置成'whyGreen'那麼在不指定面板的情況下都使用'whyGreen'面板了
whyGreen面板: skin:'whyGreen'
<input id="d322" class="Wdate" type="text" onfocus="WdatePicker({skin:'whyGreen'})"/>
4. 日期範圍限制
1. 靜態限制
注意:日期格式必須與realDateFmt和realTimeFmt一致
你可以給通過配置minDate(最小日期),maxDate(最大日期)為靜態日期值,來限定日期的範圍
示例4-1-1 限制日期的範圍是 2006-09-10到2008-12-20
<input id="d411" class="Wdate" type="text" onfocus="WdatePicker({skin:'whyGreen',minDate:'2006-09-10',maxDate:'2008-12-20'})"/>
示例4-1-2 限制日期的範圍是 2008-3-8 11:30:00 到 2008-3-10 20:59:30
<input type="text" class="Wdate" id="d412" onfocus="WdatePicker({skin:'whyGreen',dateFmt:'yyyy-MM-dd HH:mm:ss',minDate:'2008-03-08 11:30:00',maxDate:'2008-03-10 20:59:30'})" value="2008-03-09 11:00:00"/>
示例4-1-3 限制日期的範圍是 2008年2月 到 2008年10月
<input type="text" class="Wdate" id="d413" onfocus="WdatePicker({dateFmt:'yyyy年M月',minDate:'2008-2',maxDate:'2008-10'})"/>
示例4-1-4 限制日期的範圍是 8:00:00 到 11:30:00
<input type="text" class="Wdate" id="d414" onfocus="WdatePicker({dateFmt:'H:mm:ss',minDate:'8:00:00',maxDate:'11:30:00'})"/>
2. 動態限制
注意:日期格式必須與realDateFmt和realTimeFmt一致
你可以通過系統給出的動態變數,如%y(當前年),%M(當前月)等來限度日期範圍,你
還可以通過#{}進行表示式運算,如:#{%d+1}:表示明天
動態變量表
|
格式 |
說明 |
|
%y |
當前年 |
|
%M |
當前月 |
|
%d |
當前日 |
|
%ld |
本月最後一天 |
|
%H |
當前時 |
|
%m |
當前分 |
|
%s |
當前秒 |
|
#{} |
運算表示式,如:#{%d+1}:表示明天 |
|
#F{} |
{}之間是函式可寫自定義JS程式碼 |
示例4-2-1 只能選擇今天以前的日期(包括今天)
<input id="d421" class="Wdate" type="text" onfocus="WdatePicker({skin:'whyGreen',maxDate:'%y-%M-%d'})"/>
示例4-2-2 使用了運算表示式只能選擇今天以後的日期(不包括今天)
<input id="d422" class="Wdate" type="text" onfocus="WdatePicker({minDate:'%y-%M-#{%d+1}'})"/>
示例4-2-3 只能選擇本月的日期1號至本月最後一天
<input id="d423" class="Wdate" type="text" onfocus="WdatePicker({minDate:'%y-%M-01',maxDate:'%y-%M-%ld'})"/>
示例4-2-4 只能選擇今天7:00:00至明天21:00:00的日期
<input id="d424" class="Wdate" type="text" onfocus="WdatePicker({dateFmt:'yyyy-M-d H:mm:ss',minDate:'%y-%M-%d 7:00:00',maxDate:'%y-%M-#{%d+1} 21:00:00'})"/>
示例4-2-5 使用了運算表示式只能選擇 20小時前至 30小時後的日
期
<input id="d425" class="Wdate" type="text" onClick="WdatePicker({dateFmt:'yyyy-MM-dd HH:mm',minDate:'%y-%M-%d #{%H-20}:%m:%s',maxDate:'%y-%M-%d #{%H+30}:%m:%s'})"/>
3 . 指令碼自定義限制
注意:日期格式必須與realDateFmt和realTimeFmt一致
系統提供了$dp.$D和$dp.$DV這兩個API來輔助你進行日期運算,此外你還可以通過在#F{}中填入你自定義的指令碼,做任何你想做的日期限制
示例4-3-1 前面的日期不能大於後面的日期且兩個日期都不能大於 2020-10-01
合同有效期從到<input id="d4311" class="Wdate" type="text" onFocus="WdatePicker({maxDate:'#F{$dp.$D(\'d4312\')||\'2020-10-01\'}'})"/>
<input id="d4312" class="Wdate" type="text" onFocus="WdatePicker({minDate:'#F{$dp.$D(\'d4311\')}',maxDate:'2020-10-01'})"/>
注意:
兩個日期的日期格式必須相同
$dp.$ 相當於
document.getElementById 函式.
那麼為什麼裡面的 ' 使用\'呢?那是因為"
和 '
都被外圍的函式使用了,故使用轉義符\ ,否則會提示JS語法錯誤.
所以您在其他地方使用時注意把 \' 改成"或者
' 來使用.
#F{$dp.$D(\'d4312\')||\'2020-10-01\'} 表示當
d4312 為空時,採用2020-10-01的值作為最大值
示例4-3-2 前面的日期+3天 不能大於 後面的日期
日期從到<input type="text" class="Wdate" id="d4321"
onFocus="WdatePicker({maxDate:'#F{$dp.$D(\'d4322\',{d:-3});}'})"/>
<input type="text" class="Wdate" id="d4322"
onFocus="WdatePicker({minDate:'#F{$dp.$D(\'d4321\',{d:3});}'})"/>
使用 $dp.$D函式可以將日期框中的值,加上定義的日期差量:
兩個引數: id={字元型別}需要處理的文字框的id值
, obj={物件型別}日期差量
日期差量用法:
屬性y,M,d,H,m,s分別代表年月日時分秒