Excel JavaScript API を使用して図形を操作する

[アーティクル]
04/07/2023

Excel では、Excel の描画レイヤー上にある任意のオブジェクトとして図形を定義します。つまり、セルの外部にあるものは図形です。この記事では、図形、線、および画像を Shape API と ShapeCollection API と組み合わせて使用する方法について説明します。グラフについては、 Excel JavaScript API を使用したグラフの操作に関する記事を参照してください。

次の図は、温度計を形成する図形を示しています。 Excel 図形として作成された温度計の画像。

図形を作成する

図形はを通じて作成され、ワークシートの図形コレクション (Worksheet.shapes) に格納されます。 ShapeCollection には、この目的のためにいくつかの .add* 方法があります。すべての図形の名前と ID は、コレクションに追加されたときに生成されます。これらは name それぞれプロパティと id プロパティです。 name メソッドを使用して簡単に取得 ShapeCollection.getItem(name) できるように、アドインで設定できます。

関連付けられたメソッドを使用して、次の種類の図形が追加されます。

Shape	Tabs.Add メソッド (Outlook フォームスクリプト)	署名
ジオメトリシェイプ	addGeometricShape	`addGeometricShape(geometricShapeType: Excel.GeometricShapeType): Excel.Shape`
画像 (JPEG または PNG)	Addimage	`addImage(base64ImageString: string): Excel.Shape`
Line	addLine	`addLine(startLeft: number, startTop: number, endLeft: number, endTop: number, connectorType?: Excel.ConnectorType): Excel.Shape`
Svg	addSvg	`addSvg(xml: string): Excel.Shape`
テキストボックス	addTextBox	`addTextBox(text?: string): Excel.Shape`

幾何学的図形

ジオメトリシェイプはで ShapeCollection.addGeometricShape作成されます。そのメソッドは、引数として GeometrShapeType 列挙型を受け取ります。

次のコードサンプルでは 、"Square" という名前の 150 x 150 ピクセルの四角形を作成し、ワークシートの上端と左側から 100 ピクセル配置します。

// This sample creates a rectangle positioned 100 pixels from the top and left sides
// of the worksheet and is 150x150 pixels.
await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;

    let rectangle = shapes.addGeometricShape(Excel.GeometricShapeType.rectangle);
    rectangle.left = 100;
    rectangle.top = 100;
    rectangle.height = 150;
    rectangle.width = 150;
    rectangle.name = "Square";

    await context.sync();
});

画像

JPEG、PNG、SVG の画像は、図形としてワークシートに挿入できます。メソッドは ShapeCollection.addImage 、base64 でエンコードされた文字列を引数として受け取ります。これは、文字列形式の JPEG または PNG イメージです。 ShapeCollection.addSvg また、文字列も受け取りますが、この引数はグラフィックを定義する XML です。

次のコードサンプルは、 FileReader によって文字列として読み込まれているイメージファイルを示しています。文字列には、図形が作成される前にメタデータ "base64" が削除されています。

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

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

// Read in the image file as a data URL.
reader.readAsDataURL(myFile.files[0]);

Lines

を使用して ShapeCollection.addLine行が作成されます。このメソッドには、行の始点と終点の左端と上端の余白が必要です。また、 ConnectorType 列挙型を使用して、エンドポイント間の行の競合を指定します。次のコードサンプルでは、ワークシートに直線を作成します。

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

線は、他の Shape オブジェクトに接続できます。メソッドと connectEndShape メソッドはconnectBeginShape、指定した接続ポイントの図形に線の開始と終了をアタッチします。これらのポイントの場所は形状によって異なりますが Shape.connectionSiteCount 、を使用して、アドインが境界外のポイントに接続しないようにすることができます。と disconnectEndShape メソッドを使用して、アタッチされた図形から線がdisconnectBeginShape切断されます。

次のコードサンプルでは、"MyLine" 行を "LeftShape" と "RightShape" という名前の 2 つの図形に接続します。

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

図形の移動とサイズ変更

図形はワークシートの上に置かれます。それらの配置は、プロパティと top プロパティによって定義されますleft。これらはワークシートのそれぞれの端の余白として機能し、[0, 0] が左上隅になります。これらは、メソッドと incrementTop メソッドを使用incrementLeftして、直接設定することも、現在の位置から調整することもできます。この方法では、図形が既定の位置から回転する量も確立されます。プロパティは絶対量であり、 rotation メソッドは既存の incrementRotation 回転を調整します。

他の図形に対する図形の深さは、プロパティによって定義されます zorderPosition 。これは、ShapeZOrder をsetZOrder受け取るメソッドを使用して設定されます。 setZOrder は、現在の図形の順序を他の図形に対して調整します。

