图表 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, Tools, Univer } from '@univerjs/core';
import { defaultTheme } from "@univerjs/design";
import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart';
import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui';
import SheetsChartZhCN from '@univerjs-pro/sheets-chart/locale/zh-CN';
import SheetsChartUIZhCN from '@univerjs-pro/sheets-chart-ui/locale/zh-CN';
import '@univerjs-pro/sheets-chart-ui/lib/index.css';
const univer = new Univer({
theme: defaultTheme,
locale: LocaleType.ZH_CN,
locales: {
[LocaleType.ZH_CN]: Tools.deepMerge(
{},
SheetsChartZhCN,
SheetsChartUIZhCN
),
},
});
univer.registerPlugin(UniverSheetsChartPlugin);
univer.registerPlugin(UniverSheetsChartUIPlugin);
Univer on Node.js 手动组合安装
npm install @univerjs-pro/sheets-chart
import { LocaleType, Tools, 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]: Tools.deepMerge(
SheetsChartZhCN,
),
},
});
univer.registerPlugin(UniverSheetsChartPlugin);
图表简介
图表是一种可视化数据的方式,可以帮助用户更直观地理解数据。在 Sheets 中,您可以使用图表功能将数据转换为图表,以便更好地展示数据的关系和趋势。
我们提供一下几种图表类型:
- 折线图:折线图用于展示数据的变化趋势,适用于时间序列数据。
- 柱状图:柱状图用于展示数据的大小关系,适用于比较数据。
- 饼图/环形图/玫瑰图:饼图用于展示数据的占比关系,适用于展示数据的相对比例。
- 散点图:散点图用于展示数据的分布关系,适用于展示数据的相关性。
- 面积图:面积图用于展示数据的累积关系,适用于展示数据的变化趋势。
- 条形图/堆叠条形图/百分比堆叠条形图:条形图用于展示数据的大小关系,适用于比较数据。
- 雷达图:雷达图用于展示数据的多维关系,适用于展示数据的多维分析。
- 组合图:组合图用于展示多组数据的关系,适用于展示多组数据的比较。
在 Sheets 中,您可以根据需要选择不同的图表类型,以便更好地展示数据。我们会根据用户的反馈,不断优化图表功能,提供更多的图表类型,以便更好地满足用户的需求。 以下是Univer chart的枚举类型,您可以通过查看这些枚举来了解我们支持的图表类型和配置项:
显示枚举
import { ChartTypeBits } from '@univerjs-pro/sheets-chart';
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是一种图表的编程接口,可以帮助您更方便地使用图表功能。
- 在使用图表的facade api之前, 您需要引入相关的facade包:
import '@univerjs-pro/sheets-chart-ui/facade';
我们提供了chart builder 来设置图标的各种属性, 然后通过调用ChartBuilder的build方法来创建图表。以下是一个设置折线图的示例:
// import { ChartTypeBits, LegendPositionEnum } from '@univerjs-pro/sheets-chart';
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
// 获取构建需要的builder
const fChartBuilder = fSheet.newChartBuilder();
// 设置对应的属性
const updateChartInfo = fChartBuilder
.setChartType(ChartType.LINE)
.setRange('Sheet1!A1:B4')
.setPosition(5, 5, 0, 0)
.setTitle('Sales Performance')
.setLegendPosition(LegendPositionEnum.Right)
.build();
// 插入到对应的sheet
fSheet.updateChart(updateChartInfo);
在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,用于插入/更新图表 |
目前我们支持一下的配置项, 通过setOptions方法来设置, 您可以通过查阅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;
};
backgroundColor?: string;
borderColor?: string;
gradientFill?: boolean;
theme?: string;
invalidValueType?: InvalidValueType;
}
创建一个折线图示例
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 buildInfo = chartBuilder
.setTheme('myTheme') // theme 名称是我们查找theme的方式,如果未找到就会使用默认的主题
.addRange('A1:B8')
.build();
fSheet.insertChart(chartInfo);