Skip to content

charts.zh-CN.mdx

Latest commit

 

History

History
596 lines (518 loc) · 18.6 KB

charts.zh-CN.mdx

File metadata and controls

596 lines (518 loc) · 18.6 KB
Raw
title 图表
icon #pro/ChartPie

<MetaData lang="zh-CN" isPro meta={{ preset: [{ client: '@univerjs/preset-sheets-advanced', locale: '@univerjs/preset-sheets-advanced/locales/zh-CN', style: '@univerjs/preset-sheets-advanced/lib/index.css', }], plugins: [{ client: '@univerjs-pro/sheets-chart', locale: '@univerjs-pro/sheets-chart/locale/zh-CN', }, { client: '@univerjs-pro/sheets-chart-ui', locale: '@univerjs-pro/sheets-chart-ui/locale/zh-CN', style: '@univerjs-pro/sheets-chart-ui/lib/index.css', }], server: false, }} />

图表是数据可视化的重要工具，可以帮助用户更直观地理解和分析数据。在 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' // [!code ++]
import UniverPresetSheetsAdvancedZhCN from '@univerjs/preset-sheets-advanced/locales/zh-CN' // [!code ++]
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingZhCN from '@univerjs/preset-sheets-drawing/locales/zh-CN' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css' // [!code ++]
import '@univerjs/preset-sheets-advanced/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      UniverPresetSheetsCoreZhCN,
      UniverPresetSheetsDrawingZhCN, // [!code ++]
      UniverPresetSheetsAdvancedZhCN, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
    UniverSheetsAdvancedPreset(), // [!code ++]
  ],
})

如果你拥有 Univer 的商业许可证，请参考在客户端使用许可证进行配置。

{/* ### 预设与配置 */}

插件模式

安装

npm install @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui

使用

import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart' // [!code ++]
import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui' // [!code ++]
import SheetsChartUIZhCN from '@univerjs-pro/sheets-chart-ui/locale/zh-CN' // [!code ++]
import SheetsChartZhCN from '@univerjs-pro/sheets-chart/locale/zh-CN' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/sheets-chart/facade' // [!code ++]

import '@univerjs-pro/sheets-chart-ui/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      SheetsChartZhCN, // [!code ++]
      SheetsChartUIZhCN, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetsChartPlugin)
univer.registerPlugin(UniverSheetsChartUIPlugin)

如果你拥有 Univer 的商业许可证，请参考在客户端使用许可证进行配置。

支持的图表类型

Univer Sheets 支持以下图表类型：

图表类型 说明
Column 柱状图
ColumnStacked 堆积柱状图
ColumnPercentStacked 百分比堆积柱状图
Bar 条形图
BarStacked 堆积条形图
BarPercentStacked 百分比堆积条形图
Line 折线图
Area 面积图
AreaStacked 堆积面积图
AreaPercentStacked 百分比堆积面积图
Pie 饼图
Doughnut 环形图
Radar 雷达图
Scatter 散点图
Bubble 气泡图
Combination 组合图
WordCloud 词云图
Funnel 漏斗图
Relation 关系图
Waterfall 瀑布图
Pareto 帕累托图
Sankey 桑基图
Heatmap 热力图
Boxplot 箱线图

Facade API

完整 Facade API 类型定义，请查看 FacadeAPI。

引入

仅插件模式需要手动引入 Facade 包。预设模式已内置对应的 Facade 包，无需额外导入。 
import '@univerjs-pro/sheets-chart/facade'

插入图表

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 来获取对应的配置：

显示配置 ```typescript export interface IChartBuildOptions { /** * @property {string} [title] The title of the chart. */ title?: { /** * @property {string} [titlePosition] The position of the chart title. */ position?: TitlePositionEnum /** * @property {string} [titleAlignment] The alignment of the chart title.The possible values are 'left', 'center' & 'right'. */ titleAlignment: LabelAlignEnum } & 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} [yAxisTitle] The 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?: Partial seriesStyleMap?: { [id: string]: ISeriesStyle } /** * @property {string} [area] The area of line/area chart. */ area?: { lineStyle: AreaLineStyle } /** * @property {RadarShape} [radar] The radar of the chart. */ radar?: { /** * @property {RadarShape} [shape] The shape of the radar chart. */ shape?: RadarShape /** * @property {boolean} [fill] True if the radar chart is filled; false otherwise. */ fill?: boolean } /** * @property {string} [pie] The pie configuration of the chart. */ pie?: { /** * @property {number} [doughnutHole] The size of the hole in the center of the pie chart. */ doughnutHole: number /** * @property {string} [borderColor] The color of the border around the pie chart. */ borderColor: string /** * @property {boolean} [hasPaddingAngle] True if the pie chart has a padding angle. */ hasPaddingAngle: boolean /** * @property {boolean} [isHalfPie] True if the pie chart is a half pie chart. */ isHalfPie: boolean /** * @property {boolean} [rosePie] True if the pie chart is a rose pie chart. */ rosePie: boolean /** * @property {boolean} [showLabelLine] True if the pie chart shows label lines. */ showLabelLine: boolean } /** * @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 } })
创建一个折线图示例 ```typescript 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() // 更新图表 fWorksheet.updateChart(newChartInfo) } }, 3000)

</details>

目前我们还提供了以下的 builder 来创建对应的图表，这些 builder 都可以通过类似 `fWorkSheet.newChart().asLineChart()` 来创建，他们派生自 `FChartBuilderBase` 并且具有一些特有的配置：

```typescript
const lineChartBuilder = fWorkSheet.newChart().asLineChart()
const pieChartBuilder = fWorkSheet.newChart().asPieChart()
const radarChartBuilder = fWorkSheet.newChart().asRadarChart()

// 也可以通过下面的方式来创建
const chartBuilder = fWorkSheet.newChart()
.setChartType(univerAPI.Enum.ChartType.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，用于插入/更新图表

获取图表

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])
  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)