foucui 1.0.1

package/components/QiuTable/useMerge.ts

@@ -0,0 +1,105 @@
+import type { QiuTableColumnConfig, QiuTableMergeCell, QiuTableSpanMethod } from './types'
+
+export type SpanResult = { rowspan: number; colspan: number; visible: boolean }
+
+/**
+ * 根据 spanMethod / mergeCells 计算单元格合并。
+ * columnIndex 为叶子数据列下标（不含 selection/index）。
+ */
+export function resolveCellSpan(opts: {
+  row: any
+  column: QiuTableColumnConfig
+  rowIndex: number
+  columnIndex: number
+  data: any[]
+  spanMethod?: QiuTableSpanMethod
+  mergeCells?: QiuTableMergeCell[]
+  /** 预计算：被合并覆盖的格子 key `${rowIndex}:${columnIndex}` */
+  covered?: Set<string>
+}): SpanResult {
+  const key = `${opts.rowIndex}:${opts.columnIndex}`
+  if (opts.covered?.has(key)) {
+    return { rowspan: 0, colspan: 0, visible: false }
+  }
+
+  let rowspan = 1
+  let colspan = 1
+
+  if (opts.mergeCells?.length) {
+    const hit = opts.mergeCells.find(
+      (m) => m.row === opts.rowIndex && m.col === opts.columnIndex
+    )
+    if (hit) {
+      rowspan = hit.rowspan
+      colspan = hit.colspan
+    }
+  }
+
+  if (opts.spanMethod) {
+    const res = opts.spanMethod({
+      row: opts.row,
+      column: opts.column,
+      rowIndex: opts.rowIndex,
+      columnIndex: opts.columnIndex,
+      data: opts.data,
+    })
+    if (Array.isArray(res)) {
+      rowspan = Number(res[0] ?? 1)
+      colspan = Number(res[1] ?? 1)
+    } else if (res && typeof res === 'object') {
+      rowspan = Number(res.rowspan ?? 1)
+      colspan = Number(res.colspan ?? 1)
+    }
+  }
+
+  if (rowspan === 0 || colspan === 0) {
+    return { rowspan: 0, colspan: 0, visible: false }
+  }
+  return { rowspan, colspan, visible: true }
+}
+
+/** 根据 mergeCells 生成被覆盖格子集合 */
+export function buildMergeCoveredSet(mergeCells?: QiuTableMergeCell[]): Set<string> {
+  const covered = new Set<string>()
+  if (!mergeCells?.length) return covered
+  for (const m of mergeCells) {
+    for (let r = m.row; r < m.row + m.rowspan; r++) {
+      for (let c = m.col; c < m.col + m.colspan; c++) {
+        if (r === m.row && c === m.col) continue
+        covered.add(`${r}:${c}`)
+      }
+    }
+  }
+  return covered
+}
+
+/**
+ * 将 mergeHeaderCells 应用到表头矩阵（按 row/col 下标合并 th）
+ * children 多级表头已自动合并；本 API 用于扁平表头额外合并。
+ */
+export function applyMergeHeaderCells(
+  headerRows: import('./types').QiuTableHeaderCell[][],
+  merges?: QiuTableMergeCell[]
+): import('./types').QiuTableHeaderCell[][] {
+  if (!merges?.length || !headerRows.length) return headerRows
+  const covered = buildMergeCoveredSet(merges)
+  return headerRows.map((row, ri) => {
+    const next: typeof row = []
+    for (const cell of row) {
+      const key = `${ri}:${cell.colIndex}`
+      if (covered.has(key)) continue
+      const hit = merges.find((m) => m.row === ri && m.col === cell.colIndex)
+      if (hit) {
+        next.push({
+          ...cell,
+          rowspan: hit.rowspan,
+          colspan: hit.colspan,
+        })
+      } else {
+        next.push(cell)
+      }
+    }
+    return next
+  })
+}
+

package/components/QiuTable/useResize.ts

