Dialog Widget

Categories: Widgets

version added: 1.0

Description: 在一个交互覆盖层中打开内容。

QuickNavExamples

Options

Methods

Extension Points

Events

对话框是一个悬浮窗口,包括一个标题栏和一个内容区域。对话框窗口可以移动,重新调整大小,默认情况下通过 'x' 图标关闭。

如果内容长度超过最大高度,一个滚动条会自动出现。

一个底部按钮栏和一个半透明的模式覆盖层是常见的添加选项。

焦点

当打开一个对话框时,焦点会自动移动到满足下面条件的第一个项目:

  1. 带有 autofocus 属性的对话框内的第一个元素
  2. 对话框内容内的第一个 :tabbable 元素
  3. 对话框按钮面板内的第一个 :tabbable 元素
  4. 对话框的关闭按钮
  5. 对话框本身

当打开时,对话框部件(Dialog Widget)确保通过 tab 切换对话框内元素间的焦点,不包括对话框外的元素。模态对话框防止鼠标用户点击对话框外的元素。

当关闭对话框时,焦点自动返回到之前对话框打开时获得焦点的元素上。

隐藏关闭按钮

在一些情况下,您可能想要隐藏关闭按钮,例如,在按钮面板中已经有一个关闭按钮的情况。最好的解决方法是通过 CSS。作为实例,您可以定义一个简单的规则,比如:

.no-close .ui-dialog-titlebar-close {
  display: none;
}

然后,您可以添加 no-close class 到任意的对话框,用来隐藏关闭按钮:

$( "#dialog" ).dialog({
  dialogClass: "no-close",
  buttons: [
    {
      text: "OK",
      click: function() {
        $( this ).dialog( "close" );
      }
    }
  ]
});

主题

对话框部件(Dialog Widget)使用 jQuery UI CSS 框架 来定义它的外观和感观的样式。如果需要使用对话框指定的样式,则可以使用下面的 CSS class 名称:

  • ui-dialog:对话框的外层容器。
    • ui-dialog-titlebar:包含对话框标题和关闭按钮的标题栏。
      • ui-dialog-title:对话框文本标题周围的容器。
      • ui-dialog-titlebar-close:对话框的关闭按钮。
    • ui-dialog-content:对话框内容周围的容器。这也是部件被实例化的元素。
    • ui-dialog-buttonpane:包含对话按钮的面板。只有当设置了 buttons 选项时才呈现。
      • ui-dialog-buttonset:按钮周围的容器。

此外,当设置了 modal 选项时,一个带有 ui-widget-overlay class 名称的元素被追加到 <body>

依赖

其他注意事项:

  • 该部件要求一些功能性的 CSS,否则将无法工作。如果您创建了一个自定义的主题,请使用小部件指定的 CSS 文件作为起点。

Options

appendToType: Selector

Default: "body"

dialog(和遮罩层,如果modal存在)应该被追加到哪个元素。

注意:当dialog处于打开状态的时候appendTo选项不应该被改变。(version added: 1.10.0)Code examples:

初始化带有指定 appendTo选项的 dialog:

$( ".selector" ).dialog({ appendTo: "#someElem" });

在初始化后,获取或设置appendTo 选项:

// getter
var appendTo = $( ".selector" ).dialog( "option", "appendTo" );

// setter
$( ".selector" ).dialog( "option", "appendTo", "#someElem" );

autoOpenType: Boolean

Default: true当设置为 true 时, dialog 会在初始化时自动打开. 如果为 false dialog 将会继续隐藏直到调用open()方法 。Code examples:

初始化带有指定 autoOpen选项的 dialog:

$( ".selector" ).dialog({ autoOpen: false });

在初始化后,获取或设置autoOpen 选项:

// getter
var autoOpen = $( ".selector" ).dialog( "option", "autoOpen" );

// setter
$( ".selector" ).dialog( "option", "autoOpen", false );

buttonsType: Object or Array

