ساخت کتابخانه برای همگام سازی وضعیت جدول TanStack با پارامترهای URL

Summarize this content to 400 words in Persian Lang
Tanstack Table یک کتابخانه UI بسیار قابل تنظیم و بدون هد برای ساخت جداول قدرتمند در چارچوب های مختلف از جمله React، Vue و Solid است.

من یک کتابخانه به نام ایجاد کرده ام tanstack-table-search-params. این کتابخانه وضعیت TanStack Table – مانند جستجو و مرتب‌سازی – را با پارامترهای URL در برنامه‌های React همگام‌سازی می‌کند.

React Hook برای همگام سازی وضعیت TanStack Table با پارامترهای جستجوی URL.

React Hook برای همگام سازی وضعیت TanStack Table با پارامترهای جستجوی URL.

tanstack-table-search-params.mp4

🚀 شروع سریع

ابتدا بسته را نصب کنید.

npm i tanstack-table-search-params

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

به عنوان مثال، اگر از Next.js (مسیریاب صفحات) استفاده می کنید، می توانید از هوک به این صورت استفاده کنید.

import { useReactTable } from “tanstack-table”;
import { useRouter } from “next/router”;
import { useTableSearchParams } from “tanstack-table-search-params”;
const router = useRouter();

// Get state and onChanges
const stateAndOnChanges = useTableSearchParams({
query: router.query,
pathname: router.pathname,
replace: router.replace,
// or
push: router.push,
});

