# useTableRowStatus

## 使用方法

返回一个 `TablePlugin`，在表格最前面加一列窄列，用来标示每一行的状态。语义状态返回 `{status, label}`，只接受 success、warning、error 三个值：图标和色调由当前主题决定。自定义标记返回 `{color, icon?, label}`：`color` 只决定颜色，不给 `icon` 就画一个固定的 8px 圆点，给了 `icon` 就画你指定的那个图标。图标名仍然沿用 Icon 的颜色映射；用原始 CSS 颜色的自定义图标，完全按你给的颜色画。`label` 是必填的：它既做无障碍名称，也做悬浮提示；返回 `null` 表示这一行不放标记。列表头视觉上是空的，但对读屏软件有一个本地化的名字。`getStatus` 里如果要读响应式状态，把它放进 getter 里；插件每次渲染都会调用它。

```ts
import { useTableRowStatus } from '@astryx-vue/core/Table'
```

## 示例

### useTableRowStatus —— 行状态

行首的标记可以是主题里的语义图标（成功、警告、错误），也可以是一个自定义颜色的小圆点。label 既是无障碍名称，也是悬浮提示。

```vue
<script setup lang="ts">
import type { TableColumn, TableRowStatus } from '@astryx-vue/core/Table'
import { proportional, Table, useTableRowStatus } from '@astryx-vue/core/Table'

interface Check extends Record<string, unknown> {
  id: string
  name: string
  detail: string
  state: 'success' | 'warning' | 'error' | 'neutral'
}

const checks: Check[] = [
  { id: '1', name: 'Payments', detail: 'Settled', state: 'success' },
  { id: '2', name: 'Inventory', detail: 'Low stock', state: 'warning' },
  { id: '3', name: 'Mail', detail: 'Bounced', state: 'error' },
  { id: '4', name: 'Notes', detail: 'No signal', state: 'neutral' },
]

const columns: TableColumn<Check>[] = [
  { key: 'name', header: 'Service', width: proportional(1) },
  { key: 'detail', header: 'Detail', width: proportional(1) },
]

function statusFor(check: Check): TableRowStatus | null {
  if (check.state === 'neutral')
    return { color: 'gray', label: 'No signal' }
  if (check.state === 'success')
    return { status: 'success', label: 'Settled' }
  if (check.state === 'warning')
    return { status: 'warning', label: 'Low stock' }
  return { status: 'error', label: 'Bounced' }
}

const status = useTableRowStatus<Check>({ getStatus: statusFor })
</script>

<template>
  <Table
    :data="checks"
    :columns="columns"
    id-key="id"
    :plugins="{ status }"
  />
</template>
```

## 属性

配置对象是 `MaybeRefOrGetter`：传一个 getter 或 ref，插件才会跟着最新值走。

## 参数

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `getStatus` | `(item: T) => TableRowStatus \| null` | — | 返回语义状态或自定义标记。`{status, label}` 只认 success、error、warning 三个值，图标和色调从当前主题取。`{color, icon?, label}` 是自定义标记这条路：颜色只负责上色，不给图标就画 8px 圆点，给了图标就画你指定的那个。颜色名就算叫 success、error、warning，不给图标也还是圆点。可用的图标名：close、chevronDown、chevronLeft、chevronRight、chevronsLeft、chevronsRight、check、success、error、warning、info、calendar、clock、externalLink、menu、moreHorizontal、search、upload、arrowUp、arrowDown、arrowsUpDown、funnel、eyeSlash、viewColumns、copy、checkDouble、wrench、stop、microphone、image。两种写法互斥，`label` 必填并通过 `role="img"` 读出来，返回 `null` 则这一格是空的。 |

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `status` | `'success' \| 'warning' \| 'error'` | 语义结果。图标和色调都来自主题，和 `color` 互斥。 |
| `color` | `'accent' \| 'success' \| 'error' \| 'warning' \| 'red' \| 'orange' \| 'green' \| 'yellow' \| 'blue' \| 'gray' \| (string & {})` | 标记的颜色。没有 `icon` 时给 8px 圆点上色；直接给 CSS 颜色就按原样用。 |
| `icon` | `string` | 上面列出的图标名；带 `:` 的字符串按 Iconify id 处理。颜色名会沿用 Icon 的颜色映射，原始 CSS 颜色则精确按你给的上色。 |
| `label` | `string` | 标记的无障碍名称，同时作为悬浮提示显示。 |

## 返回值

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `transformColumns` | `(columns: TableColumn[]) => TableColumn[]` | 在最前面加状态列。列键是 `__rowStatus`，宽 `pixel(28)`，不能拖宽。列表头视觉上为空，但带有来自内置文案的本地化名称。 |