CTable

Bảng của trang danh sách: khung card có tiêu đề và toolbar, header bảng nền primary, phân trang "Tổng số dòng N", drawer lọc và drawer thiết lập cột. Bọc a-table và chuyển tiếp nguyên vẹn mọi prop, slot, sự kiện của nó — nên mọi thứ biết về a-table vẫn dùng được.

Dùng khi: hiển thị danh sách bản ghi có phân trang, sắp xếp, lọc — trang danh sách, bảng con trong trang chi tiết, bảng trong drawer.

Không dùng khi: danh sách ngắn, cố định, không thao tác gì (dùng CDescriptions hoặc danh sách thường); hoặc dữ liệu dạng cây/biểu đồ.

<script setup lang="ts">
// Khung tối thiểu: cột + dữ liệu. Không bật toolbar thì bảng chỉ có khung viền.
interface Order {
  id: number
  code: string
  customer: string
}

const columns = [
  { title: 'Mã đơn', dataIndex: 'code', key: 'code', width: 140 },
  { title: 'Khách hàng', dataIndex: 'customer', key: 'customer' },
]

const dataSource: Order[] = [
  { id: 1, code: 'DH-0001', customer: 'Công ty An Bình' },
  { id: 2, code: 'DH-0002', customer: 'Tập đoàn Bắc Sơn' },
  { id: 3, code: 'DH-0003', customer: 'Cửa hàng Cường Thịnh' },
]
</script>

<template>
  <CTable
    row-key="id"
    :columns="columns"
    :data-source="dataSource"
    :pagination="false"
  />
</template>

Không bật tuỳ chọn nào của toolbar thì CTable chỉ là bảng trong khung viền — tương thích với cách dùng a-table thuần.

Đi cùng useTable

Trong app, gần như luôn dùng cặp useTable + CTable: composable giữ trang, sắp xếp, bộ lọc và gọi backend; component lo giao diện.

<script setup lang="ts">
const { fetchOrders } = useOrdersApi()
const { dataSource, loading, pagination, onChange } = useTable<Order>(fetchOrders, { pageSize: 20 })
</script>

<template>
  <CTable
    row-key="id"
    :columns="columns"
    :data-source="dataSource"
    :loading="loading"
    :pagination="pagination"
    @change="onChange"
  />
</template>

Mẫu trang đầy đủ: Trang danh sách.

Các phần của bảng

Phần	Bật bằng	Chi tiết
Cột và ô dữ liệu	columns + slot #bodyCell	Cột và ô dữ liệu
Toolbar (Thêm mới, tìm kiếm, xuất, tải lại)	show-*	Toolbar
Bộ lọc dựng sẵn	filter-fields + v-model:filter-values	Lọc và tìm kiếm
Sắp xếp, phân trang	sorter trên cột, pagination	Sắp xếp và phân trang
Thiết lập cột của người dùng	show-column-setting + settings-key	Thiết lập bảng
Đang tải, rỗng, dòng xen kẽ	loading, striped, slot #emptyText	Trạng thái bảng

Khung card

CTable dùng chính CCard làm khung, nên nhận các prop khung tương ứng:

<CTable
  title="Mặt hàng của đơn"
  type="default"
  collapsible
  :default-open="false"
  borderless
/>

Prop	Mặc định	Ý nghĩa
title	''	Tiêu đề bên trái header; slot #title để tuỳ biến
type	default	Biến thể khung như CCard; default (header trắng) là chuẩn trang danh sách
collapsible, default-open	false, true	Thu gọn cả bảng — hợp với bảng con
borderless	false	Bỏ viền và bóng

Vì bảng đã có khung riêng, không bọc CTable trong CCard.

API

Props

