图表 0.5.0+
Facade API | 可付费升级 | 需要 Univer 服务端 | Univer on Node.js | Preset |
---|---|---|---|---|
✅ | ✅ | - | ✅ | UniverSheetsAdvancedPreset |
图表提供了在表格中基于区域数据插入浮动图表的功能。
该功能包含以下插件包:
@univerjs-pro/sheets-chart
- 图表插件@univerjs-pro/sheets-chart-ui
图表 UI 插件
Presets 安装
按照 打印功能 中的引导安装即可。
手动组合安装
npm install @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/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+
在 Univer Sheets 中,您可以使用 Facade API 来创建、配置和管理图表。Facade API 是一种图表的编程接口,可以帮助您更方便地使用图表功能。
Chart Builder
我们提供了 ChartBuilder 来设置图表的各种属性, 然后通过调用 ChartBuilder 的 build 方法来创建图表。以下是一个设置折线图的示例:
import { ChartTypeBits, LegendPositionEnum } from '@univerjs-pro/sheets-chart';
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
// 获取构建需要的 builder
const fChartBuilder = fSheet.newChart();
// 设置对应的属性
const chartBuildInfo = fChartBuilder
.addRange('Sheet1!A1:B4')
.setChartType(ChartTypeBits.Line)
.setPosition(5, 5, 0, 0)
.setXAxisTitle('Sales Performance')
.setOptions('legend.position', LegendPositionEnum.Right)
.build();
// 插入到对应的 sheet
fSheet.insertChart(chartBuildInfo);
在 FWorksheet 上,我们混入了以下的 api 来操作图表:
方法 | 描述 |
---|---|
insertChart | 插入图表 |
updateChart | 更新图表配置 |
newChart | 创建一个图表的 builder |
getCharts | 获取当前的 sheet 的图表列表 |
removeChart | 删除图表 |
registerChartTheme | 注册图表主题 |
以下是 ChartBuilder 上的一些成员方法
方法 | 描述 |
---|---|
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
* ```ts
* 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 fSheet = fWorkbook.getActiveSheet();
// 创建一个折线图的 builder
const chartBuilder = fSheet.newChart().asLineChart();
const chartInfo = chartBuilder.addRange('A1:D6')
// 设置位置
.setPosition(1, 1, 0, 0)
// 设置指示线
.setAxisPointerStyle({
indicatorLabelColor: '#ff0000',
indicatorLineType: 'solid', // ChartBorderDashType.Solid
indicatorLineColor: '#00ff00',
indicatorLabelTextColor: '#0000ff',
})
// 设置数据点大小
.setDataPointSize(8)
// 设置数据点形状
.setDataPointShape('triangle')
// 触发 build
.build();
// 传入 build 结果创建图表
const fChart = await fSheet.insertChart(chartInfo);
// 等待执行 insert 完成并渲染
setTimeout(() => {
if (fChart) {
const chartBuilder = fSheet.newChart(fChart);
// get the series data
const first = fChart.getSeriesData()[0];
// 设置第一个系列颜色为红色
chartBuilder.setSeriesStyle(first.index, {
color: '#ff0000',
}).build();
// 更新图表
fSheet.updateChart(chartBuilder);
}
}, 1000);
其他的 builder 0.5.2+
目前我们还提供了以下的 builder 来创建对应的图表,这些 builder 都可以通过类似 fSheet.newChart().asLineChart()
来创建,他们派生自 ChartBuilder 并且具有一些特有的配置:
const lineChartBuilder = fWorkSheet.newChart().asLineChart();
const pieChartBuilder = fWorkSheet.newChart().asPieChart();
const radarChartBuilder = fWorkSheet.newChart().asRadarChart();
// 也可以通过下面的方式来创建
const chartBuilder = fWorkSheet.newChart()
.setChartType(ChartTypeBits.Column);
- LineChartBuilder
方法 | 描述 |
---|---|
setLineStyle | 设置折线的平滑度,‘line’- 折线 , ‘smooth’- 平滑, ‘step’ -阶梯 |
setDataPointShape | 设置数据点形状,可以通过 LinePointShape 来查看支持的形状类型 |
setDataPointColor | 设置数据点颜色 |
setDataPointSize | 设置数据点大小 |
build | 生成 builder info,用于插入/更新图表 |
- PieChartBuilder
方法 | 描述 |
---|---|
setDoughnutHole | 设置饼图空心大小,该参数范围为 0-1 |
setBorderColor | 设置饼图扇区的色值 |
setHasPaddingAngle | 设置饼图扇区的是否有夹角(分离) |
setIsHalfPie | 是不是半饼 |
setRosePie | 是不是玫瑰图 |
setShowLabelLine | 显示标签线 |
build | 生成 builder info,用于插入/更新图表 |
- RadarChartBuilder
方法 | 描述 |
---|---|
setShape | 设置雷达图默认形状,目前支持的值为:‘polygon’-多边形,‘circle’-圆形 |
setFill | 是否填充雷达图 |
build | 生成 builder info,用于插入/更新图表 |
图表主题 0.5.2+
Univer chart 是基于 echarts 的图表库实现的,因此可以借助 echart 的主题构建工具来构建您的自定制主题 。 您可以在该网站构建您自己的主题并下载成为配置文件,使用以下 API 来使用您的自定义主题:
const theme = {}; // your theme object
// 注册您下载的主题
fSheet.registerChartTheme('myTheme', theme);
// 使用主题
const chartBuilder = fSheet.newChart().asLineChart();
const chartInfo = chartBuilder
.setTheme('myTheme') // theme 名称是我们查找 theme 的方式,如果未找到就会使用默认的主题
.addRange('A1:B8')
.build();
fSheet.insertChart(chartInfo);