Excel.ChartCollection class

Ссылка

Пакет:: excel

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

Extends: OfficeExtension.ClientObject

Свойства

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

Методы

add(type, sourceData, seriesBy)	Создает диаграмму.
add(typeString, sourceData, seriesByString)	Создает диаграмму.
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(typeString, sourceData, seriesByString)

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

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;

Параметры

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"

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

sourceData: Excel.Range

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

seriesByString: "Auto" | "Columns" | "Rows"

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

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)

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)

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

Поделиться через

Excel.ChartCollection class

Комментарии

Свойства

Методы

События

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

context

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

count

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

Комментарии

items

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

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

add(type, sourceData, seriesBy)

Параметры

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

Комментарии

Примеры

add(typeString, sourceData, seriesByString)

Параметры

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

Комментарии

getCount()

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

Комментарии

getItem(name)

Параметры

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

Комментарии

Примеры

getItemAt(index)

Параметры

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

Комментарии

Примеры

getItemOrNullObject(name)

Параметры

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

Комментарии

load(options)

Параметры

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

load(propertyNames)

Параметры

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

Примеры

load(propertyNamesAndPaths)

Параметры

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

toJSON()

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

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

onActivated

Тип события

Комментарии

Примеры

onAdded

Тип события

Комментарии

Примеры

onDeactivated

Тип события

Комментарии

Примеры

onDeleted

Тип события

Комментарии

Примеры

Дополнительные ресурсы