Tên	Kiểu	Mặc định	Mô tả
title	string	''	Tiêu đề ở header khung (bên trái); slot #title để tuỳ biến.
collapsible	boolean	false	Cho phép thu gọn bảng.
defaultOpen	boolean	true	Trạng thái mở ban đầu khi collapsible.
borderless	boolean	false	Bỏ viền + bóng của khung.
type	"default" | "primary" | "outline" | "ghost" | "filled"	'default'	Biến thể khung (xem CCard); `default` là header trắng — chuẩn trang danh sách.
striped	boolean	false	Nền xen kẽ giữa các dòng.
showCreate	boolean	false	Nút "Thêm mới" (sự kiện create).
createText	string	'Thêm mới'	Nhãn nút "Thêm mới".
showSearch	boolean	false	Ô tìm kiếm: v-model:searchValue, sự kiện search khi Enter hoặc bấm xoá.
searchValue	string	''	v-model:searchValue — text ô tìm kiếm.
searchPlaceholder	string	'Tìm kiếm...'	Gợi ý trong ô tìm kiếm.
showFilter	boolean	false	Nút "Lọc" (sự kiện filter) — có filterFields thì mở drawer lọc dựng sẵn, không thì trang tự mở.
filterText	string	'Lọc'	Nhãn nút "Lọc".
filterCount	number	0	Số bộ lọc đang áp dụng (lớn hơn 0 hiện chấm đỏ trên nút Lọc); có filterFields thì tự đếm.
filterFields	TableFilterField[]	undefined	Trường của drawer lọc dựng sẵn — trang khai báo, như columns. Có giá trị → nút Lọc mở drawer và thanh điều kiện lọc hiện trên bảng; trường type custom render control qua slot #filterField.
filterValues	TableFilterValues	undefined	v-model:filterValues — bộ lọc đã áp dụng (không bind thì CTable tự giữ state).
showExport	boolean	false	Nút tròn xuất dữ liệu (sự kiện export).
showReload	boolean	false	Nút tròn tải lại (sự kiện reload); icon xoay khi bảng loading.
showColumnSetting	boolean	false	Nút tròn thiết lập: drawer đổi thứ tự/ẩn cột và đặt sắp xếp mặc định (cột có `sorter`).
settingsKey	string	undefined	Khoá lưu thiết lập vào localStorage (`tasco:table:<settingsKey>`) — mỗi bảng một khoá, vd `orders`, `orders:items`. Không truyền thì thiết lập chỉ giữ trong phiên. Truyền cùng khoá cho `useTable({ settingsKey })` để lần tải đầu đã theo sắp xếp mặc định.
settings	TableSettings	undefined	v-model:settings — thiết lập đang áp dụng; bind khi trang tự lưu nơi khác (vd server), không bind thì CTable tự giữ.

Sự kiện

Tên	Payload	Mô tả
filter	[]	Bấm nút "Lọc" khi KHÔNG truyền `filterFields` (trang tự mở drawer lọc riêng).
update:searchValue	[value: string]	v-model:searchValue — text ô tìm kiếm.
search	[value: string]	Nhấn Enter hoặc bấm xoá trong ô tìm kiếm (không tự debounce).
update:filterValues	[values: TableFilterValues]	v-model:filterValues — bộ lọc sau khi bấm Áp dụng trong drawer (đã bỏ trường rỗng).
update:settings	[settings: TableSettings]	v-model:settings — thiết lập cột và sắp xếp mặc định sau khi bấm Lưu lại.
change	[pagination: TablePaginationConfig, filters: Record<string, FilterValue | null>, sorter: SorterResult<any> | SorterResult<any>[], extra: TableCurrentDataSource<...>]	Sự kiện change của a-table; CTable cũng phát (action `sort`) khi lưu sắp xếp mặc định mới.
create	[]	Bấm nút "Thêm mới".
export	[]	Bấm nút xuất dữ liệu.
reload	[]	Bấm nút tải lại.

Slot

Tên	Props của slot	Mô tả
#title	{}	Thiếu mô tả trong source
#toolbar	{}	Thiếu mô tả trong source
#filterField	{ field: TableFilterDateField | TableFilterCustomField; values: TableFilterValues; }	Thiếu mô tả trong source

Ba slot dưới đây do CTable tự render (không chuyển xuống a-table), nên không xuất hiện trong bảng sinh tự động ở trên:

Slot	Tham số	Dùng để
#title	—	Thay tiêu đề khung
#toolbar	—	Chèn nút riêng vào đầu toolbar
#filterField	{ field, values }	Render control cho trường lọc type: 'custom'

Mọi slot khác (#bodyCell, #headerCell, #expandedRowRender, #emptyText, #summary…) được chuyển tiếp xuống a-table.

Lưu ý chung

• row-key là bắt buộc và phải trỏ field định danh thật.
• class và style gắn vào khung ngoài, không phải thẻ <table>.
• Sắp xếp và lọc luôn để backend làm; xử lý tại chỗ chỉ đúng trong trang hiện tại.
• Một trang có nhiều bảng thì mỗi bảng cần settings-key riêng.

Liên quan

• useTable — state và gọi dữ liệu.
• Trang danh sách — mẫu trang hoàn chỉnh.
• CCard — khung mà bảng dùng lại.