jQuery UI API - 可调整尺寸小部件（Resizable Widget）

所属类别

交互（Interactions）

用法

描述：使用鼠标改变元素的尺寸。

版本新增：1.0

依赖：

注释：jQuery UI 可调整尺寸（Resizable）插件让被选元素可调整尺寸（意味着它们有可拖拽的调整大小的手柄）。您可以指定一个或多个手柄，也可以指定宽度和高度的最小值也最大值。

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

快速导航

选项 方法 事件
alsoResizeanimateanimateDurationanimateEasingaspectRatioautoHidecancelcontainmentdelaydisableddistanceghostgridhandleshelpermaxHeightmaxWidthminHeightminWidth destroydisableenableoptionwidget createresizestartstop

alsoResize

类型：Selector 或 jQuery 或 Element

描述：一个或多个通过 resizable 元素进行同步调整尺寸的元素。

代码实例：

初始化带有指定 alsoResize 选项的 resizable：

$( ".selector" ).resizable({ alsoResize: "#mirror" });

在初始化后，获取或设置 alsoResize 选项：

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

// setter
$( ".selector" ).resizable( "option", "alsoResize", "#mirror" );

默认值：false

animate

类型：Boolean

描述：调整尺寸后动态变化到最终尺寸。

代码实例：

初始化带有指定 animate 选项的 resizable：

$( ".selector" ).resizable({ animate: true });

在初始化后，获取或设置 animate 选项：

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

// setter
$( ".selector" ).resizable( "option", "animate", true );

默认值：false

animateDuration

类型：Number 或 String