@@ -0,0 +1,86 @@
+import { onBeforeUnmount, onMounted, reactive, type Ref } from 'vue'
+
+/** 列宽拖拽：写入 columnWidths，供 colgroup / 单元格样式使用 */
+export function useColumnResize(opts?: { minWidth?: number; maxWidth?: number }) {
+  const columnWidths = reactive<Record<string, number>>({})
+  const defaultMin = opts?.minWidth ?? 48
+  const defaultMax = opts?.maxWidth ?? Number.POSITIVE_INFINITY
+  let dragging: {
+    key: string
+    startX: number
+    startW: number
+    min: number
+    max: number
+  } | null = null
+
+  const getWidth = (key: string, fallback?: string | number) => {
+    if (columnWidths[key] != null) return columnWidths[key]
+    if (fallback == null) return undefined
+    return typeof fallback === 'number' ? fallback : parseFloat(String(fallback)) || undefined
+  }
+
+  const onResizeStart = (
+    key: string,
+    currentWidth: number,
+    e: MouseEvent,
+    bounds?: { minWidth?: number; maxWidth?: number }
+  ) => {
+    e.preventDefault()
+    e.stopPropagation()
+    const min = Math.max(bounds?.minWidth ?? defaultMin, 48)
+    const max = Math.max(bounds?.maxWidth ?? defaultMax, min)
+    dragging = {
+      key,
+      startX: e.clientX,
+      startW: currentWidth || 100,
+      min,
+      max,
+    }
+    document.addEventListener('mousemove', onMove)
+    document.addEventListener('mouseup', onUp)
+    document.body.style.cursor = 'col-resize'
+    document.body.style.userSelect = 'none'
+  }
+
+  const onMove = (e: MouseEvent) => {
+    if (!dragging) return
+    const delta = e.clientX - dragging.startX
+    const next = dragging.startW + delta
+    columnWidths[dragging.key] = Math.min(dragging.max, Math.max(dragging.min, next))
+  }
+
+  const onUp = () => {
+    dragging = null
+    document.removeEventListener('mousemove', onMove)
+    document.removeEventListener('mouseup', onUp)
+    document.body.style.cursor = ''
+    document.body.style.userSelect = ''
+  }
+
+  const setColumnWidth = (key: string, width: number) => {
+    columnWidths[key] = Math.max(48, width)
+  }
+
+  onBeforeUnmount(() => {
+    document.removeEventListener('mousemove', onMove)
+    document.removeEventListener('mouseup', onUp)
+  })
+
+  return { columnWidths, getWidth, onResizeStart, setColumnWidth }
+}
+
+export function bindAutoClearEdit(opts: {
+  rootRef: Ref<HTMLElement | null>
+  enabled: () => boolean
+  clearEdit: () => void
+}) {
+  const onDoc = (e: MouseEvent) => {
+    if (!opts.enabled()) return
+    const root = opts.rootRef.value
+    if (!root) return
+    if (root.contains(e.target as Node)) return
+    opts.clearEdit()
+  }
+  onMounted(() => document.addEventListener('mousedown', onDoc, true))
+  onBeforeUnmount(() => document.removeEventListener('mousedown', onDoc, true))
+}

package/components/QiuTable/useScrollSync.ts

