DataTable

DataTable 像試算表一樣顯示列與欄，可朝兩個方向捲動，列數與欄數不限。只有在視野內的儲存格才會建立，因此擁有一百萬列、一萬欄的表格，捲動起來與小型表格無異。可以用指標和鍵盤選取列、欄或儲存格；欄有固定寬度，可拖曳邊緣調整寬度，可拖曳標題移動位置，可固定在左側（其餘欄捲動），也可排序。標題可置於群組標籤之下，儲存格或標題亦可由應用程式自行繪製。

import { mount, signal, Text, View } from "nsh";
import { DataTable, type DataTableColumn, type DataTableSort } from "nsh/base";
import { dataTableClasses, dataTableFitPadding, Log, Segmented, Split, ui, wide } from "./palette";

const NAMES = ["Ada", "Alan", "Grace", "Linus", "Margaret", "Dennis", "Barbara", "Ken"];
const CITIES = ["Oslo", "Lima", "Kyoto", "Cairo", "Perth", "Quito", "Turin", "Hanoi"];

type Person = { id: number; name: string; city: string; score: number };

const people: Person[] = Array.from({ length: 2000 }, (_, i) => ({
  id: i + 1,
  name: `${NAMES[i % NAMES.length]} ${i + 1}`,
  city: CITIES[(i * 7) % CITIES.length],
  score: (i * 37) % 1000,
}));

const columns: DataTableColumn[] = [
  { key: "id", title: "ID", width: 70, align: "end", fixed: true, sortable: true },
  { key: "name", title: "Name", width: 150, sortable: true },
  { key: "city", title: "City", width: 120, sortable: true },
  { key: "score", title: "Score", width: 90, align: "end", sortable: true },
];

// Sorting is the app's: the table reports the next sort (`onSortChange`),
// the app orders its rows and sets `sort`.
function App() {
  const mode = signal<"row" | "cell">("row");
  const sort = signal<DataTableSort | undefined>(undefined);
  const rows = signal<Person[]>(people);
  const events = signal<string[]>([]);
  const log = (line: string) => events.set([line, ...events()].slice(0, 4));

  const sortBy = (next: DataTableSort | undefined) => {
    sort.set(next);
    if (!next) return rows.set(people);
    const key = next.key as keyof Person;
    const sign = next.direction === "descending" ? -1 : 1;
    rows.set([...people].sort((a, b) => (a[key] < b[key] ? -sign : a[key] > b[key] ? sign : 0)));
  };

  return (
    <View style={{ flex: 1, backgroundColor: ui().page, padding: 20, paddingTop: 24, gap: 14 }}>
      <Text style={{ fontSize: 22, fontWeight: "700", color: ui().text }}>data table</Text>
      <Text style={{ color: ui().muted }}>Press a title to sort, drag its edge to resize or the title to move it</Text>

      <Split
        grow
        width={680}
        inspector={
          <>
            <Segmented label="selection" options={["row", "cell"] as const} value={mode()} onChange={(v) => mode.set(v)} />
            <Log title="events" lines={events()} minHeight={96} />
          </>
        }
      >
        <View style={{ height: wide() ? 360 : 320 }}>
          <DataTable
            columns={columns.map((column) => ({ ...column, fitPadding: dataTableFitPadding }))}
            classes={dataTableClasses}
            data={rows()}
            rowHeader={false}
            stripe
            cellSelectable={mode() === "cell"}
            sort={sort()}
            onSortChange={({ sort: next }) => {
              sortBy(next ?? undefined);
              log(`onSortChange: ${next ? `${next.key} ${next.direction}` : "none"}`);
            }}
            onSelectionChange={({ selection }) => log(`onSelectionChange: ${selection ? JSON.stringify(selection) : "none"}`)}
            onColumnResize={({ key, width }) => log(`onColumnResize: ${key} ${Math.round(width)}`)}
            style={{ flex: 1 }}
          />
        </View>
      </Split>
    </View>
  );
}

mount(App);

DataTable 提供版面配置、對齊、虛擬化和互動。應用程式透過 classes 和 styles 為各部件設定內距、顏色、邊框和選取回饋。Rust 以 nsh_base::data_table() 建立，TSX 則以 <DataTable> 從 nsh/base 建立。

use nsh_base::{DataTableColumn, data_table};
use nsh_core::prelude::*;

fn column(key: &str, title: &str) -> DataTableColumn {
    let mut column = DataTableColumn::default();
    column.key = key.into();
    column.title = Some(title.into());
    column
}

fn table() -> impl IntoElement {
    data_table()
        .columns(vec![column("name", "Name"), column("city", "City")])
        .flex_1()
}

import { mount } from "nsh";
import { DataTable, type DataTableColumn } from "nsh/base";

