2009年5月8日

extJs 2.0學習筆記

  這一篇翻譯自extJs 2.0官方文檔。花了我一個晚上加一個上午的時間才搞定。這篇是關於config的。

  我在網上查了很久,關於ExtJs的core部分的中文文檔還是有不少,但是關於panel,window這些呢就好像不大齊全,而且,在js堂,它的文檔翻譯還在1.1。所以呢想翻譯出來,以後大家也好查閱。

  本人js水平、英文水平都有限,還好,通過看源代碼兩相印證,終於還是搞出來了。歡迎各位提出寶貴的意見。事實上,只要搞定了panel,其也組件的config差不多。大同小異。嘿嘿。一通百通啊。

activeItem : String/Number
用於設置當前活動的子組件,取值為此子組件的序號或者是id。但是它只能應用於那種一次只能顯示一個子組件的佈局類,例如:Ext.layout.Accordion, Ext.layout.CardLayout和Ext.layout.FitLayout。

allowDomMove;Boolean
是否可以在組件呈現的過程中移動組件的dom節點。默認值為true。

animCollapse : Boolean
設置是否在面板收縮時起用動畫,如果Ext.Fx有效(被包含進來)則默認為true,否則為false。

applyTo:Mixed
x-panel對應的div的id。


autoDestroy : Boolean
如果要把一個子組件從panel中移除且此值為true,則在移除的過程中自動會銷毀此組件,返之,則不會,必須要手工銷毀,默認值為true。


autoHeight : Boolean
如果為true,把this.el.dom.style.height='auto'。默認值為false。

autoScroll : Boolean
為true時,則把this.body.dom.style.overflow='auto'。默認值為false。

autoShow : Boolean
為true時,檢查組件是否被設成隱藏,如果有,則移除這個效果。

autoWidth : Boolean
同autoHeight一樣。。

baseCls : String
this.baseCls的class(默認值為'x-panel')

bbar : Object/Array
面板底部的工具欄。它可是一個Ext.Toolbar對象,也可以是一個toolbar的 config對象,或者是一個要加入到工具欄的按鈕的config的數組。注意:這個屬性在render後就無效了,如果要在render後使用它,請使用 getBottomToolbar獲得引用。

bodyBorder : Boolean
如果為true則為this.el對應的元素顯示邊框,默認值為true。這只在border==true時才有效。如果border==true且bodyBorder==false,那麼將顯示1px的inset邊框。給予this.el inset的效果。

bodyStyle : String/Object/Function
要應用到this.el上的css class。它的格式需求與Ext.Element.applyStyle一樣,默認值為null。

border : Boolean
也是設this.body的邊框的,默認值為true,此時,默認情況下邊框為2px。當然,它還會被bodyBorder影響。

buttonAlign : String
加入到面板中的按鈕的對齊方式,合法值為:'right','left','cente',默認值為'right'。

buttons : Array
Ext.Button的config數組,用於加入按鈕到面板的footer中。

cls : String
this.el的class。

collapseFirst : Boolean
當顯示title bar時,是否總把收縮、展開按鈕放在所有其他按鈕的前面。默認值為true。

collapsed : Boolean
在呈現時,是收縮還是展開。為true則收縮,默認值為false。


collapsedCls : String
當面板處於收縮狀態時,this.el所對應的class,默認值為'x-panel-collapsed'。

collapsible : Boolean
此面板是否可收縮或者說是否能顯示收縮、伸展按鈕。真為顯示。默認值為false。

contentEl : String
一個已存在的dom的id。作用是用於在afterRender後把它this.body.dom.appendChild掉。默認值為''。

ctCls : String
設this.container的class。

defaultType : String
當在構造函數中用items填加新成員時,如果沒有設xType,那麼就會以這個默認類型為xType加入組件。默認值為'panel'。


defaults : Object
加入此組件的所有子組件的默認config。如果這些加入的子組件設了config的話就以新設的為準。例如:{bodyStyle:'padding:15px'}。


disabledClass : String
當組件被設成disabled時的css,默認值為:"x-item-disabled"。

draggable : Boolean
是否能被拖動。默認值為false。當然也可以是一個Ext.Panel.DD config。Ext.Panel.DD是一個internal但非公開的類(我沒有找到它的源代碼),它的作用是移動一個proxy元素 (Element)以代替本應跟隨鼠標移動的panel.el。但是它在拖動過程中、放下時不提供任何其他動作,也就是說,如果你不作處理的話,鼠標一鬆,panel仍然在老地方。它是Ext.dd.DragSource的子類,所以,必須通過實現Ext.dd.DragDrop的方法來產生動作。示例代碼如下:

