extjs4.0中文API整理02——Container

extjs4.0中文API整理02——Container
材料来自于extjs官网，翻译参考脚本娃娃的中文版


一、Ext.container.Container
1.任何可能包含其它Ext.Component组件的基类。 
容器对于所包含的组件的基本处理包括添加，插入和删除项目。


最常用的的容器类Ext.panel.Panel，Ext.window.Window和 Ext.tab.Panel。
如果开发者并不需要由上述类提供的功能，可以创建一个 轻量级容器

下面的代码演示了如何显式地创建一个容器:

// 显式创建一个容器
Ext.create("Ext.container.Container", {
    layout: {
        type: "hbox"
    },
    width: 400,
    renderTo: Ext.getBody(),
    border: 1,
    style: {borderColor:"#000000", borderStyle:"solid", borderWidth:"1px"},
    defaults: {
        labelWidth: 80,
        // 隐式创建容器通过指定的xtype
        xtype: "datefield",
        flex: 1,
        style: {
            padding: "10px"
        }
    },
    items: [{
        xtype: "datefield",
        name: "startDate",
        fieldLabel: "Start date"
    },{
        xtype: "datefield",
        name: "endDate",
        fieldLabel: "End date"
    }]
});

2.引申  defaults : Object/Function
此选项提供了为所有添加的组件上应用默认设置的途径, 这些属性要么是通过 items 配置项添加的， 
或者是通过 add 或者是通过 insert 方法添加的


默认属性将会应用到所有的子组件上，但是不会覆盖子组件本身已经有的属性 (可以参见 Ext.applyIf).


如果默认选项被指定为一个函数， 那么将使用当前容器作为作用域来调用这个函数( this 引用)， 
并且传递被添加的项目作为第一个参数。 调用产生的所有结果都将被作为默认参数应用到项目上。


例如，如需自动在 Ext.panel.Panel 所包含的每个子组件上应用padding属性， 
你可以设置: defaults: {bodyStyle: "padding:15px"} 。

用法:
defaults: { // defaults 将会应用所有的子组件上,而不是父容器
    autoScroll: true
},
items: [
    // panel1 已经存在 autoScroll: false 所以 defaults将不会应用
    {
        xtype: "panel",
        id: "panel1",
        autoScroll: false
    },
    // panel2 将会 autoScroll: true
    new Ext.panel.Panel({
        id: "panel2"
    })
]

3.引申  items : Object/Object[]
单个组件,或者是以数组形式定义的子组件集合 将会自动添加到容器中去


如果开发者没有配置layout属性， 默认是按顺序将子组件渲染到在容器中，
不考虑子组件的大小和定位。

用法:
// 单个组件
items: {...},
layout: "fit",    // 布局设置为fit

// 多个子组件
items: [{...}, {...}],
layout: "hbox", // 布局设置为hbox

每个子组件可以是:


一个 Component
一个组件配置对象
如果子组件是指定的,它的实际组件的类型将根据xtype选项进行实例化. 每个组件都有各自的xtype.


如果没有指定 xtype, 那么将会使用 defaultType，默认是panel.


说明:
Ext使用延迟渲染的方式. 子组件只有在必要的时候渲染. 
子组件第一次会自动布局(隐藏的时候不调整大小), 或者是响应一个doLayout布局.


不要指定contentEl 或者 html作为子组件.




二、布局
容器类的渲染委托给子组件的布局管理器类，由容器的 layout配置属性管理.


当开发者指定任意一个 items 容器配置, 或者动态添加 adding 容器到父容器的时候， 
记得要考虑如何布局这些子容器和容器的大小, 是否使用各自的layout 布局计划. 
默认情况下, 容器使用 Auto 布局计划， 将会按顺序添加子容器到父容器里面, 并且 不使用调整子容器的大小 。


一个常见的错误，当一个开发人员忽略指定layout（例如容器是GridPanels TreePanels被添加到容器的时候，没有指定layout）。
如果使用 默认的Auto 布局计划，将会没有子组件将被重新调整，或发生变化。 或者以任何方式调整父容器的大小。


某些布局管理器是可以动态添加的子组件。
但不包括以下 Ext.layout.container.Card，Ext.layout.container.Anchor，Ext.layout.container.VBox， Ext.layout.container.HBox，
和Ext.layout.container.Table布局。例如：

//  Create the GridPanel.
var myNewGrid = Ext.create("Ext.grid.Panel", {
    store: myStore,
    headers: myHeaders,
    title: "Results", // the title becomes the title of the tab
});

myTabPanel.add(myNewGrid); // Ext.tab.Panel implicitly uses Card
myTabPanel.setActiveTab(myNewGrid);

上面的例子中添加了一个新创建的GridPanel到TabPanel中。需要注意的是一个TabPanel中使用的 Ext.layout.container.Card作为其布局管理器，
这意味着它的所有子项的大小将会 Ext.layout.container.Fit自适应。