@@ -0,0 +1,152 @@
+import { onBeforeUnmount, onMounted, ref, type Ref } from 'vue'
+
+/** 探针测量系统纵向滚动条宽度 */
+let cachedBarWidth = 0
+function probeScrollbarWidth() {
+  if (typeof document === 'undefined') return 0
+  if (cachedBarWidth > 0) return cachedBarWidth
+  const outer = document.createElement('div')
+  outer.style.cssText =
+    'position:absolute;top:-9999px;width:100px;height:100px;overflow:scroll;visibility:hidden'
+  document.body.appendChild(outer)
+  cachedBarWidth = Math.max(0, outer.offsetWidth - outer.clientWidth)
+  document.body.removeChild(outer)
+  return cachedBarWidth
+}
+
+/**
+ * 表头 / 表体 / 表尾横向滚动同步。
+ * 对齐策略（双表经典坑）：
+ * 1. 量出 body 纵向滚动条占用
+ * 2. header/footer wrap 用 paddingRight 留出同宽空隙
+ * 3. 强制 header/footer 内 table 的像素宽 = body table 宽
+ * 4. 把 body 各 col 的实际像素宽抄到 header/footer
+ * 5. 有纵向条时由根节点 --qiu-table-v-scrollbar + --scroll-y 在 padding 内侧补竖线
+ *
+ * @author qiuye
+ * @email yjk150@qq.com
+ * @date 2026-08-16
+ */
+export function useScrollSync(opts: {
+  headerWrapRef: Ref<HTMLElement | null>
+  bodyWrapRef: Ref<HTMLElement | null>
+  footerWrapRef: Ref<HTMLElement | null>
+  onLayoutChange?: () => void
+}) {
+  const scrollbarSize = ref(0)
+  let syncing = false
+  let resizeObserver: ResizeObserver | null = null
+  let rafId = 0
+
+  const measureBar = (el: HTMLElement) => {
+    let size = Math.max(0, el.offsetWidth - el.clientWidth)
+    if (size <= 0 && el.scrollHeight > el.clientHeight + 1) {
+      size = probeScrollbarWidth()
+    }
+    return size
+  }
+
+  const syncColWidths = (fromTable: HTMLElement, toTable: HTMLElement) => {
+    // 优先用首行 td 实测宽（比 col 的 getBoundingClientRect 更稳）
+    const row = fromTable.querySelector(
+      'tbody tr.qiu-table__row:not(.qiu-table__virtual-pad):not(.qiu-table__row--empty)',
+    ) as HTMLElement | null
+    const toCols = toTable.querySelectorAll(':scope > colgroup > col')
+    if (row) {
+      const cells = [...row.children] as HTMLElement[]
+      const n = Math.min(cells.length, toCols.length)
+      for (let i = 0; i < n; i++) {
+        const w = cells[i].getBoundingClientRect().width
+        if (w > 0) {
+          const col = toCols[i] as HTMLElement
+          col.style.width = `${w}px`
+          col.style.minWidth = `${w}px`
+        }
+      }
+      return
+    }
+    const fromCols = fromTable.querySelectorAll(':scope > colgroup > col')
+    const n = Math.min(fromCols.length, toCols.length)
+    for (let i = 0; i < n; i++) {
+      const w = (fromCols[i] as HTMLElement).getBoundingClientRect().width
+      if (w > 0) {
+        const col = toCols[i] as HTMLElement
+        col.style.width = `${w}px`
+        col.style.minWidth = `${w}px`
+      }
+    }
+  }
+
+  const applyFixedTable = (wrap: HTMLElement | null, bodyTable: HTMLElement, bar: number) => {
+    if (!wrap) return
+    wrap.style.paddingRight = `${bar}px`
+    wrap.style.boxSizing = 'border-box'
+    const table = wrap.querySelector(':scope > table') as HTMLElement | null
+    if (!table) return
+    const w = Math.round(bodyTable.getBoundingClientRect().width)
+    if (w > 0) {
+      table.style.width = `${w}px`
+      table.style.minWidth = `${w}px`
+    }
+    syncColWidths(bodyTable, table)
+  }
+
+  const measureAndAlign = () => {
+    const body = opts.bodyWrapRef.value
+    if (!body) return
+    const bar = measureBar(body)
+    if (scrollbarSize.value !== bar) scrollbarSize.value = bar
+
+    const bodyTable = body.querySelector(':scope > table') as HTMLElement | null
+    if (!bodyTable) return
+
+    applyFixedTable(opts.headerWrapRef.value, bodyTable, bar)
+    applyFixedTable(opts.footerWrapRef.value, bodyTable, bar)
+  }
+
+  const syncFromBody = () => {
+    if (syncing) return
+    const body = opts.bodyWrapRef.value
+    if (!body) return
+    syncing = true
+    const left = body.scrollLeft
+    if (opts.headerWrapRef.value) opts.headerWrapRef.value.scrollLeft = left
+    if (opts.footerWrapRef.value) opts.footerWrapRef.value.scrollLeft = left
+    measureAndAlign()
+    requestAnimationFrame(() => {
+      syncing = false
+    })
+  }
+
+  const scheduleLayout = () => {
+    if (rafId) cancelAnimationFrame(rafId)
+    rafId = requestAnimationFrame(() => {
+      rafId = 0
+      measureAndAlign()
+      syncFromBody()
+      opts.onLayoutChange?.()
+    })
+  }
+
+  onMounted(() => {
+    measureAndAlign()
+    requestAnimationFrame(() => measureAndAlign())
+    // 字体/行高落地后再对齐一次
+    setTimeout(() => measureAndAlign(), 50)
+    window.addEventListener('resize', scheduleLayout)
+    const body = opts.bodyWrapRef.value
+    if (body && typeof ResizeObserver !== 'undefined') {
+      resizeObserver = new ResizeObserver(() => scheduleLayout())
+      resizeObserver.observe(body)
+    }
+  })
+
+  onBeforeUnmount(() => {
+    window.removeEventListener('resize', scheduleLayout)
+    resizeObserver?.disconnect()
+    resizeObserver = null
+    if (rafId) cancelAnimationFrame(rafId)
+  })
+
+  return { scrollbarSize, measureScrollbar: measureAndAlign, syncFromBody, scheduleLayout }
+}

