快速开始

这一页在任意前端项目里装上查看器，把一张销售明细表交给 <xh-report-viewer>，由取数回调交回数据并显示出来。页面上的示例就是下面这几段代码在运行。

安装

bash

pnpm add @xihan-report/core @xihan-report/runtime @xihan-ui/styles

包	用途
`@xihan-report/core`	报表定义的类型，这一页用它写报表
`@xihan-report/runtime`	`<xh-report-viewer>` 与它的样式
`@xihan-ui/styles`	设计令牌与组件皮肤，表格、图表与参数栏的颜色与间距都取自它

包都是 ESM，用 Vite、webpack 等打包器引入即可。报表定义也可以直接写成 JSON、或从接口取回，这时业务页面只需要 @xihan-report/runtime。

注册元素并引入样式

元素不在 import 时注册，调用 defineReportViewer() 之后页面上才能用 <xh-report-viewer>，重复调用不报错。它会一并注册查看器用到的表格、图表与表单控件，不必再全量注册 UI 的元素。

import type { ReportDataProvider } from '@xihan-report/runtime'
import { defineReportViewer } from '@xihan-report/runtime'
import { rows, schema } from '../reports/quickstart.ts'
import '@xihan-ui/styles/index.css'
import '@xihan-report/runtime/style.css'

defineReportViewer()

写一张报表

报表定义是纯 JSON：datasets 描述数据集有哪些字段，body 是报表的主体。这里的主体是一张明细表：按日期倒序，金额保留两位小数并加千分位，数量与金额两列在末尾出合计。

export const schema: ReportDocument = {
  schemaVersion: 1,
  id: 'orders',
  title: '销售明细',
  datasets: [salesDataset],
  body: {
    type: 'table',
    dataset: 'sales',
    columns: [
      { id: 'orderId', field: 'orderId', width: 150 },
      { id: 'date', field: 'date', width: 120 },
      { id: 'region', field: 'region' },
      { id: 'category', field: 'category' },
      { id: 'quantity', field: 'quantity', align: 'end', summary: { aggregate: 'sum' } },
      {
        id: 'amount',
        field: 'amount',
        align: 'end',
        format: { kind: 'number', decimals: 2, grouping: true },
        summary: { aggregate: 'sum' },
      },
    ],
    sort: [{ field: 'date', direction: 'desc' }],
  },
}

数据集只描述字段，不含数据：

export const salesDataset: DatasetSchema = {
  id: 'sales',
  title: '销售订单',
  fields: [
    { name: 'orderId', type: 'string', title: '订单号' },
    { name: 'date', type: 'date', title: '日期' },
    { name: 'region', type: 'string', title: '区域' },
    { name: 'category', type: 'string', title: '品类' },
    { name: 'channel', type: 'string', title: '渠道' },
    { name: 'quantity', type: 'number', title: '数量' },
    { name: 'amount', type: 'number', title: '金额' },
  ],
}

交回数据

查看器不发网络请求。它按报表定义算出每个数据集的取数请求，交给 dataProvider；回调交回明细行，筛选、排序与汇总都在浏览器里算。这里直接交回内存里的数组：

const dataProvider: ReportDataProvider = async () => ({ kind: 'rows', rows })

请求里带着数据集 id、参数取值、筛选、排序与聚合查询，宿主可以据此查库或在服务端聚合，见与宿主集成。

显示出来

把取数回调与报表定义交给 dataProvider 与 schema 两个属性，查看器随即取数、计算并绘出表格；属性变了会自动重算。复杂数据走属性，不走 attribute。

const viewer = document.createElement('xh-report-viewer')
viewer.dataProvider = dataProvider
viewer.schema = schema
host.append(viewer)

界面语言

查看器与设计器的界面文字缺省是英文。报表给 XiHan.UI 的每种内建语言各出一份语言包，名字是 report 加 UI 语言包的名字：zhCN 对 reportZhCN，jaJP 对 reportJaJP。把同一语言的两份合并后全局设置，所有实例都跟着换。下面以中文为例。这一步要另外安装 @xihan-ui/web-components：

import { reportZhCN } from '@xihan-report/runtime/locale'
import { mergeXhConfig, setXhConfig } from '@xihan-ui/web-components'
import { zhCN } from '@xihan-ui/web-components/locale'

setXhConfig(mergeXhConfig(zhCN, reportZhCN))

下一步

报表结构：数据集、参数与几种主体视图。
看板与卡片：图表、指标与表格卡片排成看板。

快速开始 ​

安装 ​

注册元素并引入样式 ​

写一张报表 ​

交回数据 ​

显示出来 ​

界面语言 ​

下一步 ​