gridstack.js API

Table of Contents generated with DocToc

Grid Options
- DDDragOpt
- DDDragInOpt extends DDDragOpt
Grid attributes
Item Options
Item attributes
Events
API Global (static)
API
Utils
- GridStack.Utils.sort(nodes[, dir[, width]])

Grid Options

acceptWidgets - 接受从其他网格或外部拖动的部件（默认值：false）。可以是：
- true - 接受具有 '.grid-stack-item' 作为类属性的 HTML 元素，否则为 false
- 字符串 - 显式类名以进行接受
- function (el: Element): boolean - 在进入网格时，在接受项之前调用的函数。该函数将传递被拖动的项，并应返回 true 或 false。参见示例
alwaysShowResizeHandle - 可能的值（默认值：mobile）- 不适用于不可调整大小的部件
- false - 调整大小手柄仅在悬停在部件上方时显示
- true - 始终显示调整大小手柄
- 'mobile' - 如果在移动设备上运行，默认为 true（因为没有真正的悬停），否则为 false。参见mobile
animate - 打开动画以实现平滑过渡（默认值：true）
auto - 如果为 false，gridstack 将不会初始化现有项（默认值：true）
cellHeight- 单元格的高度（默认值：'auto'）。可以是：
- 整数（像素）
- 字符串（例如：'100px'、'10em'、'10rem'）。注意：% 不起作用 - 参见CellHeight
- 0 - 在这种情况下，库不会为行生成样式。一切都必须在您自己的 CSS 文件中定义。
- auto - 高度将根据正方形单元格（宽度/列数）计算，并在调整窗口大小时实时更新 - 另请参见 cellHeightThrottle
- initial - 类似于 'auto'（从正方形单元格开始），但在调整窗口大小时保持该大小。
cellHeightThrottle?: number - 当 cellHeight='auto' 时用于改善性能与可用性的节流时间延迟（以毫秒为单位）（默认值：100）。
- 值为 0 将使其瞬间完成，但代价是在每次窗口调整大小事件时重新创建 CSS 文件！
children?: GridStackWidget[] - 调用 load() 或 addGrid() 时要创建的子项列表
column - 大于 0 的整数（默认值为 12），可以使用 column(N) API 在运行时更改，或者对于嵌套网格来说，可以使用 'auto' 使其自适应父网格容器的大小（使子项具有相同的大小）。参见column 和 nested
class?: string - 除了 '.grid-stack'（我们的 CSS 必需项）之外的其他类（可选）
disableDrag - 禁止部件的拖动（默认值：false）。
disableOneColumnMode - 即使容器的宽度小于 oneColumnSize 的值（默认值为 768px），也阻止网格容器以“一列模式”显示。默认情况下，此选项设置为 "false"。
disableResize - 禁止部件的调整大小（默认值：false）。
draggable - 允许覆盖可拖动选项 - 参见 DDDragOpt（默认值：{handle: '.grid-stack-item-content', appendTo: 'body', scroll: true}）
dragOut - 是否允许用户将嵌套的网格项拖出父级（默认值为 false）。参见示例
engineClass - 要创建的引擎类型（以便您可以进行子类化），默认为 GridStackEngine
float - 启用浮动部件（默认值：false）。参见示例
handle - 可拖动的手柄选择器（默认值：'.grid-stack-item-content'）
handleClass - 可拖动的手柄类（例如 'grid-stack-item-content'）。如果设置了 handle，则忽略此选项（默认值：null）
itemClass - 部件类（默认值：'grid-stack-item'）
margin - 网格项和内容的间隙大小（默认值：10）。可以是：
- 整数（像素）
- 字符串（例如：'2em'、'20px'、'2rem'）
marginTop: numberOrString - 可以设置单独的设置（默认为 margin）
marginRight: numberOrString
marginBottom: numberOrString
marginLeft: numberOrString
maxRow - 最大行数。默认值为 0，表示无最大限制。
minRow - 最小行数，可以防止网格在为空时崩溃。默认值为 0。您还可以在网格 div 上使用 min-height CSS 属性以像素为单位进行设置，它将四舍五入到最接近的行。
nonce - 如果您使用基于 nonce 的内容安全策略，请在此处传递您的 nonce，并且 GridStack 将将其添加到创建的 <style> 元素中。
oneColumnSize - 当网格的宽度等于或小于 oneColumnSize 的值时，网格将以单列模式显示。默认情况下，此选项的值设置为"768"。
oneColumnModeDomSort - 如果希望 oneColumnMode 使用 DOM 顺序，并在排序过程中忽略来自普通多列布局的 x、y 坐标，请将其设置为 true。这使您可以拥有与其他部分不同的自定义 1 列布局。（默认值：false）
placeholderClass - 占位符的类（默认值：'grid-stack-placeholder'）
placeholderText - 占位符的默认内容（默认值：''）
resizable - 允许覆盖可调整大小选项（默认值：{handles: 'se'}）。handles 可以是 n,ne,e,se,s,sw,w,nw 或 all 的任意组合。
removable - 如果为 true，则可以通过将部件拖到网格之外来移除部件。它还可以是一个选择器字符串，在这种情况下，部件将被删除，通过将其放在那里（默认值：false）。参见示例
removeTimeout - 在将部件拖到网格之外时，部件被删除之前的时间（以毫秒为单位）。（默认值：2000）
row - 固定网格的行数。这是写入 minRow:N, maxRow:N 的快捷方式。（默认值 0，无约束）
rtl - 如果为 true，则将网格设置为 RTL。可能的值是 true、false、'auto'（默认值：'auto'）。参见示例
staticGrid - 移除拖动|放置|调整大小（默认值 false）。如果为 true，则用户无法移动/调整大小部件，但代码仍然可以移动，并且 oneColumnMode 仍然起作用。您可以使用较小的 gridstack-static.js 库。容器还会添加一个 CSS 类 grid-stack-static。
styleInHead - 如果为 true，将在 <head> 中添加样式元素，否则将添加到元素的父节点（默认值 false）。

