niuma-ui 1.0.0 → 1.0.2

package/src/composables/useRsTableScrollHost.ts

@@ -0,0 +1,75 @@
+/**
+ * RsTable 滚动宿主生命周期 + 无限加载触底。
+ */
+
+import { onActivated, onDeactivated, onMounted, ref, watch, type Ref } from 'vue'
+import { isNearScrollBottom } from '../components/table-utils'
+
+export interface UseRsTableScrollHostOptions {
+  scrollContainerRef: Ref<HTMLElement | null | undefined>
+  scheduleVirtualLayoutSync: () => void
+  bindScrollElement: (el: HTMLElement | null | undefined) => void
+  captureScrollFromDom: () => void
+  onScrollFrame: (element: HTMLElement) => void
+  hideCellTooltip: () => void
+  infinite: () => boolean
+  loading: () => boolean
+  loadingMore: () => boolean
+  hasMore: () => boolean
+  infiniteDistance: () => number
+  onLoadMore: () => void
+}
+
+/**
+ * 绑定滚动生命周期与无限加载。
+ */
+export function useRsTableScrollHost(options: UseRsTableScrollHostOptions) {
+  const loadMoreLocked = ref(false)
+
+  onMounted(() => {
+    options.scheduleVirtualLayoutSync()
+    options.bindScrollElement(options.scrollContainerRef.value)
+  })
+
+  onActivated(() => {
+    options.scheduleVirtualLayoutSync()
+  })
+
+  onDeactivated(() => {
+    options.captureScrollFromDom()
+  })
+
+  function onScroll(event: Event): void {
+    options.hideCellTooltip()
+    const element = event.target as HTMLElement
+    if (
+      options.infinite() &&
+      !options.loading() &&
+      !options.loadingMore() &&
+      options.hasMore() &&
+      !loadMoreLocked.value
+    ) {
+      if (
+        isNearScrollBottom(
+          element.scrollTop,
+          element.scrollHeight,
+          element.clientHeight,
+          options.infiniteDistance(),
+        )
+      ) {
+        loadMoreLocked.value = true
+        options.onLoadMore()
+      }
+    }
+    options.onScrollFrame(element)
+  }
+
+  watch(
+    () => [options.loadingMore(), options.hasMore()] as const,
+    ([loadingMore, hasMore]) => {
+      if (!loadingMore || !hasMore) loadMoreLocked.value = false
+    },
+  )
+
+  return { onScroll, loadMoreLocked }
+}

package/src/composables/useRsTableScrollLayout.ts