package/components/QiuTable/useVirtual.ts

@@ -0,0 +1,97 @@
+import { computed, ref, watch, type Ref } from 'vue'
+
+export interface VirtualYConfig {
+  enabled?: boolean
+  /** 超过该行数才启用虚拟滚动；默认 0（enabled 时立即启用） */
+  gt?: number
+  /** 上下额外渲染行数 */
+  oSize?: number
+  /** 预估行高 */
+  rowHeight?: number
+}
+
+/** 纵向虚拟滚动：仅渲染可视区附近行 */
+export function useVirtualY(opts: {
+  bodyWrapRef: Ref<HTMLElement | null>
+  rows: Ref<any[]> | (() => any[])
+  config: Ref<VirtualYConfig | boolean | undefined> | (() => VirtualYConfig | boolean | undefined)
+  defaultRowHeight?: number
+}) {
+  const scrollTop = ref(0)
+  const viewportHeight = ref(0)
+
+  const resolved = computed((): VirtualYConfig => {
+    const c = typeof opts.config === 'function' ? opts.config() : opts.config.value
+    if (c === true) return { enabled: true }
+    if (c && typeof c === 'object') return { enabled: c.enabled !== false, ...c }
+    return { enabled: false }
+  })
+
+  const getRows = () => (typeof opts.rows === 'function' ? opts.rows() : opts.rows.value)
+  const total = computed(() => getRows().length)
+
+  const rowHeight = computed(
+    () => resolved.value.rowHeight || opts.defaultRowHeight || 48
+  )
+
+  const overscan = computed(() => resolved.value.oSize ?? 6)
+
+  const enabled = computed(() => {
+    if (!resolved.value.enabled) return false
+    const gt = resolved.value.gt ?? 0
+    return total.value > gt
+  })
+
+  const range = computed(() => {
+    if (!enabled.value) {
+      return { start: 0, end: total.value, padTop: 0, padBottom: 0 }
+    }
+    const rh = Math.max(1, rowHeight.value)
+    // 视口尚未量到时按约一屏估算，避免先渲染全部行
+    const vh = Math.max(viewportHeight.value || 0, rh * 10)
+    const start = Math.max(0, Math.floor(scrollTop.value / rh) - overscan.value)
+    const visible = Math.ceil(vh / rh) + overscan.value * 2
+    const end = Math.min(total.value, start + Math.max(visible, 1))
+    return {
+      start,
+      end,
+      padTop: start * rh,
+      padBottom: Math.max(0, (total.value - end) * rh),
+    }
+  })
+
+  const measure = () => {
+    const el = opts.bodyWrapRef.value
+    if (!el) return
+    const h = el.clientHeight
+    if (h > 0) viewportHeight.value = h
+  }
+
+  const onScroll = () => {
+    const el = opts.bodyWrapRef.value
+    if (!el) return
+    scrollTop.value = el.scrollTop
+    if (el.clientHeight > 0) viewportHeight.value = el.clientHeight
+  }
+
+  watch(
+    () => opts.bodyWrapRef.value,
+    (el, _prev, onCleanup) => {
+      measure()
+      if (!el || typeof ResizeObserver === 'undefined') return
+      const ro = new ResizeObserver(() => measure())
+      ro.observe(el)
+      onCleanup(() => ro.disconnect())
+    },
+    { immediate: true, flush: 'post' }
+  )
+
+  watch(
+    () => [enabled.value, total.value, rowHeight.value] as const,
+    () => {
+      requestAnimationFrame(() => measure())
+    }
+  )
+
+  return { enabled, range, rowHeight, onScroll, measure, scrollTop, viewportHeight }
+}

