@gravity-ui/dashkit

中文文档
10.5.2发布于 2026/10/06MITTypeScriptESM + CJS近 30 天下载 2.7万

用于渲染仪表板网格布局的库

中文使用文档
文档目录22 节
  1. 安装
  2. 说明
  3. 插件
  4. 道具
  5. 使用量
  6. DashKit 配置
  7. 配置
  8. 参数
  9. 状态和图像
  10. DashKit实验事件
  11. 菜单
  12. 来自动作小组的可拖动项目
  13. CSS API (英语)
  14. 发展
  15. 构建监视( W)
  16. Dev 机器上的 nginx 开发配置示例
  17. 许可证
  18. 对于人工智能特工
  19. 何时使用
  20. 不使用时
  21. 常见陷阱
  22. AI代理的文件

@gravity-ui/dashkit – 页面存档备份,存于互联网档案馆 npm package CI storybook

达什基特

一个仪表板网格渲染库.

安装

npm i @gravity-ui/dashkit @gravity-ui/uikit

说明

库用于将部件排入网格,调整大小,添加新部件并删除. 部件是一个反应组件 。 例如文本,图形,和图像.

通过插件系统添加了新部件 .

插件

需要插件来创建自定义部件 .

道具

type ItemManipulationCallback = (eventData: {
  layout: Layout[];
  oldItem: Layout;
  newItem: Layout;
  placeholder: Layout;
  e: MouseEvent;
  element: HTMLElement;
}) => void;

interface DashKitProps {
  config: Config;
  editMode: boolean;
  onItemEdit: ({id}: {id: string}) => void;
  onChange: (data: {config: Config; itemsStateAndParams: ItemsStateAndParams}) => void;
  onDrop: (dropProps: ItemDropProps) => void;
  onItemMountChange: (item: ConfigItem, state: {isAsync: boolead; isMounted: boolean}) => void;
  onItemRender: (item: ConfigItem) => void;

  onDragStart?: ItemManipulationCallback;
  onDrag?: ItemManipulationCallback;
  onDragStop?: ItemManipulationCallback;
  onResizeStart?: ItemManipulationCallback;
  onResize?: ItemManipulationCallback;
  onResizeStop?: ItemManipulationCallback;

  defaultGlobalParams: GlobalParams;
  globalParams: GlobalParams;
  itemsStateAndParams: ItemsStateAndParams;
  settings: SettingsProps;
  context: ContextProps;
  overlayControls?: Record<string, OverlayControlItem[]> | null;
  overlayMenuItems?: MenuItems[] | null;
  noOverlay?: boolean;

  focusable?: boolean;
  onItemFocus: (item: ConfigItem) => void;
  onItemBlur: (item: ConfigItem) => void;

