跳转到正文

TablePro ​

RTablePro 从 @ray-template/ui/table-pro 导入。Ray Admin 内也可以继续从 @/components 导入。列、选择、排序、固定和虚拟滚动沿用 Naive UI DataTable。使用 bare 只渲染表格,或按业务需要加上搜索、分页和工具栏。

远端人员列表示例:筛选、表格工具栏、可见列与分页

交互示例 ​

打开完整在线示例,按任务体验 11 个可运行场景,每个场景附操作步骤、预期结果和同一份运行源码。

试试切换数据来源、筛选和分页。远端模式下,快速切换页码或重复提交筛选可以中止前一次查询。触发模拟失败后,可以用表格内的按钮重试。

查看示例源码
vue
<template>
  <DemoFrame :dark="dark" :locale="locale">
    <div class="ray-demo table-demo">
      <fieldset class="ray-demo-group">
        <legend>{{ copy.source }}</legend>
        <div class="ray-demo-options">
          <NRadioGroup
            v-model:value="source"
            :name="id"
            :aria-label="copy.source"
          >
            <NRadio value="local">{{ copy.local }}</NRadio>
            <NRadio value="remote">{{ copy.remote }}</NRadio>
          </NRadioGroup>
          <NCheckbox v-model:checked="virtual">{{ copy.virtual }}</NCheckbox>
        </div>
      </fieldset>
      <NButton v-if="source === 'remote'" size="small" @click="failRequest">
        {{ copy.fail }}
      </NButton>
      <p v-if="source === 'remote'" role="status">
        {{ copy.cancelled }} {{ cancelled }}
      </p>
      <RTablePro
        :key="source"
        :columns="columns"
        :data="source === 'local' ? rows : []"
        :request="source === 'remote' ? request : undefined"
        :virtualScroll="virtual"
        :search="[
          { key: 'name', label: copy.name, placeholder: copy.searchName },
        ]"
        columnStateKey="docs-demo"
        autoHeight
        @register="register"
      />
    </div>
  </DemoFrame>
</template>

<script setup lang="ts">
import { provideUiServices } from '@ray-template/ui/services'
import { RTablePro, useTablePro } from '@ray-template/ui/table-pro'
import type { TableProRequest } from '@ray-template/ui/table-pro'
import { createStorage } from '@ray-template/utils/storage'
import { NButton, NCheckbox, NRadio, NRadioGroup } from 'naive-ui'
import { computed, ref, useId } from 'vue'
import DemoFrame from './DemoFrame.vue'

const props = withDefaults(
  defineProps<{ dark?: boolean; locale?: 'zh-CN' | 'en' }>(),
  { locale: 'zh-CN' },
)
const copy = computed(() =>
  props.locale === 'en'
    ? {
        source: 'Data source',
        local: 'Local',
        remote: 'Simulated request',
        virtual: 'Virtual scroll',
        fail: 'Simulate a request failure',
        cancelled: 'Cancelled requests:',
        name: 'Name',
        searchName: 'Enter a name',
        score: 'Score',
        entry: 'Member',
      }
    : {
        source: '数据来源',
        local: '本地数据',
        remote: '模拟远端查询',
        virtual: '虚拟滚动',
        fail: '模拟请求失败',
        cancelled: '已取消请求:',
        name: '姓名',
        searchName: '请输入姓名',
        score: '分数',
        entry: '成员',
      },
)
const id = useId()
const source = ref<'local' | 'remote'>('local')
const virtual = ref(false)
const cancelled = ref(0)
const [register, { reload }] = useTablePro()
const values = new Map<string, string>()

provideUiServices({
  locale: () => props.locale,
  dark: () => props.dark,
  columnStorage: createStorage({
    getItem: (key) => values.get(key) ?? null,
    setItem: (key, value) => {
      values.set(key, value)
    },
    removeItem: (key) => {
      values.delete(key)
    },
  }),
})
const rows = computed(() =>
  Array.from({ length: 96 }, (_, index) => ({
    id: index + 1,
    name: `${copy.value.entry} ${index + 1}`,
    score: 60 + (index % 41),
  })),
)
const columns = computed(() => [
  { title: 'ID', key: 'id', width: 64 },
  { title: copy.value.name, key: 'name' },
  { title: copy.value.score, key: 'score', width: 76 },
])
let failNext = false
const request: TableProRequest = (
  { page = 1, pageSize = 10, name },
  signal,
) => {
  const shouldFail = failNext

  failNext = false

  return new Promise((resolve, reject) => {
    signal.throwIfAborted()
    const onAbort = () => {
      clearTimeout(timer)
      cancelled.value += 1
      reject(signal.reason)
    }
    const timer = setTimeout(() => {
      signal.removeEventListener('abort', onAbort)

      if (shouldFail) {
        reject(new Error('Simulated request failure'))

        return
      }

      const matching = rows.value.filter((row) =>
        row.name.includes(String(name ?? '')),
      )

      resolve({
        data: matching.slice((page - 1) * pageSize, page * pageSize),
        total: matching.length,
      })
    }, 650)

    signal.addEventListener('abort', onAbort, { once: true })
  })
}
const failRequest = () => {
  failNext = true
  void reload()
}
</script>

