@xiangge1307/icon-grid

框架无关的图标网格核心引擎：拖拽排序、分组合并、分组面板、右键菜单、内联重命名。提供 Vue 3 / React 18 适配器，也可直接使用 IconGridCore。

安装

pnpm add @xiangge1307/icon-grid

使用 Vue / React 时请安装对应适配器，并同时安装本包（peer dependency）。

必须引入样式

import '@xiangge1307/icon-grid/style.css'

未引入时布局、拖拽手型、分组面板与菜单样式会缺失。

纯 JS / TS 用法

import { IconGridCore } from '@xiangge1307/icon-grid'
import type { GridItem } from '@xiangge1307/icon-grid'
import '@xiangge1307/icon-grid/style.css'

const container = document.getElementById('grid')!
const items: GridItem[] = [
  { id: '1', label: '工作台', icon: '/icons/a.png', type: 'icon' },
  { id: '2', label: '设置', icon: '/icons/b.png', type: 'icon' },
]

const grid = new IconGridCore(container, {
  items,
  cols: 6,
  onChange: (next) => {
    // 自行持久化 / 写回数据
    console.log(next)
  },
})

// 销毁
// grid.destroy()

框架适配器

| 包 | 说明 | |----|------| | @xiangge1307/icon-grid-vue | Vue 3 <IconGrid /> | | @xiangge1307/icon-grid-react | React 18 <IconGrid /> |

功能特性

• 拖拽排序（Pointer Events + FLIP 动画）
• 悬停合并分组 / 拖入已有分组
• 分组展开面板、组内排序
• 右键 / 长按菜单：重命名、新建分组、移入分组、删除
• Web 端悬停描述（descriptionField 从 meta 读取）
• CSS 变量主题；支持 prefers-color-scheme: dark

数据模型

interface IconItem {
  id: string
  label: string
  icon: string
  type: 'icon'
  meta?: Record<string, unknown>
}

interface IconGroup {
  id: string
  label: string
  type: 'group'
  children: IconItem[]
  maxChildren?: number
}

type GridItem = IconItem | IconGroup

常用选项

| 选项 | 默认值 | 说明 | |------|--------|------| | items | — | 必填，网格数据 | | cols | 自适应 | 每行列数 | | editable | true | 是否可拖拽 / 右键 | | descriptionField | — | 悬停描述取自 meta[field]；false 关闭 | | onChange | — | 数据变更回调（深拷贝） |

完整 API 见 monorepo 文档或适配器 README。

License

MIT