DDDragOpt

handle?: string - 可拖动项的类选择器。默认为 '.grid-stack-item-content'
appendTo?: string - 默认为 'body'（TODO: 这还在使用吗？）
pause?: boolean | number - 如果设置为 true 或 msec，则仅在用户暂停后才会发生拖动放置（碰撞）。注意：这是全局的。
scroll?: boolean - 默认为 'true'，在将元素拖动到网格底部或顶部时启用或禁用滚动。
cancel?: string - 防止在指定的元素上启动拖动，列出为逗号分隔的选择器（例如：".non-draggable"）。
grid?: boolean - 如果为 true，则以网格为单位对拖动坐标进行舍入，否则保持像素（默认为 false）。

DDDragInOpt 扩展了 DDDragOpt

helper?: 'clone' | ((event: Event) => HTMLElement) - 拖放时的辅助函数（例如：'clone' 或您自己的方法）。

网格属性

大多数上述选项也可以作为 HTML 属性使用，使用 gs- 作为名称前缀，并遵循标准的破折号小写命名规范（例如：gs-column、gs-min-row、gs-static 等）。

额外属性：

gs-current-row - （内部使用）当前行数。仅由库设置。可供 CSS 规则使用。

项目选项

在调用 addWidget()、update()、load() 等方法时，可以传递的选项：

autoPosition - 告诉系统忽略 x 和 y 属性，并将元素放置在第一个可用位置。如果其中一个属性缺失，也会自动放置元素。
x、y - （数字）元素在列/行中的位置。注意：如果其中一个属性缺失，将自动进行自动定位。
w、h - （数字）元素的列/行大小（默认为1x1）。
maxW、minW、maxH、minH - 元素在列/行中的约束条件（默认为无）。
locked - 表示另一个小部件在拖动或调整大小期间无法移动它。用户仍然可以拖动或调整大小该小部件。您需要添加 noResize 和 noMove 属性来完全锁定小部件。
noResize - 禁用元素的调整大小功能。
noMove - 禁用元素的移动功能。
id - （数字或字符串）用于快速标识（例如在更改事件中使用）。
content - （字符串）在调用 grid.load()/addWidget() 时作为项目内部内容添加的 HTML 内容。
subGrid?: GridStackOptions - 可选的嵌套网格选项和子项列表。
subGridDynamic?: boolean - 启用/禁用通过将项目完全拖动到其他项目上（嵌套）或部分拖动（推动）的方式动态创建子网格。为此，强制 DDDragOpt.pause=true。

