@a-luna/svelte-simple-tables 中文文档教程

Question

svelte-simple-tables

• Features
• Examples
• Installation
• Usage
• data
• columnSettings
• tableSettings
• Themes
• CSS Custom Properties

Features

• Create sortable, paginated tables that follow WAI-ARIA guidelines.
• Columns dynamically resize to accommodate all visible content.
• Automatically responsive. Tables become horizontally scrollable without breaking page layout.
• Four color themes provided. Users can adjust every detail of existing themes or create new themes with CSS custom properties.

Examples

• svelte-simple-tables docs site
• Coming Soon: CSS Theme Editor

Installation

纱线

yarn add -D @a-luna/svelte-simple-tables

npm

npm install -D @a-luna/svelte-simple-tables

pnpm

pnpm install -D @a-luna/svelte-simple-tables

Usage

<script lang="ts">
    import SimpleTable from '@a-luna/svelte-simple-tables';
    import type { TableSettings } from '@a-luna/svelte-simple-tables/types';
    import { columnSettings } from './columnSettings';
    import { data } from './data';

    interface VaxData {
        personId: number;
        name: string;
        age: number;
        birthdate: Date;
        vaccinated: boolean;
    }

    const tableSettings: TableSettings = {
        tableId: 'vax-status-table',
        showHeader: true,
        header: 'Vax Status',
        showSortDescription: true,
        sortBy: 'age',
        sortDir: 'desc',
        tableWrapper: true,
        paginated: true,
        pageRangeFormat: 'compact',
        pageNavFormat: 'compact',
        pageSize: 10,
        pageSizeOptions: [5, 10, 15, 20, 25],
        themeName: 'darker',
        rowType: 'vax records',
    };
</script>

<SimpleTable {data} {columnSettings} {tableSettings} />

SimpleTable需要三个道具：data、columnSettings 和 tableSettings：

Name	Type	Description
data	T[]	Array of T objects (T is a generic type) . Each object will be rendered as a row in the table.
columnSettings	ColumnSettings<T>[]	Array of ColumnSettings<T> objects (T is the same generic type from data). Each ColumnSettings<T> object specifies which property to display, the column header text, etc.
tableSettings	TableSettings	Configuration object for sizing, layout, pagination, and other overall table settings.

data

您必须定义一个 type 或 interface< /code> 用于表格数据（本例中为 VaxData）。 这成为 data 和 columnSettings 道具使用的通用类型 T。

？？？ 帮助我理解 为什么需要在data 数组中指定项目的类型？ SimpleTable 使用 一个实验性的 svelte 特性，它可以将泛型类型与组件属性一起使用。 这会在您的 IDE 中启用高级错误检查和自动完成功能。

表的数据 通常是从对 API 请求或数据库查询的响应中提供的。 在此示例中，data 是从导出 VaxData 对象列表的打字稿文件 (data.ts) 导入的

// data.ts
// contains 21 items, only showing first and last item for brevity
export const data: VaxData[] = [
    {
        personId: 1,
        name: 'Alice',
        age: 11,
        birthdate: new Date(2010, 7, 12),
        vaccinated: true,
    },
    ...{
        personId: 21,
        name: 'Ulysses',
        age: 85,
        birthdate: new Date(1936, 2, 12),
        vaccinated: true,
    },
];

columnSettings

： code>data 您希望在表格中显示，下一步是确定哪些 VaxData 属性（name、age等）应显示在每一列中。 这是通过 columnSettings 属性实现的，它是 ColumnSettings 对象的列表。 ColumnSettings 的 API 如下所示：

Property	Type	Required	Default	Description
propName	string	✅	N/A	The name of the property to display
propType	PropType	✅	N/A	PropType is a string literal with valid values: 'string', 'number', 'boolean' or 'date'. In this example, if propName = 'age' => propType = 'number', or propName = 'birthdate' => propType = 'date'
headerText	string	❌	If the value provided for propName is in snake_case or camelCase format, it is converted to Snake Case or Camel Case, respectively. Otherwise, the value provided for propName is used as the default value.	The text displayed in the column header.
tooltip	string	❌	Same behavior as headerText	Tooltip value to display when mouse hovers over the column header.
sortable	boolean	❌	true	If sortable=True, clicking the column header will re-sort the table using that value. Clicking the same column header again will toggle between ascending/descending order. If sortable=False, clicking the column header will have no effect.
classList	string[]	❌	[]	A list of strings where each string will be added to the classList of each data cell in this column. Useful for utility classes such as Tailwind to control text-alignment, font-weight, etc.
colValue	(obj: T) => string	❌	(obj: T) => obj[propName] (i.e, The value of the object property propName)	A function that accepts an object from data and returns the value that should be displayed in this column. This allows you to customize the way the data is displayed in any way.