アドインには、図形の高さと幅を変更するためのオプションがいくつかあります。または width プロパティをheight設定すると、指定したディメンションが変更され、他のディメンションは変更されません。とを scaleHeight 指定し scaleWidth 、現在または元のサイズ (指定された ShapeScaleType の値に基づいて) を基準に、図形のそれぞれの寸法を調整します。省略可能な ShapeScaleFrom パラメーターは、図形のスケーリング元 (左上隅、中央、または右下隅) を指定します。プロパティが lockAspectRatio の場合、スケールメソッドは true、もう一方のディメンションも調整することで、図形の現在の縦横比を維持します。

注:

プロパティと width プロパティへのheight直接の変更は、プロパティの値にlockAspectRatio関係なく、そのプロパティにのみ影響します。

次のコードサンプルは、元のサイズの 1.25 倍にスケーリングされ、30 度回転する図形を示しています。

// In this sample, the shape "Octagon" is rotated 30 degrees clockwise
// and scaled 25% larger, with the upper-left corner remaining in place.
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("MyWorksheet");

    let shape = sheet.shapes.getItem("Octagon");
    shape.incrementRotation(30);
    shape.lockAspectRatio = true;
    shape.scaleWidth(
        1.25,
        Excel.ShapeScaleType.currentSize,
        Excel.ShapeScaleFrom.scaleFromTopLeft);

    await context.sync();
});

図形のテキスト

Geometr Shapes にはテキストを含めることができます。図形には TextFrametextFrame 型のプロパティがあります。オブジェクトは TextFrame 、テキスト表示オプション (余白やテキストオーバーフローなど) を管理します。 TextFrame.textRange は、テキストコンテンツとフォント設定を持つ TextRange オブジェクトです。

次のコードサンプルでは、"Shape Text" というテキストを使用して "Wave" という名前の幾何学的図形を作成します。また、図形とテキストの色も調整し、テキストの水平方向の配置を中央に設定します。

// This sample creates a light-blue wave shape and adds the purple text "Shape text" to the center.
await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    let wave = shapes.addGeometricShape(Excel.GeometricShapeType.wave);
    wave.left = 100;
    wave.top = 400;
    wave.height = 50;
    wave.width = 150;

    wave.name = "Wave";
    wave.fill.setSolidColor("lightblue");

    wave.textFrame.textRange.text = "Shape text";
    wave.textFrame.textRange.font.color = "purple";
    wave.textFrame.horizontalAlignment = Excel.ShapeTextHorizontalAlignment.center;

    await context.sync();
});

のメソッドはaddTextBox、白い背景と黒いテキストを持つ型Rectangleのを作成GeometricShapeShapeCollectionします。これは、[挿入] タブの [Excel のテキストボックス] ボタンによって作成されたものと同じです。 addTextBoxのテキストを設定する文字列引数をTextRange受け取ります。

次のコードサンプルは、テキスト "Hello!" を含むテキストボックスの作成を示しています。

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

図形グループ

図形はグループ化できます。これにより、ユーザーは、配置、サイズ設定、およびその他の関連タスクの 1 つのエンティティとして扱うことができます。 ShapeGroup はのShape一種であるため、アドインはグループを 1 つの図形として扱います。

次のコードサンプルは、3 つの図形がグループ化されていることを示しています。次のコードサンプルは、図形グループが右の 50 ピクセルに移動されていることを示しています。

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

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

    await context.sync();
});

// This sample moves the previously created shape group to the right by 50 pixels.
await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    let shapeGroup = shapes.getItem("Group");
    shapeGroup.incrementLeft(50);
    await context.sync();
});

重要

グループ内の個々の図形は、GroupShapeCollection 型のプロパティを介してShapeGroup.shapes参照されます。グループ化された後、ワークシートの図形コレクションからアクセスできなくなります。たとえば、ワークシートに 3 つの図形があり、それらがすべてグループ化されている場合、ワークシートの shapes.getCount メソッドは 1 のカウントを返します。

図形をイメージとしてエクスポートする

任意の Shape オブジェクトをイメージに変換できます。 Shape.getAsImage は base64 でエンコードされた文字列を返します。イメージの形式は、にgetAsImage渡される PictureFormat 列挙型として指定されます。

await Excel.run(async (context) => {
    let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
    let shape = shapes.getItem("Image");
    let stringResult = shape.getAsImage(Excel.PictureFormat.png);

    await context.sync();

    console.log(stringResult.value);
    // Instead of logging, your add-in may use the base64-encoded string to save the image as a file or insert it in HTML.
});

図形を削除する

オブジェクトのメソッドを使用 Shape して、ワークシートから図形が delete 削除されます。他のメタデータは必要ありません。

次のコードサンプルでは、 MyWorksheet からすべての図形を削除します。

// This deletes all the shapes from "MyWorksheet".
await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("MyWorksheet");
    let shapes = sheet.shapes;

    // We'll load all the shapes in the collection without loading their properties.
    shapes.load("items/$none");
    await context.sync();

    shapes.items.forEach(function (shape) {
        shape.delete();
    });
    
    await context.sync();
});

次の方法で共有