过度嵌套是一个常见的问题.一个过度嵌套的例子 当一个GridPanel添加到一个TabPanel面板 (它没有指定 layout) . 
开发者必须认识到这一点,一个GridPanel 是可以直接 添加组件的容器. 如果panel本身没有配置 layout 属性, 
那么这个过度嵌套的panel渲染 出来的大小将不会是开发者预期的那样.




三、通过远程添加配置
一个服务器端脚本可用于在服务器上动态生成的组件添加。一个例子的 
添加的GridPanel到TabPanel中某些参数的基础上由服务器生成的GridPanel其中：

// 执行一个Ajax请求来调用服务器端脚本：
Ext.Ajax.request({
    url: "gen-invoice-grid.php",
    // 发送额外的参数来获取服务器脚本
    params: {
        startDate: Ext.getCmp("start-date").getValue(),
        endDate: Ext.getCmp("end-date").getValue()
    },
    // 处理响应对象将其添加到TabPanel中：
    success: function(xhr) {
        var newComponent = eval(xhr.responseText);
        myTabPanel.add(newComponent); // 添加到TabPanel
        myTabPanel.setActiveTab(newComponent);
    },
    failure: function() {
        Ext.Msg.alert("Grid create failed", "Server communication failure");
    }
});

四、container常用配置项
(1)activeItem : String/Number
子组件id 或者是子组件所在容器的索引 
设置该属性的目的是设置那个子组件在最初显示的容器的布局上渲染. 
For example, activeItem: "itemId-1" or activeItem: 0 (容器中的第一个子组件).
activeItem 仅适用于布局样式 Ext.layout.container.Card and Ext.layout.container.Fit 并且一次只显示一个子组件。


(2)autoRender : Boolean/String/HTMLElement/Ext.Element
这个配置主要面向非 floating 组件, 这个组件可能显示可能不显示. 
这个配置允许组件首次使用 show 进行自我渲染来代替使用 renderTo 以及基于构造的渲染. 
如果 floating 为 true, 这个配置的值被忽略, 就相当于为 "true".


设置为 true 组件首次显示将自动渲染到文档的正文区域.


设置为一个元素, 或者元素的 ID 组件首次显示将自动渲染到指定元素.


Defaults to: false


(3)childEls : Object[]
一个描述组件的子元素的数组. 数组的每个成员是这些属性的对象:


name - 组件的子元素的属性名称.
itemId - ID结合组件的ID是子元素的ID.
id - 子元素的id.
如果数组成员是字符串, 它相当于 { name: m, itemId: m }.

例如, 组件呈现一个标题和正文:
Ext.create("Ext.Component", {
    renderTo: Ext.getBody(),
    renderTpl: [
        "<h1 id="{id}-title">{title}</h1>",
        "<p>{msg}</p>",
    ],
    renderData: {
        title: "Error",
        msg: "Something went wrong"
    },
    childEls: ["title"],
    listeners: {
        afterrender: function(cmp){
            // After rendering the component will have a title property
            cmp.title.setStyle({color: "red"});
        }
    }
});

(4)loader : Ext.ComponentLoader/Object
一个配置对象或者一个 Ext.ComponentLoader 实例加载组件远程内容.


(5)plugins : Object/Object[]
一个对象或者对象数组, 组件将提供自定义功能.
一个有效的插件唯一的要求是包含一个 init 方法, 接收一个 Ext.Component 类型参数. 
当组件被创建时, 如果有可用的插件, 组件将会调用每个插件的 init 方法, 并将自身的引用作为方法参数传递给它. 
然后, 每个插件就可以调用方法或者响应组件上的事件, 就像需要的那样提供自己的功能.




五、常用方法
(1)newExt.container.Container( Ext.Element/String/Object config ) : Object
an element :它被设置为在内部元件和使用它的id作为组分的id
a string : 它被假定为是一个现有元素的id和被用作组件id
anything else : 它被假定为是一个标准的配置对象，并且被施加到该组件


(2)add( Ext.Component[]/Ext.Component... ) : Ext.Component[]/Ext.Component
Adds 向当前容器中添加 Component(s).


描述:
触发 beforeadd事件在添加之前.
应用添加容器的默认属性值 default config values (具体参见 defaults).
Fires the add event after the component has been added.


具体说明:
如果子组件已经添加并渲染了，调用add的时候， 它将会渲染一个新的到父容器里面.
如果 配置了子组件的布局管理 layout, 容器在添加到时候会重新计算它的内部布局.


需要注意的是默认的布局管理器只是简单地按顺序呈现子组件 到内容区域，其后的执行不会调整子组件的大小.
如果要添加多个新的子组件，可以把它们作为一个数组传递给方法， 一次执行，这样只重新布局一次，以提高性能.

tb = new Ext.toolbar.Toolbar({
    renderTo: document.body
});  // toolbar is rendered
// add multiple items.
// (defaultType for Toolbar is "button")
tb.add([{text:"Button 1"}, {text:"Button 2"}]);

如果要添加的组件在已经存在组件之间,请使用insert 方法.


警告:
直接管理容器的BorderLayout布局管理器的组件可能不会被删除 或添加。