项目属性

所有项目选项也可以作为 HTML 属性使用，使用 gs- 作为名称前缀，并遵循标准的破折号小写命名规范（例如：gs-x、gs-min-w 等）。

事件

这些事件是在小部件被添加、移除、更改或进行拖放交互时由网格生成的。一般情况下，它们传递了发生变化的节点列表（id、x、y、width、height 等）或受影响的单个 DOM 元素。

您可以在单个事件名称上调用它，或者使用空格分隔的列表，例如： grid.on('added removed change', ...)

TypeScript 的 GridStackEvent 列出了所有可能的值，grid.on() 方法不支持其他事件，但如果基于 jQuery UI，仍然可以直接注册其他由拖放插件生成的事件（可以使用 $(".grid-stack").on(...)）。

added(event, items)

在小部件添加到网格时调用

grid.on('added', function(event: Event, items: GridStackNode[]) {
  items.forEach(function(item) {...});
});

change(event, items)

当小部件由于约束或直接更改而更改其位置/大小时触发

grid.on('change', function(event: Event, items: GridStackNode[]) {
  items.forEach(function(item) {...});
});

disable(event)

grid.on('disable', function(event: Event) {
  let grid: GridStack = event.target.gridstack;
});

dragstart(event, el)

当网格项开始拖动时调用

grid.on('dragstart', function(event: Event, el: GridItemHTMLElement) {
});

drag(event, el)

当网格项正在拖动时调用，每个新的行/列值调用一次（不是每个像素）

grid.on('drag', function(event: Event, el: GridItemHTMLElement) {
});

dragstop(event, el)

在用户完成移动项目后调用，包括更新的 DOM 属性。

grid.on('dragstop', function(event: Event, el: GridItemHTMLElement) {
  let x = parseInt(el.getAttribute('gs-x')) || 0;
  // 或获取所有值...
  let node: GridStackNode = el.gridstackNode; // {x, y, width, height, id, ....}
});

dropped(event, previousWidget, newWidget)

当项目被拖放到网格上并被接受时调用。如果该项目来自另一个网格，则还将发送先前的小部件节点信息（但 DOM 元素已经不存在）。

grid.on('dropped', function(event: Event, previousWidget: GridStackNode, newWidget: GridStackNode) {
  console.log('从网格中拖出的已删除小部件：', previousWidget);
  console.log('在放置的网格中添加的小部件：', newWidget);
});

enable(event)

grid.on('enable', function(event: Event) {
  let grid: GridStack = event.target.gridstack;
});

removed(event, items)

在从网格中删除项目时调用

grid.on('removed', function(event: Event, items: GridStackNode[]) {
  items.forEach(function(item) {...});
});

resizestart(event, el)

在用户开始

调整项目大小之前调用

grid.on('resizestart', function(event: Event, el: GridItemHTMLElement) {
});

resize(event, el)

当网格项正在调整大小时调用，每个新的行/列值调用一次（不是每个像素）

grid.on('resize', function(event: Event, el: GridItemHTMLElement) {
});

resizestop(event, el)

在用户完成调整项目大小后调用，包括更新的 DOM 属性。

grid.on('resizestop', function(event: Event, el: GridItemHTMLElement) {
  let width = parseInt(el.getAttribute('gs-w')) || 0;
  // 或获取所有值...
  let node: GridStackNode = el.gridstackNode; // {x, y, width, height, id, ....}
});

全局 API（静态）

`init(options: GridStackOptions = {}, elOrString: GridStackElement = '.grid-stack'): GridStack`

将 HTML 元素或选择器字符串初始化为网格，并返回该网格。再次调用将简单地返回现有实例（忽略传递的任何选项）。还有一个 initAll() 版本，可以同时支持多个网格的初始化。或者您可以使用 addGrid() 从 JSON 创建整个网格。
@param options 网格选项（可选）
@param elOrString 要转换为网格的元素或 CSS 选择器（使用第一个）（默认为 '.grid-stack' 类选择器）