new Ext.Panel({
title: 'Drag me',
x: 100,
y: 100,
renderTo: Ext.getBody(),
floating: true,
frame: true,
width: 400,
height: 200,
draggable: {
// Config option of Ext.Panel.DD class.
// It's a floating Panel, so do not show a placeholder proxy in the original position.
insertProxy: false,

// Called for each mousemove event while dragging the DD object.
onDrag : function(e){
// Record the x,y position of the drag proxy so that we can
// position the Panel at end of drag.
var pel = this.proxy.getEl();
this.x = pel.getLeft(true);
this.y = pel.getTop(true);

// Keep the Shadow aligned if there is one.
var s = this.panel.getEl().shadow;
if (s) {
s.realign(this.x, this.y, pel.getWidth(), pel.getHeight());
}
},

// Called on the mouseup event.
endDrag : function(e){
this.panel.setPosition(this.x, this.y);
}
}
}).show();



elements : String
一個panel有五個部分:header、tbar、body、bbar、footer。 elements就是保存當前panel包含了幾個部分,例如,一個panel有header、body,那麼:element=='body,header',默認值為:'body'。


floating : Boolean
為true的話,它會使panel.el.style.position=absolute。並且,默認情況下帶有shimming和shadow。為false則不改變原有顯示方式。
注意:把floating設為true會導致panel以offsets大量負偏移的方式隱藏。這個諸 位試一下就曉得了。所以呢,如果設了 floating=true。那麼,你render後最好還要setPostion(x,y)一下。當然如果你讓面板浮動,也要把width設成一個固定值,不然,它會向右擴展到viewport的邊緣。


footer : Boolean
為true則明確地創建footer,為false就不創建,默認情況下,如果對footer沒有什麼特殊的,那麼當一個或多個按鈕被加到footer上面時,footer會被自動創建。


frame : Boolean
為true的話呢就就在panel外面加上自定義的圓角邊框,為false的話就是1px寬的長方形邊框。


header : Boolean
為true時header被創建,反之不被創建,默認情況下,當header不處於特殊情況時,如果title被設置,它會被自動創建,否則不會被創建,如是果title被設置,但是header為false,那麼header也不會被創建。


headerAsText : Boolean
為真是在header中顯示title,為假時隱藏它。默認值為true.


height : Number
panel的高度,默認為auto。


hideBorders : Boolean
為true時,隱藏panel的所有子組件的邊框,為false則尊從子組件原有邊框設置。

hideCollapseTool : Boolean
當collapsible=true且hideCollapseTool=true時,則隱藏控制收縮、伸展的那個按鈕,為false時就顯示它,默認值為false。


hideMode : String
隱藏模式,有三種: "visibility" (css visibility), "offsets" (negative offset position) and "display" (css display) - defaults to "display"。

hideParent : Boolean
用於設置是否隱藏組件的容器,即component.container。

html : String/Object
一個html碎片,或者是滿足DomHelper語法的object,它用於設置panel的body部分的內容。默認值為''。

iconCls : String
用於設置header上的圖標的class。例如:.my-icon { background: url(../images/my-icon.gif) 0 6px no-repeat !important;}


id : String
一個為component統一分配的id值。默認值為panel.el.id。

items : Mixed
單個成員或一個子組件的數組。每個成員都可以是任何從Ext.Component繼承的object。

它的成員可以是component的引用,這樣就會馬上render,也可以是component的config。這時就會lazy render。當然,在config中,要注意加上xtype。這個東西不用講了吧。

關於xtype的所有取值情況,請見Ext.Component.xtype的config說明。裡面有講到。關於它的值,其實很多例子上都有,如果傳一個成員,則像:items:{……},傳多個的話呢,就像:[{……},{……}]。

keys : Object/Array
一個keyMap config object。用於設置快捷鍵的。默認值為null。


layout : String
設置panel.container的佈局。如果沒有設置,那麼默認為 Ext.layout.ContainerLayout,合法的值有:absolute, accordion, anchor, border, card, column, fit, form和table。如果要設置佈局的細節,則要用到layoutConfig了。


layoutConfig : Object
用於設置佈局細節的,當layout有合法設置時它才有效果。如果要知道關於這個config的設置細節,請見各佈局類:
Ext.layout.Absolute
Ext.layout.Accordion
Ext.layout.AnchorLayout
Ext.layout.BorderLayout
Ext.layout.CardLayout
Ext.layout.ColumnLayout
Ext.layout.FitLayout
Ext.layout.FormLayou
Ext.layout.TableLayout

listeners : Object
一個config對象用於包含一個或多個事件handler,它被addListener使用來註冊事件。

maskDisabled : Boolean
是否在panel.disabled的時候顯示mask。為true顯示。反之不顯示。
默認情況下,panel哪怕在disabled時,它的子元素也顯示得很正常,用戶根本不知道這個panel被禁用了,這給用戶帶來困擾,但是,有了mask,用戶就能得到提示,哦,這個panel是不可用的,被禁用了。這給用戶帶來了新的體驗。


minButtonWidth : Number
panel上所有按鈕的最小寬度,單位是px。

monitorResize : Boolean
為true時,它自動監控window的resize事件,並且讓viewport因此而變化。這個東西的經典應用就是為layout服務,而不用我們手工去調整某些組件的大小來適應窗口大小的變化。


overCls : String
當鼠標放到panel.el上面時的class。最爽的是,當鼠標out時,它會被自動刪除,從而產生hover效果。


