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

AdminForth 的 Dashboard 插件 .

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

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

访问

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

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

代理核准

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

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

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

剪贴板配置形状

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

每个部件都有共同字段:

部件支持矩阵

图表部件类型 :

查询形状

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 用于滚动日期范围。 不为随时间而移动的仪表板设置硬码日期 :

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

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

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,以及选定的集合别名:

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

成本计算示例:

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

运行时结构

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。 。 。 .