<style scoped>
.table-demo {
  --r-table-height: 460px;
}

.table-demo :deep(.n-radio-group) {
  display: flex;
  flex-wrap: wrap;
  gap: 8px 12px;
}
</style>

纯表格与远端查询 ​

tsx
import { getPersonList } from '@/api/demo/mock/person'
import { RTablePro } from '@/components'

const columns = [
  { title: '姓名', key: 'name' },
  { title: '邮箱', key: 'email' },
]

const renderBare = () => <RTablePro bare columns={columns} data={[]} />

const renderRemote = () => (
  <RTablePro
    columns={columns}
    request={getPersonList}
    search={[{ key: 'name', label: '姓名' }]}
    columnStateKey="demo:people"
  />
)
  • 远端 request(params, signal) 返回 Promise<{ data, total }>。组件只采用最新请求结果;切换请求源或筛选范围时清空旧行和总数,切页或修改每页条数时隐藏旧行。没有当前页结果时,实例取数为空、CSV 和打印不可用。请求失败时清空行与总数,沿用空态,并通过宿主 Toast 提醒;调用方可用实例 reload() 重试。要中止底层 HTTP,请把 signal 交给请求客户端。
  • 搜索提交回到第 1 页。外部筛选用 params,复杂表单可从 filters 插槽调用 submit(values)。服务端排序和过滤由调用方将事件值映射进 params。
  • 默认每页 10 条;用 pageSize、pagination.pageSizes 调整,或传 pagination={false} 关闭。关闭时不添加分页字段;bare pagination 可单独开启分页。
  • 初始页用 pagination.defaultPage。远端模式下组件管理当前页、每页条数和总数;调用方已有自己的远端控制时可传 remote + data + pagination,并自行处理范围切换。受控分页由调用方在回调中更新页码和每页条数;搜索重置和实例操作都触发对应回调。

高级搜索 ​

从下面四个场景任选一个开始。在表格下方对照草稿、已应用条件和请求参数,看看哪一步真正改变了列表。

  • 组合筛选填入状态多选与创建日期区间。切到模拟远端后点击「应用条件」,查看拆分后的 createdFrom 和 createdTo,再翻页确认条件仍然有效。
  • 快速切换组织连续发起北区和南区的候选请求。负责人会清空,最近请求里会显示北区请求已取消。打开负责人下拉,搜索南区的「王雨」。
  • 交付与金额填入商品级联、仓库树、最低金额、开票状态、自定义配送方式和交付时间。应用后展开匹配订单核对交付信息,留意请求中保留了 minAmount: 0 与 invoiced: false。
  • 试试校验提交一个字符的关键词,查看校验提示及保留的列表。修正输入后,可以切换「输入后自动应用」,快速连续编辑并观察列表请求。

在「最近请求」里还能让负责人或列表请求失败一次。负责人选项使用字段下方的重试;列表失败显示空态,通过再次查询恢复。

查看示例源码
tsx
import './search.scss'
import { useSettingGetters } from '@/store'
import { RTablePro, useTablePro } from '@ray-template/ui/table-pro'
import type {
  TableProColumn,
  TableProParams,
  TableProRequest,
  TableProSearchOptionContext,
  TableProSearchOptions,
  TableProSearchValues,
} from '@ray-template/ui/table-pro'
import {
  NButton,
  NCard,
  NCheckbox,
  NFlex,
  NRadio,
  NRadioGroup,
  NTag,
} from 'naive-ui'
import {
  computed,
  defineComponent,
  nextTick,
  ref,
  shallowRef,
  useId,
} from 'vue'
import DemoPage from '../components/DemoPage'
import { searchCopy } from './search-copy'
import {
  orderMatchesQuery,
  orders,
  organizations,
  owners,
  products,
  statuses,
  waitForDemo,
  warehouses,
} from './search-fixtures'

const initialValues: TableProSearchValues = { status: ['pending'] }
const pagination = { pageSizes: [5, 10, 20] }
const instantDelay = 350
const extraKeys = [
  'productId',
  'warehouseId',
  'minAmount',
  'invoiced',
  'delivery',
  'deliveryAt',
  'deliveryTime',
] as const

type Trace = {
  id: number
  kind: 'list' | 'owner'
  detail: number | string
  phase: 'pending' | 'success' | 'cancelled' | 'failed'
}

