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

交互示例
打开完整在线示例,按任务体验 11 个可运行场景,每个场景附操作步骤、预期结果和同一份运行源码。
试试切换数据来源、筛选和分页。远端模式下,快速切换页码或重复提交筛选可以中止前一次查询。触发模拟失败后,可以用表格内的按钮重试。
查看示例源码
<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>纯表格与远端查询
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。 - 试试校验提交一个字符的关键词,查看校验提示及保留的列表。修正输入后,可以切换「输入后自动应用」,快速连续编辑并观察列表请求。
在「最近请求」里还能让负责人或列表请求失败一次。负责人选项使用字段下方的重试;列表失败显示空态,通过再次查询恢复。
查看示例源码
import './search.scss'
import { apiMockEnabled } from '@/api/admin/client'
import {
getSearchOptions,
getSearchOrders,
getSearchOwners,
} from '@/api/demo/data'
import type { DemoOrder, SearchOptions } from '@/api/demo/data'
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 {
NAlert,
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'
const initialValues: TableProSearchValues = {}
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 queryParams = computed(() => ({ locale: getLocaleLanguage.value }))
const copy = computed(() =>
getLocaleLanguage.value === 'zh-CN' ? searchCopy.zh : searchCopy.en,
)
const options = shallowRef<SearchOptions>()
const optionsLoading = ref(false)
const optionsFailed = ref(false)
const optionsAttempt = ref(0)
watch(
[getLocaleLanguage, optionsAttempt],
async ([locale], _, cleanup) => {
const controller = new AbortController()
cleanup(() => controller.abort())
options.value = void 0
optionsFailed.value = false
optionsLoading.value = true
try {
const result = await getSearchOptions(locale, controller.signal)
if (!controller.signal.aborted) options.value = result
} catch {
if (!controller.signal.aborted) optionsFailed.value = true
} finally {
if (!controller.signal.aborted) optionsLoading.value = false
}
},
{ immediate: true },
)
const id = useId()
const [register, table] = useTablePro()
const source = ref<'local' | 'remote'>('remote')
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'],
signal: AbortSignal,
result: () => Promise<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 {
signal.throwIfAborted()
const value = await result()
signal.throwIfAborted()
finish('success')
return value
} catch (error) {
finish(signal.aborted ? 'cancelled' : 'failed')
throw error
}
}
const rows = shallowRef<DemoOrder[]>([])
const rowsLoading = ref(false)
watch(
[source, getLocaleLanguage],
async ([mode, locale], _, cleanup) => {
if (mode !== 'local') return
const controller = new AbortController()
cleanup(() => controller.abort())
rowsLoading.value = true
try {
rows.value = (
await getSearchOrders(
{ page: 1, pageSize: 100 },
locale,
controller.signal,
)
).items
} catch {
if (!controller.signal.aborted)
window.$message.error(
locale === 'zh-CN'
? '查询失败,请重试。'
: 'Query failed. Please retry.',
)
} finally {
if (!controller.signal.aborted) rowsLoading.value = false
}
},
{ immediate: true },
)
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: DemoOrder) => {
const labels = copy.value
const details = [
[labels.warehouse, row.warehouse],
[labels.invoiced, row.invoiced ? labels.yes : labels.no],
[labels.delivery, row.deliveryLabel],
[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 = String(values.orgId ?? '')
const fail = failOwnerOnce
failOwnerOnce = false
return track('owner', org, signal, () =>
getSearchOwners(org, keyword, getLocaleLanguage.value, signal, fail),
)
}
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: options.value?.statuses ?? [],
},
{
key: 'createdAt',
label: labels.created,
type: 'dateRange',
span: 2,
transform: ([createdFrom, createdTo]) => ({
createdFrom,
createdTo,
}),
},
{
key: 'orgId',
label: labels.organization,
type: 'select',
options: options.value?.organizations ?? [],
},
{
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: options.value?.productCategories ?? [],
},
},
{
key: 'warehouseId',
label: labels.warehouse,
type: 'treeSelect',
visible: showExtra,
fieldProps: {
defaultExpandAll: true,
keyField: 'value',
options: (options.value?.warehouseRegions ?? []).map(
(region) => ({
...region,
disabled: true,
}),
),
},
},
{
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>
{options.value?.deliveries.map((option) => (
<NRadio key={option.value} value={option.value}>
{option.label}
</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, signal, async () => {
const result = await getSearchOrders(
query,
getLocaleLanguage.value,
signal,
fail,
)
return { data: result.items, total: result.total }
})
}
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: options.value?.organizations.find(
({ value }) => value !== draft.value.orgId,
)?.value,
})
}
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">
{optionsFailed.value && (
<NAlert type="error" title={labels.optionsFailed}>
<NButton size="small" onClick={() => optionsAttempt.value++}>
{labels.retryOptions}
</NButton>
</NAlert>
)}
{apiMockEnabled && <strong>{labels.tryScenario}</strong>}
{apiMockEnabled && (
<NFlex size="small">
{scenarios.map((key) => (
<NButton
key={key}
size="small"
secondary
type={scenario.value === key ? 'primary' : 'default'}
disabled={
!table.isReady.value ||
optionsLoading.value ||
optionsFailed.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}
params={queryParams.value}
loading={
optionsLoading.value ||
(source.value === 'local' && rowsLoading.value)
}
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>
{apiMockEnabled && (
<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)
: (options.value?.organizations.find(
({ value }) => value === detail,
)?.label ?? detail)}
</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、dateRange | yyyy-MM-dd 字符串或二元组 | 单日精确匹配,区间包含首尾两天 |
datetime、datetimeRange | 毫秒时间戳或二元组 | 单值精确匹配,区间包含两端 |
time | HH: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,使横向滚动留在表格内。
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、copyImage 和 getTableInstance。扩展表格区域可用 title、toolbar、tableFooter、tableAction;错误区域用 error 插槽。
工具栏分为业务操作与内置工具两组。request 模式提供刷新,列设置、复制图片和全屏为直接入口;密度、斑马纹、边框和 CSV 收入「更多操作」。斑马纹和边框的功能图标始终显示,选中状态在文字右侧单独标记;密度子菜单只保留文字和选中标记。TablePro 的 size 默认是 medium(标准),菜单与表格共用该值;传入 small 或 large 时分别选中紧凑或宽松。打印默认不显示,设置 showPrint 后才加入菜单。tool={false} 隐藏内置工具,保留自定义 toolbar 插槽。
useTablePro
也可以用同一入口导出的 useTablePro 注册实例,保留 [register, actions] 的写法:
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 恢复自己的列定义。
复制表格图片
工具栏默认显示「复制表格图片」,把当前表格的表头、行、内部滚动可视区域及原生分页复制为 PNG,然后可粘贴到聊天或文档。图片排除 TablePro 标题、搜索、工具栏、提示区、tableFooter 和 tableAction;保留当前滚动位置与固定列。捕获范围是表格自身的 DOM 可视盒,虚拟滚动不会补画未挂载行,也不会请求其它页。
const [register, { copyImage }] = useTablePro()
<RTablePro onRegister={register} columns={columns} data={rows} copyImageOptions={{ pixelRatio: 1 }} />
<NButton onClick={() => void copyImage()}>复制表格图片</NButton>showCopyImage={false} 只隐藏按钮;实例和 Hook 的 copyImage(options?) 仍可使用。输出固定 PNG,copyImageOptions 支持 pixelRatio、背景、尺寸、样式、过滤、字体与资源请求配置,单次调用参数优先。默认设备像素比最高为 2。过滤回调收到临时快照节点,请按类名或数据属性判断。
必须直接从用户点击事件调用,之前不要 await 其它任务。图片生成可异步完成,但剪贴板请求需要保留用户激活;实现将 Promise<Blob> 提前交给原生 ClipboardItem。WebKit Clipboard API
成功写入返回 true;加载中、重复调用、未确认的数据、取消和失败返回 false。需要 HTTPS/localhost、支持 PNG 写入的浏览器及剪贴板许可;权限、资源或渲染失败都有反馈。数据更换或卸载会取消尚未就绪的图片并移除临时节点,无法撤销浏览器已经接受的写入。跨源图片、字体和受保护的画布仍受浏览器策略影响;完整当前页数据导出使用 CSV 或打印。
RIcon 的同源精灵图和本地 #symbol 会在临时副本中展开,保留静态矢量、尺寸与 currentColor,不复制导入 ID。只允许同源注册精灵图或公共 .svg,不携带凭据或跟随重定向;单次最多 16 个文件、每个 1 MiB。该路径不支持嵌套引用、paint server、样式表和动态 CSS 值。快照会移除脚本及内联事件属性,并拒绝 iframe/object/embed/audio/video 活动嵌入内容。
打印与 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。 |
showPrint | 默认 false;控制「更多操作」菜单内的打印入口,实例 print() 仍可按需调用。 |
showCopyImage | 默认 true;控制内置复制 PNG 按钮,实例 copyImage() 不受影响。 |
copyImageOptions | PNG 渲染默认配置,单次 copyImage(options) 可覆盖;详见复制表格图片。 |
contextMenuOptions / onContextMenuClick | 行菜单选项及选择回调 (key, option, { row, index })。右键、Shift+F10 或菜单键打开;业务行事件可用 preventDefault() 阻止。 |
常用事件有 onRequestError(error)(或 SFC @request-error)、onUpdatePage、onUpdatePageSize、onUpdate:columns。内部更新和受控回调走同一入口;已传入受控值时由调用方更新对应值。行选择、排序等依然沿用 DataTable 事件;需要服务端排序时,将条件写入 params。
分页对象使用 TableProPagination。旧 pagination.onChange/onPageSizeChange 及顶层 onPageChange/onPageSizeChange 不再调用,请迁移为 onUpdatePage/onUpdatePageSize 或 onUpdate:page/onUpdate:pageSize;原生分页组件不会再收到旧字段。
| 插槽 | 参数与位置 |
|---|---|
filters | 表格上方;接收 { submit(values) },传入字符串或数字键值,提交后回第一页。优先于内置 search。 |
title / toolbar | 标题区左侧 / 操作区右侧;bare 下两者隐藏。 |
notice | 正常情况下显示自定义提示。 |
error | 显式提供时在请求失败后替换 notice,接收 { reload } 并接管默认 Toast。 |
tableFooter / tableAction | DataTable 之后的额外区域。 |
| 其余插槽 | 转给 Naive UI DataTable,例如空态和加载。 |
TableProInst 的 reload(resetPage?)、setPage(page)、setPageSize(size) 返回 Promise<void>。请求错误由事件报告;该 Promise 的完成不能用作业务成功判据。getTableInstance() 可能为 null;print(options?) 返回 Promise<boolean> 表示是否发起预览;downloadCsv(options?) 发起浏览器下载;copyImage(options?) 返回是否成功写入 PNG 剪贴板。
远端请求将 params 与已提交筛选合并,后者覆盖同名项,页码字段最后由表格写入。关闭分页时也会删除传入的 page 和 pageSize。total 需要是非负安全整数,data 必须是数组。若筛选或删除数据后当前页超出范围,会收敛到最后一页,并在有结果时重查。