API

Grid

构造函数

declare const options: IGridOptions | undefined
const grid = new Grid(options)

createGrid

declare const options: IGridOptions | undefined
const grid = createGrid(options)

createGrid 是 new Grid(options) 的轻量封装，他返回一个markRaw的Grid实例。

构造函数配置表

选项	类型	默认值	描述
`maxRows`	`number`	`Infinity`	最大行数
`maxColumns`	`number \| number[]`	`Infinity`	最大列数，可按断点提供数组
`minColumns`	`number \| number[]`	`1`	最小列数，可按断点提供数组
`maxWidth`	`number \| number[]`	`Infinity`	列最大宽度，可按断点提供数组
`minWidth`	`number \| number[]`	`100`	列最小宽度，可按断点提供数组
`breakpoints`	`number[]`	`[720, 1280, 1920]`	断点数组
`columnGap`	`number \| number[]`	`8`	列间距，可按断点提供数组
`rowGap`	`number \| number[]`	`4`	行间距，可按断点提供数组
`colWrap`	`boolean \| boolean[]`	`true`	是否允许自动换列
`strictAutoFit`	`boolean`	`false`	是否严格约束在最小/最大宽度范围内
`shouldVisible`	`(node: GridNode, grid: Grid) => boolean`	-	自定义节点可见性
`onDigest`	`(grid: Grid) => void`	-	每次布局计算后触发
`onInitialized`	`(grid: Grid) => void`	-	首次初始化完成后触发

connect

declare const container: HTMLElement
const dispose = grid.connect(container)

返回 dispose，用于解绑 ResizeObserver / MutationObserver 与清理内部状态。

IGridOptions

interface IGridOptions {
  maxRows?: number
  maxColumns?: number | number[]
  minColumns?: number | number[]
  maxWidth?: number | number[]
  minWidth?: number | number[]
  breakpoints?: number[]
  columnGap?: number
  rowGap?: number
  colWrap?: boolean
  strictAutoFit?: boolean

  shouldVisible?: (node: GridNode, grid: Grid<HTMLElement>) => boolean
  onDigest?: (grid: Grid<HTMLElement>) => void
  onInitialized?: (grid: Grid<HTMLElement>) => void
}

GridNode

type GridNode = {
  index?: number
  visible?: boolean
  column?: number
  shadowColumn?: number
  row?: number
  shadowRow?: number
  span?: number
  originSpan?: number
  element?: HTMLElement
}

Grid 实例状态

字段	类型	说明
`width`	`number`	容器宽度
`height`	`number`	容器高度
`columns`	`number`	当前列数
`rows`	`number`	当前行数
`templateColumns`	`string`	当前 `grid-template-columns`
`gap`	`string`	当前 CSS `gap`
`breakpoint`	`number`	当前断点索引
`ready`	`boolean`	是否已执行初始化布局

Grid Span

data-grid-span 用于声明节点占列规则：

data-grid-span="n": 占 n 列。
data-grid-span="-1": 从当前列自动填满到本行末尾（用于尾部补齐）。

下面的 demo 可以切换 Actions 的 span 为 -1 或 1，直观看到自动补齐差异：

<script setup lang="ts">
import { Grid } from '@silver-formily/grid'
import { computed, onBeforeUnmount, onMounted, ref } from 'vue'

const containerRef = ref<HTMLElement | null>(null)
const useAutoFill = ref(true)
const templateColumns = ref('repeat(4,minmax(0,1fr))')
const gap = ref('8px 8px')
const columns = ref(4)

const items = computed(() => [
  { key: 'name', label: 'Name', span: 1 },
  { key: 'email', label: 'Email', span: 1 },
  {
    key: 'actions',
    label: 'Actions',
    span: useAutoFill.value ? -1 : 1,
    accent: true,
  },
  { key: 'phone', label: 'Phone', span: 1 },
  { key: 'company', label: 'Company', span: 2 },
  { key: 'city', label: 'City', span: 1 },
  { key: 'zip', label: 'Zip', span: 1 },
])

let dispose: (() => void) | undefined

const grid = new Grid({
  minColumns: 4,
  maxColumns: 4,
  minWidth: 70,
  maxWidth: 160,
  columnGap: 8,
  rowGap: 8,
  onDigest(current) {
    templateColumns.value = current.templateColumns
    gap.value = current.gap
    columns.value = current.columns
  },
})

onMounted(() => {
  if (!containerRef.value)
    return
  dispose = grid.connect(containerRef.value)
})

onBeforeUnmount(() => {
  dispose?.()
})
</script>

<template>
  <div>
    <p>
      <label><input v-model="useAutoFill" type="checkbox"> Use <code>data-grid-span="-1"</code> for Actions</label>
    </p>
    <p>
      columns={{ columns }} / Actions span={{ useAutoFill ? -1 : 1 }}
    </p>
    <div ref="containerRef" class="grid-board" :style="{ gridTemplateColumns: templateColumns, gap }">
      <div
        v-for="item in items"
        :key="item.key"
        class="grid-card"
        :class="{ accent: item.accent }"
        :data-grid-span="item.span"
      >
        <strong>{{ item.label }}</strong>
        <span>data-grid-span={{ item.span }}</span>
      </div>
    </div>
  </div>
</template>

<style scoped>
.grid-board {
  display: grid;
}

.grid-card {
  border: 1px solid var(--vp-c-divider);
  border-radius: 10px;
  padding: 10px;
  background: var(--vp-c-bg-soft);
  display: flex;
  flex-direction: column;
  gap: 6px;
}

.grid-card.accent {
  border-color: var(--vp-c-brand-1);
  background: color-mix(in srgb, var(--vp-c-brand-1) 12%, var(--vp-c-bg-soft));
}
</style>

Use data-grid-span="-1" for Actions

columns=4 / Actions span=-1

Namedata-grid-span=1

Emaildata-grid-span=1

Actionsdata-grid-span=-1

Phonedata-grid-span=1

Companydata-grid-span=2

Citydata-grid-span=1

Zipdata-grid-span=1

API ​

Grid ​

构造函数 ​

createGrid ​

构造函数配置表 ​

connect ​

IGridOptions ​

GridNode ​

Grid 实例状态 ​

Grid Span ​

API