指南Univer Sheets功能图表Pro

图表 0.5.0+

Facade API付费版本需要 Univer 服务端Univer on Node.jsPreset
--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);
 

这个页面对您有帮助吗?