let grid = GridStack.init();
// 注意：HTMLElement（类型为 GridHTMLElement）将存储一个 `gridstack: GridStack` 值，可以稍后检索
let grid = document.querySelector('.grid-stack').gridstack;

`initAll(options: GridStackOptions = {}, selector = '.grid-stack'): GridStack[]`

将初始化一组元素（给定选择器），并返回一个网格数组。
@param options 网格选项（可选）
@param selector 要转换为网格的元素选择器（默认为 '.grid-stack' 类选择器）

let grids = GridStack.initAll();
grids.forEach(...)

`addGrid(parent: HTMLElement, opt: GridStackOptions = {}): GridStack`

调用以使用给定选项创建一个网格，包括从 JSON 结构加载任何子项。这将调用 GridStack.init()，然后在任何传递的子项上调用 grid.load()（递归）。如果希望整个网格来自 JSON 序列化数据（包括选项），则是调用 init() 的绝佳替代方法。
@param parent 网格的 HTML 元素父级
@param opt 用于初始化网格的网格选项和子项列表
请参阅 nested.html 示例

`setupDragIn(dragIn?: string | HTMLElement[], dragInOptions?: DDDragInOpt, root = HTMLElement | Document)`

调用以设置从外部拖动进入（例如工具栏）的功能，通过指定类选择器和选项。在 GridStack.init() 期间作为选项调用，但也可以直接调用（最后一个参数被缓存），以防工具栏是动态创建的，并且以后需要更改。
@param dragIn 字符串选择器（例如 '.sidebar .grid-stack-item'）或 DOM 元素列表
@param dragInOptions 选项 - 参见 DDDragInOpt（默认值：{handle: '.grid-stack-item-content', appendTo: 'body'}）
@param root - 默认为 document。对于影子 DOM 支持，请传递父容器。但您可能还需要 helper: 'clone' 或您自己的回调函数）。

`GridStack.registerEngine(engineClass: typeof GridStackEngine)`

调用以指定全局自定义引擎子类 - 如果您只需要替换一个实例，可以参见 GridStackOptions.engineClass。

API

`addWidget(el?: GridStackWidget | GridStackElement, options?: GridStackWidget)`

创建新的小部件并返回它。Options 是一个包含字段 x、y、width、height 等的对象。

参数：

el：GridStackWidget | GridStackElement - 要添加的 HTML 元素、字符串定义或 GridStackWidget（也可以包含内容字符串）。
options：GridStackWidget - 小部件位置/大小选项（可选，如果第一个参数已经是选项，则忽略）- 参见 GridStackWidget。

无论结果高度是否超过实际网格高度，小部件都会被放置。在调用 addWidget 之前，您需要使用 willItFit 方法进行额外的检查。

let grid = GridStack.init();
grid.addWidget({w: 3, content: 'hello'});
// 或者
grid.addWidget('<div class="grid-stack-item"><div class="grid-stack-item-content">hello</div></div>', {w: 3});

`batchUpdate(flag = true)`

在调用一系列 addWidget() 之前使用，以防止在其中不必要的重布局（更高效），并获得单个事件回调。在调用 batchUpdate(false) 之前，您将看不到任何更改。

`compact()`

重新布局网格项以回收任何空白空间。

`cellHeight(val: number, update = true)`

更新当前单元格高度（参见 - cellHeight 选项格式）。该方法会重建内部 CSS 样式表（除非可选的 update=false）。注意：如果频繁调用此方法，可能会导致性能问题。

grid.cellHeight(grid.cellWidth() * 1.2);

`cellWidth()`

获取当前单元格宽度（网格宽度 / 列数）。

`column(column: number, layout: ColumnOptions = 'moveScale')`

设置网格中的列数。将更新现有小部件以符合新的列数，并缓存原始布局，以便可以在不丢失之前位置的情况下恢复到以前的位置。要求使用 gridstack-extra.css（或缩小的版本）进行 [2-11]，否则您将需要生成正确的 CSS（请参阅 github.com/gridstack/g…