package/components/QiuTable/utils.ts

@@ -0,0 +1,165 @@
+import type { QiuTableColumnConfig } from './types'
+
+export interface QiuTableMenuItem {
+  code: string
+  name: string
+  disabled?: boolean
+  visible?: boolean
+  children?: QiuTableMenuItem[]
+}
+
+export interface QiuTableMenuConfig {
+  enabled?: boolean
+  body?: {
+    options?: QiuTableMenuItem[][]
+  }
+  header?: {
+    options?: QiuTableMenuItem[][]
+  }
+  /** 点击菜单项回调；也可监听 @menu-click */
+  visibleMethod?: (params: {
+    type: 'body' | 'header'
+    row?: any
+    column?: QiuTableColumnConfig
+    options: QiuTableMenuItem[][]
+  }) => boolean
+}
+
+export interface QiuTableCustomConfig {
+  enabled?: boolean
+  storage?: boolean
+  checkMethod?: (column: QiuTableColumnConfig) => boolean
+}
+
+export interface QiuTableValidRule {
+  required?: boolean
+  min?: number
+  max?: number
+  pattern?: RegExp | string
+  message?: string
+  validator?: (params: {
+    cellValue: any
+    row: any
+    column: QiuTableColumnConfig
+  }) => Error | string | boolean | void | Promise<any>
+}
+
+export type QiuTableEditRules = Record<string, QiuTableValidRule | QiuTableValidRule[]>
+
+export interface QiuTableValidConfig {
+  autoClear?: boolean
+  showMessage?: boolean
+}
+
+export async function validateCell(opts: {
+  rules?: QiuTableValidRule | QiuTableValidRule[]
+  cellValue: any
+  row: any
+  column: QiuTableColumnConfig
+}): Promise<string | null> {
+  const list = !opts.rules ? [] : Array.isArray(opts.rules) ? opts.rules : [opts.rules]
+  for (const rule of list) {
+    const val = opts.cellValue
+    if (rule.required && (val == null || val === '')) {
+      return rule.message || '必填'
+    }
+    if (rule.min != null && typeof val === 'number' && val < rule.min) {
+      return rule.message || `不能小于 ${rule.min}`
+    }
+    if (rule.max != null && typeof val === 'number' && val > rule.max) {
+      return rule.message || `不能大于 ${rule.max}`
+    }
+    if (rule.pattern) {
+      const re = typeof rule.pattern === 'string' ? new RegExp(rule.pattern) : rule.pattern
+      if (val != null && val !== '' && !re.test(String(val))) {
+        return rule.message || '格式不正确'
+      }
+    }
+    if (rule.validator) {
+      try {
+        const res = await rule.validator({
+          cellValue: val,
+          row: opts.row,
+          column: opts.column,
+        })
+        if (res instanceof Error) return res.message
+        if (typeof res === 'string' && res) return res
+        if (res === false) return rule.message || '校验失败'
+      } catch (e: any) {
+        return e?.message || rule.message || '校验失败'
+      }
+    }
+  }
+  return null
+}
+
+export function parseCsv(text: string): string[][] {
+  const rows: string[][] = []
+  let cur: string[] = []
+  let cell = ''
+  let inQuote = false
+  const pushCell = () => {
+    cur.push(cell)
+    cell = ''
+  }
+  const pushRow = () => {
+    pushCell()
+    if (cur.some((c) => c !== '')) rows.push(cur)
+    cur = []
+  }
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+    if (inQuote) {
+      if (ch === '"') {
+        if (text[i + 1] === '"') {
+          cell += '"'
+          i++
+        } else inQuote = false
+      } else cell += ch
+      continue
+    }
+    if (ch === '"') {
+      inQuote = true
+      continue
+    }
+    if (ch === ',') {
+      pushCell()
+      continue
+    }
+    if (ch === '\n') {
+      pushRow()
+      continue
+    }
+    if (ch === '\r') continue
+    cell += ch
+  }
+  if (cell || cur.length) pushRow()
+  return rows
+}
+
+export function csvToObjects(
+  rows: string[][],
+  columns: QiuTableColumnConfig[]
+): any[] {
+  if (!rows.length) return []
+  const header = rows[0].map((h) => String(h ?? '').trim())
+  const cols = columns.filter((c) => c.prop || c.field)
+  const mapIdx = cols.map((c) => {
+    const prop = String(c.prop || c.field || '')
+    const label = String(c.label || '').trim()
+    let i = header.findIndex((h) => h === prop)
+    if (i < 0 && label) i = header.findIndex((h) => h === label)
+    return i
+  })
+  // 若表头对不上，按列顺序映射
+  const useOrder = mapIdx.every((i) => i < 0)
+  return rows.slice(1).map((r) => {
+    const obj: any = {}
+    cols.forEach((c, i) => {
+      const p = String(c.prop || c.field || '')
+      const idx = useOrder ? i : mapIdx[i] >= 0 ? mapIdx[i] : i
+      obj[p] = r[idx] ?? ''
+    })
+    return obj
+  })
+}