Default: {}指定哪些按钮应该在dialog上显示。 回调的上下文是dialog元素(愚人码头注:this指向); 如果你需要访问按钮, 可以利用事件对象的目标元素。支持多个类型:

  • Object: 键是按钮标签,值是点击相关按钮时执行的回调函数。
  • Array: 该数组的每个元素必须是 一个定义特性,属性,和按钮上设置的事件处理程序的对象。

Code examples:

初始化带有指定 buttons选项的 dialog:

$( ".selector" ).dialog({ buttons: [ { text: "Ok", click: function() { $( this ).dialog( "close" ); } } ] });

在初始化后,获取或设置buttons 选项:

// getter
var buttons = $( ".selector" ).dialog( "option", "buttons" );

// setter
$( ".selector" ).dialog( "option", "buttons", [ { text: "Ok", click: function() { $( this ).dialog( "close" ); } } ] );

closeOnEscapeType: Boolean

Default: true指定具有焦点的dialog,在用户按下退出(ESC)键时,是否应该关闭 。Code examples:

初始化带有指定 closeOnEscape选项的 dialog:

$( ".selector" ).dialog({ closeOnEscape: false });

在初始化后,获取或设置closeOnEscape 选项:

// getter
var closeOnEscape = $( ".selector" ).dialog( "option", "closeOnEscape" );

// setter
$( ".selector" ).dialog( "option", "closeOnEscape", false );

closeTextType: String

Default: "close"指定关闭按钮的文本。 注意,关闭文本在使用标准的主题时,是隐藏的(visibly:hidden)。Code examples:

初始化带有指定 closeText选项的 dialog:

$( ".selector" ).dialog({ closeText: "hide" });

在初始化后,获取或设置closeText 选项:

// getter
var closeText = $( ".selector" ).dialog( "option", "closeText" );

// setter
$( ".selector" ).dialog( "option", "closeText", "hide" );

dialogClassType: String

Default: ""在使用额外附加的主题时,指定dialog的类名称,这些样式添加到dialog上。Code examples:

初始化带有指定 dialogClass选项的 dialog:

$( ".selector" ).dialog({ dialogClass: "alert" });

在初始化后,获取或设置dialogClass 选项:

// getter
var dialogClass = $( ".selector" ).dialog( "option", "dialogClass" );

// setter
$( ".selector" ).dialog( "option", "dialogClass", "alert" );

draggableType: Boolean

Default: true如果设置为true, dialog将可以使用标题栏实现拖动。需要包含 jQuery UI Draggable 部件Code examples:

初始化带有指定 draggable选项的 dialog:

$( ".selector" ).dialog({ draggable: false });

在初始化后,获取或设置draggable 选项:

// getter
var draggable = $( ".selector" ).dialog( "option", "draggable" );

// setter
$( ".selector" ).dialog( "option", "draggable", false );

heightType: Number or String

Default: "auto"设置对话框的高度(单位:像素)。支持多个类型:

  • Number: 高度,单位:像素。
  • String: 唯一支持的字符串值为"auto",这将使对话框高度根据其内容进行自动调整。

Code examples:

初始化带有指定 height选项的 dialog:

$( ".selector" ).dialog({ height: 400 });

在初始化后,获取或设置height 选项:

// getter
var height = $( ".selector" ).dialog( "option", "height" );

// setter
$( ".selector" ).dialog( "option", "height", 400 );

hideType: Boolean or Number or String or Object

Default: nulldialog关闭(隐藏)时的动画效果。支持多个类型:

  • Boolean: 当设置为false, 将不使用动画效果,该dialog会立即被隐藏。 如果设置为true, 该dialog将会以默认的持续时间和默认的效果淡出。
  • Number: 该dialog将以指定的时间和默认的效果淡出。
  • String: 该dialog将使用指定的效果被隐藏。 该值可以是一个jQuery内置的动画方法的名称, 如"slideUp", 或一个 jQuery UI 效果的名称, 如"fold"。 在这两种情况下,将使用默认持续时间和默认的动画效果。
  • Object: 如果该值是一个对象, 那么 effect, delay, duration, 和easing可能要提供。 如果 effect 属性包含一个jQuery方法的名称, 那么该方法将被使用; 否则它被假定为是一个jQuery UI的效果的名称。 当使用jQuery UI 支持额外设置 的效果 , 你可以在对象中包含那些设置 并且它们将被传递到的效果。如果duration持续时间或easing属性被省略, 那么默认值将被使用。 如果effect被省略, 那么"fadeOut" 将被使用。如果delay被省略, 那么将不使用延迟。

