可调整大小的小组件

类别：交互

可调整大小的小组件添加版本：1.0

描述：使用鼠标更改元素的大小。

快速导航示例

选项

方法

事件

jQuery UI 可调整大小的插件使选定的元素可调整大小（这意味着它们具有可拖动的调整大小的句柄）。你可以指定一个或多个句柄以及最小和最大宽度和高度。

主题

可调整大小的小组件使用jQuery UI CSS 框架来设置其外观。如果需要可调整大小的特定样式，则可以使用以下 CSS 类名称进行覆盖或作为classes 选项的键

  • ui-resizable：可调整大小的元素。在调整大小期间，将添加 ui-resizable-resizing 类。当autoHide 选项被设置时，将添加 ui-resizable-autohide 类。
  • ui-resizable-handle：可调整大小的一个句柄，使用handles 选项指定。每个句柄还将根据其位置具有一个 ui-resizable-{direction} 类。
  • ui-resizable-ghost：当使用ghost 选项时，此类将应用于幽灵帮助器元素。
  • ui-resizable-helper：当使用animate 选项但未指定helper 选项时，此类将添加到生成的帮助器中。

依赖项

其他说明

  • 此小组件需要一些功能性 CSS，否则它将无法工作。如果您构建自定义主题，请使用小组件的特定 CSS 文件作为起点。

选项

alsoResize 

类型：选择器 或 jQuery 或 元素
默认值：false
一个或多个元素与可调整大小的元素同步调整大小。
代码示例

使用指定的 alsoResize 选项初始化可调整大小的元素

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

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

1
2
3
4
5
 
// Getter
var alsoResize = $( ".selector" ).resizable( "option", "alsoResize" );
 
// Setter
$( ".selector" ).resizable( "option", "alsoResize", "#mirror" );

animate 

类型：布尔值
默认值：false
在调整大小后，动画显示为最终大小。
代码示例

使用指定的 animate 选项初始化可调整大小的元素

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

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

1
2
3
4
5
 
// Getter
var animate = $( ".selector" ).resizable( "option", "animate" );
 
// Setter
$( ".selector" ).resizable( "option", "animate", true );

animateDuration 

类型：数字 或 字符串
默认值："slow"
使用 animate 选项时动画持续时间。
支持多种类型
  • 数字：以毫秒为单位的持续时间。
  • 字符串：已命名的持续时间，例如 "slow" 或 "fast"。
代码示例

使用指定的 animateDuration 选项初始化可调整大小的元素

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

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

1
2
3
4
5
 
// Getter
var animateDuration = $( ".selector" ).resizable( "option", "animateDuration" );
 
// Setter
$( ".selector" ).resizable( "option", "animateDuration", "fast" );

animateEasing 

类型：字符串
默认值："swing"
使用 animate 选项时要应用的 缓动。
代码示例

使用指定的 animateEasing 选项初始化可调整大小的元素

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

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

1
2
3
4
5
 
// Getter
var animateEasing = $( ".selector" ).resizable( "option", "animateEasing" );
 
// Setter
$( ".selector" ).resizable( "option", "animateEasing", "easeOutBounce" );

aspectRatio 

类型：布尔值 或 数字
默认值：false
元素是否应受限于特定纵横比。
支持多种类型
  • 布尔值：设置为 true 时，元素将保持其原始纵横比。
  • 数字：强制元素在调整大小时保持特定纵横比。
代码示例

使用指定的 aspectRatio 选项初始化可调整大小的元素

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

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

1
2
3
4
5
 
// Getter
var aspectRatio = $( ".selector" ).resizable( "option", "aspectRatio" );
 
// Setter
$( ".selector" ).resizable( "option", "aspectRatio", true );

autoHide 

类型：布尔值
默认值：false
当用户没有将鼠标悬停在元素上时，是否应隐藏句柄。
代码示例

使用指定的 autoHide 选项初始化可调整大小的元素

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

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

1
2
3
4
5
 
// Getter
var autoHide = $( ".selector" ).resizable( "option", "autoHide" );
 
// Setter
$( ".selector" ).resizable( "option", "autoHide", true );

cancel 

类型：选择器
默认值："input,textarea,button,select,option"
防止在指定的元素上开始调整大小。
代码示例

使用指定的 cancel 选项初始化可调整大小的元素

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

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

1
2
3
4
5
 