描述：当使用 [animate](#option-animate) 选项时，动画持续的时间。

支持多个类型：

  • Number：持续时间，以毫秒计。
  • String：一个命名的持续时间，比如 "slow" 或 "fast"。

代码实例：

初始化带有指定 animateDuration 选项的 resizable：

$( ".selector" ).resizable({ animateDuration: "fast" });

在初始化后，获取或设置 animateDuration 选项：

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

// setter
$( ".selector" ).resizable( "option", "animateDuration", "fast" );

默认值："slow"

animateEasing

类型：String

描述：当使用 [animate](#option-animate) 选项时要使用的 Easings。

代码实例：

初始化带有指定 animateEasing 选项的 resizable：

$( ".selector" ).resizable({ animateEasing: "easeOutBounce" });

在初始化后，获取或设置 animateEasing 选项：

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

// setter
$( ".selector" ).resizable( "option", "animateEasing", "easeOutBounce" );

默认值："swing"

aspectRatio

类型：Boolean 或 Number

描述：元素是否应该被限制在一个特定的长宽比。

支持多个类型：

  • Boolean：当设置为 true 时，元素将保持其原有的长宽比。
  • Number：强制在调整尺寸时元素保持特定的长宽比。

代码实例：

初始化带有指定 aspectRatio 选项的 resizable：

$( ".selector" ).resizable({ aspectRatio: true });

在初始化后，获取或设置 aspectRatio 选项：

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

// setter
$( ".selector" ).resizable( "option", "aspectRatio", true );

默认值：false

autoHide

类型：Boolean

描述：当用户鼠标没有悬浮在元素上时是否隐藏手柄。

代码实例：

初始化带有指定 autoHide 选项的 resizable：

$( ".selector" ).resizable({ autoHide: true });

在初始化后，获取或设置 autoHide 选项：

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

// setter
$( ".selector" ).resizable( "option", "autoHide", true );

默认值：false

cancel

类型：Selector

描述：防止从指定的元素上开始调整尺寸。

代码实例：

初始化带有指定 cancel 选项的 resizable：

$( ".selector" ).resizable({ cancel: ".cancel" });

在初始化后，获取或设置 cancel 选项：

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

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

默认值："input, textarea, button, select, option"

containment

类型：Selector 或 Element 或 String

描述：约束在指定元素或区域的边界内调整尺寸。

支持多个类型：

  • Selector：可调整尺寸元素将被包含在 selector 第一个元素的边界内。如果未找到元素，则不设置 containment。
  • Element：可调整尺寸元素将被包含在元素的边界内。
  • String：可能的值："parent"、"document"。

代码实例：

初始化带有指定 containment 选项的 resizable：

$( ".selector" ).resizable({ containment: "parent" });

在初始化后，获取或设置 containment 选项：

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

// setter
$( ".selector" ).resizable( "option", "containment", "parent" );

默认值：false

delay

类型：Number

描述：鼠标按下后直到调整尺寸开始为止的时间，以毫秒计。如果指定了该选项，调整只有在鼠标移动超过时间后才开始。该选项可以防止点击在某个元素上时不必要的调整尺寸。

代码实例：

初始化带有指定 delay 选项的 resizable：

$( ".selector" ).resizable({ delay: 150 });

在初始化后，获取或设置 delay 选项：

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

// setter
$( ".selector" ).resizable( "option", "delay", 150 );

默认值：0

disabled

类型：Boolean

描述：如果设置为 true，则禁用该 resizable。

代码实例：

初始化带有指定 disabled 选项的 resizable：

$( ".selector" ).resizable({ disabled: true });

在初始化后，获取或设置 disabled 选项：

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

// setter
$( ".selector" ).resizable( "option", "disabled", true );

默认值：false

distance

类型：Number

描述：鼠标按下后调整尺寸开始前必须移动的距离，以像素计。如果指定了该选项，调整只有在鼠标移动超过距离后才开始。该选项可以防止点击在某个元素上时不必要的调整尺寸。

代码实例：

初始化带有指定 distance 选项的 resizable：

$( ".selector" ).resizable({ distance: 30 });

在初始化后，获取或设置 distance 选项：

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

// setter
$( ".selector" ).resizable( "option", "distance", 30 );

默认值：1

ghost

类型：Boolean

描述：如果设置为 true，则为调整尺寸显示一个半透明的辅助元素。

代码实例：

初始化带有指定 ghost 选项的 resizable：

$( ".selector" ).resizable({ ghost: true });

在初始化后，获取或设置 ghost 选项：

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

// setter
$( ".selector" ).resizable( "option", "ghost", true );

默认值：false

grid

类型：Array

描述：把可调整尺寸元素对齐到网格，每个 x 和 y 像素。数组形式必须是 [ x, y ]。

代码实例：

初始化带有指定 grid 选项的 resizable：

$( ".selector" ).resizable({ grid: [ 20, 10 ] });

在初始化后，获取或设置 grid 选项：

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

// setter
$( ".selector" ).resizable( "option", "grid", [ 20, 10 ] );

默认值：false

handles

类型：String 或 Object

描述：可用于调整尺寸的处理程序。

支持多个类型：

  • String：一个逗号分隔的列表，列表值为下面所列出的任意值：n, e, s, w, ne, se, sw, nw, all。必要的处理程序由插件自动生成。
  • Object：支持下面的键：{ n, e, s, w, ne, se, sw, nw }。任何指定的值应该是一个匹配作为处理程序使用的 resizable 的子元素的 jQuery 选择器。

注释：当生成您自己的处理程序时，每个处理程序必须有 ui-resizable-handle class，也可以是适当的 appropriate ui-resizable-{direction} class，比如 ui-resizable-s。

代码实例：

初始化带有指定 handles 选项的 resizable：

$( ".selector" ).resizable({ handles: "n, e, s, w" });

在初始化后，获取或设置 handles 选项：

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

// setter
$( ".selector" ).resizable( "option", "handles", "n, e, s, w" );

默认值："e, s, se"

helper

类型：String

描述：一个将被添加到代理元素的 class 名称，用于描绘调整手柄拖拽过程中调整的轮廓。一旦调整完成，原来的元素则被重新定义尺寸。

代码实例：

初始化带有指定 helper 选项的 resizable：

$( ".selector" ).resizable({ helper: "resizable-helper" });

在初始化后，获取或设置 helper 选项：

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

// setter
$( ".selector" ).resizable( "option", "helper", "resizable-helper" );

默认值：false

maxHeight

类型：Number

描述：resizable 允许被调整到的最大高度。

代码实例：

初始化带有指定 maxHeight 选项的 resizable：

$( ".selector" ).resizable({ maxHeight: 300 });

在初始化后，获取或设置 maxHeight 选项：

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

// setter
$( ".selector" ).resizable( "option", "maxHeight", 300 );

默认值：null

maxWidth

类型：Number

描述：resizable 允许被调整到的最大宽度。

代码实例：

初始化带有指定 maxWidth 选项的 resizable：

$( ".selector" ).resizable({ maxWidth: 300 });

在初始化后，获取或设置 maxWidth 选项：

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

// setter
$( ".selector" ).resizable( "option", "maxWidth", 300 );

默认值：null

minHeight

类型：Number

描述：resizable 允许被调整到的最小高度。

代码实例：

初始化带有指定 minHeight 选项的 resizable：

$( ".selector" ).resizable({ minHeight: 150 });

在初始化后，获取或设置 minHeight 选项：

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

// setter
$( ".selector" ).resizable( "option", "minHeight", 150 );

默认值：10

minWidth

类型：Number

描述：resizable 允许被调整到的最小宽度。

代码实例：

初始化带有指定 minWidth 选项的 resizable：

$( ".selector" ).resizable({ minWidth: 150 });

在初始化后，获取或设置 minWidth 选项：

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

// setter
$( ".selector" ).resizable( "option", "minWidth", 150 );

默认值：10

方法

destroy()

类型：jQuery (plugin only)

描述：完全移除 resizable 功能。这会把元素返回到它的预初始化状态。

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

代码实例：

调用 destroy 方法：

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

disable()

类型：jQuery (plugin only)

描述：禁用 resizable。

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

代码实例：

调用 disable 方法：

$( ".selector" ).resizable( "disable" );

enable()

类型：jQuery (plugin only)

描述：启用 resizable。

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

代码实例：

调用 enable 方法：

$( ".selector" ).resizable( "enable" );

option( optionName )

类型：Object

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

  • optionName 类型：String 描述：要获取的选项的名称。

代码实例：

调用该方法：

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

option()

类型：PlainObject

描述：获取一个包含键/值对的对象，键/值对表示当前 resizable 选项哈希。

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

代码实例：

调用该方法：

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

option( optionName, value )

类型：jQuery (plugin only)

描述：设置与指定的 optionName 关联的 resizable 选项的值。

  • optionName 类型：String 描述：要设置的选项的名称。
  • value 类型：Object 描述：要为选项设置的值。

代码实例：

调用该方法：

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

option( options )

类型：jQuery (plugin only)

描述：为 resizable 设置一个或多个选项。

  • options 类型：Object 描述：要设置的 option-value 对。

代码实例：

调用该方法：

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

widget()

类型：jQuery

描述：返回一个包含 resizable 元素的 jQuery 对象。

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

代码实例：

调用 widget 方法：

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

事件

create( event, ui )

类型：resizecreate

描述：当 resizable 被创建时触发。

  • event 类型：Event
  • ui 类型：Object

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

代码实例：

初始化带有指定 create 回调的 resizable：

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

绑定一个事件监听器到 resizecreate 事件：

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

resize( event, ui )

类型：resize

描述：在调整尺寸期间当调整手柄拖拽时触发。

  • event 类型：Event
  • ui 类型：Object
    • element 类型：jQuery 描述：jQuery 对象，表示要被调整尺寸的元素。
    • helper 类型：jQuery 描述：jQuery 对象，表示被调整尺寸的助手（helper）。
    • originalElement 类型：jQuery 描述：jQuery 对象，表示被包裹之前的原始元素。
    • originalPosition 类型：Object 描述：resizable 调整前的位置，表示为 { top, left }。
    • originalSize 类型：Object 描述：resizable 调整前的尺寸，表示为 { width, height }。
    • position 类型：Object 描述：当前位置，表示为 { top, left }。
    • size 类型：Object 描述：当前位置，表示为 { width, height }。

代码实例：

初始化带有指定 resize 回调的 resizable：

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

绑定一个事件监听器到 resize 事件：

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

start( event, ui )

类型：resizestart

描述：当调整尺寸操作开始时触发。

  • event 类型：Event
  • ui 类型：Object
    • element 类型：jQuery 描述：jQuery 对象，表示要被调整尺寸的元素。
    • helper 类型：jQuery 描述：jQuery 对象，表示被调整尺寸的助手（helper）。
    • originalElement 类型：jQuery 描述：jQuery 对象，表示被包裹之前的原始元素。
    • originalPosition 类型：Object 描述：resizable 调整前的位置，表示为 { top, left }。
    • originalSize 类型：Object 描述：resizable 调整前的尺寸，表示为 { width, height }。
    • position 类型：Object 描述：当前位置，表示为 { top, left }。
    • size 类型：Object 描述：当前位置，表示为 { width, height }。

代码实例：

初始化带有指定 start 回调的 resizable：

$( ".selector" ).resizable({
  start: function( event, ui ) {}
});

绑定一个事件监听器到 resizestart 事件：

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

stop( event, ui )

类型：resizestop

描述：当调整尺寸操作停止时触发。

  • event 类型：Event
  • ui 类型：Object
    • element 类型：jQuery 描述：jQuery 对象，表示要被调整尺寸的元素。
    • helper 类型：jQuery 描述：jQuery 对象，表示被调整尺寸的助手（helper）。
    • originalElement 类型：jQuery 描述：jQuery 对象，表示被包裹之前的原始元素。
    • originalPosition 类型：Object 描述：resizable 调整前的位置，表示为 { top, left }。
    • originalSize 类型：Object 描述：resizable 调整前的尺寸，表示为 { width, height }。
    • position 类型：Object 描述：当前位置，表示为 { top, left }。
    • size 类型：Object 描述：当前位置，表示为 { width, height }。

代码实例：

初始化带有指定 stop 回调的 resizable：

$( ".selector" ).resizable({
  stop: function( event, ui ) {}
});

绑定一个事件监听器到 resizestop 事件：

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

实例

一个简单的 jQuery UI 可调整尺寸小部件（Resizable Widget）。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>可调整尺寸小部件（Resizable Widget）演示</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
  <style>
  #resizable {
    width: 100px;
    height: 100px;
    background: #ccc;
}    </style>
  <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>

<div id="resizable"></div>

<script>
$( "#resizable" ).resizable();
</script>

</body>
</html>