Excel.ChartCollection class

Коллекция всех объектов диаграмм на листе.

Свойства

context	Контекст запроса, связанный с объектом. Это соединяет процесс надстройки с процессом основного приложения Office.
count	Возвращает количество диаграмм на листе.
items	Получает загруженные дочерние элементы в этой коллекции.

Методы

add(type, sourceData, seriesBy)	Создает диаграмму.
add(type, sourceData, seriesBy)	Создает диаграмму.
getCount()	Возвращает количество диаграмм на листе.
getItem(name)	Возвращает диаграмму по ее имени. Если одно и то же имя принадлежит нескольким диаграммам, будет возвращена первая из них.
getItemAt(index)	Возвращает диаграмму с учетом ее положения в коллекции.
getItemOrNullObject(name)	Возвращает диаграмму по ее имени. Если одно и то же имя принадлежит нескольким диаграммам, будет возвращена первая из них. Если диаграммы не существует, этот метод возвращает объект со свойством `isNullObjecttrue`. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
load(options)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNames)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNamesAndPaths)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
toJSON()	Переопределяет метод JavaScript `toJSON()` , чтобы обеспечить более полезные выходные данные при передаче объекта API в `JSON.stringify()`. (`JSON.stringify`, в свою очередь, вызывает `toJSON` метод переданного ему объекта.) В то время как исходный `Excel.ChartCollection` объект является объектом API, `toJSON` метод возвращает простой объект JavaScript (типизированный как `Excel.Interfaces.ChartCollectionData`), который содержит массив «items» с неглубокими копиями любых загруженных свойств из элементов коллекции.

События

onActivated	Возникает при активации диаграммы.
onAdded	Возникает при добавлении на лист новой диаграммы.
onDeactivated	Возникает при деактивации диаграммы.
onDeleted	Возникает при удалении диаграммы.

context

Контекст запроса, связанный с объектом. Это соединяет процесс надстройки с процессом основного приложения Office.

context: RequestContext;

Значение свойства

Excel.RequestContext

count

Возвращает количество диаграмм на листе.

readonly count: number;

Значение свойства

number

items

Получает загруженные дочерние элементы в этой коллекции.

readonly items: Excel.Chart[];

Значение свойства

Excel.Chart[]

add(type, sourceData, seriesBy)

Создает диаграмму.

add(type: Excel.ChartType, sourceData: Range, seriesBy?: Excel.ChartSeriesBy): Excel.Chart;

Параметры

type: Excel.ChartType

Представляет тип диаграммы. См. Excel.ChartType дополнительные сведения.

sourceData: Excel.Range

Объект Range , соответствующий исходным данным.

seriesBy: Excel.ChartSeriesBy

Необязательный параметр. Определяет способ использования столбцов или строк в качестве рядов данных на диаграмме. См. Excel.ChartSeriesBy дополнительные сведения.

Возвращаемое значение

Excel.Chart

Примеры

// 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");
});

add(type, sourceData, seriesBy)

Создает диаграмму.

add(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" | "ColumnClusteredEx" | "ColumnStackedEx" | "ColumnStacked100Ex" | "LineEx" | "LineStackedEx" | "LineStacked100Ex" | "PieEx" | "DoughnutEx" | "BarClusteredEx" | "BarStackedEx" | "BarStacked100Ex" | "AreaEx" | "AreaStackedEx" | "AreaStacked100Ex" | "XYScatterEx" | "BubbleEx", sourceData: Range, seriesBy?: "Auto" | "Columns" | "Rows"): Excel.Chart;

Параметры

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" | "ColumnClusteredEx" | "ColumnStackedEx" | "ColumnStacked100Ex" | "LineEx" | "LineStackedEx" | "LineStacked100Ex" | "PieEx" | "DoughnutEx" | "BarClusteredEx" | "BarStackedEx" | "BarStacked100Ex" | "AreaEx" | "AreaStackedEx" | "AreaStacked100Ex" | "XYScatterEx" | "BubbleEx"

Представляет тип диаграммы. См. Excel.ChartType дополнительные сведения.

sourceData: Excel.Range

Объект Range , соответствующий исходным данным.

seriesBy: "Auto" | "Columns" | "Rows"

Необязательный параметр. Определяет способ использования столбцов или строк в качестве рядов данных на диаграмме. См. Excel.ChartSeriesBy дополнительные сведения.

Возвращаемое значение

Excel.Chart

getCount()

Возвращает количество диаграмм на листе.

getCount(): OfficeExtension.ClientResult<number>;

Возвращаемое значение

OfficeExtension.ClientResult<number>

getItem(name)

Возвращает диаграмму по ее имени. Если одно и то же имя принадлежит нескольким диаграммам, будет возвращена первая из них.

getItem(name: string): Excel.Chart;

Параметры

name: string

Имя получаемой диаграммы.

Возвращаемое значение

Excel.Chart

Примеры

// 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);
});

