Excel JavaScript API を使用して図形を操作するWork with shapes using the Excel JavaScript API

Excel では、図形は Excel の描画層にある任意のオブジェクトとして定義されます。Excel defines shapes as any object that sits on the drawing layer of Excel. つまり、セルの外部にあるものは図形です。That means anything outside of a cell is a shape. この記事では、図形および shapes ecollection api と組み合わせて、ジオメトリック図形、線、およびイメージを使用する方法について説明します。This article describes how to use geometric shapes, lines, and images in conjunction with the Shape and ShapeCollection APIs. グラフについては、「 Excel JavaScript API を使用してグラフを操作する」で説明されています。Charts are covered in their own article, Work with charts using the Excel JavaScript API.

図形を作成するCreate shapes

図形は、ワークシートの shape コレクション (Worksheet.shapes) を使用して作成され、格納されます。Shapes are created through and stored in a worksheet's shape collection (Worksheet.shapes). ShapeCollectionには.add* 、この目的のためにいくつかの方法があります。ShapeCollection has several .add* methods for this purpose. すべての図形には、コレクションに追加されたときに名前と Id が生成されます。All shapes have names and IDs generated for them when they are added to the collection. これらは、 nameおよびidプロパティです。These are the name and id properties, respectively. nameアドインで設定して、 ShapeCollection.getItem(name)メソッドを使用して簡単に取得することができます。name can be set by your add-in for easy retrieval with the ShapeCollection.getItem(name) method.

次の種類の図形は、関連付けられているメソッドを使用して追加されます。The following types of shapes are added using the associated method:

ShapeShape Tabs.Add メソッド (Outlook フォーム スクリプト)Add Method 署名Signature
幾何学的図形Geometric Shape addGeometricShapeaddGeometricShape addGeometricShape(geometricShapeType: Excel.GeometricShapeType): Excel.Shape
画像 (JPEG または PNG のいずれか)Image (either JPEG or PNG) addImageaddImage addImage(base64ImageString: string): Excel.Shape
枠線Line addLineaddLine addLine(startLeft: number, startTop: number, endLeft: number, endTop: number, connectorType?: Excel.ConnectorType): Excel.Shape
SVGSVG addSvgaddSvg addSvg(xml: string): Excel.Shape
テキスト ボックスText Box addTextBoxaddTextBox addTextBox(text?: string): Excel.Shape

幾何学的な図形Geometric shapes

ジオメトリック図形が作成されShapeCollection.addGeometricShapeます。A geometric shape is created with ShapeCollection.addGeometricShape. このメソッドは、 GeometricShapeType enum を引数として受け取ります。That method takes a GeometricShapeType enum as an argument.

次のコードサンプルでは、ワークシートの上端と左端から100ピクセルに配置された、 "Square" という名前の150x150 ピクセルの四角形を作成します。The following code sample creates a 150x150-pixel rectangle named "Square" that is positioned 100 pixels from the top and left sides of the worksheet.

// This sample creates a rectangle positioned 100 pixels from the top and left sides
// of the worksheet and is 150x150 pixels.
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var rectangle = shapes.addGeometricShape(Excel.GeometricShapeType.rectangle);
    rectangle.left = 100;
    rectangle.top = 100;
    rectangle.height = 150;
    rectangle.width = 150;
    rectangle.name = "Square";
    return context.sync();


JPEG、PNG、SVG の画像は、図形としてワークシートに挿入できます。JPEG, PNG, and SVG images can be inserted into a worksheet as shapes. メソッドShapeCollection.addImageは、base64 でエンコードされた文字列を引数として受け取ります。The ShapeCollection.addImage method takes a base64-encoded string as an argument. これは、文字列形式の JPEG または PNG 画像のいずれかです。This is either a JPEG or PNG image in string form. ShapeCollection.addSvgも文字列で受け取りますが、この引数はグラフィックを定義する XML です。ShapeCollection.addSvg also takes in a string, though this argument is XML that defines the graphic.