const traceTypes = {
  pending: 'info',
  success: 'success',
  cancelled: 'default',
  failed: 'error',
} as const

const scenarios = ['combine', 'race', 'deliveryRecipe', 'validation'] as const

type Scenario = (typeof scenarios)[number]

function nonemptyValues(values: TableProSearchValues) {
  return Object.fromEntries(
    Object.entries(values).filter(
      ([, value]) =>
        value != null &&
        value !== '' &&
        (!Array.isArray(value) || value.length > 0),
    ),
  )
}

export default defineComponent({
  name: 'TableDemoSearch',
  setup() {
    const { getLocaleLanguage } = useSettingGetters()
    const copy = computed(() =>
      getLocaleLanguage.value === 'zh-CN' ? searchCopy.zh : searchCopy.en,
    )
    const id = useId()
    const [register, table] = useTablePro()
    const source = ref<'local' | 'remote'>('local')
    const submitMode = ref<'manual' | 'change'>('manual')
    const more = ref(false)
    const scenario = ref<Scenario>()
    const listPayload = shallowRef<TableProParams>({})
    const mapped = shallowRef<Readonly<Record<string, unknown>>>(initialValues)
    const trace = shallowRef<readonly Trace[]>([])
    let requestId = 0
    let failListOnce = false
    let failOwnerOnce = false

    const track = async <T,>(
      kind: Trace['kind'],
      detail: Trace['detail'],
      delay: number,
      signal: AbortSignal,
      result: () => T,
    ) => {
      const id = ++requestId
      const entry: Trace = { id, kind, detail, phase: 'pending' }

      trace.value = [entry, ...trace.value].slice(0, 6)
      const finish = (phase: Trace['phase']) => {
        trace.value = trace.value.map((entry) =>
          entry.id === id ? { ...entry, phase } : entry,
        )
      }

      try {
        await waitForDemo(delay, signal)
        const value = result()

        finish('success')

        return value
      } catch (error) {
        finish(signal.aborted ? 'cancelled' : 'failed')
        throw error
      }
    }

    const rows = computed(() =>
      orders.map((row) => ({
        ...row,
        product: copy.value.products[row.productIndex],
        statusLabel: copy.value.statuses[row.statusIndex],
        organization: copy.value.teams[row.orgId === 'north' ? 0 : 1],
        owner: copy.value.people[row.ownerIndex],
      })),
    )
    const money = computed(
      () =>
        new Intl.NumberFormat(getLocaleLanguage.value, {
          style: 'currency',
          currency: copy.value.currency,
          maximumFractionDigits: 0,
        }),
    )
    const dateTime = computed(
      () =>
        new Intl.DateTimeFormat(getLocaleLanguage.value, {
          dateStyle: 'medium',
          timeStyle: 'short',
        }),
    )
    const deliveryDetails: TableProColumn = {
      type: 'expand',
      renderExpand: (row: (typeof orders)[number]) => {
        const labels = copy.value
        const details = [
          [labels.warehouse, labels.warehouseLabels[row.warehouseIndex]],
          [labels.invoiced, row.invoiced ? labels.yes : labels.no],
          [
            labels.delivery,
            row.delivery === 'express' ? labels.express : labels.standard,
          ],
          [labels.deliveryAt, dateTime.value.format(row.deliveryAt)],
        ]

        return (
          <dl class="r-search-demo__order">
            {details.map(([label, value]) => (
              <div key={label}>
                <dt>{label}</dt>
                <dd>{value}</dd>
              </div>
            ))}
          </dl>
        )
      },
    }
    const columns = computed<TableProColumn[]>(() => [
      ...(more.value ? [deliveryDetails] : []),
      { key: 'orderNo', title: copy.value.order, minWidth: 92 },
      { key: 'product', title: copy.value.product, minWidth: 90 },
      { key: 'statusLabel', title: copy.value.status, minWidth: 82 },
      { key: 'createdAt', title: copy.value.created, minWidth: 108 },
      { key: 'organization', title: copy.value.organization, minWidth: 90 },
      { key: 'owner', title: copy.value.owner, minWidth: 90 },
      {
        key: 'amount',
        title: copy.value.amount,
        minWidth: 85,
        render: (row: Record<string, unknown>) =>
          money.value.format(Number(row.amount)),
      },
    ])

    const draft = computed(() =>
      table.isReady.value ? nonemptyValues(table.getSearchValues()) : {},
    )
    const applied = computed(() =>
      table.isReady.value ? table.getSearchValues('applied') : initialValues,
    )
    const dirty = computed(
      () => JSON.stringify(draft.value) !== JSON.stringify(applied.value),
    )
    const pageRows = computed(() =>
      table.isReady.value ? table.getCurrentPageData().length : 0,
    )
    const showExtra = () => more.value

    const fillDraft = (values: TableProSearchValues) => {
      table.setSearchValues({
        ...Object.fromEntries(
          Object.keys(table.getSearchValues()).map((key) => [key, null]),
        ),
        ...values,
      })
    }

    const loadOwners = ({
      keyword,
      values,
      signal,
    }: TableProSearchOptionContext) => {
      const org = values.orgId === 'north' ? 'north' : 'south'
      const fail = failOwnerOnce

      failOwnerOnce = false

      return track('owner', org, org === 'north' ? 800 : 450, signal, () => {
        if (fail) throw new Error('Simulated assignee request failure')

        return owners.flatMap(({ id, orgId }, index) => {
          const label = copy.value.people[index]

          return orgId === org &&
            label.toLowerCase().includes(keyword.trim().toLowerCase())
            ? [{ label, value: id }]
            : []
        })
      })
    }

    const search = computed<TableProSearchOptions>(() => {
      const labels = copy.value

      return {
        initialValues,
        submitMode: submitMode.value,
        debounce: instantDelay,
        searchText: labels.apply,
        resetText: labels.reset,
        renderActions: ({ defaultActions, submit }) => (
          <>
            <NButton
              text
              attrType="button"
              onClick={() => {
                fillDraft({})
                void submit()
              }}
            >
              {labels.clear}
            </NButton>
            {defaultActions}
          </>
        ),
        fields: [
          {
            key: 'keyword',
            label: labels.keyword,
            type: 'text',
            placeholder: labels.keywordHint,
            getValue: (row) => `${row.orderNo} ${row.product}`,
            rules: {
              trigger: 'blur',
              validator: (_rule, value: unknown) =>
                typeof value !== 'string' ||
                value.trim().length === 0 ||
                value.trim().length >= 2 ||
                new Error(labels.keywordError),
            },
          },
          {
            key: 'status',
            label: labels.status,
            type: 'select',
            multiple: true,
            options: statuses.map((value, index) => ({
              value,
              label: labels.statuses[index],
            })),
          },
          {
            key: 'createdAt',
            label: labels.created,
            type: 'dateRange',
            span: 2,
            transform: ([createdFrom, createdTo]) => ({
              createdFrom,
              createdTo,
            }),
          },
          {
            key: 'orgId',
            label: labels.organization,
            type: 'select',
            options: organizations.map((value, index) => ({
              value,
              label: labels.teams[index],
            })),
          },
          {
            key: 'ownerId',
            label: labels.owner,
            type: 'select',
            dependsOn: ['orgId'],
            visible: ({ orgId }) => orgId != null,
            loadOptions: loadOwners,
          },
          {
            key: 'productId',
            label: labels.category,
            type: 'cascader',
            visible: showExtra,
            fieldProps: {
              options: labels.groups.map((label, group) => ({
                label,
                value: `category-${group}`,
                children: products
                  .slice(group * 2, group * 2 + 2)
                  .map((value, index) => ({
                    value,
                    label: labels.products[group * 2 + index],
                  })),
              })),
            },
          },
          {
            key: 'warehouseId',
            label: labels.warehouse,
            type: 'treeSelect',
            visible: showExtra,
            fieldProps: {
              defaultExpandAll: true,
              options: labels.teams.map((label, region) => ({
                label,
                key: `region-${region}`,
                disabled: true,
                children: warehouses
                  .slice(region * 2, region * 2 + 2)
                  .map((key, index) => ({
                    key,
                    label: labels.warehouseLabels[region * 2 + index],
                  })),
              })),
            },
          },
          {
            key: 'minAmount',
            label: labels.minAmount,
            type: 'number',
            visible: showExtra,
            fieldProps: { min: 0, step: 50 },
            getValue: (row) => row.amount,
            matches: (cell, minimum) =>
              typeof cell === 'number' && cell >= minimum,
          },
          {
            key: 'invoiced',
            label: labels.invoiced,
            type: 'boolean',
            visible: showExtra,
          },
          {
            key: 'delivery',
            label: labels.delivery,
            type: 'custom',
            visible: showExtra,
            render: ({ inputId, labelId, value, setValue }) => (
              <NRadioGroup
                name={inputId}
                aria-labelledby={labelId}
                value={typeof value === 'string' ? value : 'any'}
                onUpdateValue={(next) => setValue(next === 'any' ? null : next)}
              >
                <NFlex size="small">
                  <NRadio value="any">{labels.any}</NRadio>
                  <NRadio value="standard">{labels.standard}</NRadio>
                  <NRadio value="express">{labels.express}</NRadio>
                </NFlex>
              </NRadioGroup>
            ),
          },
          {
            key: 'deliveryAt',
            label: labels.deliveryAt,
            type: 'datetimeRange',
            span: 2,
            visible: showExtra,
            transform: ([deliveryFrom, deliveryTo]) => ({
              deliveryFrom,
              deliveryTo,
            }),
          },
          {
            key: 'deliveryTime',
            label: labels.deliveryTime,
            type: 'time',
            visible: showExtra,
          },
        ],
      }
    })

    const request: TableProRequest = (query, signal) => {
      const { page = 1, pageSize = 5 } = query
      const fail = failListOnce

      listPayload.value = query
      failListOnce = false

      return track('list', page, 400, signal, () => {
        if (fail) throw new Error('Simulated list request failure')

        const matched = rows.value.filter((row) =>
          orderMatchesQuery(row, query),
        )
        const start = (page - 1) * pageSize

        return {
          data: matched.slice(start, start + pageSize),
          total: matched.length,
        }
      })
    }

    const startScenario = async (next: Scenario) => {
      scenario.value = next
      more.value = next === 'deliveryRecipe'

      switch (next) {
        case 'combine':
          fillDraft({
            status: ['pending', 'paid'],
            createdAt: ['2026-11-01', '2026-11-08'],
          })
          break
        case 'race':
          fillDraft({})
          await nextTick()
          table.setSearchValues({ orgId: 'north', ownerId: 'n1' })
          await nextTick()
          table.setSearchValues({ orgId: 'south' })
          break
        case 'deliveryRecipe':
          fillDraft({
            productId: 'notebook',
            warehouseId: 'north-main',
            minAmount: 0,
            invoiced: false,
            delivery: 'express',
            deliveryAt: [
              new Date(2026, 10, 2).getTime(),
              new Date(2026, 10, 10, 23, 59).getTime(),
            ],
            deliveryTime: '09:00:00',
          })
          break
        default:
          fillDraft({ keyword: 'O' })
          await table.submitSearch()
          break
      }
    }

    const failList = () => {
      failListOnce = true
      void table.reload()
    }
    const failOwner = () => {
      failOwnerOnce = true
      table.setSearchValues({
        orgId: draft.value.orgId === 'north' ? 'south' : 'north',
      })
    }

    const scenarioHint = computed(
      () =>
        ({
          combine: copy.value.combineHint,
          race: copy.value.raceHint,
          deliveryRecipe: copy.value.deliveryHint,
          validation: copy.value.validationHint,
        })[scenario.value ?? 'combine'],
    )

    return () => {
      const labels = copy.value
      const query = table.queryState.value
      const output =
        source.value === 'remote'
          ? ([labels.payload, listPayload.value] as const)
          : ([labels.mapped, mapped.value] as const)

      return (
        <DemoPage title={labels.title} description={labels.description}>
          <NCard size="small">
            <div class="r-search-demo__guide">
              <strong>{labels.tryScenario}</strong>
              <NFlex size="small">
                {scenarios.map((key) => (
                  <NButton
                    key={key}
                    size="small"
                    secondary
                    type={scenario.value === key ? 'primary' : 'default'}
                    disabled={!table.isReady.value}
                    onClick={() => void startScenario(key)}
                  >
                    {labels[key]}
                  </NButton>
                ))}
              </NFlex>
              {scenario.value && <p role="status">{scenarioHint.value}</p>}
              <div class="r-search-demo__settings">
                <NRadioGroup
                  name={`${id}-source`}
                  aria-label={labels.source}
                  value={source.value}
                  onUpdateValue={(value) => {
                    source.value = value === 'remote' ? 'remote' : 'local'
                  }}
                >
                  <NFlex size="small">
                    <NRadio value="local">{labels.local}</NRadio>
                    <NRadio value="remote">{labels.remote}</NRadio>
                  </NFlex>
                </NRadioGroup>
                <NRadioGroup
                  name={`${id}-mode`}
                  aria-label={labels.submitMode}
                  value={submitMode.value}
                  onUpdateValue={(value) => {
                    submitMode.value = value === 'change' ? 'change' : 'manual'
                  }}
                >
                  <NFlex size="small">
                    <NRadio value="manual">{labels.manual}</NRadio>
                    <NRadio value="change">{labels.instant}</NRadio>
                  </NFlex>
                </NRadioGroup>
              </div>
              <p>
                {submitMode.value === 'manual'
                  ? labels.manualHint
                  : labels.instantHint}
              </p>
              <NCheckbox
                checked={more.value}
                onUpdateChecked={(checked) => {
                  more.value = checked

                  if (!checked)
                    table.setSearchValues(
                      Object.fromEntries(extraKeys.map((key) => [key, null])),
                    )
                }}
              >
                {labels.more}
              </NCheckbox>
            </div>
          </NCard>

          <RTablePro
            onRegister={register}
            columns={columns.value}
            search={search.value}
            data={source.value === 'local' ? rows.value : void 0}
            request={source.value === 'remote' ? request : void 0}
            pageSize={5}
            pagination={pagination}
            scrollX={more.value ? 700 : 645}
            tool={false}
            onSearch={({ params }) => {
              mapped.value = params
            }}
          />

          <div role="status">
            <NFlex size="small" align="center">
              <NTag size="small" type={dirty.value ? 'warning' : 'success'}>
                {dirty.value ? labels.dirty : labels.clean}
              </NTag>
              <NTag size="small">{labels.pageRows(pageRows.value)}</NTag>
              {query?.total != null && (
                <NTag size="small">{labels.matchedRows(query.total)}</NTag>
              )}
            </NFlex>
          </div>

          <details class="r-search-demo__details" open>
            <summary>{labels.inspector}</summary>
            <div class="r-search-demo__values">
              {(
                [
                  [labels.draft, draft.value],
                  [labels.applied, applied.value],
                  output,
                ] as const
              ).map(([label, values]) => (
                <div class="r-demo-result" key={label}>
                  <span class="r-demo-result__label">{label}</span>
                  <div class="r-demo-result__value">
                    <pre>{JSON.stringify(values, null, 2)}</pre>
                  </div>
                </div>
              ))}
            </div>
          </details>

          <NCard size="small">
            <div class="r-search-demo__trace-head">
              <strong>{labels.trace}</strong>
              <NFlex size="small">
                <NButton
                  size="small"
                  secondary
                  disabled={!table.isReady.value}
                  onClick={failOwner}
                >
                  {labels.failOwner}
                </NButton>
                {source.value === 'remote' && (
                  <NButton
                    size="small"
                    secondary
                    disabled={!table.isReady.value || query?.loading}
                    onClick={failList}
                  >
                    {labels.failList}
                  </NButton>
                )}
              </NFlex>
            </div>
            {trace.value.length ? (
              <ol class="r-search-demo__trace" aria-label={labels.trace}>
                {trace.value.map(({ id, kind, detail, phase }) => (
                  <li key={id}>
                    <span>
                      {kind === 'list'
                        ? labels.listRequest
                        : labels.ownerRequest}
                    </span>
                    <span>
                      {typeof detail === 'number'
                        ? labels.page(detail)
                        : labels.teams[detail === 'north' ? 0 : 1]}
                    </span>
                    <NTag size="small" type={traceTypes[phase]}>
                      {labels.phases[phase]}
                    </NTag>
                  </li>
                ))}
              </ol>
            ) : (
              <p class="r-search-demo__empty">{labels.emptyTrace}</p>
            )}
          </NCard>
        </DemoPage>
      )
    }
  },
})