@@ -0,0 +1,255 @@
+/**
+ * RsTable 滚动与视口布局：测量、节流同步、keep-alive / layoutActive 恢复。
+ *
+ * 职责边界：
+ * - 做：scrollTop/Left、视口宽高、写回 DOM、ResizeObserver、RAF 节流滚动
+ * - 不做：虚拟切片本身、无限加载业务判定（由调用方在 onScroll 钩子中处理）
+ */
+
+import {
+  computed,
+  nextTick,
+  onUnmounted,
+  ref,
+  watch,
+  type ComputedRef,
+  type Ref,
+} from 'vue'
+
+/** 统一读取 ComputedRef / getter */
+function read<T>(source: ComputedRef<T> | (() => T)): T {
+  return typeof source === 'function' ? (source as () => T)() : source.value
+}
+
+export interface UseRsTableScrollLayoutOptions {
+  /** 显式高度（number / px 字符串优先于测量值） */
+  height: ComputedRef<number | string | undefined> | (() => number | string | undefined)
+  /** 外层 keep-alive 可见性；false→快照，true→恢复 */
+  layoutActive: ComputedRef<boolean | undefined> | (() => boolean | undefined)
+  /** 视图切换标识；变化时重置滚动（跳过首次） */
+  viewKey: ComputedRef<string | number | undefined> | (() => string | number | undefined)
+  /** 无测量值时的回退视口高度 */
+  fallbackViewportHeight?: number
+}
+
+/**
+ * 表格滚动容器与视口状态。
+ *
+ * @returns 滚动状态、视口尺寸、恢复/重置 API、bindScrollElement / onScrollFrame
+ */
+export function useRsTableScrollLayout(options: UseRsTableScrollLayoutOptions) {
+  const scrollTop = ref(0)
+  const scrollLeft = ref(0)
+  const scrollContainerRef = ref<HTMLElement | null>(null)
+  const measuredViewportHeight = ref(0)
+  const measuredViewportWidth = ref(0)
+
+  let viewportResizeObserver: ResizeObserver | null = null
+  let preservedScrollTop = 0
+  let preservedScrollLeft = 0
+  let restoringScroll = false
+  let restoreGeneration = 0
+  let scrollRafId = 0
+
+  const fallback = options.fallbackViewportHeight ?? 320
+
+  /** 虚拟切片用视口高度：显式 height > 测量值 > DOM > fallback */
+  const viewportHeight = computed(() => {
+    const h = read(options.height)
+    if (typeof h === 'number' && h > 0) return h
+    if (typeof h === 'string') {
+      const parsed = Number.parseInt(h, 10)
+      if (Number.isFinite(parsed) && parsed > 0 && !h.includes('%')) return parsed
+    }
+    if (measuredViewportHeight.value > 0) return measuredViewportHeight.value
+    const el = scrollContainerRef.value
+    if (el && el.clientHeight > 0) return el.clientHeight
+    return fallback
+  })
+
+  function syncMeasuredViewportSize(): void {
+    const el = scrollContainerRef.value
+    if (!el) return
+    const nextH = el.clientHeight
+    if (nextH > 0 && nextH !== measuredViewportHeight.value) {
+      measuredViewportHeight.value = nextH
+    }
+    const nextW = el.clientWidth
+    if (nextW > 0 && nextW !== measuredViewportWidth.value) {
+      measuredViewportWidth.value = nextW
+    }
+  }
+
+  /**
+   * 失活前快照滚动。
+   * DOM 脱离文档后 scrollTop 常为 0——切勿用 0 覆盖 onScroll 已写入的位置。
+   */
+  function captureScrollFromDom(): void {
+    const el = scrollContainerRef.value
+    if (el) {
+      if (el.scrollTop > 0) scrollTop.value = el.scrollTop
+      if (el.scrollLeft > 0) scrollLeft.value = el.scrollLeft
+    }
+    if (scrollTop.value > 0) preservedScrollTop = scrollTop.value
+    if (scrollLeft.value > 0) preservedScrollLeft = scrollLeft.value
+  }
+
+  /** 将内部保存的滚动写回 DOM，并同步 reactive（驱动虚拟切片）。 */
+  function restoreScrollToDom(): void {
+    const el = scrollContainerRef.value
+    if (!el) return
+    syncMeasuredViewportSize()
+    const top = preservedScrollTop
+    const left = preservedScrollLeft
+    if (scrollTop.value !== top) scrollTop.value = top
+    if (scrollLeft.value !== left) scrollLeft.value = left
+    if (el.scrollTop !== top) el.scrollTop = top
+    if (el.scrollLeft !== left) el.scrollLeft = left
+  }
+
+  /**
+   * 布局稳定后多次写回滚动：keep-alive 切回首帧 clientHeight 常为 0，
+   * 需等 nextTick / rAF / 视口测稳后再设 scrollTop，否则会被浏览器钳成 0。
+   */
+  function scheduleVirtualLayoutSync(): void {
+    restoreGeneration += 1
+    const gen = restoreGeneration
+    restoringScroll = true
+    const apply = (): void => {
+      if (gen !== restoreGeneration) return
+      restoreScrollToDom()
+    }
+    apply()
+    void nextTick(() => {
+      apply()
+      requestAnimationFrame(() => {
+        apply()
+        requestAnimationFrame(() => {
+          apply()
+          if (gen === restoreGeneration) restoringScroll = false
+        })
+      })
+    })
+  }
+
+  function resetScrollPosition(): void {
+    preservedScrollTop = 0
+    preservedScrollLeft = 0
+    scrollTop.value = 0
+    scrollLeft.value = 0
+    const el = scrollContainerRef.value
+    if (el) {
+      el.scrollTop = 0
+      el.scrollLeft = 0
+    }
+    scheduleVirtualLayoutSync()
+  }
+
+  function isRestoringScroll(): boolean {
+    return restoringScroll
+  }
+
+  /**
+   * RAF 节流写入滚动位置；恢复窗口内忽略伪 scrollTop=0。
+   * @returns true 表示本帧已调度或处于恢复中（调用方仍可先做无限加载判断）
+   */
+  function onScrollFrame(element: HTMLElement): void {
+    if (scrollRafId) return
+    scrollRafId = requestAnimationFrame(() => {
+      if (restoringScroll) {
+        scrollRafId = 0
+        return
+      }
+      scrollTop.value = element.scrollTop
+      scrollLeft.value = element.scrollLeft
+      preservedScrollTop = element.scrollTop
+      preservedScrollLeft = element.scrollLeft
+      scrollRafId = 0
+    })
+  }
+
+  /**
+   * 绑定滚动容器 ResizeObserver：视口从 0→实高时补一次恢复写回。
+   */
+  function bindScrollElement(el: HTMLElement | null | undefined): void {
+    viewportResizeObserver?.disconnect()
+    viewportResizeObserver = null
+    if (!el || typeof ResizeObserver === 'undefined') return
+    viewportResizeObserver = new ResizeObserver(() => {
+      const prevH = measuredViewportHeight.value
+      syncMeasuredViewportSize()
+      if (
+        prevH === 0 &&
+        measuredViewportHeight.value > 0 &&
+        (preservedScrollTop > 0 || preservedScrollLeft > 0)
+      ) {
+        restoringScroll = true
+        restoreScrollToDom()
+        requestAnimationFrame(() => {
+          restoringScroll = false
+        })
+      }
+    })
+    viewportResizeObserver.observe(el)
+  }
+
+  function disposeScrollLayout(): void {
+    viewportResizeObserver?.disconnect()
+    viewportResizeObserver = null
+    if (scrollRafId) {
+      cancelAnimationFrame(scrollRafId)
+      scrollRafId = 0
+    }
+  }
+
+  watch(
+    () => read(options.layoutActive),
+    (active, prev) => {
+      if (active === false && prev !== false) {
+        captureScrollFromDom()
+      }
+    },
+    { flush: 'sync' },
+  )
+
+  watch(
+    () => read(options.layoutActive),
+    (active) => {
+      if (active) scheduleVirtualLayoutSync()
+    },
+    { flush: 'post' },
+  )
+
+  watch(
+    () => read(options.viewKey),
+    (_next, prev) => {
+      if (prev === undefined) return
+      resetScrollPosition()
+    },
+  )
+
+  onUnmounted(() => {
+    disposeScrollLayout()
+  })
+
+  return {
+    scrollTop,
+    scrollLeft,
+    scrollContainerRef,
+    measuredViewportHeight,
+    measuredViewportWidth,
+    viewportHeight,
+    syncMeasuredViewportSize,
+    captureScrollFromDom,
+    restoreScrollToDom,
+    scheduleVirtualLayoutSync,
+    resetScrollPosition,
+    isRestoringScroll,
+    onScrollFrame,
+    bindScrollElement,
+    disposeScrollLayout,
+  }
+}
+
+/** useRsTableScrollLayout 返回值类型 */
+export type RsTableScrollLayoutApi = ReturnType<typeof useRsTableScrollLayout>

