gridKeyboardNav

网格式列表的键盘方向导航：由方向键解析位移并计算下一选中索引。

函数签名

type GridKeyboardNavDirection = 'up' | 'down' | 'left' | 'right'

function gridKeyboardDirectionFromKey(key: string): GridKeyboardNavDirection | null
function measureGridColumnsByOffsetTop(items: ArrayLike<{ offsetTop: number }>): number
function measureGridColumns(gridEl: { querySelectorAll: ... }, itemSelector: string): number
function resolveGridKeyboardNavIndex(
  currentIndex: number,
  direction: GridKeyboardNavDirection,
  itemCount: number,
  columns: number,
): number | null

参数

函数	参数	说明
gridKeyboardDirectionFromKey	key	键盘 event.key，仅识别四个方向键
measureGridColumnsByOffsetTop	items	按首行 offsetTop 统计列数
measureGridColumns	gridEl, itemSelector	在容器内查询子项并统计列数
resolveGridKeyboardNavIndex	currentIndex, direction, itemCount, columns	计算下一索引，无法移动返回 null

返回值

函数	类型	说明
gridKeyboardDirectionFromKey	GridKeyboardNavDirection | null	非方向键返回 null
measureGridColumns*	number	至少为 1
resolveGridKeyboardNavIndex	number | null	新索引或边界外 null

工作原理

1. 列数测量：首行连续相同 offsetTop 的元素个数即为列数。
2. 索引映射：col = index % columns，row = floor(index / columns)。
3. 位移规则：左右移 ±1；上移 -columns；下移 +columns，且不超过 itemCount - 1。
4. 边界：已在边缘或目标越界时返回 null，由调用方忽略按键。