@wot-ui/ui 1.0.0 → 2.0.0-alpha.3

package/components/wd-table/types.ts

@@ -0,0 +1,160 @@
+import type { ExtractPropTypes, InjectionKey, ComputedRef } from 'vue'
+import { baseProps, makeBooleanProp, makeNumericProp, makeRequiredProp, numericProp } from '../../common/props'
+import type { TableColumnProps } from '../wd-table-column/types'
+import type { PropType } from 'vue'
+
+/**
+ * span-method 回调参数
+ */
+export interface SpanMethodParams {
+  /** 当前行的数据对象 */
+  row: Record<string, any>
+  /** 当前列的配置（字段名和标题） */
+  column: { prop: string; label: string }
+  /** 当前行索引（从 0 开始） */
+  rowIndex: number
+  /** 当前列索引（从 0 开始） */
+  columnIndex: number
+}
+
+/**
+ * span-method 返回值，定义单元格的合并行列数
+ */
+export interface SpanMethodResult {
+  /**
+   * 合并的行数
+   * 1 表示正常不合并，大于 1 表示向下合并 N 行，0 表示该单元格被合并隐藏
+   */
+  rowspan: number
+  /**
+   * 合并的列数
+   * 1 表示正常不合并，大于 1 表示向右合并 N 列，0 表示该单元格被合并隐藏
+   */
+  colspan: number
+}
+
+/**
+ * 合并单元格的回调函数类型
+ * @param params - 包含行数据、列配置、行列索引
+ * @returns 返回合并配置 { rowspan, colspan }，返回 void 时使用默认 { 1, 1 }
+ */
+export type SpanMethod = (params: SpanMethodParams) => SpanMethodResult | void
+
+export const tableProps = {
+  ...baseProps,
+  /**
+   * 表格显示的数据数组
+   * 类型: Record<string, any>[]
+   */
+  data: makeRequiredProp(Array<Record<string, any>>),
+  /**
+   * 是否显示表格边框
+   * 默认值: true
+   */
+  border: makeBooleanProp(true),
+  /**
+   * 是否显示斑马纹（奇偶行不同背景色）
+   * 默认值: true
+   */
+  stripe: makeBooleanProp(true),
+  /**
+   * 表格最大高度，超出后纵向滚动
+   * 类型: string | number
+   */
+  height: numericProp,
+  /**
+   * 是否显示表头
+   * 默认值: true
+   */
+  showHeader: makeBooleanProp(true),
+  /**
+   * 单元格文本是否超出两行后省略
+   * 默认值: false
+   */
+  ellipsis: makeBooleanProp(false),
+  /**
+   * 是否显示索引列，传入对象可自定义索引列配置
+   * 类型: boolean | Partial<TableColumnProps>
+   * 默认值: false
+   */
+  index: {
+    type: [Object, Boolean] as PropType<boolean | Omit<Partial<TableColumnProps>, 'prop'>>,
+    default: false
+  },
+  /**
+   * 是否固定表头（使用 CSS sticky 定位）
+   * 默认值: true
+   */
+  fixedHeader: makeBooleanProp(true),
+  /**
+   * 合并单元格的回调方法
+   * 类型: SpanMethod
+   * 默认值: undefined
+   */
+  spanMethod: {
+    type: Function as PropType<SpanMethod>,
+    default: undefined
+  },
+  /**
+   * 是否开启虚拟滚动（大数据量时只渲染可视区域行）
+   * 默认值: false
+   */
+  virtual: makeBooleanProp(false),
+  /**
+   * 行高（虚拟滚动时必填，用于计算可视行范围和总滚动高度）
+   * 类型: number
+   * 默认值: 44
+   */
+  rowHeight: makeNumericProp(44),
+  /**
+   * 可视区域上下各额外预渲染的行数
+   * 类型: number
+   * 默认值: 5
+   */
+  buffer: makeNumericProp(5)
+}
+
+/** 表格 Props 类型 */
+export type TableProps = ExtractPropTypes<typeof tableProps>
+
+/**
+ * 表格组件通过 provide/inject 向子列组件提供的接口
+ */
+export type TableProvide = {
+  /** 表格 props（不含 index、customStyle、customClass） */
+  props: Omit<TableProps, 'index' | 'customStyle' | 'customClass'>
+  /** 表格滚动状态 */
+  state: {
+    /** 当前水平滚动偏移量，用于固定列阴影判断 */
+    scrollLeft: number
+  }
+  /** 当前可视行范围（虚拟滚动时只渲染此范围内的行） */
+  visibleRange: ComputedRef<{ start: number; end: number }>
+  /**
+   * 行点击事件回调
+   * @param index - 被点击行的索引
+   */
+  rowClick: (index: number) => void
+  /**
+   * 判断指定列是否为最后一个固定列
+   * @param column - 列配置（含 fixed 和 prop）
+   * @returns 是否为最后一个固定列
+   */
+  getIsLastFixed: (column: { fixed: boolean; prop: string }) => boolean
+  /**
+   * 获取指定列的固定 left 偏移量
+   * @param columnIndex - 列索引
+   * @returns CSS left 值字符串
+   */
+  getFixedLeft: (columnIndex: number) => string
+  /**
+   * 获取指定单元格的合并信息
+   * @param rowIndex - 行索引
+   * @param columnIndex - 列索引
+   * @returns 合并配置 { rowspan, colspan }
+   */
+  getSpan: (rowIndex: number, columnIndex: number) => SpanMethodResult
+}
+
+/** 表格组件的 InjectionKey */
+export const TABLE_KEY: InjectionKey<TableProvide> = Symbol('wd-table')