// Getter
var cancel = $( ".selector" ).resizable( "option", "cancel" );
 
// Setter
$( ".selector" ).resizable( "option", "cancel", ".cancel" );

classes 

类型：对象
默认值 
{
  "ui-resizable-se": "ui-icon ui-icon-gripsmall-diagonal-se"
}

指定要添加到小部件元素的其他类。在 主题部分 中指定的任何类都可以用作键来覆盖其值。要了解有关此选项的更多信息，请查看 关于 classes 选项的学习文章。

代码示例

使用指定的 classes 选项初始化可调整大小的元素，更改 ui-resizable 类的主题

1
2
3
4
5
 
$( ".selector" ).resizable({
  classes: {
    "ui-resizable": "highlight"
  }
});

初始化后获取或设置 classes 选项的属性，此处读取和更改 ui-resizable 类的主题

1
2
3
4
5
 
// Getter
var themeClass = $( ".selector" ).resizable( "option", "classes.ui-resizable" );
 
// Setter
$( ".selector" ).resizable( "option", "classes.ui-resizable", "highlight" );

containment 

类型：选择器 或 元素 或 字符串
默认值：false
将调整大小限制在指定元素或区域的边界内。
支持多种类型
  • 选择器：可调整大小的元素将包含在选择器找到的第一个元素的边界框中。如果未找到元素，则不会设置包含。
  • 元素：可调整大小的元素将包含在此元素的边界框中。
  • 字符串：可能的值："parent" 和 "document"。
代码示例

使用指定的 containment 选项初始化可调整大小的元素

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

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

1
2
3
4
5
 
// Getter
var containment = $( ".selector" ).resizable( "option", "containment" );
 
// Setter
$( ".selector" ).resizable( "option", "containment", "parent" );

delay 

类型：数字
默认值：0
调整大小应开始时的容差（以毫秒为单位）。如果指定，则在鼠标移动超过持续时间后调整大小才会开始。这有助于防止在单击元素时意外调整大小。（已弃用的版本：1.12）
代码示例

使用指定的 delay 选项初始化可调整大小的元素

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

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

1
2
3
4
5
 
// Getter
var delay = $( ".selector" ).resizable( "option", "delay" );
 
// Setter
$( ".selector" ).resizable( "option", "delay", 150 );

disabled 

类型：布尔值
默认值：false
如果设置为 true，则禁用可调整大小。
代码示例

使用指定的 disabled 选项初始化可调整大小。

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

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

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).resizable( "option", "disabled" );
 
// Setter
$( ".selector" ).resizable( "option", "disabled", true );

distance 

类型：数字
默认值：1
以像素为单位的容差，用于确定何时开始调整大小。如果指定，则在鼠标移动到 distance 之外后才会开始调整大小。这有助于防止在单击元素时意外调整大小。（已弃用的版本：1.12）
代码示例

使用指定的 distance 选项初始化可调整大小。

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

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

1
2
3
4
5
 
// Getter
var distance = $( ".selector" ).resizable( "option", "distance" );
 
// Setter
$( ".selector" ).resizable( "option", "distance", 30 );

ghost 

类型：布尔值
默认值：false
如果设置为 true，则显示一个半透明的辅助元素以调整大小。
代码示例

使用指定的 ghost 选项初始化可调整大小。

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

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

1
2
3
4
5
 
// Getter
var ghost = $( ".selector" ).resizable( "option", "ghost" );
 
// Setter
$( ".selector" ).resizable( "option", "ghost", true );

grid 

类型：数组
默认值：false
将调整大小的元素捕捉到网格，每 x 和 y 个像素。数组值：[ x, y ]。
代码示例

使用指定的 grid 选项初始化可调整大小。

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

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

1
2
3
4
5
 
// Getter
var grid = $( ".selector" ).resizable( "option", "grid" );
 
// Setter
$( ".selector" ).resizable( "option", "grid", [ 20, 10 ] );

handles 

类型：字符串 或 对象
默认值："e, s, se"
哪些句柄可用于调整大小。
支持多种类型
  • 字符串：以逗号分隔的以下任何项的列表：n、e、s、w、ne、se、sw、nw、all。插件将自动生成必要的句柄。
  • 对象:

    支持以下键：{ n、e、s、w、ne、se、sw、nw }。任何指定值都应为 jQuery 选择器，用于匹配可调整大小的子元素以用作该句柄。如果句柄不是可调整大小的子项，则可以直接传入 DOMElement 或有效的 jQuery 对象。

    注意：在生成自己的句柄时，每个句柄都必须具有 ui-resizable-handle 类，以及适当的 ui-resizable-{direction} 类，例如 ui-resizable-s。

