# @adminforth/dashboard 中文文档

规范地址：https://npmcn.com/package/%40adminforth/dashboard/

版本：2\.1\.3
npm 元数据更新时间：2026-10-21T12:19:27.068Z
中文译文更新时间：2026-11-09T20:35:34.783Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40adminforth/dashboard
原文对照：https://npmcn.com/package/%40adminforth/dashboard/?lang=original
项目主页：https://adminforth.dev/docs/tutorial/Plugins/dashboard/
源码仓库：https://github.com/devforth/adminforth-dashboard

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.4 MB，137 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：adminforth ^4\.7\.3
- 首次发布：2026-05-28T14:54:14.399Z
- 最新版本发布：2026-10-21T12:19:18.137Z
- 近 30 天下载量：1743（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：54（近 12 个月 54 个）

## 中文简介

行政板插件

## 安装

```sh
npm install @adminforth/dashboard
```

也可以使用：`pnpm add @adminforth/dashboard`、`yarn add @adminforth/dashboard`、`bun add @adminforth/dashboard`

## README

# @adminforth/ dashboard (中文(简体) )

AdminForth 的 Dashboard 插件 .

它增加了可配置的由行政资源支持的仪表板页面。 Dashboard 记录定义组和部件,插件使其在 `/dashboard/:slug`,贡献a **盘子** 侧边栏组,并曝光来自“管理Forth UI”的编辑组和部件的端点.