  draggableHandleClassName?: string;
  getPreparedCopyItemOptions?: (options: PreparedCopyItemOptions) => PreparedCopyItemOptions;
  onCopyFulfill?: (error: null | Error, data?: PreparedCopyItemOptions) => void;
}
  • 配置数字 : 图片。 。 。 .
  • 编辑模式: 是否启用了编辑模式.
  • 项目编辑: 单击编辑部件时调用.
  • 变化: 配置时调用或 状态和图像 改为.
  • 打开: 使用(# DashKitDnDWrapper) 从 ActionPanel 跳出项目时调用
  • 项目MountChange: 当项目挂载状态改变时调用
  • 项目招标人: 当项目完成时调用
  • 默认全球图片, (中文(简体) ), 全球图片数字 : 参数 影响所有部件。 在数据Lens, defaultGlobalParams 是在仪表板设置中设置的全球参数. globalParams 是可以在url中设置的全局参数.
  • 状态和图像数字 : 状态和图像。 。 。 .
  • 设置: DashKit 设置.
  • 上下文: 将安装在所有部件上的对象.
  • 覆盖控制: 编辑时超过部件控制的对象。 如果不转发,则将显示基本控件。 若为 null 只通过关闭按钮或自定义菜单.
  • 覆盖梅努项目: 自定义下拉菜单项
  • 无重叠: 如果 true,在编辑时不显示覆盖和控件.
  • 可聚焦: 如果 true,网格项目将可聚焦.
  • 项目焦点: 调用时 focusable 真实,项目是焦点.
  • 关于项目Blur: 调用时 focusable 正确,项目被聚焦.
  • 可拖动的手表Name : 使部件可拖动的元素的 QSS 类名称.
  • 在DragStart上开始: 当项目拖动开始时, ReactGridLayout 呼叫
  • 打开 Drag: 在项目拖动时, ReactGridLayout 呼叫
  • 在Drag停止时: 当项目拖动停止时, ReactGridLayout 呼叫
  • 启动: 项目调整大小时, ReactGridLayout 呼叫
  • 回复: 在项目调整大小时, ReactGridLayout 呼叫
  • 恢复状态: 当项目调整大小停止时, ReactGridLayout 呼叫
  • 获得准备的项目选项: 调用在保存到本地存储之前将复制的项目转换为可序列对象 。 应该用它来代替去腐烂 context.getPreparedCopyItemOptions 道具
  • 装入: 项目复制完成时调用 error=null 定义 data 已成功运行的 error: Error 无 data 否则

使用量

DashKit 配置

使用前 DashKit 作为反应组件,它必须配置.

  • 设置语言

    import {configure, Lang} from '@gravity-ui/uikit';
    
    configure({lang: Lang.En});
    
  • DashKit.set 设置

    用于全局 DashKit 设置( 如部件间边距、 默认部件大小和部件上覆菜单)

    import {DashKit} from '@gravity-ui/dashkit';
    
    DashKit.setSettings({
      gridLayout: {margin: [8, 8]},
      isMobile: true,
      // menu: [] as Array<MenuItem>,
    });
    
  • DashKit.register 普卢金斯

    注册和配置插件

    import {DashKit} from '@gravity-ui/dashkit';
    import {pluginTitle, pluginText} from '@gravity-ui/dashkit';
    
    DashKit.registerPlugins(
      pluginTitle,
      pluginText.setSettings({
        apiHandler({text}) {
          return api.getMarkdown(text);
        },
      }),
    );
    
    DashKit.registerPlugins({
      type: 'custom',
      defaultLayout: {
        w: 10,
        h: 8,
      },
      renderer: function CustomPlugin() {
        return <div>Custom widget with custom controls</div>;
      },
    });
    

配置

export interface Config {
  salt: string; // to form a unique id
  counter: number; // to form a unique id, only increases
  items: ConfigItem[]; //  initial widget states
  layout: ConfigLayout[]; // widget position on the grid https://github.com/react-grid-layout
  aliases: ConfigAliases; // aliases for parameters see #Params
  connections: ConfigConnection[]; // links between widgets see #Params
}

配置示例 :

import {DashKitProps} from '@gravity-ui/dashkit';

const config: DashKitProps['config'] = {
  salt: '0.46703554571365613',
  counter: 4,
  items: [
    {
      id: 'tT',
      data: {
        size: 'm',
        text: 'Caption',
        showInTOC: true,
      },
      type: 'title',
      namespace: 'default',
      orderId: 1,
    },
    {
      id: 'Ea',
      data: {
        text: 'mode _editActive',
        _editActive: true,
      },
      type: 'text',
      namespace: 'default',
    },
    {
      id: 'zR',
      data: {
        text: '### Text',
      },
      type: 'text',
      namespace: 'default',
      orderId: 0,
    },
    {
      id: 'Dk',
      data: {
        foo: 'bar',
      },
      type: 'custom',
      namespace: 'default',
      orderId: 5,
    },
  ],
  layout: [
    {
      h: 2,
      i: 'tT',
      w: 36,
      x: 0,
      y: 0,
    },
    {
      h: 6,
      i: 'Ea',
      w: 12,
      x: 0,
      y: 2,
    },
    {
      h: 6,
      i: 'zR',
      w: 12,
      x: 12,
      y: 2,
    },
    {
      h: 4,
      i: 'Dk',
      w: 8,
      x: 0,
      y: 8,
    },
  ],
  aliases: {},
  connections: [],
};

在配置中添加新项目 :

const newLayout = updateLayout: [
  {
    h: 6,
    i: 'Ea',
    w: 12,
    x: 0,
    y: 6,
  },
  {
    h: 4,
    i: 'Dk',
    w: 8,
    x: 0,
    y: 12,
  },
];

const newConfig = DashKit.setItem({
  item: {
    data: {
      text: `Some text`,
    },
    namespace: 'default',
    type: 'text',
    // Optional. If new item needed to be inserted in current layout with predefined dimensions
    layout: { // Current item inseterted before 'Ea'
      h: 6,
      w: 12,
      x: 0,
      y: 2,
    },,
  },
  config: config,
  options: {
    // Optional. New layout values for existing items when new element is dropped from ActionPanel
    updateLayout: newLayout,
  },
});

更改配置中的现有项目 :

const newConfig = DashKit.setItem({
  item: {
    id: 'tT', // item.id
    data: {
      size: 'm',
      text: `New caption`,
    },
    namespace: 'default',
    type: 'title',
  },
  config: config,
});

删除配置中的一个项目 :

import {DashKitProps} from '@gravity-ui/dashkit';

const oldItemsStateAndParams: DashKitProps['itemsStateAndParams'] = {};

const {config: newConfig, itemsStateAndParams} = DashKit.removeItem({
  id: 'tT', // item.id
  config: config,
  itemsStateAndParams: this.state.itemsStateAndParams,
});

参数

type Params = Record<string, string | string[]>;

DashKit 根据部件、链接和别名的默认参数生成参数。 这些参数是: 图表Kit 图书馆.

生成顺序 :

  1. defaultGlobalParams
  2. 默认部件参数 item.default
  3. globalParams
  4. 参数来源 状态和图像 根据队列.

状态和图像

存储部件参数和状态以及参数更改队列的对象 . 它有一个 __meta__ 字段用于存储队列和元信息.

interface StateAndParamsMeta = {
    __meta__: {
        queue: {id: string}[]; // queue
        version: number; // current version itemsStateAndParams
    };
}

还有部件状态和参数:

interface ItemsStateAndParamsBase {
  [itemId: string]: {
    state?: Record<string, any>;
    params?: Params;
  };
}
type ItemsStateAndParams = StateAndParamsMeta & ItemsStateAndParamsBase;

DashKit实验事件

实验:这种API可以改变小释放.

DashKit 曝光实验事件 API. 使用组件校对并订阅 dashkitRef.current?.on(eventName, handler)。该方法返回未订阅的回调.

第一个支持的活动是 change。当布局发生变化时,在 onChange 名为. 处理器可以读取下个和以前的完整布局,读取布局补丁,或者调用 preventDefault() 停止默认 onChange 电话.

import React from 'react';
import {DashKit} from '@gravity-ui/dashkit';
import type {DashKitChangeEvent} from '@gravity-ui/dashkit';

function Dashboard() {
  const dashkitRef = React.useRef<DashKit>(null);

  React.useEffect(() => {
    const unsubscribe = dashkitRef.current?.on('change', (event: DashKitChangeEvent) => {
      console.log(event.patches);

      if (event.patches.length > 0) {
        event.preventDefault();
      }
    });

    return () => unsubscribe?.();
  }, []);

  return <DashKit ref={dashkitRef} config={config} editMode={true} onChange={onChange} />;
}
type DashKitLayoutPatch = Pick<ConfigLayout, 'i'> &
  Partial<Pick<ConfigLayout, 'x' | 'y' | 'w' | 'h' | 'parent'>>;

type DashKitChangeEvent = {
  patches: DashKitLayoutPatch[];
  layout: ConfigLayout[];
  previousLayout: ConfigLayout[];
  preventDefault: () => void;
  readonly defaultPrevented: boolean;
};

事件驱动的布局更新

如果您使用 preventDefault() 输入 change 事件处理器,您现在可以处理布局更新而无需重新初始化配置道具. DashKit 维持内部基线,并逐步计算补丁:

function Dashboard() {
  const [config, setConfig] = useState(initialConfig);
  const dashkitRef = useRef<DashKit>(null);

  useEffect(() => {
    const unsubscribe = dashkitRef.current?.on('change', (event) => {
      event.preventDefault(); // Don't call onChange

      // Send only the incremental patches to your backend
      sendPatches(event.patches);

      // No need to call setConfig({ ...config, layout: event.layout })
      // DashKit maintains the visual state internally
    });

    return unsubscribe;
  }, []);

  return <DashKit ref={dashkitRef} config={config} editMode onChange={() => {}} />;
}

重要内容: 如果您稍后更新 config.layout 从道具(例如从服务器同步),DashKit将重设内部基线来匹配新的道具. 这确保了与事件驱动和控制下的工作流程的相容性.

菜单

您可以在编辑模式下指定自定义 DashKit 部件覆盖菜单

type MenuItem = {
  id: string; // uniq id
  title?: string; // string title
  icon?: ReactNode; // node of icon
  iconSize?: number | string; // icon size in px as number or as string with units
  handler?: (item: ConfigItem) => void; // custom item action handler
  visible?: (item: ConfigItem) => boolean; // optional visibility handler for filtering menu items
  className?: string; // custom class property
};

// use array of menu items in settings
<Dashkit overlayMenuItems={[] as Array<MenuItem> | null} />

[deprecated]
// overlayMenuItems property has greater priority over setSettings menu
DashKit.setSettings({menu: [] as Array<MenuItem>});

来自动作小组的可拖动项目

DashKitDnD 剪贴机

type DraggedOverItem = {
  h: number;
  w: number;
  type: string;
  parent: string;
  i?: number;
};

interface DashKitDnDWrapperProps {
  dragImageSrc?: string;
  onDragStart?: (dragProps: ItemDragProps) => void;
  onDragEnd?: () => void;
  onDropDragOver?: (
    draggedItem: DraggedOverItem,
    sharedItem: DraggedOverItem | null,
  ) => void | boolean;
}
  • 拖动图像Sc: 可选自定义拖动图像. 默认情况下,拖曳的 ActionPannel 项将显示为预览.
  • 在DragStart上开始: 当元素从动作板被拖取时调用回调
  • 打开: 元素被丢弃或被拖曳取消时调用回电
type ItemDragProps = {
  type: string; // Plugin type
  layout?: {
    // Optional. Layout item size for preview and init
    w?: number;
    h?: number;
  };
  extra?: any; // Custom user context
};
type ItemDropProps = {
  commit: () => void; // Callback should be called after all config operations are made
  dragProps: ItemDragProps; // Item drag props
  itemLayout: ConfigLayout; // Calculated item layout dimensions
  newLayout: ConfigLayout[]; // New layout after element is dropped
};

示例

const overlayMenuItems = [
  {
    id: 'chart',
    icon: <Icon data={ChartColumn} />,
    title: 'Chart',
    qa: 'chart',
    dragProps: { // ItemDragProps
        type: 'custom', // Registered plugin type
    },
  }
]

const onDrop = (dropProps: ItemDropProps) => {
  // ... add element to your config
  dropProps.commit();
}

<DashKitDnDWrapper>
  <DashKit editMode={true} config={config} onChange={onChange} onDrop={onDrop} />
  <ActionPanel items={overlayMenuItems} />
</DashKitDnDWrapper>

CSS API (英语)

名称说明
行动小组变量
--dashkit-action-panel-color背景颜色
--dashkit-action-panel-border-color边框颜色
--dashkit-action-panel-border-radius边界半径
行动小组项目变量
--dashkit-action-panel-item-color后灰色颜色
--dashkit-action-panel-item-text-color文本颜色
--dashkit-action-panel-item-color-hover弯腰后灰色
--dashkit-action-panel-item-color-dragging拖动背景颜色
--dashkit-action-panel-item-text-color-hover隐藏文本颜色
--dashkit-action-panel-item-text-color-dragging拖动文本颜色
重叠变量
--dashkit-overlay-border-color边框颜色
--dashkit-overlay-color背景颜色
--dashkit-overlay-opacity不透明度
网格项目变量
--dashkit-grid-item-edit-opacity不透明度
--dashkit-grid-item-border-radius边界半径
占位符变量
--dashkit-placeholder-color背景颜色
--dashkit-placeholder-opacity不透明度

用法实例

.custom-theme-wrapper {
  --dashkit-grid-item-edit-opacit: 1;
  --dashkit-overlay-color: var(--g-color-base-float);
  --dashkit-overlay-border-color: var(--g-color-base-float);
  --dashkit-overlay-opacity: 0.5;

  --dashkit-action-panel-border-color: var(--g-color-line-info);
  --dashkit-action-panel-color: var(--g-color-base-float-accent);
  --dashkit-action-panel-border-radius: var(--g-border-radius-xxl);
}
// ....

const CustomThemeWrapper = (props: {
  dashkitProps: DashkitProps;
  actionPanelProps: ActionPanelProps;
}) => {
  return (
    <div className="custom-theme-wrapper">
      <Dashkit {...props.dashkitProps} />
      <ActionPanel {...props.actionPanelProps} />
    </div>
  );
};

发展

构建监视( W)

  • 建立依赖关系 npm ci
  • 构建工程 npm run build
  • 构建故事本 npm run start

默认情况下, 故事本运行在 http://localhost:7120/。 。 。 . 在故事本运行时,项目的新变化并不总是被取出,因此最好手动重建项目并重启故事本.

Dev 机器上的 nginx 开发配置示例

server {
    server_name dashkit.username.ru;

    include common/ssl;

    access_log /home/username/logs/common.access.log;
    error_log /home/username/logs/common.error.log;

    root /home/username/projects/dashkit;

    location / {
        try_files $uri @node;
    }

    location @node {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://127.0.0.1:7120;
        proxy_redirect off;
    }
}

许可证

根据麻省理工学院的许可证分发。 见 自由主义 详细情况.

对于人工智能特工

一个仪表板网格作曲器,通过插件系统在应答网格中安排可重塑可拖动的部件——当您构建出一个用户可编辑的仪表板(添加/移动/调整大小/删除部件)而不是手工放置单个图表或面板时,可以到达.

何时使用

  • 制作可配置的仪表板,将部件定位、调整大小并重新排列在网格上(建造于 react-grid-layout) (中文(简体) ).
  • 用户编辑版式:从动作面板上添加/删除部件,拖放,有覆盖控件的编辑模式.
  • 基于插件的部件,每个部件类型(标题、文本、图表、自定义)都登记一次,并由一个部件驱动 config。 。 。 .

不使用时

  • 用于单个固定图表或面板 @gravity-ui/charts 或者说 @gravity-ui/chartkit 直接的——网格/插件机械是一个部件的起落架.
  • 对于不是部件仪表板的通用响应网格,使用 react-grid-layout 直接说.
  • 在 DashKit 仪表板内嵌入 ChartKit 备份的图表部件时, DashKit 是 shell; 它仍然依赖 @gravity-ui/chartkit 以制作实际图表.

常见陷阱

  • 幻觉成分 <Dashboard> - 出口为 <DashKit> (拖放壳为: <DashKitDnDWrapper> 包装 <DashKit> + 键 <ActionPanel>) (中文(简体) ).
  • 变异 config 而不是使用帮助 - 使用静态 DashKit.setItem({...}) 编号 : DashKit.removeItem({...}) 帮助添加/更改/移动项目这样布局,ids保持不变.
  • 忘记 DashKit.setSettings 编号 : DashKit.registerPlugins —— 组件在被渲染前必须配置( 语言, 网格设置, 插件注册) , 或者部件显示什么也没有 .
  • 混淆两个参数道具 —— 说 defaultGlobalParams (磁盘级别默认值) vs globalParams (URL- overridable globals); 两者都流入ChartKit所消耗的参数生成队列.
  • 通话 onChange 手动与 change 事件 - 当你 event.preventDefault() 在实验中 change 处理器, DashKit 保持视觉状态内部; 重置 config.layout 从道具重置基线.

AI代理的文件

安装版本的可代理读取文档位于 node_modules/@gravity-ui/dashkit/build/docs/INDEX.md。 。 。 .

版本与发布记录

@gravity-ui/dashkit 共发布 186 个版本,首次发布于 2022/10/03;过去 12 个月发布了 21 个版本。

版本发布日期距今
10.5.2latest2026/10/061 个月前
10.5.12026/10/051 个月前
10.5.02026/10/031 个月前
10.4.42026/09/171 个月前
10.4.32026/09/032 个月前
10.4.22026/09/022 个月前

其他发布通道:alpha → 3.1.0-alpha.2,unstable-4 → 4.1.1-unstable-4.0,untagged → 8.27.0,beta → 10.0.0-beta.0。

关于 @gravity-ui/dashkit 的常见问题

@gravity-ui/dashkit 是什么?

用于渲染仪表板网格布局的库

如何安装 @gravity-ui/dashkit?

在项目目录运行 npm install @gravity-ui/dashkit,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^16.8.0 || ^17 || ^18 || ^19)、react-dom(^16.8.0 || ^17 || ^18 || ^19)、@gravity-ui/icons(^2.13.0)、@gravity-ui/uikit(^7.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gravity-ui/dashkit 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gravity-ui/dashkit 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gravity-ui/dashkit 可以商用吗?

@gravity-ui/dashkit 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gravity-ui/dashkit 的下载量有多少?

根据 npm 官方下载统计,@gravity-ui/dashkit 在 2026/10/17 – 2026/11/15 这 30 天内被下载 27,040 次,日均约 901 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gravity-ui/dashkit 还在维护吗?

最新版本 10.5.2 发布于 2026/10/06(1 个月前);至今共发布 186 个版本,其中过去 12 个月发布了 21 个;首次发布于 2022/10/03。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。