excel.chartcollection.yml

### YamlMime:TSType
name: Excel.ChartCollection
uid: 'excel!Excel.ChartCollection:class'
package: excel!
fullName: Excel.ChartCollection
summary: A collection of all the chart objects on a worksheet.
remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
isPreview: false
isDeprecated: false
type: class
properties:
  - name: context
    uid: 'excel!Excel.ChartCollection#context:member'
    package: excel!
    fullName: context
    summary: >-
      The request context associated with the object. This connects the add-in's process to the Office host
      application's process.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'context: RequestContext;'
      return:
        type: '<xref uid="excel!Excel.RequestContext:class" />'
  - name: count
    uid: 'excel!Excel.ChartCollection#count:member'
    package: excel!
    fullName: count
    summary: Returns the number of charts in the worksheet.
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly count: number;'
      return:
        type: number
  - name: items
    uid: 'excel!Excel.ChartCollection#items:member'
    package: excel!
    fullName: items
    summary: Gets the loaded child items in this collection.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly items: Excel.Chart[];'
      return:
        type: '<xref uid="excel!Excel.Chart:class" />[]'
methods:
  - name: 'add(type, sourceData, seriesBy)'
    uid: 'excel!Excel.ChartCollection#add:member(1)'
    package: excel!
    fullName: 'add(type, sourceData, seriesBy)'
    summary: Creates a new chart.
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      // Add a chart of chartType "ColumnClustered" on worksheet "Charts" 
      // with sourceData from range "A1:B4" and seriesBy set to "auto".
      await Excel.run(async (context) => {
          const sheet = context.workbook.worksheets.getItem("Sheet1");
          const rangeSelection = "A1:B4";
          const range = sheet.getRange(rangeSelection);
          const chart = sheet.charts.add(
          Excel.ChartType.columnClustered, 
          range, 
          Excel.ChartSeriesBy.auto);
          await context.sync();

          console.log("New Chart Added");
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'add(type: Excel.ChartType, sourceData: Range, seriesBy?: Excel.ChartSeriesBy): Excel.Chart;'
      parameters:
        - id: type
          description: Represents the type of a chart. See `Excel.ChartType` for details.
          type: '<xref uid="excel!Excel.ChartType:enum" />'
        - id: sourceData
          description: The `Range` object corresponding to the source data.
          type: '<xref uid="excel!Excel.Range:class" />'
        - id: seriesBy
          description: >-
            Optional. Specifies the way columns or rows are used as data series on the chart. See `Excel.ChartSeriesBy`
            for details.
          type: '<xref uid="excel!Excel.ChartSeriesBy:enum" />'
      return:
        type: '<xref uid="excel!Excel.Chart:class" />'
        description: ''
  - name: 'add(typeString, sourceData, seriesByString)'
    uid: 'excel!Excel.ChartCollection#add:member(2)'
    package: excel!
    fullName: 'add(typeString, sourceData, seriesByString)'
    summary: Creates a new chart.
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        add(typeString: "Invalid" | "ColumnClustered" | "ColumnStacked" | "ColumnStacked100" | "3DColumnClustered" |
        "3DColumnStacked" | "3DColumnStacked100" | "BarClustered" | "BarStacked" | "BarStacked100" | "3DBarClustered" |
        "3DBarStacked" | "3DBarStacked100" | "LineStacked" | "LineStacked100" | "LineMarkers" | "LineMarkersStacked" |
        "LineMarkersStacked100" | "PieOfPie" | "PieExploded" | "3DPieExploded" | "BarOfPie" | "XYScatterSmooth" |
        "XYScatterSmoothNoMarkers" | "XYScatterLines" | "XYScatterLinesNoMarkers" | "AreaStacked" | "AreaStacked100" |
        "3DAreaStacked" | "3DAreaStacked100" | "DoughnutExploded" | "RadarMarkers" | "RadarFilled" | "Surface" |
        "SurfaceWireframe" | "SurfaceTopView" | "SurfaceTopViewWireframe" | "Bubble" | "Bubble3DEffect" | "StockHLC" |
        "StockOHLC" | "StockVHLC" | "StockVOHLC" | "CylinderColClustered" | "CylinderColStacked" |
        "CylinderColStacked100" | "CylinderBarClustered" | "CylinderBarStacked" | "CylinderBarStacked100" |
        "CylinderCol" | "ConeColClustered" | "ConeColStacked" | "ConeColStacked100" | "ConeBarClustered" |
        "ConeBarStacked" | "ConeBarStacked100" | "ConeCol" | "PyramidColClustered" | "PyramidColStacked" |
        "PyramidColStacked100" | "PyramidBarClustered" | "PyramidBarStacked" | "PyramidBarStacked100" | "PyramidCol" |
        "3DColumn" | "Line" | "3DLine" | "3DPie" | "Pie" | "XYScatter" | "3DArea" | "Area" | "Doughnut" | "Radar" |
        "Histogram" | "Boxwhisker" | "Pareto" | "RegionMap" | "Treemap" | "Waterfall" | "Sunburst" | "Funnel",
        sourceData: Range, seriesByString?: "Auto" | "Columns" | "Rows"): Excel.Chart;
      parameters:
        - id: typeString
          description: Represents the type of a chart. See `Excel.ChartType` for details.
          type: >-
            "Invalid" | "ColumnClustered" | "ColumnStacked" | "ColumnStacked100" | "3DColumnClustered" |
            "3DColumnStacked" | "3DColumnStacked100" | "BarClustered" | "BarStacked" | "BarStacked100" |
            "3DBarClustered" | "3DBarStacked" | "3DBarStacked100" | "LineStacked" | "LineStacked100" | "LineMarkers" |
            "LineMarkersStacked" | "LineMarkersStacked100" | "PieOfPie" | "PieExploded" | "3DPieExploded" | "BarOfPie" |
            "XYScatterSmooth" | "XYScatterSmoothNoMarkers" | "XYScatterLines" | "XYScatterLinesNoMarkers" |
            "AreaStacked" | "AreaStacked100" | "3DAreaStacked" | "3DAreaStacked100" | "DoughnutExploded" |
            "RadarMarkers" | "RadarFilled" | "Surface" | "SurfaceWireframe" | "SurfaceTopView" |
            "SurfaceTopViewWireframe" | "Bubble" | "Bubble3DEffect" | "StockHLC" | "StockOHLC" | "StockVHLC" |
            "StockVOHLC" | "CylinderColClustered" | "CylinderColStacked" | "CylinderColStacked100" |
            "CylinderBarClustered" | "CylinderBarStacked" | "CylinderBarStacked100" | "CylinderCol" | "ConeColClustered"
            | "ConeColStacked" | "ConeColStacked100" | "ConeBarClustered" | "ConeBarStacked" | "ConeBarStacked100" |
            "ConeCol" | "PyramidColClustered" | "PyramidColStacked" | "PyramidColStacked100" | "PyramidBarClustered" |
            "PyramidBarStacked" | "PyramidBarStacked100" | "PyramidCol" | "3DColumn" | "Line" | "3DLine" | "3DPie" |
            "Pie" | "XYScatter" | "3DArea" | "Area" | "Doughnut" | "Radar" | "Histogram" | "Boxwhisker" | "Pareto" |
            "RegionMap" | "Treemap" | "Waterfall" | "Sunburst" | "Funnel"
        - id: sourceData
          description: The `Range` object corresponding to the source data.
          type: '<xref uid="excel!Excel.Range:class" />'
        - id: seriesByString
          description: >-
            Optional. Specifies the way columns or rows are used as data series on the chart. See `Excel.ChartSeriesBy`
            for details.
          type: '"Auto" | "Columns" | "Rows"'
      return:
        type: '<xref uid="excel!Excel.Chart:class" />'
        description: ''
  - name: getCount()
    uid: 'excel!Excel.ChartCollection#getCount:member(1)'
    package: excel!
    fullName: getCount()
    summary: Returns the number of charts in the worksheet.
    remarks: '\[ [API set: ExcelApi 1.4](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getCount(): OfficeExtension.ClientResult<number>;'
      return:
        type: '<xref uid="office!OfficeExtension.ClientResult:class" />&lt;number&gt;'
        description: ''
  - name: getItem(name)
    uid: 'excel!Excel.ChartCollection#getItem:member(1)'
    package: excel!
    fullName: getItem(name)
    summary: 'Gets a chart using its name. If there are multiple charts with the same name, the first one will be returned.'
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      // Get the number of charts.
      await Excel.run(async (context) => { 
          const charts = context.workbook.worksheets.getItem("Sheet1").charts;
          charts.load('count');
          await context.sync();
          
          console.log("charts: Count= " + charts.count);
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getItem(name: string): Excel.Chart;'
      parameters:
        - id: name
          description: Name of the chart to be retrieved.
          type: string
      return:
        type: '<xref uid="excel!Excel.Chart:class" />'
        description: ''
  - name: getItemAt(index)
    uid: 'excel!Excel.ChartCollection#getItemAt:member(1)'
    package: excel!
    fullName: getItemAt(index)
    summary: Gets a chart based on its position in the collection.
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => { 
          const lastPosition = context.workbook.worksheets.getItem("Sheet1").charts.count - 1;
          const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItemAt(lastPosition);
          await context.sync();

          console.log(chart.name);
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getItemAt(index: number): Excel.Chart;'
      parameters:
        - id: index
          description: Index value of the object to be retrieved. Zero-indexed.
          type: number
      return:
        type: '<xref uid="excel!Excel.Chart:class" />'
        description: ''
  - name: getItemOrNullObject(name)
    uid: 'excel!Excel.ChartCollection#getItemOrNullObject:member(1)'
    package: excel!
    fullName: getItemOrNullObject(name)
    summary: >-
      Gets a chart using its name. If there are multiple charts with the same name, the first one will be returned. If
      the chart doesn't exist, then this method returns an object with its `isNullObject` property set to `true`<!--
      -->. For further information, see [*OrNullObject methods and
      properties](https://learn.microsoft.com/office/dev/add-ins/develop/application-specific-api-model#ornullobject-methods-and-properties)<!--
      -->.
    remarks: '\[ [API set: ExcelApi 1.4](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getItemOrNullObject(name: string): Excel.Chart;'
      parameters:
        - id: name
          description: Name of the chart to be retrieved.
          type: string
      return:
        type: '<xref uid="excel!Excel.Chart:class" />'
        description: ''
  - name: load(options)
    uid: 'excel!Excel.ChartCollection#load:member(1)'
    package: excel!
    fullName: load(options)
    summary: >-
      Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading
      the properties.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        load(options?: Excel.Interfaces.ChartCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions):
        Excel.ChartCollection;
      parameters:
        - id: options
          description: Provides options for which properties of the object to load.
          type: >-
            <xref uid="excel!Excel.Interfaces.ChartCollectionLoadOptions:interface" /> & <xref
            uid="excel!Excel.Interfaces.CollectionLoadOptions:interface" />
      return:
        type: '<xref uid="excel!Excel.ChartCollection:class" />'
        description: ''
  - name: load(propertyNames)
    uid: 'excel!Excel.ChartCollection#load:member(2)'
    package: excel!
    fullName: load(propertyNames)
    summary: >-
      Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading
      the properties.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'load(propertyNames?: string | string[]): Excel.ChartCollection;'
      parameters:
        - id: propertyNames
          description: A comma-delimited string or an array of strings that specify the properties to load.
          type: 'string | string[]'
      return:
        type: '<xref uid="excel!Excel.ChartCollection:class" />'
        description: |-


          #### Examples

          ```TypeScript
          await Excel.run(async (context) => { 
              const charts = context.workbook.worksheets.getItem("Sheet1").charts;
              charts.load('items');
              await context.sync();
              
              for (let i = 0; i < charts.items.length; i++) {
                  console.log(charts.items[i].name);
              }
          });
          ```
  - name: load(propertyNamesAndPaths)
    uid: 'excel!Excel.ChartCollection#load:member(3)'
    package: excel!
    fullName: load(propertyNamesAndPaths)
    summary: >-
      Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading
      the properties.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Excel.ChartCollection;'
      parameters:
        - id: propertyNamesAndPaths
          description: >-
            `propertyNamesAndPaths.select` is a comma-delimited string that specifies the properties to load, and
            `propertyNamesAndPaths.expand` is a comma-delimited string that specifies the navigation properties to load.
          type: '<xref uid="office!OfficeExtension.LoadOption:interface" />'
      return:
        type: '<xref uid="excel!Excel.ChartCollection:class" />'
        description: ''
  - name: toJSON()
    uid: 'excel!Excel.ChartCollection#toJSON:member(1)'
    package: excel!
    fullName: toJSON()
    summary: >-
      Overrides the JavaScript `toJSON()` method in order to provide more useful output when an API object is passed to
      `JSON.stringify()`<!-- -->. (`JSON.stringify`<!-- -->, in turn, calls the `toJSON` method of the object that is
      passed to it.) Whereas the original `Excel.ChartCollection` object is an API object, the `toJSON` method returns a
      plain JavaScript object (typed as `Excel.Interfaces.ChartCollectionData`<!-- -->) that contains an "items" array
      with shallow copies of any loaded properties from the collection's items.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'toJSON(): Excel.Interfaces.ChartCollectionData;'
      return:
        type: '<xref uid="excel!Excel.Interfaces.ChartCollectionData:interface" />'
        description: ''
events:
  - name: onActivated
    uid: 'excel!Excel.ChartCollection#onActivated:member'
    package: excel!
    fullName: onActivated
    summary: Occurs when a chart is activated.
    remarks: >-
      \[ [API set: ExcelApi 1.8](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-chart-activated.yaml


      await Excel.run(async (context) => {

          const pieChart = context.workbook.worksheets.getActiveWorksheet().charts.getItem("Pie");

          // Register the onActivated and onDeactivated event handlers.
          pieChart.onActivated.add(chartActivated);
          pieChart.onDeactivated.add(chartDeactivated);

          await context.sync();

          console.log("Added handlers for Chart onActivated and onDeactivated events.");
      });


      ...


      async function chartActivated(event) {
          await Excel.run(async (context) => {
              // Retrieve the worksheet.
              const sheet = context.workbook.worksheets.getActiveWorksheet();

              // Retrieve the activated chart by ID and load the name of the chart. 
              const activatedChart = sheet.charts.getItem(event.chartId);
              activatedChart.load(["name"]);
              await context.sync();

              // Print out the activated chart's data.
              console.log(`A chart was activated. ID: ${event.chartId}. Chart name: ${activatedChart.name}.`);
          });
      }

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onActivated: OfficeExtension.EventHandlers<Excel.ChartActivatedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.ChartActivatedEventArgs:interface" />&gt;
  - name: onAdded
    uid: 'excel!Excel.ChartCollection#onAdded:member'
    package: excel!
    fullName: onAdded
    summary: Occurs when a new chart is added to the worksheet.
    remarks: |-
      \[ [API set: ExcelApi 1.8](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => {
          context.workbook.worksheets.getActiveWorksheet()
              .charts.onAdded.add(function (event) {
              return Excel.run(async (context) => {
                  console.log("A chart has been added with ID: " + event.chartId);
                  await context.sync();
              });
          });
          await context.sync();
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onAdded: OfficeExtension.EventHandlers<Excel.ChartAddedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.ChartAddedEventArgs:interface" />&gt;
  - name: onDeactivated
    uid: 'excel!Excel.ChartCollection#onDeactivated:member'
    package: excel!
    fullName: onDeactivated
    summary: Occurs when a chart is deactivated.
    remarks: >-
      \[ [API set: ExcelApi 1.8](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-chart-activated.yaml


      await Excel.run(async (context) => {

          const pieChart = context.workbook.worksheets.getActiveWorksheet().charts.getItem("Pie");

          // Register the onActivated and onDeactivated event handlers.
          pieChart.onActivated.add(chartActivated);
          pieChart.onDeactivated.add(chartDeactivated);

          await context.sync();

          console.log("Added handlers for Chart onActivated and onDeactivated events.");
      });


      ...


      async function chartDeactivated(event) {
          await Excel.run(async (context) => {
              // Callback function for when the chart is deactivated.
              console.log("The pie chart is NOT active.");
          });
      }

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onDeactivated: OfficeExtension.EventHandlers<Excel.ChartDeactivatedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.ChartDeactivatedEventArgs:interface" />&gt;
  - name: onDeleted
    uid: 'excel!Excel.ChartCollection#onDeleted:member'
    package: excel!
    fullName: onDeleted
    summary: Occurs when a chart is deleted.
    remarks: |-
      \[ [API set: ExcelApi 1.8](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => {
          context.workbook.worksheets.getActiveWorksheet()
              .charts.onDeleted.add(function (event) {
              return Excel.run(async (context) => {
                  console.log("The chart with this ID was deleted: " + event.chartId);
                  await context.sync();
              });
          });
          await context.sync();
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onDeleted: OfficeExtension.EventHandlers<Excel.ChartDeletedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.ChartDeletedEventArgs:interface" />&gt;
extends: '<xref uid="office!OfficeExtension.ClientObject:class" />'