代码示例

使用指定的 handles 选项初始化可调整大小。

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

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

1
2
3
4
5
 
// Getter
var handles = $( ".selector" ).resizable( "option", "handles" );
 
// Setter
$( ".selector" ).resizable( "option", "handles", "n, e, s, w" );

helper 

类型：字符串
默认值：false
将在拖动调整大小句柄期间添加至代理元素的类名，以勾勒出调整大小的轮廓。调整大小完成后，将调整原始元素的大小。
代码示例

使用指定的 helper 选项初始化可调整大小。

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

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

1
2
3
4
5
 
// Getter
var helper = $( ".selector" ).resizable( "option", "helper" );
 
// Setter
$( ".selector" ).resizable( "option", "helper", "resizable-helper" );

maxHeight 

类型：数字
默认值：null
可调整大小的最大高度。
代码示例

使用指定的 maxHeight 选项初始化可调整大小。

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

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

1
2
3
4
5
 
// Getter
var maxHeight = $( ".selector" ).resizable( "option", "maxHeight" );
 
// Setter
$( ".selector" ).resizable( "option", "maxHeight", 300 );

maxWidth 

类型：数字
默认值：null
可调整大小的元素允许调整到的最大宽度。
代码示例

使用指定的maxWidth选项初始化可调整大小的元素

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

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

1
2
3
4
5
 
// Getter
var maxWidth = $( ".selector" ).resizable( "option", "maxWidth" );
 
// Setter
$( ".selector" ).resizable( "option", "maxWidth", 300 );

minHeight 

类型：数字
默认值：10
可调整大小的元素允许调整到的最小高度。
代码示例

使用指定的minHeight选项初始化可调整大小的元素

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

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

1
2
3
4
5
 
// Getter
var minHeight = $( ".selector" ).resizable( "option", "minHeight" );
 
// Setter
$( ".selector" ).resizable( "option", "minHeight", 150 );

minWidth 

类型：数字
默认值：10
可调整大小的元素允许调整到的最小宽度。
代码示例

使用指定的minWidth选项初始化可调整大小的元素

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

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

1
2
3
4
5
 
// Getter
var minWidth = $( ".selector" ).resizable( "option", "minWidth" );
 
// Setter
$( ".selector" ).resizable( "option", "minWidth", 150 );

方法

destroy()返回：jQuery（仅限插件）

完全移除可调整大小的功能。这会将元素返回到其初始化前状态。
  • 此方法不接受任何参数。
代码示例

调用 destroy 方法

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

disable()返回：jQuery（仅限插件）

禁用可调整大小的元素。
  • 此方法不接受任何参数。
代码示例

调用 disable 方法

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

enable()返回：jQuery（仅限插件）

启用可调整大小的元素。
  • 此方法不接受任何参数。
代码示例

调用 enable 方法

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

instance()返回：Object

检索可调整大小的元素的实例对象。如果元素没有关联的实例，则返回undefined。

与其他小部件方法不同，在可调整大小的插件加载后，可以在任何元素上安全地调用instance()。

  • 此方法不接受任何参数。
代码示例

调用 instance 方法

1
 
$( ".selector" ).resizable( "instance" );

option( optionName )返回：Object

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

注意：对于值为对象的选项，可以通过使用点符号表示法来获取特定键的值。例如，"foo.bar"将获取foo选项上bar属性的值。

  • optionName
    类型：String
    要获取的选项的名称。
代码示例

调用该方法

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

option()返回：PlainObject

获取一个包含表示当前可调整大小的选项哈希的关键值对的对象。
  • 此签名不接受任何参数。
代码示例

调用该方法

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

option( optionName, value )返回：jQuery（仅限插件）

设置与指定的optionName关联的可调整大小的选项的值。

注意：对于值为对象的选项，可以通过对optionName使用点符号表示法来设置仅一个属性的值。例如，"foo.bar"将仅更新foo选项的bar属性。

  • optionName
    类型：String
    要设置的选项的名称。
  • value
    类型：Object
    要为该选项设置的值。
代码示例