package/src/composables/useRsTableSelectionSource.ts

@@ -0,0 +1,89 @@
+/**
+ * 表格分析/图表数据源：viewRows + selectedRows → 稳定 sourceRows。
+ *
+ * 约定（便于柱状图/饼图等后期扩展）：
+ * - 有选中行时 sourceMode='selected'，图表跟随勾选
+ * - 无选中时回退 viewRows（筛选/排序后的业务行）
+ * - subscribe 仅在浅层引用变化时通知，不做 deep watch
+ */
+
+import { computed, watch, type ComputedRef, type Ref } from 'vue'
+import type { RsTableRowData } from '../components/table-utils'
+
+export type RsTableAnalyticsSourceMode = 'selected' | 'view'
+
+/** 分析快照：图表 / 指标卡 / 服务端请求共用 */
+export interface RsTableAnalyticsSnapshot<T extends RsTableRowData = RsTableRowData> {
+  viewRows: readonly T[]
+  selectedRows: readonly T[]
+  sourceRows: readonly T[]
+  sourceMode: RsTableAnalyticsSourceMode
+  selectedCount: number
+  viewCount: number
+}
+
+export interface UseRsTableSelectionSourceOptions<T extends RsTableRowData> {
+  viewRows: Ref<T[]> | ComputedRef<T[]>
+  selectedRows?: Ref<T[]> | ComputedRef<T[]>
+}
+
+/**
+ * 选中优先的分析数据源。
+ *
+ * @returns sourceRows / sourceMode / getSnapshot / subscribe
+ */
+export function useRsTableSelectionSource<T extends RsTableRowData>(
+  options: UseRsTableSelectionSourceOptions<T>,
+) {
+  const viewRows = computed(() => options.viewRows.value ?? [])
+  const selectedRows = computed(() => options.selectedRows?.value ?? [])
+
+  const sourceMode = computed<RsTableAnalyticsSourceMode>(() =>
+    selectedRows.value.length > 0 ? 'selected' : 'view',
+  )
+
+  const sourceRows = computed(() =>
+    sourceMode.value === 'selected' ? selectedRows.value : viewRows.value,
+  )
+
+  function getSnapshot(): RsTableAnalyticsSnapshot<T> {
+    return {
+      viewRows: viewRows.value,
+      selectedRows: selectedRows.value,
+      sourceRows: sourceRows.value,
+      sourceMode: sourceMode.value,
+      selectedCount: selectedRows.value.length,
+      viewCount: viewRows.value.length,
+    }
+  }
+
+  /**
+   * 订阅快照变化。
+   * 依赖：viewRows 引用、selectedRows 引用、sourceMode。
+   * @returns teardown
+   */
+  function subscribe(listener: (snap: RsTableAnalyticsSnapshot<T>) => void): () => void {
+    const stop = watch(
+      () => [viewRows.value, selectedRows.value, sourceMode.value] as const,
+      () => {
+        listener(getSnapshot())
+      },
+      { flush: 'post' },
+    )
+    listener(getSnapshot())
+    return stop
+  }
+
+  return {
+    viewRows,
+    selectedRows,
+    sourceRows,
+    sourceMode,
+    getSnapshot,
+    subscribe,
+  }
+}
+
+export type RsTableSelectionSourceApi<T extends RsTableRowData> = ReturnType<
+  typeof useRsTableSelectionSource<T>
+>