getItemAt(index)

Возвращает диаграмму с учетом ее положения в коллекции.

getItemAt(index: number): Excel.Chart;

Параметры

index: number

Значение индекса получаемого объекта. Используется нулевой индекс.

Возвращаемое значение

Excel.Chart

Примеры

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);
});

getItemOrNullObject(name)

Возвращает диаграмму по ее имени. Если одно и то же имя принадлежит нескольким диаграммам, будет возвращена первая из них. Если диаграммы не существует, этот метод возвращает объект со свойством isNullObjecttrue. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

getItemOrNullObject(name: string): Excel.Chart;

Параметры

name: string

Имя получаемой диаграммы.

Возвращаемое значение

Excel.Chart

load(options)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

load(options?: Excel.Interfaces.ChartCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions): Excel.ChartCollection;

Параметры

options: Excel.Interfaces.ChartCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions

Предоставляет параметры для загружаемых свойств объекта.

Возвращаемое значение

Excel.ChartCollection

load(propertyNames)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

load(propertyNames?: string | string[]): Excel.ChartCollection;

Параметры

propertyNames: string | string[]

Строка с разделителями-запятыми или массив строк, которые определяют свойства для загрузки.

Возвращаемое значение

Excel.ChartCollection

Примеры

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);
    }
});

load(propertyNamesAndPaths)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Excel.ChartCollection;

Параметры

propertyNamesAndPaths: OfficeExtension.LoadOption

propertyNamesAndPaths.select — это строка с разделителями-запятыми, указывающая загружаемые свойства, и строка propertyNamesAndPaths.expand через запятую, указывающая свойства навигации для загрузки.

Возвращаемое значение

Excel.ChartCollection

toJSON()

Переопределяет метод JavaScript toJSON() , чтобы обеспечить более полезные выходные данные при передаче объекта API в JSON.stringify(). (JSON.stringify, в свою очередь, вызывает toJSON метод переданного ему объекта.) В то время как исходный Excel.ChartCollection объект является объектом API, toJSON метод возвращает простой объект JavaScript (типизированный как Excel.Interfaces.ChartCollectionData), который содержит массив «items» с неглубокими копиями любых загруженных свойств из элементов коллекции.

toJSON(): Excel.Interfaces.ChartCollectionData;

Возвращаемое значение

Excel.Interfaces.ChartCollectionData

onActivated

Возникает при активации диаграммы.

readonly onActivated: OfficeExtension.EventHandlers<Excel.ChartActivatedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.ChartActivatedEventArgs>

Примеры

// 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}.`);
    });
}

onAdded

Возникает при добавлении на лист новой диаграммы.

readonly onAdded: OfficeExtension.EventHandlers<Excel.ChartAddedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.ChartAddedEventArgs>

Примеры

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();
});

onDeactivated

Возникает при деактивации диаграммы.

readonly onDeactivated: OfficeExtension.EventHandlers<Excel.ChartDeactivatedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.ChartDeactivatedEventArgs>

Примеры

// 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.");
    });
}

onDeleted

Возникает при удалении диаграммы.

readonly onDeleted: OfficeExtension.EventHandlers<Excel.ChartDeletedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.ChartDeletedEventArgs>

Примеры

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();
});

Комментарии

Используется

Свойства

Методы

События

Сведения о свойстве

context

Значение свойства

count

Значение свойства

Комментарии

items

Значение свойства

Сведения о методе

add(type, sourceData, seriesBy)

Параметры

Возвращаемое значение

Комментарии

Примеры

add(type, sourceData, seriesBy)

Параметры

Возвращаемое значение

Комментарии

getCount()

Возвращаемое значение

Комментарии

getItem(name)

Параметры

Возвращаемое значение

Комментарии

Примеры

getItemAt(index)

Параметры

Возвращаемое значение

Комментарии

Примеры

getItemOrNullObject(name)

Параметры

Возвращаемое значение

Комментарии

load(options)

Параметры

Возвращаемое значение

load(propertyNames)

Параметры

Возвращаемое значение

Примеры

load(propertyNamesAndPaths)

Параметры

Возвращаемое значение

toJSON()

Возвращаемое значение

Сведения о событии

onActivated

Тип события

Комментарии

Примеры

onAdded

Тип события

Комментарии

Примеры

onDeactivated

Тип события

Комментарии

Примеры

onDeleted

Тип события

Комментарии

Примеры

Обратная связь