ExcelScript.Shape interface

リファレンス

パッケージ:: ExcelScript

ワークシート内のジェネリック図形オブジェクトを表します。図形には、幾何学的図形、線、図形のグループなどがあります。

注釈

例

/**
 * This script creates a hexagon shape on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  const currentSheet = workbook.getActiveWorksheet();
  const hexagon: ExcelScript.Shape = 
    currentSheet.addGeometricShape(ExcelScript.GeometricShapeType.hexagon);
  
  // Set the hexagon size to 40x40 pixels.
  hexagon.setHeight(40);
  hexagon.setWidth(40);

  // Position the hexagon at [100,100] pixels.
  hexagon.setLeft(100);
  hexagon.setTop(100);
}

メソッド

copyTo(destinationSheet)	オブジェクトをコピーして貼り付けます `Shape` 。貼り付けた図形は、この図形と同じピクセル位置にコピーされます。
delete()	ワークシートから図形を削除します。
getAltTextDescription()	オブジェクトの代替説明テキストを `Shape` 指定します。
getAltTextTitle()	オブジェクトの代替タイトルテキストを `Shape` 指定します。
getAsImage(format)	図形を画像に変換し、base 64 でエンコードされた文字列として画像を返します。 DPI は 96 です。サポートされている形式は、`ExcelScript.PictureFormat.BMP`、、`ExcelScript.PictureFormat.PNGExcelScript.PictureFormat.JPEG`、および `ExcelScript.PictureFormat.GIF`のみです。
getConnectionSiteCount()	この図形の結合点の数を返します。
getFill()	この図形の塗りつぶしの書式設定を返します。
getGeometricShape()	図形に関連付けられた幾何学的図形を返します。図形の種類が "GeometricShape" ではない場合は、エラーがスローされます。
getGeometricShapeType()	このジオメトリシェイプのジオメトリシェイプタイプを指定します。詳細は「`ExcelScript.GeometricShapeType`」をご覧ください。図形の `null` 種類が "GeometrShape" でない場合はを返します。
getGroup()	図形に関連付けられた図形グループを返します。図形の種類が "GroupShape" ではない場合は、エラーがスローされます。
getHeight()	図形の高さをポイント単位で指定します。負の `InvalidArgument` 値または 0 を入力として設定すると、例外がスローされます。
getId()	図形識別子を指定します。
getImage()	図形に関連付けられた画像を返します。図形の種類が "Image" ではない場合は、エラーがスローされます。
getImageAsBase64(format)	図形を画像に変換し、base 64 でエンコードされた文字列として画像を返します。 DPI は 96 です。サポートされている形式は、`ExcelScript.PictureFormat.BMP`、、`ExcelScript.PictureFormat.PNGExcelScript.PictureFormat.JPEG`、および `ExcelScript.PictureFormat.GIF`のみです。
getLeft()	図形の左側からワークシートの左側までの距離 (ポイント数) です。負の値を `InvalidArgument` 入力として設定すると、例外がスローされます。
getLevel()	指定した図形のレベルを指定します。たとえば、レベル 0 は図形がどのグループの一部でもないことを意味し、レベル 1 は図形が最上位グループの一部であることを意味し、レベル 2 は図形が最上位レベルのサブグループの一部であることを意味します。
getLine()	図形に関連付けられた線を返します。図形の種類が "Line" ではない場合は、エラーがスローされます。
getLineFormat()	この図形の線の書式設定を返します。
getLockAspectRatio()	この図形の縦横比がロックされているかどうかを指定します。
getName()	図形の名前を指定します。
getParentGroup()	この図形の親グループを指定します。
getPlacement()	オブジェクトがその下のセルに接続されている方法を表します。
getRotation()	図形の回転を度単位で指定します。
getTextFrame()	この図形のテキストフレームオブジェクトを返します。
getTop()	図形の上端からワークシートの上までのポイント単位の距離です。負の値を `InvalidArgument` 入力として設定すると、例外がスローされます。
getType()	この図形の種類を返します。詳細は「`ExcelScript.ShapeType`」をご覧ください。
getVisible()	図形を表示するかどうかを指定します。
getWidth()	図形の幅をポイント単位で指定します。負の `InvalidArgument` 値または 0 を入力として設定すると、例外がスローされます。
getZOrderPosition()	指定された図形の z オーダーでの位置を返します。0 はオーダースタックの一番下を表します。
incrementLeft(increment)	指定したポイント数だけ水平方向に図形を移動します。
incrementRotation(increment)	z 軸を中心に、指定された度数だけ、図形を時計回りに回転します。プロパティを `rotation` 使用して、図形の絶対回転を設定します。
incrementTop(increment)	指定したポイント数だけ垂直方向に図形を移動します。
scaleHeight(scaleFactor, scaleType, scaleFrom)	指定した係数分だけ図形の高さを変更します。画像の場合は、図形を元のサイズに対して拡大または縮小するのか、現在のサイズに対して拡大または縮小するのかを指定できます。画像以外の図形の場合は、常に現在の高さに対して拡大または縮小されます。
scaleWidth(scaleFactor, scaleType, scaleFrom)	指定した係数分だけ図形の幅を変更します。画像の場合は、図形を元のサイズに対して拡大または縮小するのか、現在のサイズに対して拡大または縮小するのかを指定できます。画像以外の図形の場合は、常に現在の幅に対して拡大または縮小されます。
setAltTextDescription(altTextDescription)	オブジェクトの代替説明テキストを `Shape` 指定します。
setAltTextTitle(altTextTitle)	オブジェクトの代替タイトルテキストを `Shape` 指定します。
setGeometricShapeType(geometricShapeType)	このジオメトリシェイプのジオメトリシェイプタイプを指定します。詳細は「`ExcelScript.GeometricShapeType`」をご覧ください。図形の `null` 種類が "GeometrShape" でない場合はを返します。
setHeight(height)	図形の高さをポイント単位で指定します。負の `InvalidArgument` 値または 0 を入力として設定すると、例外がスローされます。
setLeft(left)	図形の左側からワークシートの左側までの距離 (ポイント数) です。負の値を `InvalidArgument` 入力として設定すると、例外がスローされます。
setLockAspectRatio(lockAspectRatio)	この図形の縦横比がロックされているかどうかを指定します。
setName(name)	図形の名前を指定します。
setPlacement(placement)	オブジェクトがその下のセルに接続されている方法を表します。
setRotation(rotation)	図形の回転を度単位で指定します。
setTop(top)	図形の上端からワークシートの上までのポイント単位の距離です。負の値を `InvalidArgument` 入力として設定すると、例外がスローされます。
setVisible(visible)	図形を表示するかどうかを指定します。
setWidth(width)	図形の幅をポイント単位で指定します。負の `InvalidArgument` 値または 0 を入力として設定すると、例外がスローされます。
setZOrder(position)	指定された図形をコレクションの z オーダーで上または下に移動します。他の図形の手前または奥に移動します。

メソッドの詳細

copyTo(destinationSheet)

オブジェクトをコピーして貼り付けます Shape 。貼り付けた図形は、この図形と同じピクセル位置にコピーされます。

copyTo(destinationSheet?: Worksheet | string): Shape;

パラメーター

destinationSheet: ExcelScript.Worksheet | string

図形オブジェクトを貼り付けるシート。既定値は、コピーした図形のワークシートです。

戻り値

ExcelScript.Shape

delete()

ワークシートから図形を削除します。

delete(): void;

戻り値

void

例

/**
 * This script deletes all the shapes on the current worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the collection of shapes on the currently selected worksheet.
  const shapes = workbook.getActiveWorksheet().getShapes();

  // Remove each shape.
  shapes.forEach(shape =>{
    shape.delete();
  });
}

getAltTextDescription()

オブジェクトの代替説明テキストを Shape 指定します。

getAltTextDescription(): string;

戻り値

string

getAltTextTitle()

オブジェクトの代替タイトルテキストを Shape 指定します。

getAltTextTitle(): string;

戻り値

string

getAsImage(format)

警告

この API は非推奨になりました。

Use getImageAsBase64 instead.

図形を画像に変換し、base 64 でエンコードされた文字列として画像を返します。 DPI は 96 です。サポートされている形式は、ExcelScript.PictureFormat.BMP、、ExcelScript.PictureFormat.PNGExcelScript.PictureFormat.JPEG、および ExcelScript.PictureFormat.GIFのみです。

getAsImage(format: PictureFormat): string;

パラメーター

format: ExcelScript.PictureFormat

イメージの形式を指定します。

戻り値

string

例

/**
 * This script creates a star shape with the value from cell A1.
 * It then returns the image as a base64-encoded string. 
 * This string would be used as part of a Power Automate flow to add the image elsewhere.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the value of A1 from the worksheet named Sheet1.
  const sheet = workbook.getWorksheet("Sheet1");
  const value = sheet.getRange("A1").getValue();

  // Create a Shape object that looks like a 5-pointed star.
  const star = sheet.addGeometricShape(ExcelScript.GeometricShapeType.star5);

  // Set the text of star and make sure the shape fits the text.
  const textFrame = star.getTextFrame();
  textFrame.getTextRange().setText(value.toString());
  textFrame.setAutoSizeSetting(ExcelScript.ShapeAutoSize.autoSizeShapeToFitText);

  // Return the shape as a PNG image represented by a base64-encoded string.
  return star.getAsImage(ExcelScript.PictureFormat.png);
}

getConnectionSiteCount()

この図形の結合点の数を返します。

getConnectionSiteCount(): number;

戻り値

number

getFill()

この図形の塗りつぶしの書式設定を返します。

getFill(): ShapeFill;

戻り値

ExcelScript.ShapeFill

getGeometricShape()

図形に関連付けられた幾何学的図形を返します。図形の種類が "GeometricShape" ではない場合は、エラーがスローされます。

getGeometricShape(): GeometricShape;

戻り値

ExcelScript.GeometricShape

getGeometricShapeType()

このジオメトリシェイプのジオメトリシェイプタイプを指定します。詳細は「ExcelScript.GeometricShapeType」をご覧ください。図形の null 種類が "GeometrShape" でない場合はを返します。

getGeometricShapeType(): GeometricShapeType;

戻り値

ExcelScript.GeometricShapeType

getGroup()

図形に関連付けられた図形グループを返します。図形の種類が "GroupShape" ではない場合は、エラーがスローされます。

getGroup(): ShapeGroup;

戻り値

ExcelScript.ShapeGroup

getHeight()

図形の高さをポイント単位で指定します。負の InvalidArgument 値または 0 を入力として設定すると、例外がスローされます。

getHeight(): number;

戻り値

number

getId()

図形識別子を指定します。

getId(): string;

戻り値

string

getImage()

図形に関連付けられた画像を返します。図形の種類が "Image" ではない場合は、エラーがスローされます。

getImage(): Image;

戻り値

ExcelScript.Image

例

/**
 * This script transfers an image from one worksheet to another.
 */
