# @bdlite/gridstack 中文文档
规范地址：https://npmcn.com/package/%40bdlite/gridstack/
版本：8\.4\.2
npm 元数据更新时间：2023-12-11T03:31:28.725Z
中文译文更新时间：2026-11-07T19:22:17.968Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40bdlite/gridstack
原文对照：https://npmcn.com/package/%40bdlite/gridstack/?lang=original
项目主页：http://gridstackjs.com/
源码仓库：https://github.com/gridstack/gridstack.js
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：2.7 MB，159 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-08-04T07:03:45.958Z
- 最新版本发布：2023-12-11T03:31:28.496Z
- 近 30 天下载量：4106（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）
## 中文简介
TypeScript/JS lib 用于仪表板布局和创建,响应性,移动支持,没有外部依赖性,有许多包件(React,Angular,Vue,Ember,淘汰.)
## 安装
```sh
npm install @bdlite/gridstack
```
也可以使用：`pnpm add @bdlite/gridstack`、`yarn add @bdlite/gridstack`、`bun add @bdlite/gridstack`
## README
# (原始内容存档于2018-09-21). greatstack.js
[](https://www.npmjs.com/package/gridstack) [](https://coveralls.io/github/gridstack/gridstack.js?branch=develop) [](https://www.npmjs.com/package/gridstack)
方便移动的现代Typescript库,用于仪表板布局和创建. 制作一个拖放,多栏响应的仪表板从来就没有那么容易了. 具有多种绑定功能, 并与之配合良好 [角质](https://angular.io/) (包括), [反应](https://reactjs.org/), (中文(简体) ), [阴道](https://vuejs.org/), (中文(简体) ), [击倒. js](http://knockoutjs.com/), (中文(简体) ), [琥珀](https://www.emberjs.com/) 和其他事项(见 [框架](https://npmcn.com/package/%40bdlite/gridstack/#readme-specific-frameworks) 页:1.
受到无长者维持的克格勒斯特的启发,用爱来建造.
检查 [http://gridstackjs.com (中文(简体) )](http://gridstackjs.com/) 财务报告和审定财务报表 [这些演示](http://gridstackjs.com/demo/)。 。 。 .
如果你觉得这个乐章有用,请捐赠 [付费页](https://www.paypal.me/alaind831) (使用时 **“交给朋友”** 避免收取3%的费用)或 [温莫](https://www.venmo.com/adumesny) 帮助支持它!
[](https://www.paypal.me/alaind831) [](https://www.venmo.com/adumesny)
加入我们的Slack: [https://gridstackjs.slack.com (中文(简体) )](https://join.slack.com/t/gridstackjs/shared_invite/zt-1jobnclsy-FqGGeLX5dFPM_ZQzTunBsw)
**目录** _生成方式 [DocTOC 文档](http://doctoc.herokuapp.com/)_
- [Demo 和 API 文档](https://npmcn.com/package/%40bdlite/gridstack/#readme-demo-and-api-documentation)
- [使用量](https://npmcn.com/package/%40bdlite/gridstack/#readme-usage)
- [安装](https://npmcn.com/package/%40bdlite/gridstack/#readme-install)
- [包含](https://npmcn.com/package/%40bdlite/gridstack/#readme-include)
- [基本用途](https://npmcn.com/package/%40bdlite/gridstack/#readme-basic-usage)
- [所需资源](https://npmcn.com/package/%40bdlite/gridstack/#readme-requirements)
- [具体框架](https://npmcn.com/package/%40bdlite/gridstack/#readme-specific-frameworks)
- [扩展库](https://npmcn.com/package/%40bdlite/gridstack/#readme-extend-library)
- [扩展引擎](https://npmcn.com/package/%40bdlite/gridstack/#readme-extend-engine)
- [更改网格列](https://npmcn.com/package/%40bdlite/gridstack/#readme-change-grid-columns)
- [自定义列 CSS](https://npmcn.com/package/%40bdlite/gridstack/#readme-custom-columns-css)
- [覆盖可调整/可调整选项](https://npmcn.com/package/%40bdlite/gridstack/#readme-override-resizabledraggable-options)
- [触摸装置支持](https://npmcn.com/package/%40bdlite/gridstack/#readme-touch-devices-support)
- [移动](https://npmcn.com/package/%40bdlite/gridstack/#readme-migrating)
- [移动到 v. 6](https://npmcn.com/package/%40bdlite/gridstack/#readme-migrating-to-v06)
- [移动到 v1](https://npmcn.com/package/%40bdlite/gridstack/#readme-migrating-to-v1)
- [移动到 v2](https://npmcn.com/package/%40bdlite/gridstack/#readme-migrating-to-v2)
- [移动到 v3](https://npmcn.com/package/%40bdlite/gridstack/#readme-migrating-to-v3)
- [移动到 v4](https://npmcn.com/package/%40bdlite/gridstack/#readme-migrating-to-v4)
- [移动到 v5](https://npmcn.com/package/%40bdlite/gridstack/#readme-migrating-to-v5)
- [移动到 v6](https://npmcn.com/package/%40bdlite/gridstack/#readme-migrating-to-v6)
- [移动到 v7](https://npmcn.com/package/%40bdlite/gridstack/#readme-migrating-to-v7)
- [移动到 v8](https://npmcn.com/package/%40bdlite/gridstack/#readme-migrating-to-v8)
- [j 查询应用程序](https://npmcn.com/package/%40bdlite/gridstack/#readme-jquery-application)
- [变动](https://npmcn.com/package/%40bdlite/gridstack/#readme-changes)
- [监察组](https://npmcn.com/package/%40bdlite/gridstack/#readme-the-team)
# Demo 和 API 文档
请访问 [http://gridstackjs.com (中文(简体) )](http://gridstackjs.com/) 财务报告和审定财务报表 [这些演示](http://gridstackjs.com/demo/),则完成 [API 文档](https://github.com/gridstack/gridstack.js/tree/master/doc)
# 使用量
## 安装
[](https://www.npmjs.com/package/gridstack)
```js
yarn add gridstack
// or
npm install --save gridstack
```
## 包含
ES6 或打字符
```js
import 'gridstack/dist/gridstack.min.css';
import { GridStack } from 'gridstack';
```
或者( 单个合并文件, 注意 - all.js) html
```html
// ...in your script
var grid = GridStack.init();
grid.addWidget({w: 2, content: 'item 1'});
```
...或从列表创建
```js
// using serialize data instead of .addWidget()
const serializedData = [
{x: 0, y: 0, w: 2, h: 2},
{x: 2, y: 3, w: 3, content: 'item 2'},
{x: 1, y: 3}
];
grid.load(serializedData);
```
... 或 DOM 创建项目
```js
// ...in your HTML
// ...in your script
GridStack.init();
```
...或见所有列表 [API 和选项](https://github.com/gridstack/gridstack.js/tree/master/doc) 可用.
见 [jsfile 样本](https://jsfiddle.net/adumesny/jqhkry7g) 作为运行中的例子.
## 所需资源
GridStack到v1时不再需要外部依赖(lodash被去掉v0.5和jquery API被去掉v1). v3 是一个完整的 HTML5 重写去除 jquery 的需要. v6是本地鼠标和触摸事件,用于移动支持,不再有jquery-ui版本. 你现在只需要包括 `gridstack-all.js` 财务报告和审定财务报表 `gridstack.min.css` (使用基于%的 CSS 栏进行排出).
## 具体框架
搜索 [国家防范机制下的"gridstack"](https://www.npmjs.com/search?q=gridstack&ranking=popularity) 最近,还有更多...
- **角质**:我们现在用Angular包装器组件从盒子中运出 - 看 [角构件](https://github.com/gridstack/gridstack.js/tree/master/angular)。 。 。 .
- **角点9**数字 : [电网](https://github.com/pfms84/lb-gridstack) 注:非常古老的 v. 3 格栅实例 **只有您想要使用指令时,才会使用**代码 **未通风** 当我使用组件.
- **角 JS 语言**数字 : [网格正方形](https://github.com/kdietrich/gridstack-angular)
- **琥珀**数字 : [电源网](https://github.com/yahoo/ember-gridstack)
- **淘汰**: 见 [演示](https://gridstackjs.com/demo/knockout.html) 使用组件,但检查 [定制绑定票](https://github.com/gridstack/gridstack.js/issues/465) 这可能是更好的方法.
- **铁路**数字 : [电网-js-铁路](https://github.com/randoum/gridstack-js-rails)
- **反应**: 见 [演示](https://gridstackjs.com/demo/react.html) 与 [曲线](https://github.com/gridstack/gridstack.js/tree/master/demo/react.html),或 [反应-网格-实例](https://github.com/Inder2108/react-gridstack-example/tree/master/src/App.js),或者读到什么 [要使用的钩](https://github.com/gridstack/gridstack.js/issues/735#issuecomment-329888796)
- **阴道**: 见 [演示](https://gridstackjs.com/demo/vue3js.html) 与 [v3 斜弧](https://github.com/gridstack/gridstack.js/tree/master/demo/vue3js.html) 或者说 [v2 曲线](https://github.com/gridstack/gridstack.js/tree/master/demo/vue2js.html)
- **奥雷利亚**数字 : [奥雷利亚-网球](https://github.com/aurelia-ui-toolkits/aurelia-gridstack),参见 [演示](https://aurelia-ui-toolkits.github.io/aurelia-gridstack/)
## 扩展库
您可以用这样的代码轻松地扩展或补丁网格:
```js
// extend gridstack with our own custom method
GridStack.prototype.printCount = function() {
console.log('grid has ' + this.engine.nodes.length + ' items');
};
let grid = GridStack.init();
// you can now call
grid.printCount();
```
## 扩展引擎
现在可以轻松地创建出自己的布局引擎来进一步自定义你的用法. 这里有一个打字例
```ts
import { GridStack, GridStackEngine, GridStackNod, GridStackMoveOpts } from 'gridstack';
class CustomEngine extends GridStackEngine {
/** refined this to move the node to the given new location */
public moveNode(node: GridStackNode, o: GridStackMoveOpts): boolean {
// keep the same original X and Width and let base do it all...
o.x = node.x;
o.w = node.w;
return super.moveNode(node, o);
}
}
GridStack.registerEngine(CustomEngine); // globally set our custom class
```
## 更改网格列
GridStack 使您在需要 \[1-12\] 框外的列( 默认为 12) 时非常容易, 但是您总是需要 **两件事** 如果您需要自定义 :
1. 改变 `column` 创建您数字 N 的网格时的网格选项
```js
GridStack.init( {column: N} );
```
2. 还包括: `gridstack-extra.css` 若为 **N < 12号** (然后是自定义 CSS - 见下一节). 没有这些,事情就不会得到正确处理.
```html
...
```
注:类别 `.grid-stack-N` 自动添加,我们包括 `gridstack-extra.min.css` 定义带有自定义 \[2-11\] 列的网格的 CSS。 任何更多,你都需要自己生成SASS/CSS(见下).
参见实例: [2个网格演示](http://gridstack.github.io/gridstack.js/demo/two.html) 有6个栏
## 自定义列 CSS
如果您需要 > 12列或想要手工生成 CSS , 您需要生成 CSS 规则 `.grid-stack-item[gs-w="X"]` 财务报告和审定财务报表 `.grid-stack-item[gs-x="X"]`。 。 。 .
例如,对于四列网格,您需要 CSS :
```css
.gs-4 > .grid-stack-item[gs-x="1"] { left: 25% }
.gs-4 > .grid-stack-item[gs-x="2"] { left: 50% }
.gs-4 > .grid-stack-item[gs-x="3"] { left: 75% }
.gs-4 > .grid-stack-item { width: 25% }
.gs-4 > .grid-stack-item[gs-w="2"] { width: 50% }
.gs-4 > .grid-stack-item[gs-w="3"] { width: 75% }
.gs-4 > .grid-stack-item[gs-w="4"] { width: 100% }
```
更好的是,这里有一个SCSS代码片段, 你可以使用网站,比如 [sassmeistor.com (中文(简体) )](https://www.sassmeister.com/) 为您生成 CSS :
```scss
$columns: 20;
@function fixed($float) {
@return round($float * 1000) / 1000; // total 2+3 digits being %
}
.gs-#{$columns} > .grid-stack-item {
width: fixed(100% / $columns);
@for $i from 1 through $columns - 1 {
&[gs-x='#{$i}'] { left: fixed((100% / $columns) * $i); }
&[gs-w='#{$i+1}'] { width: fixed((100% / $columns) * ($i+1)); }
}
}
```
您也可以使用 SCSS 软件 [src/gridstack-extra.scs (英语)](https://github.com/gridstack/gridstack.js/tree/master/src/gridstack-extra.scss) 列入国家防范机制包并作修改以增加栏目.
30个列的 gulp 样本命令 :
```js
gulp.src('node_modules/gridstack/dist/src/gridstack-extra.scss')
.pipe(replace('$start: 2 !default;','$start: 30;'))
.pipe(replace('$end: 11 !default;','$end: 30;'))
.pipe(sass({outputStyle: 'compressed'}))
.pipe(rename({extname: '.min.css'}))
.pipe(gulp.dest('dist/css'))
```
## 覆盖可调整/可调整选项
您可以覆盖默认 `resizable`编号 :`draggable` 选项。 例如启用其它右下角调整大小的手柄 你可以进入网格的像:
```js
GridStack.init({
resizable: {
handles: 'e,se,s,sw,w'
}
});
```
## 触摸装置支持
gridstack v6+ 现在支持移动出框,同时添加了本地触摸事件(连同鼠标事件),用于拖放和调整大小. 更古老的版本(3.2+)需要jq版本并加上了触摸出出拳来,但与被打入巢的网格效果不佳.
此选项现在是默认 :
```js
let options = {
alwaysShowResizeHandle: 'mobile' // true if we're on mobile devices
};
GridStack.init(options);
```
见 [实例](http://gridstack.github.io/gridstack.js/demo/mobile.html)。 。 。 .
# 移动
## 移动到 v. 6
从0.6.x开始 `change` 事件不再被发送(对于几乎大多数节点!),因为项目只是添加/删除,除非它也改变其他节点(不正确并造成效率低下)。 您可能需要跟踪 `added|removed` [事件](https://github.com/gridstack/gridstack.js/tree/master/doc#events) 如果你没有 并依赖 旧的破败行为.
## 移动到 v1
v1.0.0 从API和外部依赖中移除了Jquery,这将需要一些代码修改. 以下是更改列表:
0. ưμ㼯a
1. 您的代码只需要 `import GridStack from 'gridstack'` 或包含 `gridstack.all.js` 财务报告和审定财务报表 `gristack.css` (不包括其他JS),建议你这样做,因为内部依赖性会随时间而改变. 如果你是JKERY总部,看 [jquery 应用程序](https://npmcn.com/package/%40bdlite/gridstack/#readme-jquery-application) 节.
2. 代码更改 :
**旧的** 初始化代码 + 添加部件 + 添加事件 :
```js
// initialization returned Jquery element, requiring second call to get GridStack var
var grid = $('.grid-stack').gridstack(opts?).data('gridstack');
// returned Jquery element
grid.addWidget($(''), undefined, undefined, 2, undefined, true);
// jquery event handler
$('.grid-stack').on('added', function(e, items) {/* items contains info */});
// grid access after init
var grid = $('.grid-stack').data('gridstack');
```
**新建**
```js
// element identifier defaults to '.grid-stack', returns the grid
// Note: for Typescript use window.GridStack.init() until next native 2.x TS version
var grid = GridStack.init(opts?, element?);
// returns DOM element
grid.addWidget('', {width: 2});
// Note: in 3.x it's ever simpler
// grid.addWidget({w:2, content: 'test'})
// event handler
grid.on('added', function(e, items) {/* items contains info */});
// grid access after init
var grid = el.gridstack; // where el = document.querySelector('.grid-stack') or other ways...
```
其他重命名更改
```js
`GridStackUI` --> `GridStack`
`GridStackUI.GridStackEngine` --> `GridStack.Engine`
`grid.container` (jquery grid wrapper) --> `grid.el` // (grid DOM element)
`grid.grid` (GridStackEngine) --> `grid.engine`
`grid.setColumn(N)` --> `grid.column(N)` and `grid.column()` // to get value, old API still supported though
```
建议看 [许多样本](https://npmcn.com/package/%40bdlite/gridstack/demo) 更多代码示例.
## 移动到 v2
确保首先读取 v1 迁移 !
v2是一个Typescript重写1.x,去除所有jquery事件,使用类和整体代码清理支持ES6模块. 您的代码可能需要从 1. x 更改
1. 在一般方法中,没有使用args(getter) vs setter,当参数不同时(set/get也不是函数调用,所以API会更改),不能在TS中使用. 相反,我们决定 **返回所有设定的方法** `GridStack` 它们可以连锁(例如: `grid.float(true).cellHeight(10).column(6)`) (中文(简体) ). 另外,过去使用许多参数的遗留方法现在将采用单一对象(通常为: `GridStackOptions` 或者说 `GridStackWidget`) (中文(简体) ).
```js
`addWidget(el, x, y, width, height)` --> `addWidget(el, {with: 2})`
// Note: in 2.1.x you can now just do addWidget({with: 2, content: "text"})
`float()` --> `getFloat()` // to get value
`cellHeight()` --> `getCellHeight()` // to get value
`verticalMargin` --> `margin` // grid options and API that applies to all 4 sides.
`verticalMargin()` --> `getMargin()` // to get value
```
2. 事件签名是通用的,不再依赖jquery-ui. `gsresizestop` 已删除为 `resizestop|dragstop` 现在叫做 **之后** dOM 属性已更新.
3. `oneColumnMode` 会在 `window.width` < 768px 默认值。 我们现在检查网格宽度( 更正确并支持筑巢) 。 你可能需要调整网格 `oneColumnSize` 或者说 `disableOneColumnMode`。 。 。 .
**说明:** 2.x由于使用更紧凑的ES6输出和打字本地代码,不再支持遗留的IE11及更老. 你需要留在一号线
## 移动到 v3
确保先读 v2 迁移 !
v3有一个新的 HTML5 拖放插件( 共63k, 所有本地代码), 同时仍然允许您使用遗留的 jquery- ui 版本取而代之 (188k), 或一个新的静态网格版本( 34k, 没有用户拖放而是完整的 API 支持) 。 您需要决定使用哪个版本作为 `gridstack.all.js` 已经不复存在(现在也是) `gridstack-jq.js`\- 看见了 [包含信息](https://npmcn.com/package/%40bdlite/gridstack/#readme-include)。 。 。 .
**页:1**: HTML5 版本与以 jquery- ui 为主的旧拖放几乎是等价的. 页:1 `containment` (防止儿童被拖出父母的门外)和 `revert` (尚不清楚其用途)在 v3.0.0 的初始发布中尚未执行.
还有移动设备不支持h5 `drag` 事件(需要处理) `touch`) 而 v3.2 jq 版本现在支持退出框(参见 [v3.2 释放](https://github.com/gridstack/gridstack.js/releases/tag/v3.2.0)(中文(简体) )
中断更改 :
1. 包括(如上所述)需要改变
2. `GridStack.update(el, opt)` 现在要单身 `GridStackWidget` 而不是只支持(x,y,w,h),但联署材料中遗留下来的呼声目前将继续沿用。 这种方法是一个完全重写的方法,现在对所有可用的参数进行正确的限制和更新.
3. `locked()`, (中文(简体) ), `move()`, (中文(简体) ), `resize()`, (中文(简体) ), `minWidth()`, (中文(简体) ), `minHeight()`, (中文(简体) ), `maxWidth()`, (中文(简体) ), `maxHeight()` 方法被隐藏在 Typescript (JS 仍然可以调用) , 因为它们只是周围的一行包 `update(el, opt)` 无论如何,而且会很快离开。 (单位:千美元) `move(el, x, y)` => `update(el, {x, y})`(中文(简体) )
4. 项目属性类似 `data-gs-min-width` 现在 `gs-min-w`。我们从所有属性中删除了“ data ” , 将“ width- hiight” 缩写为“ w|h ” , 以要求打字次数少, 效率更高(2k 仅用. js 保存 !) .
5. `GridStackWidget` 用于大多数 API `width|height|minWidth|minHeight|maxWidth|maxHeight` 现在更短 `w|h|minW|minH|maxW|maxH` 还有
## 移动到 v4
确保先读出v3迁移!
v4 是一个完整的重写相撞并拖入/出高压以修正一些非常长的站立请求和bug. 它还大大提高了可用性。 详读出下注.
**不太可能,也许** 中断更改( 内部使用 ) :
1. `removeTimeout` 已删除( 垃圾后反馈将立即删除 - 鼠标上实际删除)
2. 以下 `GridStackEngine` 方法改变(内部使用,不影响 `GridStack` 公共 API)
```js
// moved to 3 methods with new option params to support new code and pixel coverage check
`collision()` -> `collide(), collideAll(), collideCoverage()`
`moveNodeCheck(node, x, y, w, h)` -> `moveNodeCheck(node, opt: GridStackMoveOpts)`
`isNodeChangedPosition(node, x, y, w, h)` -> `changedPosConstrain(node, opt: GridStackMoveOpts)`
`moveNode(node, x, y, w, h, noPack)` -> `moveNode(node, opt: GridStackMoveOpts)`
```
3. (v.0.6-v1方法/设备) `getGridHeight()`, (中文(简体) ), `verticalMargin`, (中文(简体) ), `data-gs-current-height`, (中文(简体) ), `locked()`, (中文(简体) ), `maxWidth()`, (中文(简体) ), `minWidth()`, (中文(简体) ), `maxHeight()`, (中文(简体) ), `minHeight()`, (中文(简体) ), `move()`, (中文(简体) ), `resize()`
## 移动到 v5
确保先读出v4迁移!
v5 没有任何从 v4 的分解变化,而是以 h5 模式聚焦于嵌入网格: 您现在可以拖入或拖出父方到被窝子, 并带有新的 API 参数值 。 见出所注.
## 移动到 v6
aPI 并没有从 v5 真正更改,而是完全重写 Drag&Drop 以使用本地 `mouseevent` (而不是HTML可拖取= truth 这在Mac Safari上是buggy, 而在移动设备上不起作用)和 `touchevent` (移动),而且我们不再有jquery ui选项(对于被嵌入的网格来说效果不好,不想维持后遗症).
主要的区别在于您只需要包含 grestack.js 并让 D&D(桌面和移动) 出框,大小与 h5 版本相同.
## 移动到 v7
新加法,每句没有API中断. 参见有关在苍蝇上创建子网格的发布注释.
## 移动到 v8
如果使用嵌入式网格JSON格式,或原角包装器,或依赖特定的CSS路径,则可能发生断裂变化. 目标也是ES2020(见发布说明).
- `GridStackOptions.subGrid` - > (中文) `GridStackOptions.subGridOpts` 复更名相. 我们现在有了 `GridStackWidget.subGridOpts` 对 `GridStackNode.subGrid` (这两类都容易出错)
- `GridStackOptions.addRemoveCB` - > (中文) `GridStack.addRemoveCB` 现在为全局性,而不是网格选项
- 删除 `GridStackOptions.dragInOptions` 自此以来 `GridStack.setupDragIn()` 自4.0起更换
- 删除 `GridStackOptions.minWidth` 5.1 已过时,使用 `oneColumnSize` 换成
- CSS 规则已删除 `.grid-stack` 任何已基于 gs 的字符前缀, 12 列( 默认) 现在使用 `.gs-12`外加cs还不到原尺寸的四分之一, `gs-min|max_w|h` 属性不再写入( 但已读)
# j 查询应用程序
这是 **旧的,不再适用于v6+**。您需要使用v5.1.1 和之前
```js
import 'gridstack/dist/gridstack.min.css';
import { GridStack } from 'gridstack';
import 'gridstack/dist/jq/gridstack-dd-jqueryui';
```
**说明**数字 : `jquery` 打开 `jquery-ui` 以名称导入,所以您必须在您的网络包(或等同的)配置文件中指定其位置, 也就是说你可以带自己的版本
```js
alias: {
'jquery': 'gridstack/dist/jq/jquery.js',
'jquery-ui': 'gridstack/dist/jq/jquery-ui.js',
'jquery.ui': 'gridstack/dist/jq/jquery-ui.js',
'jquery.ui.touch-punch': 'gridstack/dist/jq/jquery.ui.touch-punch.js',
},
```
或者( 单个合并文件) html
```html