pageX : Number
組件相對於頁面的x坐標

pageY : Number
組件相對於頁面的y坐標

plugins : Object/Array
一個對象或對象數組,它為component提供自定義的功能。每個對象都是一個插件的引用,當然,前提是這個插件定義了init方法,在component初始化時,這個init方法將被調用。沒用著。不說了。難翻譯啊。

renderTo : Mixed
Ext.get(panel.renderTo)就是panel.container。用語言說不清楚,這樣直接了當。

shadow : Boolean/String
為true就給panel顯示一個陰影,為false不顯示。當然,也可設置成為shadow的類型,詳情見Ext.Shadow、Ext.Shadow.mode。注意,這個選項只有在floating = true時才發生作用。

shadowOffset : Number
陰影偏移,默認值為4,只有在floating = true時才發生作用。

shim : Boolean
是否為組件創建shim,什麼是shim呢?存在這樣的情況,用div做的菜單,但是,好死不死有個 applet或flash蓋在上面的話,那菜單就會被蓋在下面。這件事情曾經一度讓b/s人員鬱悶,ext提供一個通用的解決方案,在要避免這個問題的組件的同一位置創建一個與它大小一樣的iframe,且使得這個組件的z-index大於iframe。由於iframe不會被其他東西遮住,所以,z- index在iframe之上的東西也不會被遮,iframe相當於個墊子,把我們要用的東西墊高了,而shim英語裡面也是薄墊片的意思。高呼 extjs萬歲。當然,iframe的src必須為''。

stateEvents : Array
事件數組,當這此事件觸發時,組件狀態被保存。

stateId : String
用於管理組件狀態的id,默認值為組件的id.

stateful : Boolean
一個標誌,它表示組件在創建時是否從某個地方加載組件狀態。哪些屬性能作為狀態保存呢?只有internal屬性可以。
為了讓組件狀態能保存,組件狀態管理器提供者必須實現Ext.state.Provider,也就是要實重寫它的set、get方法以保存/重讀鍵/值對,一個內鍵的提供者是: Ext.state.CookieProvider。

為當前頁面設置狀態提供者的方法如下:
Ext.state.Manager.setProvider(new Ext.state.CookieProvider());

組件試圖在stateEvents裡面配置了事件時保存狀態。你可以自己寫點代碼進行一處理,如在:beforestaterestore, staterestore, beforestatesave和statesave事件的處理代碼中。

style : String
一個應用於panel.el上的樣式,語法必須滿足Ext.Element.applyStyles的接口。


tabTip : String
當panel是Ext.TabPanel中的一頁時,為這個panel設tooltips的。不過,在render之前得先調用Ext.QuickTips.init()初始化一下。

tbar : Object/Array
panel頂部的工具欄,它可以是一個Ext.Toolbar,也可以是一個按鈕數組或一個按鈕的config。注意:在render之後,這個引用就沒用了。如果要處理它請使用getTopToolbar。

title : String
顯示在panel的header中的標題,當title被設置時,header就會被創建,除非header 被設成false。如果你需要title,但不是在panel創建時,而是在之後的某個時刻,這時你需要為title設置一個非空值(如一個空格)或者是把header設為true。這樣,panel在創建時才會創建header,不然,header將不會被創建。

titleCollapse : Boolean
當collapsible = true且titleCollapse=true時,用戶點擊panel標題欄的任意一處都會產生摺疊/伸展效果,否則則只能通過單擊那個按鈕(上文有講到)來產生這個效果了。


tools : Array
一個工具欄按鈕數組,這個工具欄非同一般哦,不是tbar,也不是bbar,而是header上的標題欄,header上的標題欄是怎樣的概念?你看到的panel的關閉按鈕這個鈕,超爽吧。每個工具欄元素以一個Element引用的方式向開發人員公開,通過
   tools.的方式引用。暴爽。
每個工具欄成員的config要包含下面屬性:
id:string
  必需的,工具欄按鈕的類型,可取值如下:

toggle (Created by default when collapsible is true)
close
minimize
maximize
restore
gear
pin
unpin
right
left
up
down
refresh
minus
plus
help
search
save
print

handler : Function
必需,當按鈕被單擊時被執行。它的參數說明如下:
  event:Ext.EventObject
  toolel:Ext.Element
  Panel : Ext.Panel宿主panel

scope : Object
qtip:String/Object
一個tips字符串或者是tips config,用於Ext.QuickTip.register.

hidden : Boolean
on : Object
自定義事件處理器的config,為addListener所用。


示例如下:
tools:[{
id:'refresh',
qtip: 'Refresh form Data',
// hidden:true,
handler: function(event, toolEl, panel){
// refresh logic
}
}]
  注意:除了toggle之外,其他工具欄成員都只是提供一個可視化的圖標,沒有任何功能,所以,如果你要加入它們,得自己寫處理函數。


width : Number
component的寬度,單位用px,默認值為:auto。

x : Number
獲得組件的x,相當於panel.el.style.left

xtype : String
這個東西不用說了,見Ext.Component的config裡面的xtype。

y : Number
與x同理。