function main(workbook: ExcelScript.Workbook)
{
  // Get the worksheet with the image on it.
  let firstWorksheet = workbook.getWorksheet("FirstSheet");

  // Get the first image from the worksheet.
  // If a script added the image, you could add a name to make it easier to find.
  let image: ExcelScript.Image;
  firstWorksheet.getShapes().forEach((shape, index) => {
    if (shape.getType() === ExcelScript.ShapeType.image) {
      image = shape.getImage();
      return;
    }
  });

  // Copy the image to another worksheet.
  image.getShape().copyTo("SecondSheet");
}

getImageAsBase64(format)

getImageAsBase64(format: PictureFormat): string;

パラメーター

format: ExcelScript.PictureFormat

イメージの形式を指定します。

戻り値

string

getLeft()

図形の左側からワークシートの左側までの距離 (ポイント数) です。負の値を InvalidArgument 入力として設定すると、例外がスローされます。

getLeft(): number;

戻り値

number

getLevel()

指定した図形のレベルを指定します。たとえば、レベル 0 は図形がどのグループの一部でもないことを意味し、レベル 1 は図形が最上位グループの一部であることを意味し、レベル 2 は図形が最上位レベルのサブグループの一部であることを意味します。

getLevel(): number;

戻り値

number

getLine()