const columns: DataTableColumn[] = [
  { key: "name", title: "Name", width: 160, sortable: true },
  { key: "city", title: "City", width: 120 },
  { key: "score", title: "Score", width: 90, align: "end" },
];

const rows = [
  { name: "Ada", city: "Oslo", score: 91 },
  { name: "Grace", city: "Lima", score: 87 },
  { name: "Linus", city: "Kyoto", score: 78 },
];

function App() {
  return <DataTable columns={columns} data={rows} class="flex-1" />;
}

mount(App);

表格會填滿應用程式給予的方框（flex-1、高度），並在內部捲動：垂直捲動列，橫向捲動欄，附有捲動條（scrollbar={false} 會隱藏捲動條，bounces={false} 在有回彈效果的平台上，讓捲動到盡頭時不再回彈）。

#列與欄

data 是列資料：物件（其欄位由各欄的 key 指名），或由欄按位置索引的陣列。數字、布林值和字串以文字顯示。Rust 一次提供列的一個欄位，每個欄位屬同一類型：DataTableRows::new(2).texts("symbol", ["AAPL", "MSFT"]).numbers("change", [1.2, -0.4])。欄是一個 DataTableColumn：

rowHeight 是內容列的高度（預設 32），headerHeight 是標題列的高度（預設與列高相同）。rowHeader 會在左側加入列號欄，可用來選取列。stripe 讓奇數列套用 rowOdd 部件。

#群組標籤

groups 在欄的上方加入標籤，由最低層開始。每一層是 { label, span } 的清單，其跨度總和等於欄數，或等於下一層的數目。

<DataTable
  columns={columns}
  data={rows}
  groups={[
    [{ label: "Person", span: 2 }, { label: "Result", span: 1 }],
  ]}
  class="flex-1"
/>

#列數不限

表格按位置向應用程式要求列，由應用程式供應。rowCount 是列的總數，data 是應用程式持有的列，dataStart 是其中第一列的位置。data 以外的列在應用程式提供之前都是空的。onVisibleRowsChange 在每個捲動步驟報告視野內的列 { range: { start, end } }，適合在此取得其周圍一頁的資料。

const ROWS = 1_000_000;
const page = signal({ start: 0, rows: load(0) });

<DataTable
  columns={columns}
  data={page().rows}
  dataStart={page().start}
  rowCount={ROWS}
  onVisibleRowsChange={({ range: { start, end } }) => {
    // Keep the rows in view inside the page held.
    const held = page();
    if (start < held.start || end > held.start + held.rows.length) {
      const first = Math.max(0, start - 200);
      page.set({ start: first, rows: load(first) });
    }
  }}
  class="flex-1"
/>

對於在尾端不斷增加的清單，請設定 hasMore：當視野內的列與最後一列相距在 loadMoreThreshold（預設 20）以內時，每個列數只會觸發一次 onLoadMore。當 loading 為 true 時會等待，而 loadingView slot 會顯示在列之上。沒有列時會顯示 empty slot。

內容超過數百萬點後，捲動條會涵蓋縮放後的範圍，因此一百萬列仍可捲動到每一列。

#選取

與 gpui-component 一樣，由三個開關決定按下時選取甚麼：

設定 cellSelectable 而列標頭隱藏（rowHeader={false}）時，再按一次已選取的儲存格，會選取其所在的列。按住 Shift 或平台的 command 鍵按下時，只有在 selectOnModifierPress（預設 true）時才會選取列，因此自行保存多列選取的應用程式要自行處理這些按下動作：onRowPress 會報告主體每一次按下的資料，包括其所在列、指標下的欄、列內的點擊次數和按住的修飾鍵。selectable 為 false 的欄，本身及其儲存格都不會被選取。

資料中的列由 0 起算，欄則以其在 columns 中的索引表示，無論使用者將它們移到甚麼次序。onSelectionChange 報告使用者選取了甚麼（沒有選取時為 null）。selection 屬性由應用程式設定選取；不設定的話，表格會自行保存。onDoublePress 報告被連按兩下的列、儲存格或標題，onContextMenu 則報告次要按下或長按，並附上應開啟應用程式的Menu的位置。兩者都會指出指標下的儲存格（其 row 與 column）、列號（只有 row）或標題（只有 column）。在下一次按下之前，被要求顯示選單的儲存格會套用 cellActive 部件；在儲存格不可選取的情況下，則由其所在列套用 rowActive 部件。

螢幕閱讀器會讀出一個網格（由 accessibilityLabel 命名），包含欄標頭與儲存格，已選取的會讀作已選取。

#鍵盤

按下表格，或以 Tab 移至表格（macOS、網頁），表格便取得鍵盤，直到再按其他地方、焦點移到別處或 blur() 為止；focus() 則由應用程式把鍵盤交給表格。表格是 Tab 的一個停駐點：在表格內 Tab 會移動選取，按 Escape 則交還鍵盤。