Code examples:

初始化带有指定 hide选项的 dialog:

$( ".selector" ).dialog({ hide: { effect: "explode", duration: 1000 } });

在初始化后,获取或设置hide 选项:

// getter
var hide = $( ".selector" ).dialog( "option", "hide" );

// setter
$( ".selector" ).dialog( "option", "hide", { effect: "explode", duration: 1000 } );

maxHeightType: Number

Default: falsedialog可以调整的最大高度,以像素为单位。Code examples:

初始化带有指定 maxHeight选项的 dialog:

$( ".selector" ).dialog({ maxHeight: 600 });

在初始化后,获取或设置maxHeight 选项:

// getter
var maxHeight = $( ".selector" ).dialog( "option", "maxHeight" );

// setter
$( ".selector" ).dialog( "option", "maxHeight", 600 );

maxWidthType: Number

Default: falsedialog可以调整的最大宽度,以像素为单位。Code examples:

初始化带有指定 maxWidth选项的 dialog:

$( ".selector" ).dialog({ maxWidth: 600 });

在初始化后,获取或设置maxWidth 选项:

// getter
var maxWidth = $( ".selector" ).dialog( "option", "maxWidth" );

// setter
$( ".selector" ).dialog( "option", "maxWidth", 600 );

minHeightType: Number

Default: 150dialog可以调整的最小高度,以像素为单位。Code examples:

初始化带有指定 minHeight选项的 dialog:

$( ".selector" ).dialog({ minHeight: 200 });

在初始化后,获取或设置minHeight 选项:

// getter
var minHeight = $( ".selector" ).dialog( "option", "minHeight" );

// setter
$( ".selector" ).dialog( "option", "minHeight", 200 );

minWidthType: Number

Default: 150dialog可以调整的最小宽度,以像素为单位。Code examples:

初始化带有指定 minWidth选项的 dialog:

$( ".selector" ).dialog({ minWidth: 200 });

在初始化后,获取或设置minWidth 选项:

// getter
var minWidth = $( ".selector" ).dialog( "option", "minWidth" );

// setter
$( ".selector" ).dialog( "option", "minWidth", 200 );

modalType: Boolean

Default: false如果设置为true,该dialog将会有遮罩层; 页面上的其他项目将被禁用, 即,不能交互。 遮罩层创建对话框下方,但高于其它页面元素。Code examples:

初始化带有指定 modal选项的 dialog:

$( ".selector" ).dialog({ modal: true });

在初始化后,获取或设置modal 选项:

// getter
var modal = $( ".selector" ).dialog( "option", "modal" );

// setter
$( ".selector" ).dialog( "option", "modal", true );

positionType: Object or String or Array

Default: { my: "center", at: "center", of: window }

指定dialog显示的位置。该dialog将会处理冲突 ,使得尽可能多的dialog尽可能地可见。

注意: 不赞成使用 StringArray 格式。

支持多个类型:

  • Object: 确定dialog打开时的位置。 of选项默认为窗口, 但您可以指定其他元素定位。 你可以参考jQuery UI Position实用工具,了解各种选项的更多细节。
  • String:一个字符串,表示可视区内的位置。可能的值:"center", "left", "right", "top", "bottom".
  • Array: 一个包含相对于可见区域左上角x, y偏移坐标(单位为像素) 的数组, 或 一个可能值的字符串名称。

Code examples:

初始化带有指定 position选项的 dialog:

$( ".selector" ).dialog({ position: { my: "left top", at: "left bottom", of: button } });

在初始化后,获取或设置position 选项:

// getter
var position = $( ".selector" ).dialog( "option", "position" );

// setter
$( ".selector" ).dialog( "option", "position", { my: "left top", at: "left bottom", of: button } );

resizableType: Boolean

Default: true如果设置为true, 那么dialog允许调整大小。需要包含jQuery UI Resizable widgetCode examples:

