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 يوفر التخطيط والمحاذاة والافتراضية (virtualization) والتفاعل. أما المسافات الداخلية والألوان والحدود وتأثيرات التحديد لأجزائه فيحددها التطبيق عبر 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: يُطلق onLoadMore مرة واحدة لكل عدد من الصفوف عندما تصبح الصفوف الظاهرة ضمن loadMoreThreshold (الافتراضي 20) من آخر صف. وما دام loading صحيحًا ينتظر، ويظهر الفتحة 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) ويسلّمها كـ 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. أي دالة تُعطى صفًا أو عمودًا أو مفتاح عمود لا يملكه الجدول لا تغيّر شيئًا وتسجّل تحذيرًا يسمّي الدالة والقيمة؛ و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",
  }}
/>

#الخصائص

#الأحداث

#ذات صلة

• Editor وDiffView: المكوّنات الأساسية الأخرى كثيفة البيانات.
• Menu: القائمة التي تُفتح من onContextMenu.
• nsh/base: المكوّنات الأساسية الأخرى.