完整的设置指南 : [https://adminforth.dev/docs/tutorial/Plugins/dashboard/ 页面存档备份,存于互联网档案馆](https://adminforth.dev/docs/tutorial/Plugins/dashboard/)

## 访问

台板取景和编辑仅限于 `superadmin` 默认。 设定 `editRoles` 允许其他角色编辑仪表板,以及 `viewRoles` 让角色查看仪表板而不编辑它们:

```ts
new DashboardPlugin({
  dashboardConfigsResourceId: 'dashboard_configs',
  editRoles: ['superadmin', 'developer'],
  viewRoles: ['manager'],
})
```

## 代理核准

默认情况下,AI代理在更改仪表板设置,组或部件配置,或删除组和部件之前,会向用户请求批准. 设定 `agentEditsRequireApproval: false` 允许它实施这些修改,而不要求:

```ts
new DashboardPlugin({
  dashboardConfigsResourceId: 'dashboard_configs',
  agentEditsRequireApproval: false,
})
```

`editRoles` 仍然适用,而MCP客户端不再收到这些工具的破坏性提示.

## 剪贴板配置形状

```ts
type DashboardConfig = {
  version: number
  groups: {
    id: string
    label: string
    order: number
  }[]
  widgets: DashboardWidgetConfig[]
}
```

每个部件都有共同字段:

| 外地 | 说明 |
| --- | --- |
| `id` | 错误部件 ID . |
| `group_id` | 组合部件的渲染位置 . |
| `label` | 可选部件标题 . |
| `target` | 部件类型 : `table`, (中文(简体) ), `chart`, (中文(简体) ), `kpi_card`, (中文(简体) ), `pivot_table`,或 `gauge_card`。 。 。 . |
| `order` | 组内的部件顺序 . |
| `variables` | 可选部件变量传递给部件数据加载 。 内部没有变量 `query.calcs`。 。 。 . |
| `size` | 预设宽度 : `small`, (中文(简体) ), `medium`, (中文(简体) ), `large`, (中文(简体) ), `wide`,或 `full`。 。 。 . |
| `width`, (中文(简体) ), `height`, (中文(简体) ), `min_width`, (中文(简体) ), `max_width` | 可选的明确布局限制. 无 `height`,图表,表格和中枢表格高400px,KPI和测量卡符合其内容. |
| `query` | 数据查询定义. |

## 部件支持矩阵

| 部件目标 | 配置字段 | 主要设置 | 数据使用情况 |
| --- | --- | --- | --- |
| `table` | `table` | `pagination`, (中文(简体) ), `page_size`, (中文(简体) ), `columns` | 用途 `query` 以显示生行或集合行. |
| `chart` | `chart` | `type`, (中文(简体) ), `x`, (中文(简体) ), `y`, (中文(简体) ), `label`, (中文(简体) ), `value`, (中文(简体) ), `series`, (中文(简体) ), `buckets`, (中文(简体) ), `color`, (中文(简体) ), `colors` | 使用同样的 `query` 大多数图表类型的形状。 多资源图表的使用 `query.source: steps`; 添加 `query.bucket` 用于共享跨资源的数字桶. |
| `kpi_card` | `card` | `value`, (中文(简体) ), `subtitle`, (中文(简体) ), `comparison`, (中文(简体) ), `sparkline` | 读取第一个返回的查询行. |
| `gauge_card` | `card` | `value`, (中文(简体) ), `target`, (中文(简体) ), `progress`, (中文(简体) ), `color` | 读取第一个返回的查询行. |
| `pivot_table` | `pivot` | `rows`, (中文(简体) ), `columns`, (中文(简体) ), `values` | 使用查询行来构建枢轴表. |

图表部件类型 :

| 图表类型 | 页:1 |
| --- | --- |
| `line` | 用途 `x` 财务报告和审定财务报表 `y`· ; `y` 可能包含多个配置字段. |
| `pie` | 用途 `label` 财务报告和审定财务报表 `value`。 。 。 . |
| `bar` | 用途 `x` 财务报告和审定财务报表 `y`。 。 。 . |
| `stacked_bar` | 用途 `x`, (中文(简体) ), `y`,以及 `series`。 。 。 . |
| `funnel` | 用途 `label`, (中文(简体) ), `value`选择 `colors`。数据来自同一数据 `query` 形状与其他图表一样. |
| `histogram` | 用途 `x`, (中文(简体) ), `y`选择 `buckets`。当前直方图运行时间支持仅为单资源:为数字字段提供生行并允许 `chart.buckets` 生成前端的计数。 多资源桶分配,使用 `stacked_bar` 与 `query.source: steps` 财务报告和审定财务报表 `query.bucket`。 。 。 . |

## 查询形状

```ts
type QueryConfig = {
  source?: 'resource'
  resource: string
  select?: Array<
    | { field: string; as?: string; grain?: 'day' | 'week' | 'month' | 'year' }
    | { agg: 'sum' | 'count' | 'count_distinct' | 'avg' | 'min' | 'max' | 'median'; field?: string; as: string; filters?: DashboardFilter | DashboardFilter[] }
    | { calc: string; as: string }
  >
  filters?: DashboardFilter | DashboardFilter[]
  group_by?: Array<string | { field: string; as?: string; grain?: 'day' | 'week' | 'month' | 'year'; timezone?: string }>
  order_by?: Array<{ field: string; direction?: 'asc' | 'desc' }>
  limit?: number
  offset?: number
  bucket?: { field: string; buckets: Array<{ label: string; min?: number; max?: number }> }
  calcs?: Array<{ calc: string; as: string }>
  formatting?: Record<string, JsonValue>
} | {
  source: 'steps'
  steps: Array<{
    name: string
    resource: string
    select: Array<{ agg: 'sum' | 'count' | 'count_distinct' | 'avg' | 'min' | 'max' | 'median'; field?: string; as: string; filters?: DashboardFilter | DashboardFilter[] }>
    filters?: DashboardFilter | DashboardFilter[]
  }>
  calcs?: Array<{ calc: string; as: string }>
  order_by?: Array<{ field: string; direction?: 'asc' | 'desc' }>
  limit?: number
  offset?: number
  formatting?: Record<string, JsonValue>
}

`source: 'steps'` returns one aggregate row per step by default. Each step supports aggregate `select` items plus optional `filters`; it does not support per-step `field` selects, `calc` selects, or `group_by`. Add `query.bucket` when multiple resources need the same numeric buckets, for example a stacked bar distribution by price range.

type DashboardFilter =
  | { and: DashboardFilter[] }
  | { or: DashboardFilter[] }
  | {
      field: string
      eq?: FilterValue
      neq?: FilterValue
      gt?: FilterValue
      gte?: FilterValue
      lt?: FilterValue
      lte?: FilterValue
      in?: FilterValue[]
      not_in?: FilterValue[]
      like?: FilterValue
      ilike?: FilterValue
    }

type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue }
type RelativeDateValue = { now: true } | { now_minus: `${number}${'h' | 'd' | 'w' | 'mo' | 'y'}` }
type FilterValue = JsonValue | RelativeDateValue
```

使用 `filters` 用于滚动日期范围。 不为随时间而移动的仪表板设置硬码日期 :

```yaml
query:
  resource: orders
  filters:
    and:
      - field: created_at
        gte:
          now_minus: 30d
      - field: created_at
        lt:
          now: true
```

使用多种资源查询 `source: steps`。每个步骤使用 `select`即使它只有一个总和:

```yaml
target: chart
label: Average price by database
chart:
  type: bar
  title: Average price by database
  x:
    field: name
  y:
    field: value
query:
  source: steps
  steps:
    - name: SQLite
      resource: cars_sl
      select:
        - agg: avg
          field: price
          as: value
    - name: MySQL
      resource: cars_mysql
      select:
        - agg: avg
          field: price
          as: value
```

多资源查询的使用 `query.bucket`。仪表板每桶运行一步,返回一行 `label`, (中文(简体) ), `name`, (中文(简体) ), `resource`,以及选定的集合别名:

```yaml
target: chart
label: Cars by price range and database
chart:
  type: stacked_bar
  title: Cars by price range and database
  x:
    field: label
  y:
    field: count
  series:
    field: name
query:
  source: steps
  bucket:
    field: price
    buckets:
      - label: Budget
        max: 3500
      - label: Mid-range
        min: 3500
        max: 7000
      - label: Premium
        min: 7000
  steps:
    - name: SQLite
      resource: cars_sl
      select:
        - agg: count
          as: count
    - name: MySQL
      resource: cars_mysql
      select:
        - agg: count
          as: count
```

成本计算示例:

```yaml
target: chart
label: Model costs
chart:
  type: stacked_bar
  title: GPT-5.4 costs by day
  x:
    field: day
  y:
    - field: input_cost
    - field: output_cost
    - field: cached_cost
query:
  resource: model_usage
  filters:
    and:
      - field: model
        eq: gpt-5.4
      - field: used_at
        gte:
          now_minus: 7d
      - field: used_at
        lt:
          now: true
  select:
    - field: used_at
      as: day
      grain: day
    - agg: sum
      field: input_tokens
      as: input_tokens
    - agg: sum
      field: output_tokens
      as: output_tokens
    - agg: sum
      field: cached_tokens
      as: cached_tokens
  group_by:
    - field: used_at
      as: day
      grain: day
  calcs:
    - calc: input_tokens / 1000000 * 2.5
      as: input_cost
    - calc: output_tokens / 1000000 * 15
      as: output_cost
    - calc: cached_tokens / 1000000 * 0.25
      as: cached_cost
```

## 运行时结构

```text
DashboardPage.vue
└── DashboardRuntime.vue
    └── DashboardGroup.vue
        └── WidgetShell.vue
            └── WidgetRenderer.vue
                ├── TableWidget.vue
                ├── ChartWidget.vue
                ├── KpiCardWidget.vue
                ├── PivotTableWidget.vue
                └── GaugeCardWidget.vue
```

`DashboardPage.vue` 用弹子装入仪表板, `DashboardRuntime.vue` 制作命令组, `WidgetShell.vue` 提供部件框架和编辑器动作,以及 `WidgetRenderer.vue` 选择部件组件 `target`。 。 。 .

## 常见问题

### @adminforth/dashboard 是什么？

行政板插件

### 如何安装 @adminforth/dashboard？

在项目目录运行 npm install @adminforth/dashboard，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：adminforth（^4\.7\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @adminforth/dashboard 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @adminforth/dashboard 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @adminforth/dashboard 可以商用吗？

@adminforth/dashboard 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @adminforth/dashboard 的下载量有多少？

根据 npm 官方下载统计，@adminforth/dashboard 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,743 次，日均约 58 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @adminforth/dashboard 还在维护吗？

最新版本 2\.1\.3 发布于 2026/10/21（19 天前）；至今共发布 54 个版本，其中过去 12 个月发布了 54 个；首次发布于 2026/05/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。