字段配置 ​

search 接受原有数组、TableProSearchOptions 对象或 false。数组中不传 type 时,有 options 渲染单选,无 options 渲染文本。对象模式可用 fields 独立声明搜索字段,也可以省略 fields,从标记了 search: true 或 search: { type, ... } 的数据列生成。列分组、选择列和展开列不会生成字段,显示列设置也不会移除搜索条件。显式提供的 fields 优先,包括空数组。每个字段用唯一的 key 标识。

type草稿和提交的值默认本地匹配
text字符串,提交时去掉首尾空白忽略大小写,包含匹配
number、boolean数字、布尔值。布尔字段可以清空为不限精确匹配
select、treeSelect、cascader字符串或数字,multiple: true 时为数组单选精确匹配。多选任一值命中即可
date、dateRangeyyyy-MM-dd 字符串或二元组单日精确匹配,区间包含首尾两天
datetime、datetimeRange毫秒时间戳或二元组单值精确匹配,区间包含两端
timeHH:mm:ss 字符串精确匹配
custom字符串、数字、布尔值或字符串/数字数组单值精确匹配,数组任一值命中即可

字段之间用 AND。默认读取 row[key],嵌套数据、时间戳转业务日期等情况可用 getValue(row),特殊匹配用 matches(cell, value, row)。控件支持 placeholder 和类型化的 fieldProps。树选择和级联的节点、懒加载等原生配置从 fieldProps 传入。自定义控件用 render({ value, setValue, values, inputId, labelId }),并为可聚焦控件关联标签。

