artDialog.js的使用

開發項目中用到了artDialog.js，從而專門學習一下如何配置和使用。

一、artDialog是什么

artDialog是一個精巧的web對話框組件，壓縮后只有十多KB，並且不依賴其他框架。

二、artDialog的使用

以下內容引用 http://www.2cto.com/kf/201303/195812.html，artDialog基本使用，詳細內容有調整和更改。

在頁面head引入artDialog，注意如果文件帶有skin參數將會無阻塞的方式自動加載對應的皮膚css文件，當然你仍然可以使用傳統方式引用“skins/”目錄下的css文件，二者選其一。

<script src="artDialog.js?skin=default"></script>

如果項目采用jQuery作為框架，則引用jQuery artDialog版本：<script src="jquery.artDialog.js?skin=default"></script>

如果需要在iframe應用下提供 更好的支持，需要加上：<script src="artDialog.iframeTools.js"></script>

三、配置參數

	名稱	類型	默認值	描述	說明
內容	title	String	'消息'	標題內容
	content	String	null	消息內容	1、如果內容類型是Object(JSON)還需要tmpl參數配合； 2、如果傳入的是HTMLElement類型，如果是隱藏元素會給其設置display:block以顯示該元素，其他屬性與綁定的事件都會完整保留，對話框關閉后此元素又將恢復原來的display屬性，並且重新插入原文檔所在位置； 3、如果沒有設定content的值則會有loading的動畫。 HTMLElement Object
按鈕	yesFn	Function	null	確定按鈕回調函數	函數如果返回false將阻止對話框關閉；函數this指針指向內部api；如果傳入true表示只顯示有關閉功能的按鈕。 Boolean
	noFn	Function	null	取消按鈕回調函數	函數如果返回false將阻止對話框關閉；函數this指針指向內部api；如果傳入true表示只顯示有關閉功能的按鈕。 對話框標題欄的關閉按鈕其實就是取消按鈕，只不過視覺不同罷了，點擊同樣觸發noFn事件。 Boolean
	yesText	String	'確定'	確定按鈕文本
	noText	String	'取消'	取消按鈕文字
	button	Array	null	自定義按鈕	參數{name:按鈕名稱,callback:按下后執行的函數,focus:是否聚焦點,disabled:是否標記按鈕為不可用狀態}(后續可使用控制接口讓其恢復可用狀態)。 示例：參數如[{name:'登錄', callback: function () {}}, {name: '取消'}]。 注意點擊按鈕默認會觸發按鈕關閉動作，需要阻止觸發關閉請讓回調函數返回false。
尺寸	width	Number	'auto'	設置消息內容寬度	可以帶單位。一般不需要設置此，對話框框架會自己適應內容。 如果設置為百分值單位，將會以根據瀏覽器可視范圍作為基准，此時如果瀏覽器窗口大小被改變其也會進行相應的調整。 String
	height	Number	'auto'	設置消息內容高度	可以帶單位。不建議設置此，而應該讓內容自己撐開高度。 如果設置為百分值單位，將會以根據瀏覽器可視范圍作為基准，此時如果瀏覽器窗口大小被改變其也會進行相應的調整。 String
位置	fixed	Boolean	false	開啟靜止定位	靜止定位是css2.1的一個屬性，它靜止在瀏覽器某個地方不動，也不受滾動條拖動影響(artDialog支持IE6 fixed)。
	follow	HTMLElement	null	讓對話框依附在指定元素附近	可傳入元素ID名稱，注意ID名稱需要以“#”號作為前綴。 String
	left	Number	'50%'	X軸的坐標	1、如果開啟了fixed參數則以瀏覽器視口為基准； 2、可以使用'0%'~ '100%'作為相對坐標，如果瀏覽器窗口大小被改變其也會進行相應的調整。 String
	top	Number	'goldenRatio'	Y軸的坐標	1、如果開啟了fixed參數則以瀏覽器視口為基准； 2、可以使用'0%'~ '100%'、''goldenRatio''作為相對坐標，如果瀏覽器窗口大小被改變其也會進行相應的調整，其中'goldenRatio'表示為黃金比例垂直居中，絕對居中請使用'50%'。 String
