图表 0.5.0+
Facade API | 可付费升级 | 需要 Univer 服务端 | Univer on Node.js | Preset |
---|---|---|---|---|
✅ | ✅ | - | ✅ | UniverSheetsAdvancedPreset |
图表提供了在表格中基于区域数据插入浮动图表的功能。
该功能包含以下插件包:
@univerjs-pro/engine-chart
- 图表引擎插件@univerjs-pro/sheets-chart
- 表格图表插件@univerjs-pro/sheets-chart-ui
表格图表 UI 插件
Presets 安装
按照 打印功能 中的引导安装即可。
手动组合安装
npm install @univerjs-pro/engine-chart @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
import { LocaleType, merge, Univer } from '@univerjs/core';
import { defaultTheme } from "@univerjs/design";
import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart';
import SheetsChartZhCN from '@univerjs-pro/sheets-chart/locale/zh-CN';
import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui';
import SheetsChartUIZhCN from '@univerjs-pro/sheets-chart-ui/locale/zh-CN';
import '@univerjs-pro/sheets-chart-ui/facade';
import '@univerjs-pro/sheets-chart-ui/lib/index.css';
const univer = new Univer({
theme: defaultTheme,
locale: LocaleType.ZH_CN,
locales: {
[LocaleType.ZH_CN]: merge(
SheetsChartZhCN,
SheetsChartUIZhCN
),
},
});
univer.registerPlugin(UniverSheetsChartPlugin);
univer.registerPlugin(UniverSheetsChartUIPlugin);
Univer on Node.js 手动组合安装
npm install @univerjs-pro/engine-chart @univerjs-pro/sheets-chart
import { LocaleType, merge, Univer } from '@univerjs/core';
import { defaultTheme } from "@univerjs/design";
import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart';
import SheetsChartZhCN from '@univerjs-pro/sheets-chart/locale/zh-CN';
const univer = new Univer({
theme: defaultTheme,
locale: LocaleType.ZH_CN,
locales: {
[LocaleType.ZH_CN]: merge(
SheetsChartZhCN,
),
},
});
univer.registerPlugin(UniverSheetsChartPlugin);
图表简介
图表是一种可视化数据的方式,可以帮助用户更直观地理解数据。在 Sheets 中,您可以使用图表功能将数据转换为图表,以便更好地展示数据的关系和趋势。
我们提供一下几种图表类型:
- 折线图:折线图用于展示数据的变化趋势,适用于时间序列数据。
- 柱状图:柱状图用于展示数据的大小关系,适用于比较数据。
- 饼图/环形图/玫瑰图:饼图用于展示数据的占比关系,适用于展示数据的相对比例。
- 散点图:散点图用于展示数据的分布关系,适用于展示数据的相关性。
- 面积图:面积图用于展示数据的累积关系,适用于展示数据的变化趋势。
- 条形图/堆叠条形图/百分比堆叠条形图:条形图用于展示数据的大小关系,适用于比较数据。
- 雷达图:雷达图用于展示数据的多维关系,适用于展示数据的多维分析。
- 组合图:组合图用于展示多组数据的关系,适用于展示多组数据的比较。
在 Sheets 中,您可以根据需要选择不同的图表类型,以便更好地展示数据。我们会根据用户的反馈,不断优化图表功能,提供更多的图表类型,以便更好地满足用户的需求。
以下是Univer chart的枚举类型,您可以通过查看这些枚举来了解我们支持的图表类型和配置项:
显示枚举
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 0.5.2+
完整 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();
console.log(charts);
以下是 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]);
console.log(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);