提交和请求 ​

  • initialValues 优先于字段的 initialValue。默认条件参与首查,重置恢复默认并重新查询。字段配置 rules 后,查询按钮和 submitSearch() 会校验,失败保留上次结果。重置会清理校验提示并应用默认值。空值、空白文本和空数组省略,0 和 false 保留。
  • transform(value, values) 返回请求参数片段。例如日期区间可返回 { createdFrom, createdTo },原字段不再进入参数。本地匹配仍使用字段值。列表请求按外部 params、转换后的搜索参数、表格的 page 和 pageSize 合并,提交回到第 1 页,分页和重试沿用已提交的条件。
  • onSearch 接收 { values, params, reason },reason 为 submit 或 reset。使用对象式 search 与 remote + data + pagination 时,可在事件中自行取数并控制页码和总数。搜索回调抛错会触发 onSearchError,并保留上次有效条件;本地默认字段读取支持 customer.name 等路径,getValue 优先。动态替换字段的匹配、读取、转换或可见规则时,仍兼容的条件会按新规则重新计算。
  • 实例和 useTablePro() 都提供 getSearchValues('draft' | 'applied')、setSearchValues(patch)、submitSearch()、resetSearch()。读取默认是草稿。提交和重置返回 Promise<boolean>,表示是否成功应用条件。设 submitMode: 'change' 可在编辑时防抖提交,debounce 默认 300 ms。

