图表
@univerjs/preset-sheets-advanced
图表是数据可视化的重要工具,可以帮助用户更直观地理解和分析数据。在 Univer Sheets 中,图表功能提供了多种类型的图表,包括柱状图、折线图、饼图等,用户可以根据需要选择合适的图表类型来展示数据。
预设模式
图表功能被包含在 @univerjs/preset-sheets-advanced
预设中。
安装
@univerjs/preset-sheets-advanced 的 UniverSheetsAdvancedPreset
预设在运行时依赖 UniverSheetsDrawingPreset
预设,请先安装 @univerjs/preset-sheets-drawing。
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
使用
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'
import UniverPresetSheetsAdvancedZhCN from '@univerjs/preset-sheets-advanced/locales/zh-CN'
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'
import UniverPresetSheetsDrawingZhCN from '@univerjs/preset-sheets-drawing/locales/zh-CN'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css'
import '@univerjs/preset-sheets-advanced/lib/index.css'
const { univerAPI } = createUniver({
locale: LocaleType.ZH_CN,
locales: {
[LocaleType.ZH_CN]: mergeLocales(
UniverPresetSheetsCoreZhCN,
UniverPresetSheetsDrawingZhCN,
UniverPresetSheetsAdvancedZhCN,
),
},
presets: [
UniverSheetsCorePreset(),
UniverSheetsDrawingPreset(),
UniverSheetsAdvancedPreset(),
],
})
如果你拥有 Univer 的商业许可证,请参考在客户端使用许可证进行配置。
插件模式
安装
npm install @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
使用
import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart'
import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui'
import SheetsChartUIZhCN from '@univerjs-pro/sheets-chart-ui/locale/zh-CN'
import SheetsChartZhCN from '@univerjs-pro/sheets-chart/locale/zh-CN'
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import '@univerjs-pro/sheets-chart-ui/facade'
import '@univerjs-pro/sheets-chart-ui/lib/index.css'
const univer = new Univer({
locale: LocaleType.ZH_CN,
locales: {
[LocaleType.ZH_CN]: mergeLocales(
SheetsChartZhCN,
SheetsChartUIZhCN,
),
},
})
univer.registerPlugin(UniverSheetsChartPlugin)
univer.registerPlugin(UniverSheetsChartUIPlugin)
如果你拥有 Univer 的商业许可证,请参考在客户端使用许可证进行配置。
枚举
显示枚举
export enum ChartAttributeBits {
Stack = 1 << 30,
PercentStack = 1 << 29 | ChartAttributeBits.Stack,
Horizontal = 1 << 28,
}
export enum ChartTypeBits {
None = 0,
Line = 1 << 1,
Column = 1 << 2,
ColumnStacked = ChartTypeBits.Column | ChartAttributeBits.Stack,
ColumnPercentStacked = ChartTypeBits.Column | ChartAttributeBits.PercentStack,
Bar = 1 << 2 | ChartAttributeBits.Horizontal,
BarStacked = ChartTypeBits.Bar | ChartAttributeBits.Stack,
BarPercentStacked = ChartTypeBits.Bar | ChartAttributeBits.PercentStack,
Pie = 1 << 3,
Doughnut = 1 << 8 | ChartTypeBits.Pie,
Area = 1 << 4,
AreaStacked = ChartTypeBits.Area | ChartAttributeBits.Stack,
AreaPercentStacked = ChartTypeBits.Area | ChartAttributeBits.PercentStack,
Radar = 1 << 5,
Scatter = 1 << 6,
Combination = 1 << 7,
}
Facade API
完整 Facade API 类型定义,请查看 FacadeAPI。
在 Univer Sheets 中,您可以使用 Facade API 来创建、配置和管理图表。Facade API 是一种图表的编程接口,可以帮助您更方便地使用图表功能。
插入图表
FWorksheet.newChart()
方法用于创建一个图表构建器,返回一个 FChartBuilderBase
实例,您可以通过链式调用方法来设置图表的各种属性。
然后调用 build()
生成 IChartBuilderInfo
对象,通过 FWorksheet.insertChart(chartBuildInfo: IChartBuilderInfo)
方法将图表插入到表格中。
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
// 创建一个柱状图,数据源为 A1:D6。
// 开始位置为单元格 B2 的左上角。
// 图表的宽度为 600,高度为 400。
const chartInfo = fWorksheet.newChart()
.setChartType(univerAPI.Enum.ChartType.Column)
.addRange('A1:D6')
.setPosition(1, 1, 0, 0)
.setWidth(600)
.setHeight(400)
.build()
await fWorksheet.insertChart(chartInfo)
以下是 FChartBuilderBase
上的一些成员方法:
方法 | 描述 |
---|---|
addRange | 指定图表数据源范围 |
setPosition | 以 row,col 锚点方式设置图表位置 |
setAbsolutePosition | 以像素方式设置图表位置 |
setChartType | 设置图表类型 |
setWidth | 设置图表宽度 |
setHeight | 设置图标高度 |
setOptions | 设置图表配置项 |
setTransposeRowsAndColumns | 行列转换 |
setTheme | 设置主题 |
setXAxisTitle | 设置X轴标题 |
setYAxisTitle | 设置Y轴标题 |
setRightYAxisTitle | 设置右轴标题 |
setXAxisTextStyle | 设置X轴标题样式 |
setYAxisTextStyle | 设置Y轴标题样式 |
setRightYAxisTextStyle | 设置右轴标题样式 |
setInvalidValueStrategy | 设置空单元格显示方式 |
setAxisPointerStyle | 设置指示线样式 |
setALLSeriesStyle | 设置所有系列样式 |
setSeriesStyle | 设置系列样式 |
build | 生成 builder info,用于插入/更新图表 |
目前我们支持以下的配置项,您可以通过查阅 IChartBuildOptions 来获取对应的配置:
显示配置
export interface IChartBuildOptions {
/**
* @property {string} [title] The title of the chart.
*/
title?: {
/**
* @property {string} [titlePosition] The position of the chart title.
*/
position?: TitlePositionEnum
} & IChartTextStyle
/**
* @property {string} [legend] The legend of the chart.
*/
legend?: {
/**
* @property {string} [legendPosition] The position of the legend.The possible values are 'top', 'bottom', 'left', 'right' & 'hide'.
*/
position?: LegendPositionEnum
/**
* @property {number} [fontSize] The font size of the legend.
*/
fontSize?: number
/**
* @property {string} [color] The font color of the legend.
*/
color?: string
/**
* @property {string} [bold] The font style of the legend.
*/
bold?: boolean
/**
* @property {string} [italic] The font weight of the legend.
*/
italic?: boolean
/**
* @property {SelectModeEnum} [selectMode] The select mode of the legend.The possible values are 'single', 'multiple' & 'close'.
*/
selectMode?: SelectModeEnum
}
/**
* @property {string} [xAxisTitle] The x-axis title of the chart.
* @example
* ```typescript
* chartBuilder.setOptions('xAxisTitle.content', 'xAxis Title text')
* .setOptions('xAxisTitle.font', 1)
* .setOptions('xAxisTitle.fontSize', 12)
* .setOptions('xAxisTitle.fontColor', '#ff0000')
* .build();
* ```
*/
xAxisTitle?: IChartTextStyle
/**
* @property {string} [rightYAxisTitle] The right y-axis title of the chart.
*/
yAxisTitle?: IChartTextStyle
/**
* @property {string} [rightYAxisTitle] The right y-axis title of the chart.
*/
rightYAxisTitle?: IChartTextStyle
xAxis?: IAxisOptions
yAxis?: IAxisOptions
yRightAxis?: IAxisOptions
axisPointer?: {
/**
* @property {string} [indicatorLineType] The line type of the axis pointer.
*/
indicatorLineType?: string
/**
* @property {ChartBorderDashType} [indicatorLineColor] The line color of the axis pointer.The maybe values are 'solid', 'dotted', 'dashed'.
*/
indicatorLineColor?: ChartBorderDashType
/**
* @property {string} [indicatorLabelColor] The line width of the axis pointer.
*/
indicatorLabelColor?: string
/**
* @property {string} [indicatorLabelTextColor] The font color of the axis pointer.
*/
indicatorLabelTextColor?: string
}
allSeriesStyle?: IAllSeriesStyle
seriesStyleMap?: {
[id: string]: ISeriesStyle
}
/**
* @property {string} [area] The area of line/area chart.
*/
area?: {
lineStyle: AreaLineStyle
}
/**
* @property {string} [backgroundColor] The background color of the chart.
*/
backgroundColor?: string
/**
* @property {string} [borderColor] The border color of the chart.
*/
borderColor?: string
/**
* @property {boolean} [gradientFill] Whether to use gradient fill.This property does not work in line charts.
*/
gradientFill?: boolean
/**
* @property {string} [theme] The theme of the chart.
*/
theme?: string
/**
* @property {InvalidValueType} [invalidValueType] The display mode for empty cells.
*/
invalidValueType?: InvalidValueType
}
配置项通过 setOptions 方法来设置,有以下两种方式:
setOptions(optionPath, optionVal)
:setOptions('legend.color', '#ff0000')
setOptions('', IChartBuildOptions)
:setOptions('', { legend: { color: '#ff0000', bold: true } })
创建一个折线图示例
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
// 创建一个折线图
const chartInfo = fWorksheet.newChart()
// 折线图
.asLineChart()
// 设置数据源 A1:D6
.addRange('A1:D6')
// 设置起始位置 B2 单元格左上角
.setPosition(1, 1, 0, 0)
// 设置指示线样式
.setAxisPointerStyle({
indicatorLabelColor: '#ff0000',
indicatorLineType: univerAPI.Enum.ChartBorderDashType.Solid,
indicatorLineColor: '#00ff00',
indicatorLabelTextColor: '#0000ff',
})
// 设置数据点大小 10
.setDataPointSize(10)
// 设置数据点形状为圆形
.setDataPointShape(univerAPI.Enum.LinePointShape.CIRCLE)
// 生成 builder info
.build()
const fChart = await fWorksheet.insertChart(chartInfo)
// 3 秒后更新图表
setTimeout(() => {
if (fChart) {
// 获取第一个系列数据
const first = fChart.getSeriesData()[0]
// 设置第一个系列颜色为红色
const newChartInfo = fWorksheet.newChart(fChart)
.setSeriesStyle(first.index, {
color: '#ff0000',
})
.build()
// 更新图表
fSheet.updateChart(newChartInfo)
}
}, 3000)
目前我们还提供了以下的 builder 来创建对应的图表,这些 builder 都可以通过类似 fWorkSheet.newChart().asLineChart()
来创建,他们派生自 FChartBuilderBase
并且具有一些特有的配置:
const lineChartBuilder = fWorkSheet.newChart().asLineChart()
const pieChartBuilder = fWorkSheet.newChart().asPieChart()
const radarChartBuilder = fWorkSheet.newChart().asRadarChart()
// 也可以通过下面的方式来创建
const chartBuilder = fWorkSheet.newChart()
.setChartType(univerAPI.Enum.ChartType.Column)
方法 | 描述 |
---|---|
setLineStyle | 设置折线的平滑度,'line'- 折线 , 'smooth'- 平滑, 'step' -阶梯 |
setDataPointShape | 设置数据点形状,可以通过 LinePointShape 来查看支持的形状类型 |
setDataPointColor | 设置数据点颜色 |
setDataPointSize | 设置数据点大小 |
build | 生成 builder info,用于插入/更新图表 |
方法 | 描述 |
---|---|
setDoughnutHole | 设置饼图空心大小,该参数范围为 0-1 |
setBorderColor | 设置饼图扇区的色值 |
setHasPaddingAngle | 设置饼图扇区的是否有夹角(分离) |
setIsHalfPie | 是不是半饼 |
setRosePie | 是不是玫瑰图 |
setShowLabelLine | 显示标签线 |
build | 生成 builder info,用于插入/更新图表 |
方法 | 描述 |
---|---|
setShape | 设置雷达图默认形状,目前支持的值为:'polygon'-多边形,'circle'-圆形 |
setFill | 是否填充雷达图 |
build | 生成 builder info,用于插入/更新图表 |
获取图表
FWorksheet.getCharts()
方法用于获取当前工作表中的所有图表,返回一个 FChart[]
数组。
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
// 获取当前工作表中的所有图表
const charts = fWorksheet.getCharts()
以下是 FChart
上的一些成员方法:
方法 | 描述 |
---|---|
getRange | 获取图表数据源范围 |
getSeriesData | 获取图表系列数据 |
getCategoryData | 获取图表类别数据 |
updateRange | 更新图表数据源范围 |
更新图表
FWorksheet.updateChart(chartBuildInfo: IChartBuilderInfo)
方法用于更新图表,传入一个 IChartBuilderInfo
对象,用于更新图表的配置。
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
// 创建一个柱状图,数据源为 A1:D6.
// 起始位置为单元格 B2 的左上角.
const chartInfo = fWorksheet.newChart()
.setChartType(univerAPI.Enum.ChartType.Column)
.addRange('A1:D6')
.setPosition(1, 1, 0, 0)
.build()
await fWorksheet.insertChart(chartInfo)
// 获取当前工作表中的所有图表
const charts = fWorksheet.getCharts()
// 3 秒后更新第一个图表
setTimeout(() => {
const newChartInfo = fWorksheet.newChart(charts[0])
.asLineChart()
.setOptions('legend.position', univerAPI.Enum.LegendPositionEnum.Right)
.build()
fWorksheet.updateChart(newChartInfo)
}, 3000)
删除图表
FWorksheet.removeChart(chart: FChart)
方法用于删除图表,传入一个 FChart
对象,用于删除指定的图表。
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
// 创建一个柱状图,数据源为 A1:D6.
// 起始位置为单元格 B2 的左上角.
const chartInfo = fWorksheet.newChart()
.setChartType(univerAPI.Enum.ChartType.Column)
.addRange('A1:D6')
.setPosition(1, 1, 0, 0)
.build()
await fWorksheet.insertChart(chartInfo)
// 获取当前工作表中的所有图表
const charts = fWorksheet.getCharts()
// 3 秒后删除第一个图表
setTimeout(async () => {
await fWorksheet.removeChart(charts[0])
fWorksheet.getCharts()
}, 3000)
图表主题
FWorksheet.registerChartTheme(themeName: string, theme: IEchartTheme)
方法用于注册图表主题,传入一个主题名称和主题对象,用于注册自定义主题。
Univer chart 是基于 echarts 的图表库实现的,因此可以借助 echart 的主题构建工具来构建您的自定制主题。 您可以在该网站构建您自己的主题并下载成为配置文件,使用以下 API 来使用您的自定义主题:
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
// 注册您的主题
const theme = { // 您的主题配置
version: 1,
themeName: 'myTheme',
theme: {
// ... 为了简洁,省略了一些代码
color: [
'#893448',
'#d95850',
'#eb8146',
'#ffb248',
'#f2d643',
'#ebdba4',
],
// ... 为了简洁,省略了一些代码
visualMapColor: [
'#893448',
'#d95850',
'#eb8146',
'#ffb248',
'#f2d643',
'rgb(247,238,173)',
],
// ... 为了简洁,省略了一些代码
axes: [],
// ... 为了简洁,省略了一些代码
},
}
fWorksheet.registerChartTheme('myTheme', theme)
// 使用您的主题创建一个折线图
const chartInfo = fWorksheet.newChart()
.asLineChart()
.addRange('A1:D6')
.setPosition(1, 1, 0, 0)
.setTheme('myTheme')
.build()
await fWorksheet.insertChart(chartInfo)
你觉得这篇文档如何?