column - 大于 0 的整数（默认为 12）。
layout - 指定将发生的重新布局类型（位置、大小等）。注意：项目永远不会超出当前列范围。默认为 ('moveScale')。对于 1 列，忽略该选项。可能的值为：'moveScale' | 'move' | 'scale' | 'none' | (column: number, oldColumn: number, nodes: GridStackNode[], oldNodes: GridStackNode[]) => void。自定义函数选项接受新的/旧的列计数以及新的/旧的位置数组。注意：如果我们在该大小上部分地缓存了

布局（稍后添加了项目），则新列表可能已经部分填充。如果完整的缓存存在，则根本不会调用此方法。

`destroy([removeDOM])`

销毁网格实例。

参数：

removeDOM - 如果为 false，则节点和网格将不会从 DOM 中移除（可选，默认为 true）。

`disable()`

禁用小部件的移动/调整大小。这是一个快捷方式，相当于：

grid.enableMove(false);
grid.enableResize(false);

`enable()`

启用小部件的移动/调整大小。这是一个快捷方式，相当于：

grid.enableMove(true);
grid.enableResize(true);

`enableMove(doEnable)`

启用/禁用小部件的移动（默认为 true），并设置 disableDrag 网格选项。这是一个快捷方式，相当于：

grid.opts.disableDrag = !doEnable;
grid.movable('.grid-stack-item', doEnable);

`enableResize(doEnable)`

启用/禁用小部件的调整大小（默认为 true），并设置 disableResize 网格选项。这是一个快捷方式，相当于：

grid.opts.disableResize = !doEnable;
grid.resizable('.grid-stack-item', doEnable);

`float(val?)`

设置/获取浮动小部件（默认为 false）。

val - 要设置为 true/false，否则获取当前值。

`getCellHeight()`

获取当前单元格高度。

`getCellFromPixel(position[, useOffset])`

获取屏幕上像素下的单元格位置。

参数：

position - 要解析的像素的绝对坐标位置，作为具有 top 和 left 属性的对象。
useOffset - 如果为 true，则基于偏移而不是位置的值（可选，默认为 false）。当网格位于 position: relative 元素内时有用。

返回一个具有 x 和 y 属性的对象，即网格中的列和行。

`getColumn(): number`

返回网格中的列数。

`getGridItems(): GridItemHTMLElement[]`

按 DOM 顺序返回 GridItem HTML 元素的列表（排除临时占位符），无论它们是否已经是节点项（按类查找）。

`getMargin()`

返回当前边距值（如果四个边不匹配，则返回 undefined）。

`isAreaEmpty(x, y, width, height)`

检查指定区域是否为空。

`load(layout: GridStackWidget[], boolean | ((w: GridStackWidget, add: boolean) => void) = true)`

从列表中加载小部件（参见 save()）。这将调用 update() 对每个小部件进行更新（通过 id 进行匹配），或者添加/移除不在其中的小部件。
可选的 addAndRemove 布尔值（默认为 true）或回调方法可以传递以控制如何添加/删除缺失的小部件，让用户对插入有控制权。
用于恢复保存的布局的网格布局（参见 save()）。
可选的 addAndRemove 布尔值（默认为 true）或回调方法可以传递以控制如何添加/删除缺失的小部件，让用户对插入有控制权。
请参阅示例。

`makeWidget(el)`

如果您手动向网格堆栈容器添加元素，您需要在之后告诉网格堆栈将它们转换为小部件。如果您希望网格堆栈为您添加元素，请改用 addWidget。将给定的元素转换为小部件并返回它。

参数：

el - 要转换为小部件的元素

let grid = GridStack.init();
grid.el.appendChild('<div id="gsi-1" gs-x="0" gs-y="0" gs-w="3" gs-h="2" gs-auto-position="true"></div>')
grid.makeWidget('#gsi-1');

`makeSubgrid(el)`

用于将子网格添加到现有网格中。

