提供功能:

- 页面上的覆盖层;
- Overlay 基类, 扩展出 Dialog/Popup ;
- 见 Overlay demo
- 调研报告, 见 slide

### Overlay 最简单的使用

#### new S.Overlay(container, config)

当不传入 container , 表示新建 Overlay, 如果传入已有容器, 表示在此容器基础上产生 Overlay.

    KISSY.ready(function(S) {
        var popup = new S.Overlay({
            trigger: '#link',
            width: 300,
            height: 200
        });
    });

### Config

#### container - `null | String | HTMLElement`

Overlay 容器, 默认为 null 时, 表示新建 DOM;

    new S.Overlay('#popup1', {});

#### containerCls - `String`

容器 class , 默认 class 为 'ks-overlay'.

#### content - `undefined | String`

默认为 undefined, 不设置内容.

#### bdCls - `String`

body class, 默认为 'ks-overlay-bd'.

#### trigger - `null | String | HTMLElement`

触发元素, 默认为 null 时, overlay 动作需要另外 js 指定.

    var test = new S.Overlay('#popup1', {
        width: 100,
        height: 100
    });
    Event.on('#btn', 'click', function(){
        test.show();
    });

#### triggerType - `String`

触发类型, 'mouse' or 'click', 默认为 'click'.

#### width - `Number`

容器宽度, 默认为 0.

#### height - `Number`

容器高度, 默认为 0.

#### zIndex - `Number`

z-index 值, 默认为9999.

#### xy - `Array`

相对 page 定位, 有效值为 [n, m].

#### align - `Object`

相对指定 node or viewport 定位, 提供子选项

    align: {
        // 参考元素, falsy 值为可视区域, 'trigger' 为触发元素, 其他为指定元素
        node: null,
        // ['tl', 'tr'] 表示 overlay 的 tl 与参考节点的 tr 对齐
        points: [POSITION_ALIGN.CC, POSITION_ALIGN.CC],
        // 水平, 垂直方向上的偏移, 有效值为 [n, m]
        offset: [0,0]
    }

align 使用示例

    var test = new S.Overlay('#popup2', {
        trigger: '#btn1',
        triggerType: 'click',
        width: 300,
        height: 200,
        align: {
            node: 'trigger',
            points: ['tr', 'tl'],
            offset: [50, 0]
        }
    });

#### mask - `Boolean`

是否显示遮盖层, 默认为不显示.

#### shim - `Boolean`

是否需要垫片, IE6 下默认需要.

### Memeber

#### container - `HTMLElement`

指向容器元素.

#### config - `Object`

如上列出的配置选项.

#### trigger - `HTMLElement`

触发元素.

#### body - `HTMLElement`

容器 body 元素, 当 content 为空时, 不创建 ks-overlay-bd 层, 且 body 直接指向 container.

#### shim - `HTMLElement`

垫片层, 如果选项中 shim 设置为 true.

### Events

#### show

Overlay 显示之后触发的事件.

#### hide

Overlay 隐藏之后触发的事件.

### Methods

#### show()

显示 Overlay.

#### hide()

隐藏 Overlay.

#### move(x, y)

将 Overlay 移动到指定位置上, 绝对位置.

#### align(node, points, offset)

将 Overlay 定位到指定节点的特定位置上, 如果没有指定 node, 会默认使用 config 中的 align 设置.

#### center()

将 Overlay 居中到当前可视区域上.

#### setBody()

设置 body 内容.

### Widgets

#### Dialog `new S.Dialog(container, config)`

S.Dialog 增加了 header 和 footer, 因此, config 和 method 做了对应调整.

    config:
        header: '',                     // header 内容
        footer: '',                     // footer 内容

        containerCls: CLS_CONTAINER,    // 设置 containerCls , 默认为 'ks-overlay ks-dialog'
        hdCls: CLS_PREFIX + 'hd',       // 设置 header 的 class , 默认为 ks-dialog-hd
        bdCls: CLS_PREFIX + 'bd',       // 设置 body 的 class , 默认为 ks-dialog-bd
        ftCls: CLS_PREFIX + 'ft',       // 设置 footer 的 class , 默认为 ks-dialog-ft
        closeBtnCls: CLS_PREFIX + 'close',      // 设置关闭按钮的 class, 默认为 ks-dialog-close

        width: 400,                     // 设置容器宽度, 默认为 400
        height: 300,                    // 设置容器高度, 默认为 300
        closable: true                  // 是否需要关闭按钮, 默认需要
    Member:
        header                          // 对话框头部的HTML元素
        footer                          // 对话框尾部的HTML元素
        manager                         // 当前 DialogManager, 下面会介绍
    Method:
        setHeader()                     // 设置 header 内容
        setFooter()                     // 设置 footer 内容

#### DialogManager `S.DialogManager`

用于管理页面上所有的 Dialog , 目前提供功能较少.

    Method:
        register()                    // 将 dialog 实例注册到 DialogManager 中
                                      // 且, dialog 示例也可以通过自己的 manager 访问到这个 DialogManager.
        hideAll()                     // 隐藏页面上所有的 dialog

    KISSY.ready(function(S){
        var dialog = S.Dialog({
            trigger: '#btn4',
            containerCls: 'dialog4',
            width: 400,
            height: 300,
            title: 'this is title',
            footer: 'footer',
            content: 'content',
            mask: false
        });

        S.Event.on('#btn5', 'click', function(e){
            dialog.manager.hideAll();
            // or S.DialogManager.hideAll();
        });
    });

#### Popup `new S.Popup(container, config)`

S.Popup 同 S.Overlay 一致, 没有额外的 config 和 method, 简单使用如下:

    KISSY.ready(function(S){
        S.each(S.query('#multi li'), function(t){
            var popup = new S.Popup('#popup3', {
                trigger: t,
                triggerType: 'mouse',
                triggerLater: true
            });
            popup.on('show',function(){
               popup.setBody(S.DOM.html(t));
            });
        });
    });

### 其他相关

#### Mask `new S.Mask();`

创建一个遮盖层.

#### Shim `new S.Mask({ shim: true });`

创建一个垫片.

Mask 和 Shim 有自己的配置选项和方法, 相对于 Overlay 独立. 具体如下:

    Config:
        shim: false,        // 是 shim 层还是 mask 层
        opacity: .6,        // 指定 mask 的透明度
        style: ''           // 指定样式

    Member:
        iframe              // shim 和 mask 下都会有, mask 时, 标准浏览器也用 iframe 元素生成mask
        config              // 配置选项
        layer               // mask时, 且在IE下才会有这个成员, 由于 iframe 不能设置 background,
                            // 所以添加了一个 div 作为 layer , 设置透明度及背景颜色
    Method:
        show()              // 显示
        hide()              // 隐藏
        toggle()            // 切换显示/隐藏
        setSize()           // 设置宽高
        setOffset()         // 设置位置, 绝对位置

更多例子请参见 demo.

home › overlay :