@univerjs-pro/sheets-chart-ui 0.6.3 → 0.6.4

package/lib/types/facade/chart-builder/line-chart-builder.d.ts

@@ -27,24 +27,98 @@ export declare class LineChartBuilder extends FChartBuilderBase {
      * The line style of the area chart.
      * @param {AreaLineStyle} lineStyle The line style of the line chart.
      * @returns {LineChartBuilder} - The builder, for chaining.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a line chart builder with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The line style is set to the step type.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asLineChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setLineStyle('step')
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
+     * ```
      */
     setLineStyle(lineStyle: AreaLineStyle): this;
     /**
      * The shape of the data point in the line chart.
      * @param {LinePointShape} dataPointShape The shape of the data point in the line chart.
      * @returns {LineChartBuilder} - The builder, for chaining.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a line chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The data point shape is set to circle, color is red, and size is 10.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asLineChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setDataPointShape(univerAPI.Enum.LinePointShape.CIRCLE)
+     *   .setDataPointColor('#ff0000')
+     *   .setDataPointSize(10)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
+     * ```
      */
     setDataPointShape(dataPointShape: LinePointShape): this;
     /**
      * The color of the data point in the line chart.
      * @param {string} dataPointColor The color of the data point in the line chart.
      * @returns {LineChartBuilder}  The builder, for chaining.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a line chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The data point shape is set to circle, color is red, and size is 10.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asLineChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setDataPointShape(univerAPI.Enum.LinePointShape.CIRCLE)
+     *   .setDataPointColor('#ff0000')
+     *   .setDataPointSize(10)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
+     * ```
      */
     setDataPointColor(dataPointColor: string): this;
     /**
      * The size of the data point in the line chart.
      * @param {number} dataPointSize The size of the data point in the line chart.
      * @returns {LineChartBuilder} The builder, for chaining.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a line chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The data point shape is set to circle, color is red, and size is 10.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asLineChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setDataPointShape(univerAPI.Enum.LinePointShape.CIRCLE)
+     *   .setDataPointColor('#ff0000')
+     *   .setDataPointSize(10)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
+     * ```
      */
     setDataPointSize(dataPointSize: number): this;
     /**
@@ -54,15 +128,25 @@ export declare class LineChartBuilder extends FChartBuilderBase {
      *
      * @example
      * ```ts
+     * @example
+     * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const chartBuilder = fSheet.newChart().asLineChart();
-     * const chartInfo = chartBuilder.addRange('A1:B8')
-     *  .setLineStyle('smooth') // AreaLineStyle.Smooth
-     *  .setDataPointShape('triangle')
-     *  .setDataPointSize(10)
-     *  .build();
-     * fSheet.insertChart(chartInfo);
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a line chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The line style is set to the step type.
+     * // The data point shape is set to circle, color is red, and size is 10.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asLineChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setLineStyle('step')
+     *   .setDataPointShape(univerAPI.Enum.LinePointShape.CIRCLE)
+     *   .setDataPointColor('#ff0000')
+     *   .setDataPointSize(10)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
      * ```
      */
     build(): IChartBuilderInfo;

package/lib/types/facade/chart-builder/pie-chart-builder.d.ts

@@ -16,36 +16,138 @@ export declare class PieChartBuilder extends FChartBuilderBase {
      * Sets the size of the hole in the center of the pie chart as a percentage of the chart size.The value should be in the range 0-1.
      * @param {number} doughnutHole The size of the hole in the center of the pie chart as a percentage of the chart size.
      * @returns {PieChartBuilder} this builder, for chaining.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a pie chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The doughnut hole is set to 0.5.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asPieChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setDoughnutHole(0.5)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
+     * ```
      */
     setDoughnutHole(doughnutHole: number): this;
     /**
      * Sets the color of the border around the pie chart.
      * @param {string} borderColor The color of the border around the pie chart.
      * @returns {PieChartBuilder} this builder, for chaining.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a pie chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The border color is set to red.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asPieChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setBorderColor('#ff0000')
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
+     * ```
      */
     setBorderColor(borderColor: string): this;
     /**
      * Sets whether the pie chart has a padding angle.
      * @param {boolean} hasPaddingAngle True if the pie chart has a padding angle; false otherwise.
      * @returns {PieChartBuilder} this builder, for chaining.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a pie chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The pie chart has a padding angle.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asPieChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setHasPaddingAngle(true)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
+     * ```
      */
     setHasPaddingAngle(hasPaddingAngle: boolean): this;
     /**
      * Sets whether the pie chart is a half pie chart.
      * @param {boolean} isHalfPie True if the pie chart is a half pie chart; false otherwise.
      * @returns {PieChartBuilder} this builder, for chaining.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a pie chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The pie chart is a half pie chart.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asPieChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setIsHalfPie(true)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
+     * ```
      */
     setIsHalfPie(isHalfPie: boolean): this;
     /**
      * Sets whether the pie chart is a rose pie chart.
      * @param {boolean} rosePie True if the pie chart is a rose pie chart; false otherwise.
      * @returns {PieChartBuilder} this builder, for chaining.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a pie chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The pie chart is a rose pie chart.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asPieChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setRosePie(true)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
+     * ```
      */
     setRosePie(rosePie: boolean): this;
     /**
      * Sets whether the pie chart shows label lines.
      * @param {boolean} showLabelLine True if the pie chart shows label lines; false otherwise.
      * @returns {PieChartBuilder} this builder, for chaining.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a pie chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The pie chart does not show label lines.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asPieChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setShowLabelLine(false)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
+     * ```
      */
     setShowLabelLine(showLabelLine: boolean): this;
     /**
@@ -56,16 +158,24 @@ export declare class PieChartBuilder extends FChartBuilderBase {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const chartBuilder = fSheet.newChart().asPieChart();
-     * const chartInfo = chartBuilder.addRange('A1:B8')
-     *  .setChartType(univerAPI.Enum.ChartType.Pie)
-     *  .setDoughnutHole(0.5)
-     *  .setBorderColor('#ff0000')
-     *  .setHasPaddingAngle(true)
-     *  .setIsHalfPie(true)
-     *  .build();
-     * fSheet.insertChart(chartInfo);
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a pie chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The doughnut hole is set to 0.5.
+     * // The border color is set to red.
+     * // The pie chart has a padding angle.
+     * // The pie chart is a half pie chart.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asPieChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setDoughnutHole(0.5)
+     *   .setBorderColor('#ff0000')
+     *   .setHasPaddingAngle(true)
+     *   .setIsHalfPie(true)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
      * ```
      */
     build(): IChartBuilderInfo;

package/lib/types/facade/chart-builder/radar-chart-builder.d.ts

@@ -22,14 +22,20 @@ export declare class RadarChartBuilder extends FChartBuilderBase {
      *
      * @example
      * ```ts
-     * // import { ChartTypeBits, RadarShape } from '@univerjs-pro/sheets-chart';
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const chartBuilder = fSheet.newChart().asRadarChart();
-     * const chartInfo = chartBuilder.addRange('A1:B8')
-     * .setShape(RadarShape.Polygon)
-     * .build();
-     * fSheet.insertChart(chartInfo);
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a radar chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The shape of the radar chart is set to polygon and filled with red color.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asRadarChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setShape(univerAPI.Enum.RadarShape.Polygon)
+     *   .setFill(true)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
      * ```
      */
     setShape(shape: RadarShape): this;
@@ -40,14 +46,20 @@ export declare class RadarChartBuilder extends FChartBuilderBase {
      *
      * @example
      * ```ts
-     * // import { ChartTypeBits } from '@univerjs-pro/sheets-chart';
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const chartBuilder = fSheet.newChart().asRadarChart();
-     * const chartInfo = chartBuilder.addRange('A1:B8')
-     * .setFill(true)
-     * .build();
-     * fSheet.insertChart(chartInfo);
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a radar chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The shape of the radar chart is set to polygon and filled with red color.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asRadarChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setShape(univerAPI.Enum.RadarShape.Polygon)
+     *   .setFill(true)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
      * ```
      */
     setFill(fill: boolean): this;
@@ -58,16 +70,20 @@ export declare class RadarChartBuilder extends FChartBuilderBase {
      *
      * @example
      * ```ts
-     * // import { ChartTypeBits } from '@univerjs-pro/sheets-chart';
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const chartBuilder = fSheet.newChart().asRadarChart();
-     * const chartInfo = chartBuilder.addRange('A1:B8')
-     * .setChartType(univerAPI.Enum.ChartType.Radar)
-     * .setShape(RadarShape.Polygon)
-     * .setFill(true)
-     * .build();
-     * fSheet.insertChart(chartInfo);
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a radar chart with data source A1:D6.
+     * // The starting position is upper-left corner of cell B2.
+     * // The shape of the radar chart is set to polygon and filled with red color.
+     * const chartInfo = fWorksheet.newChart()
+     *   .asRadarChart()
+     *   .addRange('A1:D6')
+     *   .setPosition(1, 1, 0, 0)
+     *   .setShape(univerAPI.Enum.RadarShape.Polygon)
+     *   .setFill(true)
+     *   .build();
+     * await fWorksheet.insertChart(chartInfo);
      * ```
      */
     build(): IChartBuilderInfo;

package/lib/types/facade/f-chart.d.ts

@@ -23,30 +23,49 @@ export declare class FChart {
     /**
      * Get the chart id.
      * @returns {string} The chart id.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const charts = fWorksheet.getCharts();
+     * console.log(charts[0]?.getChartId());
+     * ```
      */
     getChartId(): string;
     /**
      * Get the range of the chart.
      * @returns {ISheetChartSourceSingleRange|undefined} The range of the chart.
+     *
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const charts = fWorksheet.getCharts();
+     * console.log(charts[0]?.getRange());
+     * ```
      */
     getRange(): ISheetChartSourceSingleRange | undefined;
     /**
      * Update the range info of the chart. The range info includes the range of the chart and the direction in source.
-     * @param rangeInfo The new range of the chart.
-     * @param rangeInfo.range.range The new range of the chart.
-     * @param rangeInfo.range.subUnitId The new sheet id of the chart.
-     * @param rangeInfo.range.unitId The new workbook id of the chart.
+     * @param {ISheetChartSourceSingleRange} rangeInfo The new range of the chart.
+     * @param {IRange} rangeInfo.range.range The new range of the chart.
+     * @param {string} rangeInfo.range.subUnitId The new sheet id of the chart.
+     * @param {string} rangeInfo.range.unitId The new workbook id of the chart.
      * @param {boolean} [rangeInfo.isRowDirection] Is treat row as category.
      * @returns {Promise<boolean>} Whether the update is successful.
      *
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const charts = fSheet.getCharts();
-     * // switch chart row direction
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Get all charts on the active sheet.
+     * const charts = fWorksheet.getCharts();
+     *
+     * // Switch chart row direction
      * if (charts.length > 0){
-     *   const rangeInfo = {...charts[0].getRange()}
+     *   const rangeInfo = { ...charts[0].getRange() };
      *   rangeInfo.isRowDirection = !rangeInfo.isRowDirection;
      *   charts[0].updateRange(rangeInfo);
      * }
@@ -66,8 +85,8 @@ export declare class FChart {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const charts = fSheet.getCharts();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const charts = fWorksheet.getCharts();
      * if (charts.length > 0){
      *   const seriesData = charts[0].getSeriesData();
      *   console.log(seriesData);
@@ -90,8 +109,8 @@ export declare class FChart {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fSheet = fWorkbook.getActiveSheet();
-     * const charts = fSheet.getCharts();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const charts = fWorksheet.getCharts();
      * if (charts.length > 0){
      *   const categoryData = charts[0].getCategoryData();
      *   console.log(categoryData);