---
url: /components/audit-timeline.md
---
# AuditTimeline 审计时间线

面向操作审计的时间线：操作者头像色按名字稳定取色，时间放轴对侧，字段级 diff 可展开查看变更前后值。

规则要点：

* 操作者名依次取 `operator`、`user`，都没有时显示 `系统`；同名操作者永远得到同一节点色；
* 仅当 `expandable` 为真且该条 `diff` 非空时才显示展开按钮，按钮文案为展开变更（条数）；
* `before` 为 undefined 或空串时显示（空），适合新建类记录（无变更前值）；
* 展开键为 `item.id`（缺省用下标），因此受控/非受控都建议给每条记录配稳定 `id`。

## 基础用法

## 受控展开

传 `expanded-items`（可配 `v-model:expanded-items`）即为受控模式，展开状态交给外部，便于默认展开某条或跨组件联动；未传时组件内部维护展开状态。本例默认展开 `a1`，其中备注字段的 `before` 为空串，渲染为（空）。

`a2` 没有 `diff`（不显示按钮），`a3` 没有 `operator / user`（显示为系统）。无论受控与否，每次切换都会 emit `expand-change`，携带展开键数组。

## 关闭展开

`expandable: false` 隐藏全部展开按钮，diff 内容不再可见，时间线退化为纯流水。

## 自定义格式化

`formatTime` 与 `formatDiffValue` 分别接管时间与 diff 值的展示，例如时间戳转本地格式、数值千分位。

## 常见问题

* 展开按钮不显示：确认 `expandable` 未被关闭，且该条 `diff` 是非空数组；
* 受控模式下点击无反应：需要监听 `update:expandedItems`（或用 `v-model:expanded-items`）并回写，组件不会修改外部数组；
* 记录很多时建议在组件外层自行分页或虚拟滚动，组件只负责渲染传入的 `items`；
* 展开状态以 `id` 为键，列表重排或追加记录时已展开项不会错位，因此务必保证 `id` 稳定唯一。

## API

本组件无插槽与实例方法，纯展示。