CTable — thiết lập bảng

Bật show-column-setting là bảng có nút ⚙ mở drawer cho người dùng tự đổi thứ tự cột, ẩn cột và đặt sắp xếp mặc định. Có settings-key thì lựa chọn được nhớ lại giữa các phiên làm việc.

<script setup lang="ts">
// Nút ⚙ mở drawer Thiết lập: đổi thứ tự cột, ẩn cột, đặt sắp xếp mặc định.
// `settings-key` lưu lựa chọn vào localStorage — thử đổi rồi tải lại trang này.
interface Order { id: number, code: string, customer: string, amount: number, createdAt: string }

const columns = [
  { title: 'Mã đơn', dataIndex: 'code', key: 'code', width: 130, sorter: true },
  { title: 'Khách hàng', dataIndex: 'customer', key: 'customer' },
  { title: 'Giá trị', dataIndex: 'amount', key: 'amount', align: 'right', width: 150, sorter: true },
  { title: 'Ngày tạo', dataIndex: 'createdAt', key: 'createdAt', width: 130, sorter: true },
]

const dataSource: Order[] = [
  { id: 1, code: 'DH-0001', customer: 'Công ty An Bình', amount: 12_500_000, createdAt: '01/09/2026' },
  { id: 2, code: 'DH-0002', customer: 'Tập đoàn Bắc Sơn', amount: 4_200_000, createdAt: '03/09/2026' },
]

const currency = new Intl.NumberFormat('vi-VN')
</script>

<template>
  <CTable
    title="Đơn hàng"
    row-key="id"
    settings-key="docs:c-table-demo"
    :columns="columns"
    :data-source="dataSource"
    :pagination="false"
    show-column-setting
  >
    <template #bodyCell="{ column, record }">
      <template v-if="column.key === 'amount'">
        {{ currency.format((record as Order).amount) }} ₫
      </template>
    </template>
  </CTable>
</template>

Demo trên lưu vào localStorage của chính trang tài liệu này — đổi thử rồi tải lại trang để thấy thiết lập được giữ.

Drawer có gì

Tab "Hiển thị cột" — kéo tay nắm ⋮⋮ (chuột) hoặc bấm ↑/↓ (bàn phím, cảm ứng) để đổi thứ tự; công tắc Hiện/Ẩn cho từng cột, luôn giữ ít nhất một cột hiện.

Tab "Khác" — chỉ có khi bảng có cột sorter: bật/tắt sắp xếp mặc định, chọn cột và chiều.

Như drawer lọc, mọi thay đổi là bản nháp: Lưu lại mới áp dụng, đóng drawer là bỏ, Đặt lại đưa nháp về cấu hình gốc (thứ tự theo columns, hiện hết cột, tắt sắp xếp).

Cột title: '' (cột tiện ích như ⋮) không xuất hiện trong danh sách và giữ nguyên vị trí. Cột fixed chỉ đổi thứ tự trong nhóm ghim của nó.

Lưu ở đâu

<CTable settings-key="orders" show-column-setting />

localStorage['tasco:table:orders'] giữ { version: 1, columnOrder, hiddenColumns, defaultSort }.

• Mỗi bảng một khoá, đặt tường minh theo màn hình: orders, orders:items. CTable không tự sinh khoá theo route (route động và bảng render có điều kiện sẽ làm khoá đổi liên tục) và cũng không cảnh báo khi trùng — hai bảng cùng khoá sẽ dùng chung thiết lập.
• Không truyền settings-key thì thiết lập chỉ sống trong phiên hiện tại.
• Lưu đúng bằng cấu hình gốc → khoá bị xoá hẳn, để cột thêm về sau hiện đúng vị trí khai báo.
• Dữ liệu hỏng, khác version, hoặc storage bị chặn (chế độ riêng tư) → dùng cấu hình gốc, không báo lỗi.

Khi columns thay đổi giữa hai lần deploy

Tình huống	Hành vi
Cột bị xoá khỏi columns	Key cũ trong thiết lập bị bỏ qua
Cột mới thêm vào	Chèn ngay sau cột đứng trước nó trong columns, mặc định hiện
Sắp xếp mặc định trỏ tới cột không còn sắp xếp được	Coi như tắt sắp xếp

Nhờ vậy không cần "xoá thiết lập của người dùng" mỗi lần đổi bảng.

Sắp xếp mặc định

• Truyền cùng khoá cho useTable({ settingsKey }) để lần tải đầu đã đúng thứ tự.
• Lưu sắp xếp mặc định mới (hoặc tắt) → CTable phát @change với action: 'sort', về trang 1, y như khi bấm tiêu đề cột → useTable.onChange tải lại. Chỉ đổi thứ tự hoặc ẩn cột thì không phát change, vì dữ liệu không đổi.
• Khi dùng thiết lập, CTable điều khiển sortOrder của các cột sorter để chỉ báo trên header khớp với sắp xếp đang áp dụng. Bấm tiêu đề cột vẫn đổi được sắp xếp, chỉ là không lưu lại.
• CTable không can thiệp nếu trang tự khai sortOrder, dùng sorter.multiple, hoặc có cột nhóm (children).
• Trang tự viết @change (không dùng useTable) thì đọc thiết lập trực tiếp:

import { getTableSettings } from '@tasco/utils'

const savedSort = getTableSettings('orders')?.defaultSort

Lưu thiết lập lên server

Muốn thiết lập theo người dùng thay vì theo trình duyệt: bỏ settings-key, tự quản lý qua v-model:settings, và kiểm tra dữ liệu đọc về bằng parseTableSettings:

import { parseTableSettings } from '@tasco/utils'
import type { TableSettings } from '@tasco/utils'

const settings = ref<TableSettings | undefined>()

onMounted(async () => {
  const raw = await api('/me/table-settings/orders')
  settings.value = parseTableSettings(raw) ?? undefined
})

async function onSettings(next: TableSettings) {
  settings.value = next
  await api('/me/table-settings/orders', { method: 'PUT', body: next })
}

<CTable :settings="settings" show-column-setting @update:settings="onSettings" />

v-model:settings thắng settings-key khi truyền cả hai.

Lỗi thường gặp

Thông báo / hiện tượng	Nguyên nhân
[@tasco/ui] CTable: cột "…" cần key hoặc dataIndex để lưu thiết lập	Cột cấu hình được thiếu định danh — thêm key
Hai bảng đổi thiết lập của nhau	Trùng settings-key
Bảng hiện chỉ báo sắp xếp nhưng dữ liệu không sắp xếp	Quên settingsKey ở useTable
Thiết lập không được nhớ	Thiếu settings-key, hoặc trình duyệt chặn localStorage

Liên quan

• Sắp xếp và phân trang.
• useTable.
• Cột và ô dữ liệu — quy tắc key của cột.