远程选项、联动和布局 ​

select.loadOptions({ keyword, values, signal }) 用于查询候选项。将 signal 传给请求客户端可取消旧请求,忽略取消的请求结果也不会覆盖新候选。关键词输入默认防抖 250 ms,可用 optionDebounce 调整。候选加载或失败重试独立于列表请求。

dependsOn: ['orgId'] 会在组织变化时清除负责人草稿,并以新组织加载负责人选项。一次 setSearchValues 可以同时传入组织和新的负责人。用 visible: ({ orgId }) => orgId != null 在组织为空时隐藏负责人并排除该条件。折叠只改变布局,仍会提交和校验折叠区域里的字段。

用 defaultCollapsed、collapsedRows、maxColumns 和字段 span 控制容器内布局。标签位置和宽度用 labelPlacement / labelWidth,按钮文案用 searchText / resetText。用 renderActions 扩展默认按钮或自行调用 submit、reset 和 setCollapsed。如果页面已有完整自定义表单,仍可用优先渲染的 filters 插槽调用 submit(values)。

布局、工具与实例 ​

autoHeight 让表格填充当前工作区;嵌入自定义区域时可用 --r-table-height 设定可用高度。宽表设置列宽与 scrollX,使横向滚动留在表格内。

tsx
import { RTablePro, type TableProInst } from '@/components'
import { shallowRef } from 'vue'

