SheetXL - v1.0.2
    Preparing search index...

    Interface IChartCollection

    Holds the charts on a sheet.

    A view over the sheet's movables: a chart is the content of a movable, and the movable is what places it — see IChart.getMovable.

    interface IChartCollection {
        isIChartCollection: true;
        isICollection: true;
        length: number;
        "[iterator]"(): IterableIterator<IChart>;
        add(
            source: string | ICellRanges | ICellRange,
            options?: IChart.AddOptions,
        ): Promise<IChart>;
        addListeners(
            listeners: ICollection.IListeners,
            options?: IListener.Options,
        ): Remove;
        at(index: number): IChart | undefined;
        every(
            predicate: (
                value: IChart,
                index: number,
                items: readonly IChart[],
            ) => boolean,
        ): boolean;
        filter<S extends IChart>(
            predicate: (
                value: IChart,
                index: number,
                items: readonly IChart[],
            ) => value is S,
        ): S[];
        filter(
            predicate: (
                value: IChart,
                index: number,
                items: readonly IChart[],
            ) => boolean,
        ): IChart[];
        find<S extends IChart>(
            predicate: (
                value: IChart,
                index: number,
                items: readonly IChart[],
            ) => value is S,
        ): S | undefined;
        find(
            predicate: (
                value: IChart,
                index: number,
                items: readonly IChart[],
            ) => boolean,
        ): IChart | undefined;
        findIndex(
            predicate: (
                value: IChart,
                index: number,
                items: readonly IChart[],
            ) => boolean,
        ): number;
        forEach(
            fn: (value: IChart, index: number, items: readonly IChart[]) => void,
        ): void;
        getByName(name: string): IChart | null;
        getCount(): number;
        getItems(options?: ICollection.GetItemsOptions): IChart[];
        indexOf(item: IChart): number;
        isClosed(): boolean;
        map<U>(
            fn: (value: IChart, index: number, items: readonly IChart[]) => U,
        ): U[];
        some(
            predicate: (
                value: IChart,
                index: number,
                items: readonly IChart[],
            ) => boolean,
        ): boolean;
        toArray(): IChart[];
        readonly [index: number]: IChart;
    }

    Hierarchy (View Summary)

    Indexable

    • readonly [index: number]: IChart

      The item at the given index, or undefined if there is none — wb.getWorksheets()[0].

      Read-only and live: each read is against the collection as it is now. Assigning through an index throws.

    Index
    isIChartCollection isICollection length
    [iterator] add addListeners at every filter find findIndex forEach getByName getCount getItems indexOf isClosed map some toArray
    isIChartCollection: true

    For runtime type checking.

    isICollection: true

    For runtime type checking.

    length: number

    The number of items — the same as getCount.

    • Iterates the collection's items.

      Returns IterableIterator<IChart>

      The unfiltered walk — for (const sheet of wb.getWorksheets()). Every other iterable surface in the SDK (ICellRange, ICellRegions, ICellRanges) reads this way, so a collection that did not was a trap: for…of over one is the obvious line to write and it threw at runtime with nothing in the types to warn first.

      getItems remains the call that takes options — filtering, ordering, anything parameterized. This is sugar over the unfiltered case, not a replacement for it.

    • Adds a chart of source, its series made from the cells by Excel's rules, as Insert Chart makes them: which cells are labels, which way the series run, and which labels name them.

      Parameters

      • source: string | ICellRanges | ICellRange

        The cells to chart: a range, or an address. A bare address is on this sheet; several areas are separated by commas. One cell charts the block of cells around it, up to blank rows and columns.

      • Optionaloptions: IChart.AddOptions

        The type, the direction of the series, and where the chart goes.

      Returns Promise<IChart>

      The chart, once its kind has loaded. The insert is one undoable step.

      The chart is drawn as Excel draws a new chart of its type: its colors, fonts, axes, a legend for two series or more, and a title of its own. Office Scripts' worksheet.addChart(type, source, seriesBy), VBA's Shapes.AddChart2.

      const chart = await sheet.getCharts().add('A1:D5', { type: 'line' });

      ExpectedError when source holds no cells, the type cannot be made new yet, or a stock type's cells hold another number of series than it is made of.

    • Returns the item at the given index, or undefined if there is none.

      Parameters

      • index: number

        The position in iteration order. A negative index counts back from the end, as Array.prototype.at does.

      Returns IChart | undefined

    • Returns true if the predicate accepts every item, including when there are none.

      Parameters

      • predicate: (value: IChart, index: number, items: readonly IChart[]) => boolean

        Called once per item in iteration order until it returns false.

      Returns boolean

    • Returns the items the predicate accepts, in iteration order.

      Type Parameters

      Parameters

      • predicate: (value: IChart, index: number, items: readonly IChart[]) => value is S

        Called once per item.

      Returns S[]

    • Returns the items the predicate accepts, in iteration order.

      Parameters

      • predicate: (value: IChart, index: number, items: readonly IChart[]) => boolean

        Called once per item.

      Returns IChart[]

    • Returns the first item the predicate accepts, or undefined if it accepts none.

      Type Parameters

      Parameters

      • predicate: (value: IChart, index: number, items: readonly IChart[]) => value is S

        Called once per item in iteration order until it returns true.

      Returns S | undefined

    • Returns the first item the predicate accepts, or undefined if it accepts none.

      Parameters

      • predicate: (value: IChart, index: number, items: readonly IChart[]) => boolean

        Called once per item in iteration order until it returns true.

      Returns IChart | undefined

    • Returns the index of the first item the predicate accepts, or -1 if it accepts none.

      Parameters

      • predicate: (value: IChart, index: number, items: readonly IChart[]) => boolean

        Called once per item in iteration order until it returns true.

      Returns number

    • Calls the function once per item, in iteration order.

      Parameters

      • fn: (value: IChart, index: number, items: readonly IChart[]) => void

        Called once per item.

      Returns void

    • Returns the chart with the given name, or null if there is none.

      Parameters

      • name: string

        The name of the chart. This is case insensitive.

      Returns IChart | null

    • Returns the total items available.

      Returns number

      returns the total number of items available.

    • Returns the index of the item in iteration order, or -1 if it is not in the collection.

      Parameters

      • item: IChart

        The item to find.

      Returns number

    • Returns true once the collection has been closed.

      Returns boolean

      A closed collection is empty and announces nothing further. Collections that are closed by their owner (the workbook's names, functions and modules, when the workbook closes) announce it once with ICollection.Events.onClose; the others are never closed and always return false.

    • Returns the result of calling the function on every item, in iteration order.

      Type Parameters

      • U

      Parameters

      • fn: (value: IChart, index: number, items: readonly IChart[]) => U

        Called once per item.

      Returns U[]

    • Returns true if the predicate accepts at least one item.

      Parameters

      • predicate: (value: IChart, index: number, items: readonly IChart[]) => boolean

        Called once per item in iteration order until it returns true.

      Returns boolean

    • Returns the items as a fresh array, in iteration order.

      Returns IChart[]

      The call to make when an array is really wanted. The array is the caller's: changing it does not change the collection, and it does not follow later changes to the collection.

    Settings
    Member Visibility

    On This Page
    Properties
    Methods