視覺	lock	Boolean	false	開啟鎖屏	中斷用戶對話框之外的交互，用於顯示非常重要的操作/消息，所以不建議頻繁使用它。
	background	String	'#000'	鎖屏遮罩顏色
	opacity	Number	0.7	鎖屏遮罩透明度
	icon	String	null	定義消息圖標	可定義“skins/icons/”目錄下的圖標名作為參數名（不包含后綴名）
	padding	String	'20px 25px'		內容與邊界填充邊距(即css padding)
交互	time	Number	null	設置對話框顯示時間	單位秒
	resize	Boolean	true	是否允許用戶調節尺寸
	drag	Boolean	true	是否允許用戶拖動位置
	esc	Boolean	true	是否允許用戶按Esc鍵關閉對話框
高級	id	String	null	設定對話框唯一標識	用途：1、防止重復彈出；2、可后續使用art.dialog.list[youID]獲取控制接口。 Number
	tmpl	String	null	啟用模板引擎拼接消息內容	還需要與content參數傳入字面量對象才能生效，詳情見示例。
	zIndex	Number	1987	重置全局zIndex初始值	用來改變對話框疊加高度。比如有時候配合外部浮動層UI組件，但是它們可能默認zIndex沒有artDialog高，導致無法浮動到artDialog之上，這個時候你就可以給對話框指定一個較小的zIndex值。 請注意這是一個會影響到全局的配置，后續出現的對話框疊加高度將重新按此累加。
	initFn	Function	null	對話框彈出后執行的函數
	closeFn	Function	null	對話框關閉前執行的函數	函數如果返回false將阻止對話框關閉。 請注意這不是關閉按鈕的回調函數，無論何種方式關閉對話框，closeFn都將執行。
	show	Boolean	true	是否顯示對話框

配置全局默認設置

(function (config) { config['lock'] = true; config['fixed'] = true; config['yesText'] = 'yes'; config['noText'] = 'no'; // [more..] })(art.dialog.defaults);

(function (config) {
    config['lock'] = true;
    config['fixed'] = true;
    config['yesText'] = 'yes';
    config['noText'] = 'no';
    // [more..]
})(art.dialog.defaults);

配置參數范例

• 內容 [content]

  1. 傳入字符串

  art.dialog({ content: '我支持HTML' });

  2. 傳入HTMLElement

  art.dialog({ content: document.getElementById('demoCode_content_DOM'), id: 'EF893L' });

  備注：1)元素不是復制而是完整移動到對話框中，所以原有的事件與屬性都將會保留；2)如果隱藏元素被傳入到對話框，會設置display:block屬性顯示該元素；3)對話框關閉的時候元素將恢復到原來在頁面的位置，style display屬性也將恢復。

  3. 高級應用：傳入Object並使用“tmpl”模板參數生成內容

  備注：拼接字符串是一個比較無趣的活兒，而artDialog內部使用一個微型模板引擎解析自身UI框架，你可以通過tmp參數繼續使用它格式化內容。模板支持原生的javascript語法，可進行條件判斷。推薦你嘗試使用type="text/tmpl"的script標簽存放模板，如：

  var tmpl = document.getElementById('tmpl_demoCode_content').innerHTML; art.dialog({ content: { code: 0, users: ['糖餅', '月月鳥', '水水', '麗麗', '花花', '大叔'], me: '糖餅', web: 'http://www.planeart.cn' }, tmpl: tmpl });

• 標題 [title]

  art.dialog({ title: 'hello world!' });