const grid = Gridstack.init()
grid.el.appendChild(`
<div id="gsi-1" gs-x="0" gs-y="0" gs-w="3" gs-h="2" gs-auto-position="true">
      <div class="grid-stack" id="nested-grid">
          <div id="gsi-2" gs-x="0" gs-y="0" gs-w="3" gs-h="2" gs-auto-position="true">
          </div>
      </div>
</div>`)
grid.addSubGrid(grid.el.getElementById('nested-grid'))

确保子网格位于网格项内部。请记住，子网格本身是可以包含其他网格项的网格项。

`margin(value: numberOrString)`

设置网格项与内容之间的间隔（默认为 10）。这将设置所有四个边，并支持以下 CSS 格式：

整数（px）
带有可能的单位的字符串（例如：'5'、'2em'、'20px'、'2rem'）
带有空格分隔的值的字符串（例如：'5px 10px 0 20px' 表示所有四个边，或者 '5em 10em' 表示上下和左右配对，就像 CSS 中一样）。
注意：所有边必须具有相同的单位（以最后一个为准，默认为 px）。

`movable(el, val)`

启用/禁用特定网格元素的用户拖动。如果要操作所有项，并且对未来的项起作用，请改用 enableMove()。对于静态网格，无操作。如果您想阻止某个项移动（因为在碰撞期间被其他项推动），请改用 locked 属性。

el - 要修改的小部件
val - 如果为 true，则小部件将可以拖动。

`removeWidget(el, removeDOM = true, triggerEvent = true)`

从网格中移除小部件。

参数：

el - 要移除的小部件。
removeDOM - 如果为 false，则节点将不会从 DOM 中移除（可选，默认为 true）。
triggerEvent - 如果为 false（静默模式），将不会将元素添加到已删除列表中，并且不会调用“removed”回调函数（默认为 true）。

`removeAll(removeDOM = true)`

从网格中移除所有小部件。

参数：

removeDOM - 如果为 false，则节点将不会从 DOM 中移除（可选，默认为 true）。

`resizable(el, val)`

启用/禁用特定网格元素的用户调整大小。如果要操作所有项，并且对未来的项起作用，请改用 enableResize()。对于静态网格，无操作。

el - 要修改的小部件
val - 如果为 true，则小部件将可以调整大小。

`save(saveContent = true, saveGridOpt = false): GridStackWidget[] | GridStackOptions`

保存当前布局，并返回用于序列化的小部件列表，可能包括任何嵌套的网格。

saveContent 如果为 true（默认值），将保存 .grid-stack-content 中的最新 HTML 到 GridStackWidget.content 字段中，否则将其删除。
saveGridOpt 如果为 true（默认为 false），则保存网格选项本身，以便您可以调用新的 GridStack.addGrid() 来从头开始重新创建所有内容。GridStackOptions.children 将包含小部件列表。
返回小部件列表或完整的网格选项，包括小部件的 .children 列表。
请参阅序列化和嵌套。

`setAnimation(doAnimate)`

切换网格的动画状态。切换 grid-stack-animate 类。

doAnimate - 如果为 true，则网格将具有动画效果。

`setStatic(staticValue)`

切换网格的静态状态。同时切换 grid-stack-static 类。

staticValue - 如果为true，则网格变为静态。

`update(el: GridStackElement, opts: GridStackWidget)`

参数：

el - 要移动的小部件（元素或类字符串）
opts - 更新传递的结构中的所有可能的项目属性（x、y、h、w 等）。仅更新设置的属性。

更新小部件的位置、大小和其他信息。注意：如果需要对所有节点调用此方法，请改用 load()，它将更新更改的节点以及其他内容。

`willItFit(x, y, width, height, autoPosition)`

如果网格的高度小于垂直约束，则返回 true。如果网格没有高度约束，则始终返回 true。

if (grid.willItFit(newNode.x, newNode.y, newNode.w, newNode.h, newNode.autoPosition)) {
  grid.addWidget(newNode.el, newNode);
}
else {
  alert('Not enough free space to place the widget');
}

工具函数

`GridStack.Utils.sort(nodes[, dir[, width]])`

对节点数组进行排序

nodes - 要排序的数组
dir - 1 表示升序，-1 表示降序（可选）
width - 网格的宽度。如果为 undefined，宽度将自动计算（可选）。