loopSelection（預設 true）讓方向鍵在兩端循環移動。

#排序

可 sortable 的欄在標題末端有排序按鈕，是一個小型 ghost 按鈕，欄未排序時會變暗。按下後會報告下一個排序（{ key, direction }），循環順序為未排序、升序、降序，再回到未排序，並附上 onSortChange({ sort })（null 表示清除）。表格不會重新排列列：由應用程式為其資料排序，或向伺服器要求新次序的列，並設定 sort 讓標題顯示出排序狀態。由於次序由應用程式掌握，即使有一百萬列從未由應用程式持有，排序的運作方式也完全相同。

<DataTable
  columns={columns}
  data={rows()}
  sort={sort()}
  onSortChange={({ sort: next }) => {
    sort.set(next ?? undefined);
    rows.set(sorted(people, next));
  }}
  class="flex-1"
/>

#調整與移動欄

拖曳欄的尾端邊緣，可在其 minWidth 與 maxWidth 之間調整寬度，onColumnResize({ key, width }) 會報告每一步。連按兩下邊緣，會將欄貼合至其最寬的文字與標題。拖曳標題可移動欄，並以一條線顯示放下的位置；onColumnMove 報告 { key, from, to, order }，order 是所有欄按顯示次序排列的 key。固定欄仍留在固定欄之中。resizableColumns 和 movableColumns 會為整個表格同時關閉這兩項功能，而欄本身的 resizable 和 movable 優先於它們。

#即時資料

報價表每秒會變動多次。應用程式格式化視野內的列及其周圍一段範圍的列（可從 onVisibleRowsChange 得知），並以 data 從 dataStart 交出，因此更新的成本只取決於畫面上的內容，與列數無關。上升與下跌的顏色取自欄的 positiveClass 和 negativeClass，並以原生方式套用到數值大於或小於零（或文字以 + 或 - 開頭）的儲存格。

const tone = { positiveClass: "text-green-600", negativeClass: "text-red-600" };
const columns: DataTableColumn[] = [
  { key: "symbol", title: "Symbol", fixed: true },
  { key: "price", title: "Price", align: "end", sortable: true },
  { key: "change", title: "Chg%", align: "end", ...tone },
];

列與欄是表格建立一次後便保留的槽位：捲動只是讓它們改為顯示其他列和欄，因此無論捲動多遠，變動的只有文字和位置。

#繪製儲存格與標題

當欄不只是文字時（例如徽章、按鈕），renderCell 會繪製應用程式自己的儲存格。它只會為視野內的儲存格呼叫，並帶有一個 DataTableCell：row、column、key、text（表格原本會顯示的內容）和 selected。應用程式以 row 查找自己的資料。renderHeaderCell 會在標題的儲存格內繪製標題，並獲傳入一個 DataTableHeaderCell：column、key、title、sort（排序方向，或無）和 selected。

<DataTable
  columns={columns}
  data={rows()}
  renderCell={(cell) =>
    cell.key === "status" ? (
      <View class={cell.text === "open" ? "rounded bg-green-500/20 px-2" : "rounded bg-muted px-2"}>
        <Text class="text-xs">{cell.text}</Text>
      </View>
    ) : (
      <Text class="px-2 text-sm">{cell.text}</Text>
    )
  }
  class="flex-1"
/>

fontFamily 和 fontSize（預設 14）設定儲存格的字型，表格亦以此字型量度文字，用來貼合欄寬。

#ref

ref 提供 DataTableRef。如果方法收到表格沒有的列、欄或欄 key，則不會改變任何東西，並記錄一則警告，指出該方法和該值；fitColumn 遇到未知的 key 會以 TypeError reject。

#為部件設定樣式

class 和 style 為表格的方框設定樣式。classes 按部件接受 Tailwind class，styles 按部件接受內嵌樣式；部件提供表格的結構與對齊，其 class 提供外觀，而 styles 優先於 class。

<DataTable
  columns={columns}
  data={rows()}
  stripe
  class="flex-1 rounded-lg border border-border"
  classes={{
    header: "bg-secondary",
    headerCell: "pl-2 pr-1",
    headerContent: "gap-1",
    cell: "px-2",
    resizeHandle: "bg-border group-hover:bg-primary",
    sortAscending: "text-muted-foreground opacity-60 selected:text-foreground selected:opacity-100",
    sortDescending: "text-muted-foreground opacity-60 selected:text-foreground selected:opacity-100",
    rowSelected: "bg-primary/10",
    rowHover: "bg-muted/50",
    fixedEdge: "bg-border",
  }}
/>

#屬性

#事件

#相關內容

• Editor 與 DiffView：其他以大量資料為主的基礎元件。
• Menu：從 onContextMenu 開啟的選單。
• nsh/base：其他基礎元件。