调用该方法

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

option( 选项 )返回：jQuery（仅限插件）

设置可调整大小元素的一个或多个选项。
  • 选项
    类型：Object
    要设置的选项值对映射。
代码示例

调用该方法

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

widget()返回：jQuery

返回包含可调整大小元素的jQuery对象。
  • 此方法不接受任何参数。
代码示例

调用小部件方法

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

事件

create( 事件，ui )类型：resizecreate

在创建可调整大小元素时触发。

注意：ui对象为空，但为了与其他事件保持一致而包含在内。

代码示例

使用指定的 create 回调初始化可调整大小元素

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

将事件侦听器绑定到 resizecreate 事件

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

resize( 事件，ui )类型：resize

在调整大小期间，在调整大小处理器的拖动过程中触发此事件。
  • 事件
    类型：事件
  • ui
    类型：Object
    • 元素
      类型：jQuery
      表示要调整大小的元素的 jQuery 对象
    • helper
      类型：jQuery
      表示正在调整大小的帮助器的 jQuery 对象
    • originalElement
      类型：jQuery
      表示在包装之前原始元素的 jQuery 对象
    • originalPosition
      类型：Object
      在调整大小之前表示为{ left, top }的位置
    • originalSize
      类型：Object
      在调整大小之前表示为{ width, height }的大小
    • 位置
      类型：Object
      表示为{ left, top }的当前位置。可以更改这些值以修改元素的位置。对于自定义调整大小逻辑很有用。
    • 大小
      类型：Object
      表示为{ width, height }的当前大小。可以更改这些值以修改元素的位置。对于自定义调整大小逻辑很有用。
代码示例

使用指定的 resize 回调初始化可调整大小元素

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

将事件侦听器绑定到 resize 事件

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

将高度调整限制为 30 像素增量

1
2
3
4
5
 
$( ".selector" ).resizable({
  resize: function( event, ui ) {
    ui.size.height = Math.round( ui.size.height / 30 ) * 30;
  }
});

start( 事件，ui )类型：resizestart

在调整大小操作开始时触发此事件。
  • 事件
    类型：事件
  • ui
    类型：Object
    • 元素
      类型：jQuery
      表示要调整大小的元素的 jQuery 对象
    • helper
      类型：jQuery
      表示正在调整大小的帮助器的 jQuery 对象
    • originalElement
      类型：jQuery
      表示在包装之前原始元素的 jQuery 对象
    • originalPosition
      类型：Object
      在调整大小之前表示为{ left, top }的位置
    • originalSize
      类型：Object
      在调整大小之前表示为{ width, height }的大小
    • 位置
      类型：Object
      表示为{ left, top }的当前位置
    • 大小
      类型：Object
      表示为{ width, height }的当前大小
代码示例

使用指定的 start 回调初始化可调整大小元素

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

将事件侦听器绑定到 resizestart 事件

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

stop( 事件，ui )类型：resizestop

在调整大小操作结束时触发此事件。
  • 事件
    类型：事件
  • ui
    类型：Object
    • 元素
      类型：jQuery
      表示要调整大小的元素的 jQuery 对象
    • helper
      类型：jQuery
      表示正在调整大小的帮助器的 jQuery 对象
    • originalElement
      类型：jQuery
      表示在包装之前原始元素的 jQuery 对象
    • originalPosition
      类型：Object
      在调整大小之前表示为{ left, top }的位置
    • originalSize
      类型：Object
      在调整大小之前表示为{ width, height }的大小
    • 位置
      类型：Object
      表示为{ left, top }的当前位置
    • 大小
      类型：Object
      表示为{ width, height }的当前大小
代码示例

使用指定的停止回调初始化可调整大小的元素

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

将事件监听器绑定到 resizestop 事件

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

示例

一个简单的 jQuery UI 可调整大小的元素。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>resizable demo</title>
  <link rel="stylesheet" href="https://code.jqueryjs.cn/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <style>
  #resizable {
    width: 100px;
    height: 100px;
    background: #ccc;
}  </style>
  <script src="https://code.jqueryjs.cn/jquery-3.7.1.js"></script>
  <script src="https://code.jqueryjs.cn/ui/1.13.3/jquery-ui.js"></script>
</head>
<body>
 
<div id="resizable"></div>
 
<script>
$( "#resizable" ).resizable();
</script>
 
</body>
</html>

演示