初始化带有指定 resizable选项的 dialog:

$( ".selector" ).dialog({ resizable: false });

在初始化后,获取或设置resizable 选项:

// getter
var resizable = $( ".selector" ).dialog( "option", "resizable" );

// setter
$( ".selector" ).dialog( "option", "resizable", false );

showType: Boolean or Number or String or Object

Default: nulldialog打开(显示)时的动画效果。支持多个类型:

  • Boolean: 当设置为false, 将不使用动画效果,该dialog会立即被隐藏。 如果设置为true, 该dialog将会以默认的持续时间和默认的效果淡出。
  • Number: 该dialog将以指定的时间和默认的效果淡出。
  • String: 该dialog将使用指定的效果被隐藏。 该值可以是一个jQuery内置的动画方法的名称, 如"slideUp", 或一个 jQuery UI 效果的名称, 如"fold"。 在这两种情况下,将使用默认持续时间和默认的动画效果。
  • Object: 如果该值是一个对象, 那么 effect, delay, duration, 和easing可能要提供。 如果 effect 属性包含一个jQuery方法的名称, 那么该方法将被使用; 否则它被假定为是一个jQuery UI的效果的名称。 当使用jQuery UI 支持额外设置 的效果 , 你可以在对象中包含那些设置 并且它们将被传递到的效果。如果duration持续时间或easing属性被省略, 那么默认值将被使用。 如果effect被省略, 那么"fadeOut" 将被使用。如果delay被省略, 那么将不使用延迟。

Code examples:

初始化带有指定 show选项的 dialog:

$( ".selector" ).dialog({ show: { effect: "blind", duration: 800 } });

在初始化后,获取或设置show 选项:

// getter
var show = $( ".selector" ).dialog( "option", "show" );

// setter
$( ".selector" ).dialog( "option", "show", { effect: "blind", duration: 800 } );

titleType: String

Default: null指定dialog的标题文字。 如果值为null,那么该dialog 元素上的title属性将被使用。Code examples:

初始化带有指定 title选项的 dialog:

$( ".selector" ).dialog({ title: "Dialog Title" });

在初始化后,获取或设置title 选项:

// getter
var title = $( ".selector" ).dialog( "option", "title" );

// setter
$( ".selector" ).dialog( "option", "title", "Dialog Title" );

widthType: Number

Default: 300设置dialog的宽度(单位:像素)。Code examples:

初始化带有指定 width选项的 dialog:

$( ".selector" ).dialog({ width: 500 });

在初始化后,获取或设置width 选项:

// getter
var width = $( ".selector" ).dialog( "option", "width" );

// setter
$( ".selector" ).dialog( "option", "width", 500 );

Methods

close()Returns: jQuery (plugin only)

关闭dialog.

  • 该方法不接受任何参数。

Code examples:

调用 close 方法:

$( ".selector" ).dialog( "close" );

destroy()Returns: jQuery (plugin only)

完全移除 dialog 功能. 这将使元素返回到之前的初始化状态.

  • 该方法不接受任何参数。

Code examples:

调用 destroy 方法:

$( ".selector" ).dialog( "destroy" );

isOpen()Returns: Boolean

确定 dialog 当前是否打开状态。

  • 该方法不接受任何参数。

Code examples:

调用 isOpen 方法:

var isOpen = $( ".selector" ).dialog( "isOpen" );

moveToTop()Returns: jQuery (plugin only)

移动dialog到所有dialog堆栈的顶部。(愚人码头注:理解为 z-index层级最高)

  • 该方法不接受任何参数。

Code examples:

调用 moveToTop 方法:

$( ".selector" ).dialog( "moveToTop" );

open()Returns: jQuery (plugin only)

打开 dialog。

  • 该方法不接受任何参数。

Code examples:

调用 open 方法:

$( ".selector" ).dialog( "open" );

option( optionName )Returns: Object

获取当前与指定的 optionName 关联的值。

  • optionNameType: String要获取值的选项的名称。

Code examples:

调用该方法:

var isDisabled = $( ".selector" ).dialog( "option", "disabled" );