const table = shallowRef<TableProInst>()
const reloadFromFirstPage = () => table.value?.reload(true)

const renderTable = () => (
  <RTablePro ref={table} columns={[{ title: '姓名', key: 'name' }]} data={[]} />
)

实例还提供 setPage、setPageSize、getCurrentPageData、downloadCsv、print 和 getTableInstance。扩展表格区域可用 title、toolbar、tableFooter、tableAction;错误区域用 error 插槽。

useTablePro ​

也可以用同一入口导出的 useTablePro 注册实例,保留 [register, actions] 的写法:

tsx
import { RTablePro, useTablePro } from '@ray-template/ui/table-pro'

const [register, { isReady, reload }] = useTablePro()

const renderTable = () => (
  <>
    <button disabled={!isReady.value} onClick={() => reload(true)}>
      回首页并刷新
    </button>
    <RTablePro
      onRegister={register}
      columns={[{ title: '姓名', key: 'name' }]}
    />
  </>
)

SFC 使用 <RTablePro @register="register" />。每张表单独调用一次 Hook;表格挂载后注册,卸载时清除。actions 提供上述实例方法、getTableProInstance() 和只读 isReady;它表示实例已绑定,和请求是否完成无关。未绑定时调用实例方法会抛错。

从 actions 解构 queryState,用 queryState.value 响应式读取 TablePro 管理的远端请求。通过组件 ref 使用时,读取 table.value?.queryState。

字段含义
loading当前请求是否正在执行。只反映 request,与外部 loading prop 无关。
failed当前请求是否失败。重试开始时清除;错误详情可通过 onRequestError 接收。
page / pageSize当前页码和每页条数;关闭分页时两者为 null。
total当前查询范围最近成功结果的筛选后总数。切换范围或请求失败后为 null,直至成功。

queryState 的值和字段均为只读。未挂载、已卸载、未传 request(包括手动远端模式)时,值为 null。被取消的旧请求不会覆盖当前查询状态。

getCurrentPageData() 返回当前页的行:本地表格已应用筛选、排序和分页,组件管理的远端表格只返回与当前查询和分页匹配的数据。返回的行用于读取,业务变更通过页面数据完成;虚拟滚动不会缩小取数范围。旧版 runTableRequest / runAsyncTableRequest 迁移到 reload,请求条件通过 params 或请求函数传入。

三个 Hook 场景均可在在线示例中运行。