您可能想知道 为什么需要为每一列指定propType？ 这是使表格可排序所必需的。 由于无法使用单一算法对数字、文本和日期值进行排序，因此 propType 用于确定适合每种数据类型的排序函数。

让我们看一个为每个 VaxData 属性呈现列的示例：生成上表的 columnSettings 属性

Name	Birthdate	Age	Vax?	ID
Alice	Thu Aug 12 2010	11	✅	1
…	…	…	…	…
Ulysses	Thu Mar 12 1936	85	✅	21

必须包含五个 ColumnSettings对象，并将配置如下：

// columnSettings.ts
import type { ColumnSettings } from '@a-luna/svelte-simple-tables/types';
import type { VaxData } from './data';

export const columnSettings: ColumnSettings<VaxData>[] = [
    {
        propName: 'name',
        propType: 'string',
        tooltip: 'First Name',
        colValue: (data: VaxData): string => `<a href="/person/${data.personId}">${data.name}</a>`,
    },
    {
        propName: 'birthdate',
        propType: 'date',
        colValue: (data: VaxData): string => data.birthdate.toDateString(),
    },
    {
        propName: 'age',
        propType: 'number',
    },
    {
        propName: 'vaccinated',
        propType: 'boolean',
        headerText: 'Vax?',
        tooltip: 'Vaccination Status',
        classList: ['text-center'],
        colValue: (data: VaxData): string => (data.vaccinated ? '✅' : '❌'),
    },
    {
        propName: 'personId',
        propType: 'number',
        headerText: 'ID',
        sortable: false,
    },
];

对于每一列，唯一需要的值是 propName 和 propType（所有其他属性都具有合理的默认值）。 在大多数情况下，colValue 是应用最“有趣”设置的地方，因为它控制列为每个对象显示的值。

例如，第一列配置为将每个对象的 name 属性显示为指向假设页面的链接。 由于 colValue 是一个函数，它接受单个 VaxData 对象并返回一个字符串，我们可以很容易地构造一个包含 VaxData 属性的锚元素对象：

colValue: (data: VaxData): string => `<a href="/person/${data.personId}">${data.name}</a>`;

此字符串将使用 svelte 中可用的特殊 @html 标记呈现，从而产生如上表所示的可点击链接。

birthdate 属性是一个 Date 值，默认情况下只需调用 Date.toString() 方法即可显示（例如，2010 年 8 月 12 日星期四 00:00:00 GMT-0700（太平洋夏令时））。 通过简单地将 colValue 配置为调用 Date.toDateString() 方法，该列将省略时间和时区信息，仅显示日期部分（Thu Aug 12 2010)：

colValue: (data: VaxData): string => data.birthdate.toDateString();

vaccinated 列包含 boolean 值，默认情况下只会显示 'true'/< code>'false' 字符串。 显示更有趣内容的最简单方法是使用三元运算符：

colValue: (data: VaxData): string => (data.vaccinated ? '✅' : '❌');

此列还利用了 classList 属性。 在 Tailwind CSS 中，text-center 是一个实用程序类，用于在 HTML 元素上设置 text-align: center。 这会将 text-center 类添加到该列中的每个数据单元格。

最后，最后一列显示 personId 属性。 sortable 属性设置为 false，使其成为唯一无法通过单击列标题进行排序的列。

♨️ HOT TIP 您可以在 .svelte 文件的

tableSettings

严格来说，最后一个道具 tableSettings 不是必需的。 将呈现如下

：

没有它，我们的表格 同意。 但是，通过自定义 tableSettings 属性，相同的 data 和 columnSettings 可以生成下表：

现在这是一张您可以引以为豪的表格！ 本自述文件开头指定的 tableSettings 对象将产生这些更改。

TableSettings 界面公开了以下配置设置：