図形に関連付けられた線を返します。図形の種類が "Line" ではない場合は、エラーがスローされます。

getLine(): Line;

戻り値

ExcelScript.Line

例

/**
 * This script adds a line that goes from cell B2 to cell F4 on the current worksheet.
 */ 
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  const sheet = workbook.getActiveWorksheet();

  // Get the ranges for the two cells.
  const b2Range = sheet.getRange("B2");
  const f4Range = sheet.getRange("F4");

  // Add a straight line that connects the top-left corners of both cells.
  const newShape = sheet.addLine(
    b2Range.getLeft(),
    b2Range.getTop(),
    f4Range.getLeft(),
    f4Range.getTop(),
    ExcelScript.ConnectorType.straight);

  // Add an open arrowhead to the end of the line, such that it points at F4.
  const line = newShape.getLine();
  line.setEndArrowheadStyle(ExcelScript.ArrowheadStyle.open);
}

getLineFormat()

この図形の線の書式設定を返します。

getLineFormat(): ShapeLineFormat;

戻り値

ExcelScript.ShapeLineFormat

getLockAspectRatio()

この図形の縦横比がロックされているかどうかを指定します。

getLockAspectRatio(): boolean;

戻り値

boolean

getName()

図形の名前を指定します。

getName(): string;

戻り値