次のコードサンプルは、 FileReaderによって、文字列としてロードされているイメージファイルを示しています。The following code sample shows an image file being loaded by a FileReader as a string. 文字列には、図形が作成される前に、メタデータ "base64" が削除されています。The string has the metadata "base64," removed before the shape is created.

// This sample creates an image as a Shape object in the worksheet.
var myFile = document.getElementById("selectedFile");
var reader = new FileReader();

reader.onload = (event) => {
    Excel.run(function (context) {
        var startIndex = event.target.result.indexOf("base64,");
        var myBase64 = event.target.result.substr(startIndex + 7);
        var sheet = context.workbook.worksheets.getItem("MyWorksheet");
        var image = sheet.shapes.addImage(myBase64);
        image.name = "Image";
        return context.sync();

// Read in the image file as a data URL.


行はにShapeCollection.addLine作成されます。A line is created with ShapeCollection.addLine. このメソッドには、行の開始点と終了点の左余白と上余白が必要です。That method needs the left and top margins of the line's start and end points. また、 ConnectorType列挙を取得して、エンドポイント間の行の contorts 方法を指定します。It also takes a ConnectorType enum to specify how the line contorts between endpoints. 次のコードサンプルでは、ワークシートに直線を作成します。The following code sample creates a straight line on the worksheet.

// This sample creates a straight line from [200,50] to [300,150] on the worksheet
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var line = shapes.addLine(200, 50, 300, 150, Excel.ConnectorType.straight);
    line.name = "StraightLine";
    return context.sync();

線は、他の Shape オブジェクトに接続することができます。Lines can be connected to other Shape objects. メソッドconnectBeginShapeconnectEndShapeメソッドは、指定された接続ポイントにある図形に対して、線の始点と終点を接続します。The connectBeginShape and connectEndShape methods attach the beginning and ending of a line to shapes at the specified connection points. これらのポイントの位置は図形によって異なりShape.connectionSiteCountますが、を使用すると、アドインが範囲外のポイントに接続されないようにすることができます。The locations of these points vary by shape, but the Shape.connectionSiteCount can be used to ensure your add-in does not connect to a point that's out-of-bounds. disconnectBeginShapeおよびdisconnectEndShapeメソッドを使用して、接続されているすべての図形から線が切断されます。A line is disconnected from any attached shapes using the disconnectBeginShape and disconnectEndShape methods.

次のコードサンプルでは、" Myline" 行を "l shape""直角図形" という名前の2つの図形に接続します。The following code sample connects the "MyLine" line to two shapes named "LeftShape" and "RightShape".

// This sample connects a line between two shapes at connection points '0' and '3'.
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var line = shapes.getItem("MyLine").line;
    line.connectBeginShape(shapes.getItem("LeftShape"), 0);
    line.connectEndShape(shapes.getItem("RightShape"), 3);
    return context.sync();

図形の移動とサイズ変更Move and resize shapes

ワークシートの一番上にある図形。Shapes sit on top of the worksheet. これらの配置は、 leftおよびtopプロパティによって定義されます。Their placement is defined by the left and top property. これらは、ワークシートの各エッジの余白として機能し、[0, 0] が左上隅になります。These act as margins from worksheet's respective edges, with [0, 0] being the upper-left corner. これらは、 incrementLeftおよびincrementTopメソッドを使用して、現在の位置から直接設定または調整することができます。These can either be set directly or adjusted from their current position with the incrementLeft and incrementTop methods. 既定の位置から図形を回転させる度合いは、この方法で設定します。 rotationこの方法では、プロパティがincrementRotation絶対量で、既存の回転を調整するメソッドも使用されます。How much a shape is rotated from the default position is also established in this manner, with the rotation property being the absolute amount and the incrementRotation method adjusting the existing rotation.

他の図形を基準とした図形の深さはzorderPosition 、プロパティによって定義されます。A shape's depth relative to other shapes is defined by the zorderPosition property. これはsetZOrderメソッドを使用して設定されます。このメソッドは、このメソッドを使用します。This is set using the setZOrder method, which takes a ShapeZOrder. setZOrder他の図形を基準に現在の図形の順序を調整します。setZOrder adjusts the ordering of the current shape relative to the other shapes.

アドインには、図形の高さと幅を変更するためのいくつかのオプションがあります。Your add-in has a couple options for changing the height and width of shapes. heightまたはwidthプロパティのいずれかを設定すると、他の次元を変更せずに、指定した次元が変更されます。Setting either the height or width property changes the specified dimension without changing the other dimension. scaleHeightを指定scaleWidthして、現在のサイズまたは元のサイズを基準にして図形のそれぞれの寸法を調整します (提供されるShapeScaleTypeの値に基づきます)。The scaleHeight and scaleWidth adjust the shape's respective dimensions relative to either the current or original size (based on the value of the provided ShapeScaleType). 省略可能なShapeScaleFromパラメーターは、図形を拡大または縮小する位置 (左上隅、中央、または右下隅) を指定します。An optional ShapeScaleFrom parameter specifies from where the shape scales (top-left corner, middle, or bottom-right corner). プロパティにlockAspectRatio trueが設定されている場合、scale メソッドは、他の次元も調整して、図形の現在の縦横比を維持します。If the lockAspectRatio property is true, the scale methods maintain the shape's current aspect ratio by also adjusting the other dimension.


プロパティにheight width対する直接の変更は、プロパティの値に関係なくlockAspectRatio 、そのプロパティにのみ影響します。Direct changes to the height and width properties only affect that property, regardless of the lockAspectRatio property's value.

次のコードサンプルでは、元のサイズに1.25 倍に拡大または縮小された図形を表示します。The following code sample shows a shape being scaled to 1.25 times its original size and rotated 30 degrees.

// In this sample, the shape "Octagon" is rotated 30 degrees clockwise
// and scaled 25% larger, with the upper-left corner remaining in place.
Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("MyWorksheet");
    var shape = sheet.shapes.getItem("Octagon");
    shape.lockAspectRatio = true;
    return context.sync();

図形内のテキストText in shapes

幾何学的な図形にはテキストを含めることができます。Geometric Shapes can contain text. 図形にはtextFrameTextFrame型のプロパティがあります。Shapes have a textFrame property of type TextFrame. オブジェクトTextFrameは、テキスト表示オプション (余白、テキストオーバーフローなど) を管理します。The TextFrame object manages the text display options (such as margins and text overflow). TextFrame.textRangeは、テキストの内容とフォントの設定を含むTextRangeオブジェクトです。TextFrame.textRange is a TextRange object with the text content and font settings.

次のコードサンプルでは、テキスト "Shape Text" を使用して "Wave" という名前のジオメトリック図形を作成します。The following code sample creates a geometric shape named "Wave" with the text "Shape Text". また、図形とテキストの色を調整するだけでなく、テキストの水平方向の配置を中央に設定します。It also adjusts the shape and text colors, as well as sets the text's horizontal alignment to the center.

// This sample creates a light-blue wave shape and adds the purple text "Shape text" to the center.
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var wave = shapes.addGeometricShape(Excel.GeometricShapeType.wave);
    wave.left = 100;
    wave.top = 400;
    wave.height = 50;
    wave.width = 150;
    wave.name = "Wave";
    wave.textFrame.textRange.text = "Shape text";
    wave.textFrame.textRange.font.color = "purple";
    wave.textFrame.horizontalAlignment = Excel.ShapeTextHorizontalAlignment.center;
    return context.sync();

addTextBox ShapeCollectionメソッドは、白GeometricShapeの背景Rectangleと黒のテキストを使用して、型を作成します。The addTextBox method of ShapeCollection creates a GeometricShape of type Rectangle with a white background and black text. これは、[挿入] タブの [Excel のテキストボックスによって**** 作成されaddTextBoxたものと同じです。文字列型 (string TextRange) の引数を指定して、のテキストを設定します。This is the same as what is created by Excel's Text Box button on the Insert tab. addTextBox takes a string argument to set the text of the TextRange.

次のコードサンプルは、"Hello!" というテキストを含むテキストボックスを作成する方法を示しています。The following code sample shows the creation of a text box with the text "Hello!".

// This sample creates a text box with the text "Hello!" and sizes it appropriately.
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var textbox = shapes.addTextBox("Hello!");
    textbox.left = 100;
    textbox.top = 100;
    textbox.height = 20;
    textbox.width = 45;
    textbox.name = "Textbox";
    return context.sync();

図形グループShape groups

図形は一緒にグループ化できます。Shapes can be grouped together. これにより、ユーザーは、配置、サイズ変更、およびその他の関連タスクのために1つのエンティティとして扱うことができます。This allows a user to treat them as a single entity for positioning, sizing, and other related tasks. 図形グループはのShape種類であるため、アドインでグループを1つの図形として扱うことができます。A ShapeGroup is a type of Shape, so your add-in treats the group as a single shape.

次のコードサンプルでは、グループ化された3つの図形を示します。The following code sample shows three shapes being grouped together. 次のコードサンプルでは、図形グループを50ピクセル右に移動していることを示します。The subsequent code sample shows that shape group being moved to the right 50 pixels.

// This sample takes three previously-created shapes ("Square", "Pentagon", and "Octagon")
// and groups them into a single ShapeGroup.
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var square = shapes.getItem("Square");
    var pentagon = shapes.getItem("Pentagon");
    var octagon = shapes.getItem("Octagon");

    var shapeGroup = shapes.addGroup([square, pentagon, octagon]);
    shapeGroup.name = "Group";
    console.log("Shapes grouped");

    return context.sync();

// This sample moves the previously created shape group to the right by 50 pixels.
Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var shapeGroup = sheet.shapes.getItem("Group");
    return context.sync();


グループ内の個々の図形は、種類ShapeGroup.shapesgroupshapecollectionであるプロパティを介して参照されます。Individual shapes within the group are referenced through the ShapeGroup.shapes property, which is of type GroupShapeCollection. グループ化された後は、ワークシートの shape コレクションからアクセスできなくなります。They are no longer accessible through the worksheet's shape collection after being grouped. たとえば、ワークシートに3つの図形があり、すべてが一緒にグループ化されshapes.getCountている場合、ワークシートのメソッドはカウントを1とします。As an example, if your worksheet had three shapes and they were all grouped together, the worksheet's shapes.getCount method would return a count of 1.

図形を画像としてエクスポートするExport shapes as images

任意Shapeのオブジェクトをイメージに変換できます。Any Shape object can be converted to an image. GetAsImageは、base64 でエンコードされた文字列を返します。Shape.getAsImage returns base64-encoded string. 画像の形式は、にgetAsImage渡される図形式の列挙体として指定されます。The image's format is specified as a PictureFormat enum passed to getAsImage.

Excel.run(function (context) {
    var shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    var shape = sheet.shapes.getItem("Image");
    var stringResult = shape.getAsImage(Excel.PictureFormat.png);

    return context.sync().then(function () {
        // Instead of logging, your add-in may use the base64-encoded string to save the image as a file or insert it in HTML.

図形を削除するDelete shapes

図形は、 Shapeオブジェクトのdeleteメソッドを使用してワークシートから削除されます。Shapes are removed from the worksheet with the Shape object's delete method. その他のメタデータは必要ありません。No other metadata is needed.

次のコードサンプルでは、 Myworksheetからすべての図形を削除します。The following code sample deletes all the shapes from MyWorksheet.

// This deletes all the shapes from "MyWorksheet".
Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("MyWorksheet");
    var shapes = sheet.shapes;

    // We'll load all the shapes in the collection without loading their properties.
    return context.sync().then(function () {
        shapes.items.forEach(function (shape) {
        return context.sync();

関連項目See also