Property	Type	Required	Default	Description
tableId	string	❌	Randomly generated ID (e.g., table-79f3e496)	This is the id attribute of the table HTML element
showHeader	boolean	❌	false	Display the  headervalue above the table (#1 in the disgram below)
header	string	❌	'' (empty string)	Table header/caption/title to display above the table
showSortDescription	boolean	❌	false	Display the sort column and sort direction currently applied (#2 in the diagram below)
sortBy	string	❌	null	propName of the column to sort the table by. If not specified, no sorting behavior will be applied when component is loaded. (#3 in the diagram below)
sortDir	SortDirection	❌	'asc'	SortDirection is a string literal type = asc or desc. Determines if the sort behavior is applied in ascending or descending order.
tableWrapper	boolean	❌	false	Display a border around the table (#4 in the diagram below)
themeName	TableTheme	❌	'lighter'	themeNameis a string literal type = 'light' | 'lighter' | 'dark' | 'darker' | 'custom’. You can check out all of the themes in the interactive docs.
clickableRows	boolean	❌.	false	The rowClicked event is raised when any row in the body of the table is clicked. The event contains the row data as an object of type T.
animateSorting	boolean	❌.	false	Changes in row order are reflected as a flip animation when the sort behavior is changed (e.g., by clicking on a column header)
paginated	boolean	❌	false	Enables pagination. If false, all rows are displayed.
pageSize	number	❌	5	(If pagination is enabled) Number of rows to display per page. Must be one of the options in pageSizeOptions.
pageSizeOptions	number[]	❌	[5, 10, 15]	(If pagination is enabled) Array of possible page sizes, user can switch between page sizes at any time.
pageRangeFormat	PageRangeFormat	❌	'auto'	(If pagination is enabled) PageRangeFormat is a string literal type = 'none' | 'compact' | 'verbose' | 'auto'. See interactive docs for examples.
pageNavFormat	PaginationLayout	❌	'auto'	(If pagination is enabled) PaginationLayout is a string literal type = 'compact' | 'full' | 'auto'. See interactive docs for examples.
rowType	string	❌	'rows'	(If pagination is enabled) Since the page range description in verbose mode displays as 'XX-YY of ZZ total rowType' you can customize the term used to dsescribe the tabular data (e.g., '1-10 of 21 patients' or '6-10 of 21 vax records' in our table).

???? LISTEN UP, CHIEF: As explained above, the tableId prop is used as the id attribute of the table HTML element. Therefore, it is very important that you treat this value as a unique identifier, per HTML requirements. If you choose to provide your own value for tableId , it is extremely important that you do not reuse this value for another SimpleTable component, or any HTML element in your project. Bad things will happen, trust me!

Themes

CSS Custom Properties

以下 CSS 自定义属性可以应用于 body 元素（如果您希望整个站点中的所有表格都使用一个统一的主题），也可以单独应用于每个表格。 详细说明和交互式主题编辑器是一个 WIP，将尽快提供：

--sst-font-size
--sst-table-wrapper-border-width
--sst-table-wrapper-border-style
--sst-table-wrapper-padding
--sst-sort-description-font-size
--sst-table-header-font-size
--sst-table-border-radius
--sst-col-header-padding
--sst-col-header-text-weight
--sst-col-header-highlight-text-weight
--sst-body-cell-padding
--sst-button-group-border-radius

--sst-table-wrapper-bg-color
--sst-table-wrapper-border-color

--sst-text-color
--sst-link-text-color
--sst-link-hover-text-color
--sst-table-outer-border-color
--sst-table-header-text-color
--sst-sort-description-text-color
--sst-page-range-description-text-color

--sst-col-header-bg-color
--sst-col-header-text-color
--sst-col-header-vert-border-color
--sst-col-header-horiz-border-color
--sst-col-header-highlight-sort-bg-color
--sst-col-header-highlight-sort-text-color
--sst-col-header-highlight-sort-vert-border-color
--sst-col-header-highlight-sort-horiz-border-color

--sst-body-even-row-bg-color
--sst-body-odd-row-bg-color
--sst-body-inner-vert-border-color
--sst-body-inner-horiz-border-color
--sst-body-highlight-sort-bg-color
--sst-body-highlight-sort-text-color
--sst-body-highlight-sort-border-color

--sst-button-text-color
--sst-button-bg-color
--sst-button-border-color

--sst-button-hover-text-color
--sst-button-hover-bg-color
--sst-button-hover-border-color

--sst-button-active-text-color
--sst-button-active-bg-color
--sst-button-active-border-color

--sst-button-disabled-text-color
--sst-button-disabled-bg-color
--sst-button-disabled-border-color

--sst-button-focus-border-color