string

getParentGroup()

この図形の親グループを指定します。

getParentGroup(): Shape;

戻り値

ExcelScript.Shape

getPlacement()

オブジェクトがその下のセルに接続されている方法を表します。

getPlacement(): Placement;

戻り値

ExcelScript.Placement

getRotation()

図形の回転を度単位で指定します。

getRotation(): number;

戻り値

number

getTextFrame()

この図形のテキストフレームオブジェクトを返します。

getTextFrame(): TextFrame;

戻り値

ExcelScript.TextFrame

例

/**
 * This script creates a star shape with the value from cell A1.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the value of A1 from the worksheet named Sheet1.
  const sheet = workbook.getWorksheet("Sheet1");
  const value = sheet.getRange("A1").getValue();

  // Create a Shape object that looks like a 5-pointed star.
  const star = sheet.addGeometricShape(ExcelScript.GeometricShapeType.star5);

  // Set the text of star and make sure the shape fits the text.
  const textFrame = star.getTextFrame();
  textFrame.getTextRange().setText(value.toString());
  textFrame.setAutoSizeSetting(ExcelScript.ShapeAutoSize.autoSizeShapeToFitText);
}

getTop()

図形の上端からワークシートの上までのポイント単位の距離です。負の値を InvalidArgument 入力として設定すると、例外がスローされます。

getTop(): number;

戻り値

number

getType()

この図形の種類を返します。詳細は「ExcelScript.ShapeType」をご覧ください。

getType(): ShapeType;

戻り値

ExcelScript.ShapeType

getVisible()

図形を表示するかどうかを指定します。

getVisible(): boolean;

戻り値

boolean

getWidth()

図形の幅をポイント単位で指定します。負の InvalidArgument 値または 0 を入力として設定すると、例外がスローされます。

getWidth(): number;

戻り値

number

getZOrderPosition()

指定された図形の z オーダーでの位置を返します。0 はオーダースタックの一番下を表します。

getZOrderPosition(): number;

戻り値

number

incrementLeft(increment)

指定したポイント数だけ水平方向に図形を移動します。

incrementLeft(increment: number): void;

パラメーター

increment: number

図形の増分がポイント単位で水平方向に移動されます。正の値を指定すると図形が右に移動し、負の値が左に移動します。シートが右から左方向の場合、これは逆になります。正の値を指定すると図形が左に移動し、負の値が右に移動します。

戻り値

void

incrementRotation(increment)

z 軸を中心に、指定された度数だけ、図形を時計回りに回転します。プロパティを rotation 使用して、図形の絶対回転を設定します。

incrementRotation(increment: number): void;

パラメーター

increment: number

図形が回転する角度。正の値を指定すると、図形が時計回りに回転し、負の値が反時計回りに回転します。

戻り値

void

incrementTop(increment)

指定したポイント数だけ垂直方向に図形を移動します。

incrementTop(increment: number): void;

パラメーター

increment: number

図形の増分がポイント単位で垂直方向に移動されます。正の値を指定すると図形が下に移動し、負の値が上に移動します。

戻り値

void

scaleHeight(scaleFactor, scaleType, scaleFrom)

指定した係数分だけ図形の高さを変更します。画像の場合は、図形を元のサイズに対して拡大または縮小するのか、現在のサイズに対して拡大または縮小するのかを指定できます。画像以外の図形の場合は、常に現在の高さに対して拡大または縮小されます。

scaleHeight(
            scaleFactor: number,
            scaleType: ShapeScaleType,
            scaleFrom?: ShapeScaleFrom
        ): void;

パラメーター

scaleFactor: number

現在の高さと変更後の高さの比率、または元の高さと変更後の高さの比率を指定します。

scaleType: ExcelScript.ShapeScaleType

図形を元のサイズと現在のサイズのどちらを基準にスケーリングするかを指定します。元のサイズスケーリングオプションは、イメージに対してのみ機能します。

scaleFrom: ExcelScript.ShapeScaleFrom

オプション。図形を拡大縮小する場合、図形の位置を保持する部分を指定します。省略すると、図形の左上隅の位置が保持されます。

戻り値

void

scaleWidth(scaleFactor, scaleType, scaleFrom)

指定した係数分だけ図形の幅を変更します。画像の場合は、図形を元のサイズに対して拡大または縮小するのか、現在のサイズに対して拡大または縮小するのかを指定できます。画像以外の図形の場合は、常に現在の幅に対して拡大または縮小されます。

scaleWidth(
            scaleFactor: number,
            scaleType: ShapeScaleType,
            scaleFrom?: ShapeScaleFrom
        ): void;

パラメーター

scaleFactor: number

現在の幅と変更後の幅の比率、または元の幅と変更後の幅の比率を指定します。

scaleType: ExcelScript.ShapeScaleType

scaleFrom: ExcelScript.ShapeScaleFrom

オプション。図形を拡大縮小する場合、図形の位置を保持する部分を指定します。省略すると、図形の左上隅の位置が保持されます。

戻り値

void

setAltTextDescription(altTextDescription)

オブジェクトの代替説明テキストを Shape 指定します。

setAltTextDescription(altTextDescription: string): void;

パラメーター

altTextDescription: string

戻り値

void

setAltTextTitle(altTextTitle)

オブジェクトの代替タイトルテキストを Shape 指定します。

setAltTextTitle(altTextTitle: string): void;

パラメーター

altTextTitle: string

戻り値

void

setGeometricShapeType(geometricShapeType)

setGeometricShapeType(geometricShapeType: GeometricShapeType): void;

パラメーター

geometricShapeType: ExcelScript.GeometricShapeType

戻り値

void

setHeight(height)

図形の高さをポイント単位で指定します。負の InvalidArgument 値または 0 を入力として設定すると、例外がスローされます。

setHeight(height: number): void;

パラメーター

height: number

戻り値

void

setLeft(left)

図形の左側からワークシートの左側までの距離 (ポイント数) です。負の値を InvalidArgument 入力として設定すると、例外がスローされます。

setLeft(left: number): void;

パラメーター

left: number

戻り値

void

setLockAspectRatio(lockAspectRatio)

この図形の縦横比がロックされているかどうかを指定します。

setLockAspectRatio(lockAspectRatio: boolean): void;

パラメーター

lockAspectRatio: boolean

戻り値

void

setName(name)

図形の名前を指定します。

setName(name: string): void;

パラメーター

name: string

戻り値

void

例

/**
 * This script creates a triangle shape on the current worksheet and names it "TRI".
 */