• 確定取消按鈕 [yesFn & noFn]

  art.dialog({ content: '如果定義了回調函數才會出現相應的按鈕', yesFn: function () { this.title('3秒后自動關閉').time(3); return false; }, noText: '關閉', noFn: true //為true等價於function(){} });
  備注：回調函數this指向擴展接口，如果返回false將阻止對話框關閉。

• 自定義按鈕 [button]

  art.dialog({ id: 'testID', content: 'hello world!', button: [ { name: '同意', callback: function () {this.content('你同意了').time(2); return false; }, focus: true }, { name: '不同意', callback: function () {alert('你不同意') } }, { name: '無效按鈕', disabled: true }, { name: '關閉我' } ] });
  備注：回調函數this指向擴展接口，如果返回false將阻止對話框關閉；button參數對應的控制接口名稱也是"button"。

• 定時關閉的消息 [time]

  art.dialog({ time: 2, content: '兩秒后關閉' });

• 防止重復彈出 [id]

  art.dialog({ id: 'testID', content: '再次點擊運行看看' }); art.dialog({id: 'testID'}).title('3秒后關閉').time(3);

• 定義消息圖標 [icon]

  art.dialog({ icon: 'succeed', content: '我可以定義消息圖標哦' });
  內置圖標：alert、succeed、error、confirm

• 內容與邊界填充邊距 [padding]

  art.dialog({ padding: 0, title: false, content: '<img src="./images/photo.jpg" width="379" height="500" />', lock: true });
  有時候並不需要默認的內容填充邊距，如展示圖片與視頻

• 鎖屏 [lock & background & opacity]

  art.dialog({ lock: true, background: '#600', // 背景色 opacity: 0.7, // 透明度 content: '中斷用戶在對話框以外的交互，展示重要操作與消息', icon: 'error', yesFn: function () { art.dialog({content: '再來一個鎖屏', lock:true}); return false; }, noFn: true });

• 跟隨元素 [follw]

  • 1、標准形式
    art.dialog({ follow: document.getElementById('followTestBtn'), content: '讓對話框跟着某個元素，一個元素同時只能出現一個對話框' });
  • 2、使用簡寫形式 （已經綁定onclick事件，注意此返回值不再是對話框控制接口）
    art('#demoCode_follow_a').dialog({ content: '讓對話框跟着某個元素，一個元素同時只能出現一個對話框' });
  • 元素觸發???

• 自定義坐標 [left & top]

  art.dialog({ left: 100, top: '60%', content: '我改變坐標了' });

• 創建一個右下角浮動的消息窗口

  art.dialog({ id: 'msg', title: '公告', content: 'hello world!', width: 320, height: 240, left: '100%', top:'100%', fixed: true, drag: false, resize: false })

• 設置大小 [width & height]

  art.dialog({ width: '20em', height: 55, content: '尺寸可以帶單位' });

• 創建一個全屏對話框

  art.dialog({ width: '100%', height: '100%', left: '0%', top: '0%', fixed: true, resize: false, drag: false })

• 靜止定位 [fixed]

  art.dialog({ fixed: true, content: '請拖動滾動條查看' });

• 不許拖拽 [drag & resize]

  art.dialog({ drag: false, resize: false, content: '禁止拖拽' });

四、控制接口

名稱	描述	說明
close()	關閉對話框
show()	顯示對話框
hide()	隱藏對話框
title(value)	寫入標題	無參數則返回標題容器元素
content(value)	向消息容器中寫入內容	參數支持字符串、DOM對象，無參數則返回內容容器元素
button(arguments)	插入一個自定義按鈕	如：button({name:'登錄', callback: function () {_form.submit();})。更多用法請見范例文檔
follow(element)	讓對話框吸附到指定元素附近
position(left,top)	重新定位對話框
size(width,height)	重新設定對話框大小
lock()	鎖屏
unlock()	解鎖
time(val)	定時關閉	單位秒

備注：控制接口返回值都是this，因此你可以使用鏈式編程風格。

控制接口范例

控制接口可以在對話框初始化后控制對話框。

• 獲取控制接口：直接引用控制接口

  var dialog = art.dialog({ title: '我是對話框', content: '我是初始化的內容' }); dialog.content('對話框內容被控制接口改變了').title('提示');

• 獲取控制接口：使用對話框ID

  art.dialog({ id: 'KDf435', title: '警告', content: '我是初始化的內容' }); art.dialog.list['KDf435'].content('對話框內容被控制接口改變了').time(2);

• 獲取控制接口：this引用

  art.dialog({ title: '警告', content: '我是初始化的內容', yesFn: function () { this.content('你點了確定按鈕').position('50%', null).lock().time(2); return false; }, initFn: function () { this.content('對話框內容被控制接口改變了'); } });

• 關閉頁面所有對話框

  var list = art.dialog.list; for (var i in list) { list[i].close(); };

• 按鈕接口演示

  備注：回調函數如果返回false將阻止對話框關閉
  var dialog = art.dialog({ title: '警告', content: '點擊管理按鈕將讓刪除按鈕可用', width: '20em', button: [{ name: '管理', callback: function () { this.content('我更改了刪除按鈕').button({ name: '刪除', disabled:false }); return false; }, focus: true }] }); dialog.button( { name: '刪除', callback: function () {alert('remove') }, disabled: true } )

• 改變關閉方式

  art.dialog({ id: 'show-hide', content: '關閉后阻止對話框被刪除，只隱藏對話框', closeFn: function () {this.hide(); return false; } }).show();

• AJAX高級應用：執行HTML片段中特殊script標簽

  HTML片段中的<script type="text/dialog"></script>標簽包裹的javascript將會在對話框中執行，其this指向對話框控制接口，代碼在閉包內執行，不會影響全局，這樣可以進一步實現內容模塊化。
  var dialog = art.dialog({id: 'N3690'}); // jQuery ajax $.ajax({ url: './ajaxContent/login.html', success:function (data) { dialog.content(data); }, cache: false });
  (本例子使用了AJAX，需要在服務器上運行。)

五、擴展：iframe應用工具集

	名稱	描述	說明
核心方法	art.dialog.parent	獲取artDialog可用最高層window對象	這與直接使用window.top不同，它能排除artDialog對象不存在已經或者頂層頁面為框架集的情況。 這是iframe應用工具集中的核心方法，你可以用它來操作父頁面對象（包括上面的對話框）
	art.dialog.data(name,value)	跨框架數據共享寫入接口	框架與框架之間以及與主頁面之間進行數據交換是非常頭疼的事情，常規情況下你必須知道框架的名稱才能進行數據交換，如果是在復雜的多層框架下操作簡直就是噩夢。 而data方法就是為了解決這個問題，你完全不用管框架層級問題，它可以寫入任何類型的數據，而做到各個頁面之間數據共享。
	art.dialog.data(name)	跨框架數據共享讀取接口	指定name即返回數據，任何引用了artDialog的頁面都有效
	art.dialog.removeData(name)	跨框架數據共享刪除接口	刪除指定名稱的數據，任何引用了artDialog的頁面都有效
異步數據對話框	art.dialog.open(url,options, cache)	創建一個iframe頁面	參數：地址, 配置參數, 緩存開關(默認true)
	art.dialog.open.api	iframe頁面獲取open方法控制接口	注意這個iframe中也必須引用artDialog腳本文件
	art.dialog.open.origin	iframe頁面獲取open方法觸發來源頁面window對象	注意這個iframe中也必須引用artDialog腳本文件
	art.dialog.close()	iframe頁面關閉open方法創建的對話框的快捷方式	close方法等同於：var api = art.dialog.open.api;api && api.close(); 注意這個iframe中也必須引用artDialog腳本文件
	art.dialog.load(url,options, cache)	Ajax加載內容	參數：地址,配置參數, 緩存開關(默認true)
基礎交互對話框	art.dialog.alert(content)	警告消息	參數：內容(同時只允許一個alert)
	art.dialog.confirm(content,yesFn, noFn)	確認	參數：內容, 確定按鈕回調函數, 取消按鈕回調函數(同時只允許一個confirm)
	art.dialog.prompt(content,yesFn, value)	提問	參數：內容, 確定按鈕回調函數, 文本框默認值(同時只允許一個prompt)
	art.dialog.tips(content,time)	短暫提示	參數：內容、顯示時間(單位秒, 默認1.5)(同時只允許一個tips)
自定義	art.dialog.through(options)	創建一個普通可穿越框架的對話框	不鼓勵直接使用window.top這樣的方式穿越，這樣可能因為對話框觸發頁面重置導致其產生所有的對象在內存中被清空，而讓對話框無法關閉，所以你應該用這個安全的方法創建自定義對話框。 框架集頁面無法覆蓋第三方元素，不過可以使用一個iframe套住框架集頁面就可以正常使用，見下面演示文檔

 

－－－－－－－－－－－－－－－－－－－－－－－分割線－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－

感謝作者整理。