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 में nsh/base से <DataTable> के साथ।

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 स्लॉट पंक्तियों के ऊपर दिखता है। जब कोई पंक्ति न हो, तो empty स्लॉट दिखता है।

कुछ दस लाख पॉइंट से ज़्यादा की सामग्री पर स्क्रॉल बार एक स्केल की हुई रेंज पर फैलते हैं, इसलिए दस लाख पंक्तियाँ भी हर पंक्ति तक स्क्रॉल होती हैं।

#चयन

gpui-component की तरह, तीन स्विच तय करते हैं कि प्रेस क्या चुनता है:

cellSelectable के साथ और रो हेडर छिपा होने पर (rowHeader={false}), चुने हुए सेल को फिर से दबाने पर उसकी पंक्ति चुनी जाती है। Shift या प्लैटफ़ॉर्म की कमांड कुंजी के साथ प्रेस केवल तब पंक्ति चुनता है जब 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 कॉलम के शीर्षक के अंत में एक सॉर्ट बटन होता है, एक छोटा घोस्ट बटन जो कॉलम के सॉर्ट न होने पर धुंधला रहता है। उसे दबाने पर बिना सॉर्ट, आरोही, अवरोही और फिर बिना सॉर्ट के चक्र में अगला सॉर्ट ({ 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 से जानता है) और उन्हें dataStart से data के रूप में सौंपता है, इसलिए अपडेट की लागत उतनी ही होती है जितना स्क्रीन पर है, पंक्तियों की संख्या चाहे जो हो। बढ़त और गिरावट अपने रंग कॉलम के 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 देता है। जो मेथड ऐसी पंक्ति, कॉलम या कॉलम कुंजी लेता है जो टेबल में नहीं है, वह कुछ नहीं बदलता और मेथड और मान का नाम बताते हुए एक चेतावनी लॉग करता है; fitColumn अज्ञात कुंजी के लिए TypeError के साथ रिजेक्ट होता है।

#पार्ट्स की स्टाइलिंग

class और style टेबल के बॉक्स को स्टाइल करते हैं। classes पार्ट के अनुसार Tailwind क्लास लेता है और styles पार्ट के अनुसार इनलाइन स्टाइल; पार्ट टेबल की संरचना और अलाइनमेंट देते हैं; उनकी क्लास रूप-रंग देती हैं, और styles क्लास पर भारी पड़ते हैं।

<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",
  }}
/>

#Props

#Events

#Related

• Editor और DiffView: डेटा-प्रधान अन्य बेस कॉम्पोनेंट।
• Menu: onContextMenu से खोला जाने वाला मेनू।
• nsh/base: अन्य बेस कॉम्पोनेंट।