function main(workbook: ExcelScript.Workbook) {
  const currentSheet = workbook.getActiveWorksheet();
  const triangle: ExcelScript.Shape = 
    currentSheet.addGeometricShape(ExcelScript.GeometricShapeType.triangle);
  
  triangle.setName("TRI");
}

setPlacement(placement)

オブジェクトがその下のセルに接続されている方法を表します。

setPlacement(placement: Placement): void;

パラメーター

placement: ExcelScript.Placement

戻り値

void

例

/**
 * This script creates a diamond shape at cell C3.
 * The shape moves and resizes as the grid underneath it changes.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get cell C3 in the current worksheet.
  const sheet = workbook.getActiveWorksheet();
  const cell = sheet.getRange("C3");

  // Create a diamond that slightly overlaps the cell C3.
  const diamond = sheet.addGeometricShape(ExcelScript.GeometricShapeType.diamond);
  // Set each dimension so that the shape extends 5 pixels beyond the cell borders.
  diamond.setLeft(cell.getLeft() - 5);
  diamond.setTop(cell.getTop() - 5);
  diamond.setHeight(cell.getHeight() + 10);
  diamond.setWidth(cell.getWidth() + 10);

  // Set the placement of the shape so that it resizes and moves with the grid.
  diamond.setPlacement(ExcelScript.Placement.twoCell);
}

setRotation(rotation)

図形の回転を度単位で指定します。

setRotation(rotation: number): void;

パラメーター

rotation: number

戻り値

void

setTop(top)

図形の上端からワークシートの上までのポイント単位の距離です。負の値を InvalidArgument 入力として設定すると、例外がスローされます。

setTop(top: number): void;

パラメーター

top: number

戻り値

void

setVisible(visible)

図形を表示するかどうかを指定します。

setVisible(visible: boolean): void;

パラメーター

visible: boolean

戻り値

void

setWidth(width)

図形の幅をポイント単位で指定します。負の InvalidArgument 値または 0 を入力として設定すると、例外がスローされます。

setWidth(width: number): void;

パラメーター

width: number

戻り値

void

setZOrder(position)

指定された図形をコレクションの z オーダーで上または下に移動します。他の図形の手前または奥に移動します。

setZOrder(position: ShapeZOrder): void;

パラメーター

position: ExcelScript.ShapeZOrder

z オーダースタック内の図形を他の図形を基準に移動する場所。詳細は「ExcelScript.ShapeZOrder」をご覧ください。

戻り値

void