option()Returns: PlainObject

获取一个包含键/值对的对象,键/值对表示当前 dialog 选项哈希。

  • 该方法不接受任何参数。

Code examples:

调用该方法:

var options = $( ".selector" ).dialog( "option" );

option( optionName, value )Returns: jQuery (plugin only)

设置与指定的 optionName 关联的 dialog 选项的值。

  • optionNameType: String要设置的选项的名称。
  • valueType: Object要为选项设置的值。

Code examples:

调用该方法:

$( ".selector" ).dialog( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

为 dialog 设置一个或多个选项。

  • optionsType: Object要设置的 option-value 对。

Code examples:

调用该方法:

$( ".selector" ).dialog( "option", { disabled: true } );

widget()Returns: jQuery

返回一个包含 生成包裹元素 的 jQuery 对象。

  • 该方法不接受任何参数。

Code examples:

调用 widget 方法:

var widget = $( ".selector" ).dialog( "widget" );

扩展点(Extension Points)

dialog小部件是widget factory构建的,并且可以扩展。 当扩展部件时, 你必须覆盖或添加新的行为到现有的方法。 下列方法被提供作为扩展点 用相同的API稳定性如上所列的plugin methods。 有关小部件扩展的更多信息, 请参阅使用Widget Factory 扩展小部件

_allowInteraction( event )Returns: Boolean

带遮罩的对话框不允许用户与对话框下面元素进行交互。 这可能会对 不属于该dialog的子元素那些绝对定位的其他元素产生问题。 _allowInteraction()方法确定用户是否应被允许与给定的目标元素进行交互; 因此, 它可用于不属于该dialog的子元素白名单中的元素 但你希望用户能够使用。

Code examples:

允许Select2插件在遮罩对话框中使用。 _super()调用确保该对话框中的元素仍然可以交互。

_allowInteraction: function( event ) {
  return !!$( event.target ).is( ".select2-input" ) || this._super( event );
}

Events

beforeClose( event, ui )Type: dialogbeforeclose

当dialog即将关闭时触发。 如果取消,dialog将不会关闭。

注意:ui 对象是空的,这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 beforeClose 回调的 dialog:

$( ".selector" ).dialog({
  beforeClose: function( event, ui ) {}
});

绑定一个事件监听器到 dialogbeforeclose 事件:

$( ".selector" ).on( "dialogbeforeclose", function( event, ui ) {} );

close( event, ui )Type: dialogclose

当dialog关闭时触发。

注意:ui 对象是空的,这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 close 回调的 dialog:

$( ".selector" ).dialog({
  close: function( event, ui ) {}
});

绑定一个事件监听器到 dialogclose 事件:

$( ".selector" ).on( "dialogclose", function( event, ui ) {} );

create( event, ui )Type: dialogcreate

在创建dialog时触发。

注意:ui 对象是空的,这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 create 回调的 dialog:

$( ".selector" ).dialog({
  create: function( event, ui ) {}
});

绑定一个事件监听器到 dialogcreate 事件:

$( ".selector" ).on( "dialogcreate", function( event, ui ) {} );

drag( event, ui )Type: dialogdrag

在dialog正在被拖动时触发。

  • eventType: Event
  • uiType: Object
    • positionType: Objectdialog当前的CSS position(位置)对象。
    • offsetType: Objectdialog当前的offset position(偏移位置)对象。

Code examples:

初始化带有指定 drag 回调的 dialog:

$( ".selector" ).dialog({
  drag: function( event, ui ) {}
});

绑定一个事件监听器到 dialogdrag 事件:

$( ".selector" ).on( "dialogdrag", function( event, ui ) {} );

dragStart( event, ui )Type: dialogdragstart

当用户开始拖动dialog时触发。

  • eventType: Event
  • uiType: Object
    • positionType: Objectdialog当前的CSS position(位置)对象。
    • offsetType: Objectdialog当前的offset position(偏移位置)对象。

Code examples:

初始化带有指定 dragStart 回调的 dialog:

$( ".selector" ).dialog({
  dragStart: function( event, ui ) {}
});

绑定一个事件监听器到 dialogdragstart 事件:

$( ".selector" ).on( "dialogdragstart", function( event, ui ) {} );

dragStop( event, ui )Type: dialogdragstop

当dialog 停止拖动时触发。

  • eventType: Event
  • uiType: Object
    • positionType: Objectdialog当前的CSS position(位置)对象。
    • offsetType: Objectdialog当前的offset position(偏移位置)对象。

Code examples:

初始化带有指定 dragStop 回调的 dialog:

$( ".selector" ).dialog({
  dragStop: function( event, ui ) {}
});

绑定一个事件监听器到 dialogdragstop 事件:

$( ".selector" ).on( "dialogdragstop", function( event, ui ) {} );

focus( event, ui )Type: dialogfocus

当对话框获取焦点时触发此事件。

注意:ui 对象是空的,这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 focus 回调的 dialog:

$( ".selector" ).dialog({
  focus: function( event, ui ) {}
});

绑定一个事件监听器到 dialogfocus 事件:

$( ".selector" ).on( "dialogfocus", function( event, ui ) {} );

open( event, ui )Type: dialogopen

当对话框打开后,触发此事件。

注意:ui 对象是空的,这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 open 回调的 dialog:

$( ".selector" ).dialog({
  open: function( event, ui ) {}
});

绑定一个事件监听器到 dialogopen 事件:

$( ".selector" ).on( "dialogopen", function( event, ui ) {} );

resize( event, ui )Type: dialogresize

当对话框大小改变时,触发此事件。

  • eventType: Event
  • uiType: Object
    • originalPositionType: Object对话框被调整大小 之前的CSS position(位置)对象 。
    • positionType: Object对话框当前的CSS position(位置)对象。
    • originalSizeType: Object对话框被调整大小 之前的size(尺寸)对象 。
    • sizeType: Object对话框当前的size(尺寸)对象。

Code examples:

初始化带有指定 resize 回调的 dialog:

$( ".selector" ).dialog({
  resize: function( event, ui ) {}
});

绑定一个事件监听器到 dialogresize 事件:

$( ".selector" ).on( "dialogresize", function( event, ui ) {} );

resizeStart( event, ui )Type: dialogresizestart

当开始改变对话框大小时,触发此事件。

  • eventType: Event
  • uiType: Object
    • originalPositionType: Object对话框被调整大小 之前的CSS position(位置)对象 。
    • positionType: Object对话框当前的CSS position(位置)对象。
    • originalSizeType: Object对话框被调整大小 之前的size(尺寸)对象 。
    • sizeType: Object对话框当前的size(尺寸)对象。

Code examples:

初始化带有指定 resizeStart 回调的 dialog:

$( ".selector" ).dialog({
  resizeStart: function( event, ui ) {}
});

绑定一个事件监听器到 dialogresizestart 事件:

$( ".selector" ).on( "dialogresizestart", function( event, ui ) {} );

resizeStop( event, ui )Type: dialogresizestop

当对话框改变大小后,触发此事件。

  • eventType: Event
  • uiType: Object
    • originalPositionType: Object对话框被调整大小 之前的CSS position(位置)对象 。
    • positionType: Object对话框当前的CSS position(位置)对象。
    • originalSizeType: Object对话框被调整大小 之前的size(尺寸)对象 。
    • sizeType: Object对话框当前的size(尺寸)对象。

Code examples:

初始化带有指定 resizeStop 回调的 dialog:

$( ".selector" ).dialog({
  resizeStop: function( event, ui ) {}
});

绑定一个事件监听器到 dialogresizestop 事件:

$( ".selector" ).on( "dialogresizestop", function( event, ui ) {} );

Example:

一个简单的 jQuery UI 对话框(Dialog)。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>dialog demo</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
  <script src="//code.jquery.com/jquery-1.10.2.js"></script>
  <script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>

<button id="opener">open the dialog</button>
<div id="dialog" title="Dialog Title">I'm a dialog</div>

<script>
$( "#dialog" ).dialog({ autoOpen: false });
$( "#opener" ).click(function() {
  $( "#dialog" ).dialog( "open" );
});
</script>

</body>
</html>