noob-components/.trellis/spec/plugs-composables/use-list-table.md

useListTable

List/table management composable with pagination, search, and Element Plus integration.

Purpose

Manages paginated table data with reactive search/filter parameters, automatic query on parameter changes, and column configuration support.

Signature

export function useListTable(options: Options): {
  rows: Record<string, any>;
  example: Record<string, any>;
  setRows: (resp?: Rows) => void;
  setExample: (params: Record<string, any>) => void;
  query: () => Promise<void>;
}

Options Interface

interface Options {
  query: (example: any) => Promise<PageResponse<any> | Record<string, any>[] | undefined>;
  initialPage?: number;
  initialPageSize?: number;
  initExample?: Record<string, any>;
  disableAutoQuery?: boolean;
  deep?: boolean;
}

Return Value

Property	Type	Description
rows	Reactive Record<string, any>	Table data (array or PageResponse with total)
example	Reactive Record<string, any>	Query parameters including page and size
setRows	(resp?) => void	Manually set table rows
setExample	(params) => void	Reset and set query parameters
query	() => Promise<void>	Manually trigger data fetch

TableColumn Interface

export interface TableColumn {
  code: string;
  name?: string;
  i18n?: string;
  type?: string;
  width?: string | number;
  fixed?: boolean | "left" | "right";
  align?: "left" | "center" | "right";
  slot?: boolean;
  dict?: string;
  timestamp?: boolean;
  filesize?: boolean;
  [others: string]: any;
}

Usage Pattern

// Example: plugs/composables/useListTable.ts
import { useListTable } from "plugs/composables";

const { rows, example, setExample, query } = useListTable({
  query: fetchUserList,
  initialPage: 1,
  initialPageSize: 10,
  initExample: { status: "active" },
});

// Modify query params and refetch
setExample({ page: 1, name: "john" });

// Manual query
await query();

Key Implementation Details

1. Pagination: Uses page and size in example object
2. Deep reactive: When deep: true, uses ref() instead of shallowRef() for rows
3. Auto-query: Uses watchEffect to auto-refetch when example changes (unless disableAutoQuery: true)
4. Row assignment: setRows handles both array and PageResponse formats
5. PageParams cleanup: When response has no total, pagination params are removed from example

Dependencies

• @vueuse/core - toReactive
• plugs/element - showMessage
• vue3-i18n - useI18n
• noob-mengyxu/utils - clearAndAssign, deepCopy

Anti-patterns

• Do not manually mutate rows directly; use setRows()
• Avoid mixing array and PageResponse formats in same table