QTable 是一個元件,可讓您以表格方式顯示資料。它通常被稱為資料表。它包含以下主要功能
- 篩選
- 排序
- 單選/多選列,帶有自訂選擇動作
- 分頁 (如果需要,包含伺服器端分頁)
- 網格模式 (例如,您可以使用 QCards 以非表格方式顯示資料)
- 透過作用域插槽完全自訂列和儲存格
- 能夠在資料列的頂部或底部新增額外的列
- 欄位選擇器 (透過 QTableColumns 元件,在其中一個章節中描述)
- 自訂頂部和/或底部表格控制項
- 響應式設計
提示
如果您不需要 QTable 的分頁、排序、篩選和所有其他功能,那麼您可能需要查看 QMarkupTable 元件。
定義欄位
讓我們以設定 columns
屬性為例。我們將告訴 QTable,row-key
是 'name',這必須是唯一的。如果這是從資料庫獲取的資料,我們可能會使用列的 id。
columns: [ // array of Objects
// column Object definition
{
// unique id
// identifies column
// (used by pagination.sortBy, "body-cell-[name]" slot, ...)
name: 'desc',
// label for header
label: 'Dessert (100g serving)',
// row Object property to determine value for this column
field: 'name',
// OR field: row => row.some.nested.prop,
// (optional) if we use visible-columns, this col will always be visible
required: true,
// (optional) alignment
align: 'left',
// (optional) tell QTable you want this column sortable
sortable: true,
// (optional) compare function if you have
// some custom data or want a specific way to compare two rows
// --> note that rows with null/undefined as value will get auto sorted
// without calling this method (if you want to handle those as well, use "rawSort" instead)
sort: (a, b, rowA, rowB) => parseInt(a, 10) - parseInt(b, 10),
// function return value:
// * is less than 0 then sort a to an index lower than b, i.e. a comes first
// * is 0 then leave a and b unchanged with respect to each other, but sorted with respect to all different elements
// * is greater than 0 then sort b to an index lower than a, i.e. b comes first
// (optional) requires Quasar v2.13+
// compare function if you have
// some custom data or want a specific way to compare two rows
// --> note that there is an alternative "sort" method (above) if you don't
// want to handle (by yourself) rows with null/undefined as value
rawSort: (a, b, rowA, rowB) => parseInt(a, 10) - parseInt(b, 10),
// has the same return value as the alternative "sort" method above
// (optional) override 'column-sort-order' prop;
// sets column sort order: 'ad' (ascending-descending) or 'da' (descending-ascending)
sortOrder: 'ad', // or 'da'
// (optional) you can format the data with a function
format: (val, row) => `${val}%`,
// one more format example:
// format: val => val
// ? /* Unicode checkmark checked */ "\u2611"
// : /* Unicode checkmark unchecked */ "\u2610",
// body td:
style: 'width: 500px',
// or as Function --> style: row => ... (return String/Array/Object)
classes: 'my-special-class',
// or as Function --> classes: row => ... (return String)
// header th:
headerStyle: 'width: 500px',
headerClasses: 'my-special-class'
},
{ name: 'calories', label: 'Calories', field: 'calories', sortable: true },
{ name: 'fat', label: 'Fat (g)', field: 'fat', sortable: true },
{ name: 'carbs', label: 'Carbs (g)', field: 'carbs' },
{ name: 'protein', label: 'Protein (g)', field: 'protein' },
{ name: 'sodium', label: 'Sodium (mg)', field: 'sodium' },
{ name: 'calcium', label: 'Calcium (%)', field: 'calcium', sortable: true, sort: (a, b) => parseInt(a, 10) - parseInt(b, 10) },
{ name: 'iron', label: 'Iron (%)', field: 'iron', sortable: true, sort: (a, b) => parseInt(a, 10) - parseInt(b, 10) }
]
基本用法
提示
您可以將 dense
屬性與 $q.screen
一起使用,以建立響應式行為。範例::dense="$q.screen.lt.md"
。更多資訊:Screen Plugin。
省略欄位定義
您可以省略指定 columns
。QTable 將從資料第一列的屬性推斷欄位。請注意,標籤會轉換為大寫,並且啟用排序
固定標頭/欄位
警告
固定標頭和欄位是透過 CSS 使用 position: sticky
實現的。並非所有瀏覽器都支援此功能。在使用此技術之前,請查看 caniuse.com。
提示
請注意以下範例中 “style” 區段中的程式碼,特別是關於 position: sticky
的部分。
分隔線
樣式設定
虛擬滾動
請注意,當啟用虛擬滾動時,您需要指定 table-style
(帶有 max-height) 屬性。在下面的範例中,我們也強制 QTable 一次顯示所有列 (請注意 pagination
和 rows-per-page-options
屬性的使用)。
當滾動到達末尾時,您可以動態載入新列
您可以同時擁有虛擬滾動和分頁
下面的範例示範如何將虛擬滾動與固定標頭一起使用。請注意 virtual-scroll-sticky-start
屬性,它被設定為標頭高度。
有 2 個實用程式 CSS 類別控制 VirtualScroll 大小計算
- 在 VirtualScroll 呈現的元素上使用
q-virtual-scroll--with-prev
類別,以指示該元素應與前一個元素分組 (主要用例是用於從同一資料列產生的多個表格列)。 - 在 VirtualScroll 呈現的元素上使用
q-virtual-scroll--skip
類別,以指示在大小計算中應忽略該元素的大小。
選擇
警告
必須設定 row-key
屬性才能使選擇正常運作。
可見欄位、自訂頂部、全螢幕
請注意,標記為 required
(在欄位定義中) 的欄位無法切換,並且始終可見。
彈出式編輯
提示
以下是一個範例,使用者可以使用 QPopupEdit 元件進行 “就地” 編輯。請注意,我們正在使用 body
作用域插槽。QPopupEdit 不適用於儲存格作用域插槽。
使用輸入框編輯
網格樣式
提示
您可以將 grid
屬性與 $q.screen
一起使用,以建立響應式行為。範例::grid="$q.screen.lt.md"
。更多資訊:Screen Plugin。
在下面的範例中,我們讓 QTable 處理網格模式的顯示 (不使用特定插槽)
但是,如果您想完全自訂內容,請查看下面的範例,其中
- 我們正在使用一個名為
item
的 Vue 作用域插槽來定義每個記錄 (在非網格模式下相當於列) 的外觀。這讓您擁有完全的自由。 - 我們正在使用多選。
展開列
警告
如果您從資料中的一列產生多個 QTr,請在 QTr 上新增唯一的 (不同的) key
。
也可以使用外部展開模型
如果您正在將虛擬滾動與 QTable 一起使用,您應該知道有 2 個實用程式 CSS 類別控制 VirtualScroll 大小計算
- 在 VirtualScroll 呈現的元素上使用
q-virtual-scroll--with-prev
類別,以指示該元素應與前一個元素分組 (主要用例是用於從同一資料列產生的多個表格列)。 - 在 VirtualScroll 呈現的元素上使用
q-virtual-scroll--skip
類別,以指示在大小計算中應忽略該元素的大小。
之前/之後插槽
分頁
提示
當 pagination
具有名為 rowsNumber
的屬性時,這表示您將為伺服器端分頁 (& 排序 & 篩選) 設定表格。請參閱“伺服器端分頁、篩選和排序”章節。
以下是兩個處理分頁 (以及排序和每頁列數) 的範例。
第一個範例重點介紹如何設定初始分頁
第二個範例使用 “v-model:pagination” 指令,因為我們希望隨時存取其目前值。以下技術的一個用例是從 QTable 外部控制分頁。
分頁插槽
為了學習目的,我們將使用預設控制項自訂分頁控制項,以便幫助您開始使用自己的控制項。
載入狀態
自訂頂部
主體插槽
下面的範例示範如何使用插槽來自訂整個列
下面,我們使用一個插槽,它應用於每個主體儲存格
我們也可以僅自訂一個特定欄位。此插槽的語法為 body-cell-[name]
,其中 [name]
應替換為用作列鍵的每一列的屬性。
標頭插槽
下面的範例示範如何使用插槽來自訂整個標頭列
下面,我們使用一個插槽,它應用於每個標頭儲存格
我們也可以僅自訂一個特定標頭儲存格。此插槽的語法為 header-cell-[name]
,其中 [name]
應替換為用作列鍵的每一列的屬性。
無資料
還有一個 “no-data” 作用域插槽 (請參閱下文),您也可以使用它來自訂篩選器未傳回任何結果或表格沒有資料可顯示時的訊息。也在 “搜尋” 輸入框中輸入一些內容。
處理底層
您可以使用一些屬性來隱藏底層或其特定部分。您可以在下面試用
自訂排序
響應式表格
為了建立響應式表格,我們有兩個工具可供使用:dense
和 grid
屬性。我們可以將這些與 $q.screen
連接。更多資訊:Screen Plugin。
下面的第一個範例使用 $q.screen.lt.md
(用於啟用密集模式),第二個範例使用 $q.screen.xs
來啟用網格模式,因此請調整瀏覽器寬度以查看它們的實際效果。
伺服器端分頁、篩選和排序
當您的資料庫包含大量表格列時,顯然由於多種原因 (記憶體、UI 呈現效能等),載入所有列是不可行的。相反,您可以僅載入表格頁面。每當使用者想要導航到另一個表格頁面,或想要按欄位排序或想要篩選表格時,都會向伺服器發送請求以獲取部分分頁資料。
啟用此行為的第一步是指定
pagination
屬性,該屬性必須包含rowsNumber
。QTable 需要知道可用的總列數,以便正確呈現分頁連結。如果篩選導致rowsNumber
變更,則必須動態修改它。第二步是監聽 QTable 上的
@request
事件。當需要從伺服器獲取資料時,會觸發此事件,因為頁碼或排序或篩選已變更。最好您也指定
loading
屬性,以便通知使用者正在進行背景處理。
提示
在下面的範例中,已採取步驟來模擬對伺服器的 ajax 呼叫。雖然概念相似,但如果您使用此程式碼,則需要進行適當的變更以連線到您自己的資料來源。
匯出資料
以下是一個簡單的 csv 編碼範例,然後使用 exportFile Quasar 實用程式匯出表格資料。瀏覽器應觸發檔案下載。對於更專業的編碼方法,我們建議使用 csv-parse 和 csv-stringify 套件。
提示
如果您想要匯出使用者篩選 + 排序的資料,您也可以使用 QTable 的 filteredSortedRows
內部計算屬性。
鍵盤導航
以下是一個在表格中使用選取列進行鍵盤導航的範例。使用 ArrowUp
、ArrowDown
、PageUp
、PageDown
、Home
和 End
鍵進行導航。