package/components/QiuTableColumn/index.vue

@@ -0,0 +1,101 @@
+<template>
+  <!-- 声明式列：向 QiuTable 注册配置与插槽，不渲染独立 DOM -->
+</template>
+
+<script lang="ts" setup>
+/**
+ * QiuTableColumn — 声明式列，可嵌套插槽内容（如 QiuButton）
+ *
+ * @example
+ * <qiu-table :data="list">
+ *   <qiu-table-column prop="name" label="姓名" />
+ *   <qiu-table-column label="操作" width="160">
+ *     <template #default="{ row }">
+ *       <qiu-button type="primary" link>编辑</qiu-button>
+ *     </template>
+ *   </qiu-table-column>
+ * </qiu-table>
+ */
+import type { QiuTableColumnConfig, QiuTableRegisterContext } from '../QiuTable/types'
+import { QIU_TABLE_REGISTER_KEY } from '../QiuTable/types'
+
+defineOptions({
+  name: 'QiuTableColumn',
+})
+
+const props = withDefaults(
+  defineProps<{
+    label?: string
+    /** vxe 别名 */
+    title?: string
+    prop?: string
+    width?: string | number
+    minWidth?: string | number
+    maxWidth?: string | number
+    fixed?: boolean | 'left' | 'right'
+    sortable?: boolean | 'custom'
+    filterable?: boolean
+    children?: QiuTableColumnConfig[]
+    aggFunc?: 'sum' | 'avg' | 'count'
+    align?: 'left' | 'center' | 'right'
+    headerAlign?: 'left' | 'center' | 'right'
+    showOverflowTooltip?: boolean
+    resizable?: boolean
+    className?: string
+    headerClassName?: string
+    labelClassName?: string
+    /** selection/index，或编辑器类型：input/switch/select/number/date/datetime/time/text */
+    type?: string
+    index?: number | ((index: number) => number)
+    columnKey?: string
+    filters?: { text: string; value: any }[]
+    filterMethod?: (value: any, row: any, column: any) => boolean
+    filteredValue?: any[]
+    filterPlacement?: string
+    filterMultiple?: boolean
+    treeNode?: boolean
+    dragSort?: boolean
+    editor?: QiuTableColumnConfig['editor']
+    editorProps?: Record<string, any>
+    options?: { label: string; value: any }[]
+    editable?: boolean
+    formatter?: (row: any, column: any, cellValue: any, index: number) => any
+  }>(),
+  {
+    align: 'left',
+    resizable: true,
+    showOverflowTooltip: true,
+  }
+)
+
+const slots = useSlots()
+const registerCtx = inject<QiuTableRegisterContext | null>(QIU_TABLE_REGISTER_KEY, null)
+const colId = Symbol('qiuTableColumn')
+
+const buildRegistration = () => ({
+  id: colId,
+  props: { ...props },
+  slots: {
+    default: slots.default,
+    header: slots.header,
+  },
+})
+
+if (registerCtx) {
+  onMounted(() => {
+    registerCtx.register(buildRegistration())
+  })
+
+  watch(
+    () => ({ ...props }),
+    () => {
+      registerCtx.update(buildRegistration())
+    },
+    { deep: true }
+  )
+
+  onBeforeUnmount(() => {
+    registerCtx.unregister(colId)
+  })
+}
+</script>