const table = useReactTable({
// Set state and onChanges
…stateAndOnChanges,
data,
columns,
getCoreRowModel: getCoreRowModel(),
getFilteredRowModel: getFilteredRowModel(),
getSortedRowModel: getSortedRowModel(),
// … other options…

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

جدول TanStack در React

در اینجا یک مقدمه سریع برای ساخت جداول با TanStack Table در React آورده شده است.

TanStack Table ارائه می دهد useReactTable قلاب، که داده ها و تعاریف ستون را می گیرد. وضعیت جدول و کنترل کننده هایی را برمی گرداند که می توانید از آنها برای رندر جدول استفاده کنید.

import {
createColumnHelper,
flexRender,
getCoreRowModel,
useReactTable,
} from “@tanstack/react-table”;

type User = { id: string; name: string };

// Sample data
const data: User[] = [
{ id: “1”, name: “John” },
{ id: “2”, name: “Sara” },
];

// Column definitions
const columnHelper = createColumnHelper<User>();
const columns = [
columnHelper.accessor(“id”, {}),
columnHelper.accessor(“name”, {}),
];

export default function UserTable() {
// Create table
const table = useReactTable({
data,
columns,
getCoreRowModel: getCoreRowModel(),
});

return (
<div>
<table>
<thead>
<tr>
{table.getFlatHeaders().map((header) => (
<th key={header.id}>
{flexRender(
header.column.columnDef.header,
header.getContext(),
)}
th>
))}
tr>
thead>
<tbody>
{/* Render table rows */}
{table.getRowModel().rows.map((row) => (
<tr key={row.id}>
{row.getAllCells().map((cell) => (
<td key={cell.id}>
{flexRender(cell.column.columnDef.cell, cell.getContext())}
td>
))}
tr>
))}
tbody>
table>
div>
);
}

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

در اینجا جدول حاصل آمده است:

در مرحله بعد، من یک ویژگی جستجو را برای این جدول اجرا کردم، همانطور که در زیر نشان داده شده است.

import {
// …
+ getFilteredRowModel,
} from “@tanstack/react-table”;

// …

export default function UserTable() {
const table = useReactTable({
data,
columns,
getCoreRowModel: getCoreRowModel(),
+ getFilteredRowModel: getFilteredRowModel(),
});

return (
<div>
+ <input
+ placeholder=”Search…”
+ value={table.getState().globalFilter}
+ onChange={(e) => table.setGlobalFilter(e.target.value)}
+ />
<table>

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

جدول اکنون از عملکرد جستجوی اولیه پشتیبانی می کند:

اینجا، getCoreRowModel و getFilteredRowModel توابعی هستند که ویژگی های جدول مختلفی به نام RowModels را پیاده سازی می کنند. در TanStack Table، می توانید از RowModel های داخلی مانند استفاده کنید getFilteredRowModel، یا RowModel های سفارشی ایجاد کنید تا عملکردها را گسترش دهید، مانند افزودن قابلیت های جستجو یا مرتب سازی به جدول خود.

معرفی کردن tanstack-table-search-params

tanstack-table-search-params همگام سازی وضعیت جدول TanStack با پارامترهای URL را ساده می کند. به عنوان مثال، در پروژه Next.js Pages Router، فقط باید:

واردات و تماس useTableSearchParams، عبور از useRouter شی
مقدار برگشتی قلاب را به useReactTable.

+ import { useRouter } from “next/router”;
+ import { useTableSearchParams } from “tanstack-table-search-params”;

// …

export default function UserTable() {
+ const router = useRouter();
+ const stateAndOnChanges = useTableSearchParams(router);
const table = useReactTable({
+ …stateAndOnChanges,
// …

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نتیجه:

چگونه کار می کند

برای توضیح چگونگی tanstack-table-search-params وضعیت جدول TanStack را با پارامترهای URL همگام می‌کند، ما کد بالا را تغییر می‌دهیم تا فقط ویژگی‌های لازم را منتقل کند، به جای اینکه کل آن را ارسال کنیم. router شی و stateAndOnChanges شی

export default function UserTable() {
const { query, pathname, replace} = useRouter();
const stateAndOnChanges = useTableSearchParams({
query: router.query,
pathname: router.pathname,
replace: router.replace,
});
const table = useReactTable({
state: {
globalFilter: stateAndOnChanges.state.globalFilter,
},
onGlobalFilterChange: stateAndOnChanges.onGlobalFilterChange,
// …

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

دلیل عبور state.globalFilter و onGlobalFilterChange به useReactTable پیکربندی تنظیمات برای مدیریت وضعیت جدول TanStack در خارج از useReactTable.

https://tanstack.com/table/latest/docs/guide/global-filtering#global-filter-state

همانطور که در کد بالا نشان داده شده است، useTableSearchParams موارد زیر را می گیرد:

query: وضعیت React برای پارامترهای URL

pathname: مسیر URL فعلی

replace (یا push): تابعی برای جایگزینی (یا فشار دادن) URL

https://github.com/taro-28/tanstack-table-search-params/blob/main/packages/tanstack-table-search-params/src/index.ts#L123-L151

و برمی گرداند:

state.globalFilter
onGlobalFilterChange

https://github.com/taro-28/tanstack-table-search-params/blob/main/packages/tanstack-table-search-params/src/index.ts#L23-L44

همانطور که از آرگومان ها و مقادیر بازگشتی می توانید تصور کنید، این قلاب از نظر عملکرد بسیار ساده است.

اول، state رمزگشایی می کند query در جدول TanStack زیر TableState تایپ کرده و آن را برمی گرداند:

بعد، onGlobalFilterChange به سادگی تابعی را برمی گرداند که هر قسمت از وضعیت جدول TanStack را در پارامترهای URL رمزگذاری کرده و اجرا می کند. replace.

هر دو فرآیند ایجاد state و onGlobalFilterChange صرفاً تبدیل هستند (شی → شی، تابع → تابع)، و هیچ یک از آنها حالت داخلی ندارند. (تنها استثنا برای debouncing است که بعداً مورد بحث قرار خواهد گرفت، جایی که حالت داخلی برای اهداف debounce استفاده می شود.)

ایالات جدول TanStack پشتیبانی می شود

در حال حاضر، کتابخانه از چهار حالت جدول TanStack زیر پشتیبانی می کند و برنامه هایی برای گسترش پشتیبانی در آینده دارد:

globalFilter
sorting
pagination
columnFilters

روترهای پشتیبانی شده

همانطور که در چگونه کار می کند، tanstack-table-search-params به سادگی حالت React پارامترهای URL را به وضعیت TanStack Table تبدیل می کند. این بدان معناست که باید (احتمالا) با هر روتری که به شما امکان می دهد پارامترهای URL را به عنوان وضعیت React بازیابی کنید، کار کند.

نمونه هایی برای سه روتر زیر موجود است. با خیال راحت آنها را بررسی کنید:

گزینه های سفارشی سازی اضافی

با tanstack-table-search-params، می توانید نام پارامترهای URL و فرمت های رمزگذاری و غیره را سفارشی کنید.

نام پارامترهای URL

به طور پیش‌فرض، نام پارامترهای URL با نام‌های موجود مطابقت دارد TableState نوع، مانند globalFilter یا sorting.

برای تغییر نام پارامترهای URL، از paramNames گزینه به عنوان آرگومان دوم useTableSearchParams.

const stateAndOnChanges = useTableSearchParams(router, {
paramNames: {
// Change the URL parameter name
globalFilter: “search”,
},
});

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

اگر می خواهید یک پیشوند یا پسوند به نام پارامترها اضافه کنید، می توانید یک تابع را ارسال کنید.

const stateAndOnChanges = useTableSearchParams(router, {
paramNames: {
// Add a prefix to the URL parameter name
globalFilter: (defaultName) => `userTable-${defaultName}`,
},
});

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

فرمت های رمزگذاری

به طور پیش فرض، فرمت رمزگذاری مقادیر پارامتر URL یک فرمت ساده است، همانطور که در زیر نشان داده شده است:

ارزش دولتی
پارامترهای URL مثال

جستجوی جهانی
?globalFilter=John

مرتب سازی
?sorting=name.desc

صفحه بندی
?pageIndex=2&pageSize=20

برای تغییر فرمت رمزگذاری، می توانید سفارشی را تعیین کنید encoders و decoders در استدلال دوم از useTableSearchParams.

const stateAndOnChanges = useTableSearchParams(router, {
encoders: {
// Change encoding format to use JSON.stringify
globalFilter: (globalFilter) => ({
globalFilter: JSON.stringify(globalFilter),
}),
},
decoders: {
globalFilter: (query) =>
query[“globalFilter”] ? JSON.parse(query[“globalFilter”])
: (query[“globalFilter”] ?? “”),
},
});

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

همچنین می توانید فرمت رمزگذاری و نام پارامترها را تغییر دهید.

const stateAndOnChanges = useTableSearchParams(router, {
encoders: {
sorting: (sorting) => ({
// Change encoding format to JSON.stringify and rename parameter to my-sorting
“my-sorting”: JSON.stringify(sorting),
}),
},
decoders: {
sorting: (query) =>
query[“my-sorting”] ? JSON.parse(query[“my-sorting”])
: query[“my-sorting”],
},
});

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

انحراف

می‌توانید همگام‌سازی حالت را با پارامترهای URL لغو کنید.

const stateAndOnChanges = useTableSearchParams(router, {
debounceMilliseconds: 500,
});

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

همچنین می‌توان تنها حالت‌های خاص جدول TanStack را بازگرداند.

const stateAndOnChanges = useTableSearchParams(router, {
debounceMilliseconds: {
// Debounce synchronization of globalFilter with URL parameters by 0.5 seconds
globalFilter: 500,
},
});

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

مقادیر پیش فرض

وقتی پارامترهای URL وجود ندارند، می‌توانید مقادیر پیش‌فرض را برای وضعیت‌های جدول TanStack تعیین کنید.

به عنوان مثال، بدون تنظیم یک مقدار پیش فرض برای مرتب سازی، state.sorting مقدار (شرایط مرتب سازی) و پارامتر URL مربوطه به صورت زیر عمل می کنند:

state.sorting ارزش
پارامتر URL

(توجه: createdAt نام ستون است.)

در مقابل، اگر ترتیب مرتب‌سازی پیش‌فرض را مطابق شکل زیر روی نزولی تنظیم کنید:

const stateAndOnChanges = useTableSearchParams(router, {
defaultValues: {
sorting: [{ id: “createdAt”, desc: true }],
},
});

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

را state.sorting مقدار و پارامتر URL مربوطه به صورت زیر عمل می کند:

state.sorting ارزش
پارامتر URL

در نتیجه گیری

این کتابخانه از کار من سرچشمه گرفته است، جایی که من به یک راه ساده برای همگام سازی حالت های جدول TanStack با پارامترهای URL نیاز داشتم.

تا کنون، من تمام ویژگی هایی را که شخصاً به آن نیاز داشتم، پیاده سازی کرده ام. در حرکت رو به جلو، من قصد دارم با پشتیبانی از وضعیت های TanStack Table بیشتر و گسترش گزینه های سفارشی سازی، کامل بودن آن را افزایش دهم.

ضمنا این اولین بار است که یکی از بسته های خودم را در npm منتشر می کنم. یادگیری نحوه انتشار در npm و کشف راحتی ابزارهایی مانند tsup یک تجربه عالی بود.

اگر شما آن را امتحان کنید، خوشحال می شوم! (و من خوشحال تر می شوم اگر مخزن را ستاره دار کنید!)

React Hook برای همگام سازی وضعیت TanStack Table با پارامترهای جستجوی URL.

React Hook برای همگام سازی وضعیت TanStack Table با پارامترهای جستجوی URL.

tanstack-table-search-params.mp4

🚀 شروع سریع

ابتدا بسته را نصب کنید.

npm i tanstack-table-search-params

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

به عنوان مثال، اگر از Next.js (مسیریاب صفحات) استفاده می کنید، می توانید از هوک به این صورت استفاده کنید.

import { useReactTable } from “tanstack-table”;
import { useRouter } from “next/router”;
import { useTableSearchParams } from “tanstack-table-search-params”;
const router = useRouter();

// Get state and onChanges
const stateAndOnChanges = useTableSearchParams({
query: router.query,
pathname: router.pathname,
replace: router.replace,
// or
push: router.push,
});

const table = useReactTable({
// Set state and onChanges
…stateAndOnChanges,
data,
columns,
getCoreRowModel: getCoreRowModel(),
getFilteredRowModel: getFilteredRowModel(),
getSortedRowModel: getSortedRowModel(),
// … other options…

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

npm i tanstack-table-search-params

import { useReactTable } from "tanstack-table";
import { useRouter } from "next/router";
import { useTableSearchParams } from "tanstack-table-search-params";
const router = useRouter();

// Get state and onChanges
const stateAndOnChanges = useTableSearchParams({
  query: router.query,
  pathname: router.pathname,
  replace: router.replace,
  // or
  push: router.push,
});

const table = useReactTable({
  // Set state and onChanges
  ...stateAndOnChanges,
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  getSortedRowModel: getSortedRowModel(),
  // ... other options

import {
  createColumnHelper,
  flexRender,
  getCoreRowModel,
  useReactTable,
} from "@tanstack/react-table";

type User = { id: string; name: string };

// Sample data
const data: User[] = [
  { id: "1", name: "John" },
  { id: "2", name: "Sara" },
];

// Column definitions
const columnHelper = createColumnHelper<User>();
const columns = [
  columnHelper.accessor("id", {}),
  columnHelper.accessor("name", {}),
];

export default function UserTable() {
  // Create table
  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
  });

  return (
    <div>
      <table>
        <thead>
          <tr>
            {table.getFlatHeaders().map((header) => (
              <th key={header.id}>
                {flexRender(
                  header.column.columnDef.header,
                  header.getContext(),
                )}
              th>
            ))}
          tr>
        thead>
        <tbody>
          {/* Render table rows */}
          {table.getRowModel().rows.map((row) => (
            <tr key={row.id}>
              {row.getAllCells().map((cell) => (
                <td key={cell.id}>
                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
                td>
              ))}
            tr>
          ))}
        tbody>
      table>
    div>
  );
}

import {
  // ...
+ getFilteredRowModel,
} from "@tanstack/react-table";

// ...

export default function UserTable() {
  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
+   getFilteredRowModel: getFilteredRowModel(),
  });

  return (
    <div>
+     <input
+       placeholder="Search..."
+       value={table.getState().globalFilter}
+       onChange={(e) => table.setGlobalFilter(e.target.value)}
+     />
      <table>

+ import { useRouter } from "next/router";
+ import { useTableSearchParams } from "tanstack-table-search-params";

// ...

export default function UserTable() {
+ const router = useRouter();
+ const stateAndOnChanges = useTableSearchParams(router);
  const table = useReactTable({
+   ...stateAndOnChanges,
    // ...

export default function UserTable() {
  const { query, pathname, replace} = useRouter();
  const stateAndOnChanges = useTableSearchParams({
    query: router.query,
    pathname: router.pathname,
    replace: router.replace,
  });
  const table = useReactTable({
    state: {
        globalFilter: stateAndOnChanges.state.globalFilter,
    },
    onGlobalFilterChange: stateAndOnChanges.onGlobalFilterChange,
    // ...

const stateAndOnChanges = useTableSearchParams(router, {
  paramNames: {
    // Change the URL parameter name
    globalFilter: "search",
  },
});

const stateAndOnChanges = useTableSearchParams(router, {
  paramNames: {
    // Add a prefix to the URL parameter name
    globalFilter: (defaultName) => `userTable-${defaultName}`,
  },
});

const stateAndOnChanges = useTableSearchParams(router, {
  encoders: {
    // Change encoding format to use JSON.stringify
    globalFilter: (globalFilter) => ({
      globalFilter: JSON.stringify(globalFilter),
    }),
  },
  decoders: {
    globalFilter: (query) =>
      query["globalFilter"]
        ? JSON.parse(query["globalFilter"])
        : (query["globalFilter"] ?? ""),
  },
});

const stateAndOnChanges = useTableSearchParams(router, {
  encoders: {
    sorting: (sorting) => ({
      // Change encoding format to JSON.stringify and rename parameter to my-sorting
      "my-sorting": JSON.stringify(sorting),
    }),
  },
  decoders: {
    sorting: (query) =>
      query["my-sorting"]
        ? JSON.parse(query["my-sorting"])
        : query["my-sorting"],
  },
});

const stateAndOnChanges = useTableSearchParams(router, {
  debounceMilliseconds: 500,
});

const stateAndOnChanges = useTableSearchParams(router, {
  debounceMilliseconds: {
    // Debounce synchronization of globalFilter with URL parameters by 0.5 seconds
    globalFilter: 500,
  },
});

const stateAndOnChanges = useTableSearchParams(router, {
  defaultValues: {
    sorting: [{ id: "createdAt", desc: true }],
  },
});

npm i tanstack-table-search-params

import { useReactTable } from "tanstack-table";
import { useRouter } from "next/router";
import { useTableSearchParams } from "tanstack-table-search-params";
const router = useRouter();

// Get state and onChanges
const stateAndOnChanges = useTableSearchParams({
  query: router.query,
  pathname: router.pathname,
  replace: router.replace,
  // or
  push: router.push,
});

const table = useReactTable({
  // Set state and onChanges
  ...stateAndOnChanges,
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  getSortedRowModel: getSortedRowModel(),
  // ... other options