列设置与缓存 ​

试试在线列设置示例。每张表使用稳定且唯一的列 key。列设置可以勾选显示、拖动或用上移与下移按钮调整根列顺序、固定或启用列宽调整;分组子列跟随根列。使用 columnStateKey 跨刷新保留隐藏列,按账户或租户隔离时将标识纳入 key。缓存不存数据、列定义、顺序、固定位置或列宽。调用方接管列配置可用 v-model:columns,返回包含隐藏列的完整定义。「恢复列布局」保留显隐;受控列由调用方通过 onResetColumnLayout 恢复自己的列定义。

打印与 CSV ​

试试在线打印与 CSV 示例。默认取当前页可见数据列。打印按当前筛选和排序输出独立表格,不复刻 Vue 单元格、操作区、展开区或合并布局。报表等专用版式通过 printTableOptions.target 指定元素、ref 或 getter;默认复制宿主样式表、根节点主题和普通表单的当前值,也可设置 includePageStyles: false。单次调用可传 title 和专用 style。依赖区域外祖先、脚本或嵌入内容的区域需要专用打印 CSS;密码和文件值不会复制。真实纸张输出由浏览器负责。

CSV 的 keepOriginalData 使用当前传给表格的整批数据,远端模式不会自动抓取全部页。列级 allowExport: false 可排除数据;getCsvCell / getCsvHeader 返回原始文本,由组件做 CSV 转义。

TablePro 完整契约 · 全部表格示例 · v6 的变更

Props、事件和插槽 ​

Naive UI DataTable 的列定义、选择、展开、加载、空态和虚拟滚动继续使用。下面列出模板层的配置与覆盖行为。

配置默认 / 行为
bare默认关。移除卡片外观并隐藏标题及工具栏,省略 pagination 时不分页;显式搜索、底部插槽仍可使用。
autoHeight默认关;开启时让内部 DataTable 使用 flexHeight,适合有可用高度的布局。
tool默认开,控制打印、密度、全屏、列设置和外观等内置工具。关掉仍可用自定义 toolbar。
title字符串或 VNode。存在 title 插槽时优先渲染插槽。
pagination普通模式缺省开,false 关闭;对象透传 Naive UI Pagination。容器小于 600px 时默认简洁模式,显式 simple 优先。
pageSize默认 10;pagination.pageSize、pagination.defaultPageSize 依次优先。远端初始页读 pagination.defaultPage。
request / params配置 request 时组件管理远端数据。params 深层变化会从第 1 页重查。
search兼容原有字段数组,支持 TableProSearchOptions 和 false。见高级搜索。
rowKey默认 row.id ?? row.key,业务数据缺少两者时必须提供稳定键。
columnStateKey缺省不持久化。传稳定标识可记住隐藏列。
downloadCsvTableOptions内置导出默认配置,模板实现使用 fileName、keepOriginalData。
onResetColumnLayout受控列的恢复布局回调。调用方在回调里更新 columns。
printTableOptions打印配置,支持 target、title、style、includePageStyles、formatHeader、formatCell。
contextMenuOptions / onContextMenuClick行菜单选项及选择回调 (key, option, { row, index })。右键、Shift+F10 或菜单键打开;业务行事件可用 preventDefault() 阻止。

常用事件有 onRequestError(error)(或 SFC @request-error)、onUpdatePage、onUpdatePageSize、onUpdate:columns。内部更新和受控回调走同一入口;已传入受控值时由调用方更新对应值。行选择、排序等依然沿用 DataTable 事件;需要服务端排序时,将条件写入 params。

插槽参数与位置
filters表格上方;接收 { submit(values) },传入字符串或数字键值,提交后回第一页。优先于内置 search。
title / toolbar标题区左侧 / 操作区右侧;bare 下两者隐藏。
notice正常情况下显示自定义提示。
error显式提供时在请求失败后替换 notice,接收 { reload } 并接管默认 Toast。
tableFooter / tableActionDataTable 之后的额外区域。
其余插槽转给 Naive UI DataTable,例如空态和加载。

TableProInst 的 reload(resetPage?)、setPage(page)、setPageSize(size) 返回 Promise<void>。请求错误由事件报告;该 Promise 的完成不能用作业务成功判据。getTableInstance() 可能为 null;print(options?) 返回 Promise<boolean> 表示是否发起预览;downloadCsv(options?) 发起浏览器下载。

远端请求将 params 与已提交筛选合并,后者覆盖同名项,页码字段最后由表格写入。关闭分页时也会删除传入的 page 和 pageSize。total 需要是非负安全整数,data 必须是数组。若筛选或删除数据后当前页超出范围,会收敛到最后一页,并在有结果时重查。

TablePro Props · 远端与分页实现 · 表格面板实现