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

达什基特
一个仪表板网格渲染库.
安装
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 图书馆.
生成顺序 :
defaultGlobalParams- 默认部件参数
item.default globalParams- 参数来源 状态和图像 根据队列.
状态和图像
存储部件参数和状态以及参数更改队列的对象 .
它有一个 __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(磁盘级别默认值) vsglobalParams(URL- overridable globals); 两者都流入ChartKit所消耗的参数生成队列. - 通话
onChange手动与change事件 - 当你event.preventDefault()在实验中change处理器, DashKit 保持视觉状态内部; 重置config.layout从道具重置基线.
AI代理的文件
安装版本的可代理读取文档位于 node_modules/@gravity-ui/dashkit/build/docs/INDEX.md。 。 。 .