package/components/wd-table/wd-table.vue

@@ -0,0 +1,331 @@
+<template>
+  <view :class="['wd-table', { 'is-border': border }, customClass]" :style="tableStyle">
+    <scroll-view :enable-flex="true" :throttle="false" :scroll-x="true" :scroll-y="scrollY" :style="scrollViewStyle" @scroll="handleScrollThrottled">
+      <view :style="contentWidthStyle">
+        <!-- 表头 -->
+        <view v-if="showHeader" :class="['wd-table__header', { 'is-sticky': fixedHeader }]" :style="gridColumnsStyle">
+          <view
+            v-for="(column, index) in children"
+            :key="index"
+            :class="[
+              'wd-table__cell',
+              'wd-table__cell--header',
+              {
+                'is-border': border,
+                'is-fixed': column.fixed,
+                'is-stripe': stripe,
+                'is-shadow': isLastFixed(index) && state.scrollLeft,
+                'is-last': index === children.length - 1
+              },
+              `is-${column.align}`
+            ]"
+            :style="getHeaderCellStyle(index)"
+          >
+            <wd-sort-button
+              v-if="column.sortable"
+              v-model="column.$.exposed!.sortDirection.value"
+              allow-reset
+              :line="false"
+              :title="column.label"
+              @change="({ value }) => handleSortChange(value, index)"
+            />
+            <text v-else :class="['wd-table__value', { 'is-ellipsis': ellipsis }]">{{ column.label }}</text>
+          </view>
+        </view>
+
+        <!-- 表体（CSS Grid 布局，虚拟滚动时包含 grid-template-rows） -->
+        <view class="wd-table__body" :style="bodyGridStyle">
+          <wd-table-column
+            v-if="showIndex"
+            :prop="indexColumn.prop"
+            :label="indexColumn.label"
+            :width="indexColumn.width"
+            :sortable="indexColumn.sortable"
+            :fixed="indexColumn.fixed"
+            :align="indexColumn.align"
+          >
+            <template #value="{ index }">
+              <text>{{ index + 1 }}</text>
+            </template>
+          </wd-table-column>
+          <slot></slot>
+        </view>
+      </view>
+    </scroll-view>
+  </view>
+</template>
+
+<script lang="ts">
+export default {
+  name: 'wd-table',
+  options: {
+    addGlobalClass: true,
+    // #ifndef MP-TOUTIAO
+    virtualHost: true,
+    // #endif
+    styleIsolation: 'shared'
+  }
+}
+</script>
+
+<script lang="ts" setup>
+import wdSortButton from '../wd-sort-button/wd-sort-button.vue'
+import { type CSSProperties, computed, reactive, ref } from 'vue'
+import { addUnit, isDef, isObj, objToStyle, throttle, uuid, isFunction } from '../../common/util'
+import type { SortDirection, TableColumn, TableColumnInstance, TableColumnProps } from '../wd-table-column/types'
+import { TABLE_KEY, tableProps, type SpanMethodResult, type TableProvide } from './types'
+import WdTableColumn from '../wd-table-column/wd-table-column.vue'
+import { useTranslate } from '../../composables/useTranslate'
+import { useChildren } from '../../composables/useChildren'
+
+const { translate } = useTranslate('tableCol')
+
+const props = defineProps(tableProps)
+const emit = defineEmits(['sort-method', 'row-click'])
+
+/** 滚动状态 */
+const state = reactive({
+  scrollLeft: 0,
+  scrollTop: 0
+})
+
+const { linkChildren, children } = useChildren<TableColumnInstance, TableProvide>(TABLE_KEY)
+
+/**
+ * 当前可视行范围
+ * @returns { start, end } 可视区域的行索引范围（含 buffer）
+ */
+const visibleRange = computed(() => {
+  const total = props.data.length
+  if (!props.virtual || total === 0) {
+    return { start: 0, end: Math.max(0, total - 1) }
+  }
+  const rowH = Number(props.rowHeight) || 44
+  const bufferSize = Number(props.buffer) || 5
+  const viewportHeight = Number(props.height) || 400
+  const start = Math.max(0, Math.floor(state.scrollTop / rowH) - bufferSize)
+  const end = Math.min(total - 1, Math.ceil((state.scrollTop + viewportHeight) / rowH) + bufferSize)
+  return { start, end }
+})
+
+linkChildren({ props, state, visibleRange, rowClick, getIsLastFixed, getFixedLeft, getSpan })
+
+/** 索引列唯一标识 */
+const indexUUID = uuid()
+
+/** 索引列配置 */
+const indexColumn = ref<TableColumnProps>({
+  prop: indexUUID,
+  label: translate('indexLabel'),
+  width: '100rpx',
+  sortable: false,
+  fixed: false,
+  align: 'left',
+  ...(isObj(props.index) ? props.index : {})
+})
+
+/** 是否显示索引列 */
+const showIndex = computed(() => props.index !== false)
+
+/** 是否开启纵向滚动（设置了 height 时启用） */
+const scrollY = computed(() => isDef(props.height))
+
+/** 滚动事件处理（节流 16ms ≈ 60fps） */
+const handleScrollThrottled = throttle(handleScroll, 16) as (event: any) => void
+
+/** 外层容器样式 */
+const tableStyle = computed(() => {
+  return `${props.customStyle}`
+})
+
+/**
+ * scroll-view 容器样式
+ * @returns 包含 max-height 的样式字符串（当设置了 height 时）
+ */
+const scrollViewStyle = computed(() => {
+  const style: CSSProperties = {
+    overflow: 'auto'
+  }
+  if (isDef(props.height)) {
+    style['max-height'] = addUnit(props.height)
+  }
+  return objToStyle(style)
+})
+
+/**
+ * 所有列宽度数组
+ * @returns 列宽字符串数组，如 ['100px', '150px', '200px']
+ */
+const columnWidths = computed(() => {
+  return children.map((child) => addUnit(child.width))
+})
+
+/**
+ * 内容总宽度样式，确保水平滚动时内容不被压缩
+ * @returns 所有列宽之和的 calc() 表达式
+ */
+const contentWidthStyle = computed(() => {
+  return objToStyle({ width: `calc(${columnWidths.value.join(' + ')})` })
+})
+
+/**
+ * CSS Grid 列定义样式，用于表头
+ * @returns 包含 display:grid 和 grid-template-columns 的样式字符串
+ */
+const gridColumnsStyle = computed(() => {
+  return objToStyle({
+    display: 'grid',
+    'grid-template-columns': columnWidths.value.join(' ')
+  })
+})
+
+/**
+ * 表体 Grid 样式（含列定义 + 虚拟滚动时的行定义）
+ * @returns 包含 grid-template-columns 和可选的 grid-template-rows 的样式字符串
+ */
+const bodyGridStyle = computed(() => {
+  const style: Record<string, string> = {
+    display: 'grid',
+    'grid-template-columns': columnWidths.value.join(' ')
+  }
+  if (props.virtual && props.data.length > 0) {
+    const rowH = Number(props.rowHeight) || 44
+    style['grid-template-rows'] = `repeat(${props.data.length}, ${rowH}px)`
+  }
+  return objToStyle(style)
+})
+
+/**
+ * 最后一个固定列的 prop 值
+ * @returns 最后一个 fixed=true 列的 prop，无固定列时返回 null
+ */
+const lastFixedProp = computed(() => {
+  const fixedCols = children.filter((c) => c.fixed)
+  return fixedCols.length ? fixedCols[fixedCols.length - 1].prop : null
+})
+
+/**
+ * 预计算每列的 left 偏移量
+ * @returns Map<列索引, CSS left 值>
+ */
+const fixedLeftMap = computed(() => {
+  const map = new Map<number, string>()
+  const leftParts: string[] = []
+
+  children.forEach((_col, i) => {
+    if (leftParts.length === 0) {
+      map.set(i, '0')
+    } else {
+      map.set(i, `calc(${leftParts.join(' + ')})`)
+    }
+    leftParts.push(addUnit(children[i].width))
+  })
+  return map
+})
+
+/**
+ * 判断指定索引的列是否为最后一个固定列（内部使用，用于表头渲染）
+ * @param colIndex - 列索引
+ * @returns 是否为最后一个固定列
+ */
+function isLastFixed(colIndex: number): boolean {
+  return children[colIndex]?.fixed && children[colIndex]?.prop === lastFixedProp.value
+}
+
+/**
+ * 判断指定列是否为最后一个固定列
+ * @param column - 列配置
+ * @returns 是否为最后一个固定列
+ */
+function getIsLastFixed(column: { fixed: boolean; prop: string }): boolean {
+  return column.fixed && column.prop === lastFixedProp.value
+}
+
+/**
+ * 获取指定列的固定 left 偏移量
+ * @param columnIndex - 列索引
+ * @returns CSS left 值字符串
+ */
+function getFixedLeft(columnIndex: number): string {
+  return fixedLeftMap.value.get(columnIndex) || '0'
+}
+
+/**
+ * 获取指定单元格的合并信息
+ * @param rowIndex - 行索引
+ * @param columnIndex - 列索引
+ * @returns 合并配置 { rowspan, colspan }
+ */
+function getSpan(rowIndex: number, columnIndex: number): SpanMethodResult {
+  if (!isFunction(props.spanMethod)) {
+    return { rowspan: 1, colspan: 1 }
+  }
+  const result = props.spanMethod({
+    row: props.data[rowIndex],
+    column: { prop: children[columnIndex].prop, label: children[columnIndex].label },
+    rowIndex,
+    columnIndex
+  })
+  return result || { rowspan: 1, colspan: 1 }
+}
+
+/**
+ * 获取表头单元格的内联样式（仅固定列需要 left 偏移）
+ * @param columnIndex - 列索引
+ * @returns 样式字符串
+ */
+function getHeaderCellStyle(columnIndex: number): string {
+  const style: CSSProperties = {}
+  if (children[columnIndex].fixed) {
+    style['left'] = fixedLeftMap.value.get(columnIndex) || '0'
+  }
+  return objToStyle(style)
+}
+
+/**
+ * 处理排序状态变更，重置其他列的排序方向并触发 sort-method 事件
+ * @param value - 新的排序方向
+ * @param index - 触发排序的列索引
+ */
+function handleSortChange(value: SortDirection, index: number) {
+  children[index].$.exposed!.sortDirection.value = value
+  children.forEach((col, i) => {
+    if (index != i) {
+      col.$.exposed!.sortDirection.value = 0
+    }
+  })
+  const column: TableColumn = {
+    prop: children[index].prop,
+    label: children[index].label,
+    width: children[index].width,
+    sortable: children[index].sortable,
+    align: children[index].align,
+    sortDirection: value,
+    fixed: children[index].fixed
+  }
+  emit('sort-method', column)
+}
+
+/**
+ * 处理滚动事件，更新水平和垂直滚动偏移量
+ * @param event - scroll-view 的滚动事件对象
+ */
+function handleScroll(event: any) {
+  state.scrollLeft = event.detail.scrollLeft
+  if (props.virtual) {
+    state.scrollTop = event.detail.scrollTop
+  }
+}
+
+/**
+ * 触发行点击事件
+ * @param index - 被点击行的索引
+ */
+function rowClick(index: number) {
+  emit('row-click', { rowIndex: index })
+}
+</script>
+
+<style lang="scss">
+@use './index.scss';
+</style>

package/components/wd-table-column/index.scss

@@ -0,0 +1,15 @@
+@use '../../styles/mixin/mixin.scss'as *;
+
+@use '../wd-table/index.scss' as *;
+
+@include b(table-column) {
+  display: contents;
+
+  .wd-table__cell:last-child {
+    @include when(border) {
+      &::before {
+        border-bottom: none;
+      }
+    }
+  }
+}

package/components/wd-table-column/types.ts

@@ -0,0 +1,81 @@
+import type { ComponentPublicInstance, ExtractPropTypes } from 'vue'
+import { makeBooleanProp, makeNumericProp, makeRequiredProp, makeStringProp } from '../../common/props'
+
+/**
+ * 列的对齐方式
+ * 可选值: 'left' | 'center' | 'right'
+ */
+export type AlignType = 'left' | 'center' | 'right'
+
+/**
+ * 列的排序方向
+ * 可选值: 0（未排序） | 1（升序） | -1（降序）
+ */
+export type SortDirection = 0 | 1 | -1
+
+/**
+ * 表格列配置信息，用于排序事件回调等场景
+ */
+export interface TableColumn {
+  /** 列对应的数据字段名 */
+  prop: string
+  /** 列的表头标题 */
+  label: string
+  /** 列宽度 */
+  width: string | number
+  /** 是否开启列排序 */
+  sortable?: boolean
+  /**
+   * 列的对齐方式
+   * 可选值: 'left' | 'center' | 'right'
+   */
+  align?: AlignType
+  /**
+   * 当前排序方向
+   * 可选值: 0（未排序） | 1（升序） | -1（降序）
+   */
+  sortDirection: SortDirection
+  /** 是否固定本列 */
+  fixed?: boolean
+}
+
+export const tableColumnProps = {
+  /**
+   * 列对应的数据字段名
+   * 类型: string
+   */
+  prop: makeRequiredProp(String),
+  /**
+   * 列的表头标题
+   * 类型: string
+   */
+  label: makeRequiredProp(String),
+  /**
+   * 列宽度
+   * 类型: string | number
+   * 默认值: 100
+   */
+  width: makeNumericProp(100),
+  /**
+   * 是否开启列排序
+   * 默认值: false
+   */
+  sortable: makeBooleanProp(false),
+  /**
+   * 是否固定本列（固定在左侧，不随水平滚动移动）
+   * 默认值: false
+   */
+  fixed: makeBooleanProp(false),
+  /**
+   * 列的对齐方式
+   * 可选值: 'left' | 'center' | 'right'
+   * 默认值: 'left'
+   */
+  align: makeStringProp<AlignType>('left')
+}
+
+/** 表格列 Props 类型 */
+export type TableColumnProps = ExtractPropTypes<typeof tableColumnProps>
+
+/** 表格列组件实例类型 */
+export type TableColumnInstance = ComponentPublicInstance<TableColumnProps>