Excel.Shape class

パッケージ:

excel

ワークシート内のジェネリック図形オブジェクトを表します。 図形には、幾何学的図形、線、図形のグループなどがあります。図形オブジェクト モデルの詳細については、「 Excel JavaScript API を使用した図形の操作」を参照してください。

Extends

OfficeExtension.ClientObject

注釈

[ API セット: ExcelApi 1.9 ]

プロパティ

altTextDescription	オブジェクトの代替説明テキストを Shape 指定します。
altTextTitle	オブジェクトの代替タイトル テキストを Shape 指定します。
connectionSiteCount	この図形の結合点の数を返します。
context	オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。
displayName	図形の表示名を取得します。 新しく作成された図形には、ローカライズされ、その nameと一致しない可能性がある生成された名前があります。 このシナリオでは、この API を使用して、UI に表示される名前を取得できます。
fill	この図形の塗りつぶしの書式設定を返します。
geometricShape	図形に関連付けられた幾何学的図形を返します。 図形の種類が "GeometricShape" ではない場合は、エラーがスローされます。
geometricShapeType	このジオメトリ シェイプのジオメトリ シェイプ タイプを指定します。 詳細は「Excel.GeometricShapeType」をご覧ください。 図形の null 種類が "GeometrShape" でない場合は を返します。
group	図形に関連付けられた図形グループを返します。 図形の種類が "GroupShape" ではない場合は、エラーがスローされます。
height	図形の高さをポイント単位で指定します。 負の InvalidArgument 値または 0 を入力として設定すると、例外がスローされます。
id	図形識別子を指定します。
image	図形に関連付けられた画像を返します。 図形の種類が "Image" ではない場合は、エラーがスローされます。
left	図形の左側からワークシートの左側までの距離 (ポイント数) です。 負の値を InvalidArgument 入力として設定すると、例外がスローされます。
level	指定した図形のレベルを指定します。 たとえば、レベル 0 は図形がどのグループの一部でもないことを意味し、レベル 1 は図形が最上位グループの一部であることを意味し、レベル 2 は図形が最上位レベルのサブグループの一部であることを意味します。
line	図形に関連付けられた線を返します。 図形の種類が "Line" ではない場合は、エラーがスローされます。
lineFormat	この図形の線の書式設定を返します。
lockAspectRatio	この図形の縦横比がロックされているかどうかを指定します。
name	図形の名前を指定します。
parentGroup	この図形の親グループを指定します。
placement	オブジェクトがその下のセルに接続されている方法を表します。
rotation	図形の回転を度単位で指定します。
textFrame	この図形のテキスト フレーム オブジェクトを返します。
top	図形の上端からワークシートの上までのポイント単位の距離です。 負の値を InvalidArgument 入力として設定すると、例外がスローされます。
type	この図形の種類を返します。 詳細は「Excel.ShapeType」をご覧ください。
visible	図形を表示するかどうかを指定します。
width	図形の幅をポイント単位で指定します。 負の InvalidArgument 値または 0 を入力として設定すると、例外がスローされます。
zOrderPosition	指定された図形の z オーダーでの位置を返します。0 はオーダー スタックの一番下を表します。

メソッド

copyTo(destinationSheet)	オブジェクトをコピーして貼り付けます Shape 。 貼り付けた図形は、この図形と同じピクセル位置にコピーされます。
delete()	ワークシートから図形を削除します。
getAsImage(format)	図形を画像に変換し、base 64 でエンコードされた文字列として画像を返します。 DPI は 96 です。 サポートされている形式は、Excel.PictureFormat.BMP、、Excel.PictureFormat.PNGExcel.PictureFormat.JPEG、および Excel.PictureFormat.GIFのみです。
getAsImage(formatString)	図形を画像に変換し、base 64 でエンコードされた文字列として画像を返します。 DPI は 96 です。 サポートされている形式は、Excel.PictureFormat.BMP、、Excel.PictureFormat.PNGExcel.PictureFormat.JPEG、および Excel.PictureFormat.GIFのみです。
incrementLeft(increment)	指定したポイント数だけ水平方向に図形を移動します。
incrementRotation(increment)	z 軸を中心に、指定された度数だけ、図形を時計回りに回転します。 プロパティを rotation 使用して、図形の絶対回転を設定します。
incrementTop(increment)	指定したポイント数だけ垂直方向に図形を移動します。
load(options)	オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。
load(propertyNames)	オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。
load(propertyNamesAndPaths)	オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。
scaleHeight(scaleFactor, scaleType, scaleFrom)	指定した係数分だけ図形の高さを変更します。 画像の場合は、図形を元のサイズに対して拡大または縮小するのか、現在のサイズに対して拡大または縮小するのかを指定できます。 画像以外の図形の場合は、常に現在の高さに対して拡大または縮小されます。
scaleHeight(scaleFactor, scaleTypeString, scaleFromString)	指定した係数分だけ図形の高さを変更します。 画像の場合は、図形を元のサイズに対して拡大または縮小するのか、現在のサイズに対して拡大または縮小するのかを指定できます。 画像以外の図形の場合は、常に現在の高さに対して拡大または縮小されます。
scaleWidth(scaleFactor, scaleType, scaleFrom)	指定した係数分だけ図形の幅を変更します。 画像の場合は、図形を元のサイズに対して拡大または縮小するのか、現在のサイズに対して拡大または縮小するのかを指定できます。 画像以外の図形の場合は、常に現在の幅に対して拡大または縮小されます。
scaleWidth(scaleFactor, scaleTypeString, scaleFromString)	指定した係数分だけ図形の幅を変更します。 画像の場合は、図形を元のサイズに対して拡大または縮小するのか、現在のサイズに対して拡大または縮小するのかを指定できます。 画像以外の図形の場合は、常に現在の幅に対して拡大または縮小されます。
set(properties, options)	オブジェクトの複数のプロパティを同時に設定します。 適切なプロパティを持つプレーン オブジェクトまたは同じ型の別の API オブジェクトを渡すことができます。
set(properties)	既存の読み込まれたオブジェクトに基づいて、オブジェクトに複数のプロパティを同時に設定します。
setZOrder(position)	指定された図形をコレクションの z オーダーで上または下に移動します。他の図形の手前または奥に移動します。
setZOrder(positionString)	指定された図形をコレクションの z オーダーで上または下に移動します。他の図形の手前または奥に移動します。
toJSON()	API オブジェクトが に渡されたときにより便利な出力を提供するために、JavaScript toJSON() メソッドを JSON.stringify()オーバーライドします。 (JSON.stringifyさらに、渡される オブジェクトの メソッドを呼び出 toJSON します)。元の Excel.Shape オブジェクトは API オブジェクトですが、メソッドは、元の toJSON オブジェクトから読み込まれた子プロパティの浅いコピーを含むプレーンな JavaScript オブジェクト (として Excel.Interfaces.ShapeData型指定) を返します。

イベント

onActivated	図形がアクティブになったときに発生します。
onDeactivated	図形が非アクティブになると発生します。

プロパティの詳細

altTextDescription

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

altTextDescription: string;

プロパティ値

string

注釈

[ API セット: ExcelApi 1.9 ]

altTextTitle

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

altTextTitle: string;

プロパティ値

string

注釈

[ API セット: ExcelApi 1.9 ]

connectionSiteCount

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

readonly connectionSiteCount: number;

プロパティ値

number

注釈

[ API セット: ExcelApi 1.9 ]

context

オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。

context: RequestContext;

プロパティ値

Excel.RequestContext

displayName

図形の表示名を取得します。 新しく作成された図形には、ローカライズされ、その nameと一致しない可能性がある生成された名前があります。 このシナリオでは、この API を使用して、UI に表示される名前を取得できます。

readonly displayName: string;

プロパティ値

string

注釈

[ API セット: ExcelApi 1.15 ]

fill

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

readonly fill: Excel.ShapeFill;

プロパティ値

Excel.ShapeFill

注釈

[ API セット: ExcelApi 1.9 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.addGeometricShape(Excel.GeometricShapeType.smileyFace);
    shape.left = 300;
    shape.top = 100;
    shape.height = 100;
    shape.width = 100;
    shape.fill.foregroundColor = "yellow"
    await context.sync();
});

geometricShape

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

readonly geometricShape: Excel.GeometricShape;

プロパティ値

Excel.GeometricShape

注釈

[ API セット: ExcelApi 1.9 ]

geometricShapeType

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

geometricShapeType: Excel.GeometricShapeType | "LineInverse" | "Triangle" | "RightTriangle" | "Rectangle" | "Diamond" | "Parallelogram" | "Trapezoid" | "NonIsoscelesTrapezoid" | "Pentagon" | "Hexagon" | "Heptagon" | "Octagon" | "Decagon" | "Dodecagon" | "Star4" | "Star5" | "Star6" | "Star7" | "Star8" | "Star10" | "Star12" | "Star16" | "Star24" | "Star32" | "RoundRectangle" | "Round1Rectangle" | "Round2SameRectangle" | "Round2DiagonalRectangle" | "SnipRoundRectangle" | "Snip1Rectangle" | "Snip2SameRectangle" | "Snip2DiagonalRectangle" | "Plaque" | "Ellipse" | "Teardrop" | "HomePlate" | "Chevron" | "PieWedge" | "Pie" | "BlockArc" | "Donut" | "NoSmoking" | "RightArrow" | "LeftArrow" | "UpArrow" | "DownArrow" | "StripedRightArrow" | "NotchedRightArrow" | "BentUpArrow" | "LeftRightArrow" | "UpDownArrow" | "LeftUpArrow" | "LeftRightUpArrow" | "QuadArrow" | "LeftArrowCallout" | "RightArrowCallout" | "UpArrowCallout" | "DownArrowCallout" | "LeftRightArrowCallout" | "UpDownArrowCallout" | "QuadArrowCallout" | "BentArrow" | "UturnArrow" | "CircularArrow" | "LeftCircularArrow" | "LeftRightCircularArrow" | "CurvedRightArrow" | "CurvedLeftArrow" | "CurvedUpArrow" | "CurvedDownArrow" | "SwooshArrow" | "Cube" | "Can" | "LightningBolt" | "Heart" | "Sun" | "Moon" | "SmileyFace" | "IrregularSeal1" | "IrregularSeal2" | "FoldedCorner" | "Bevel" | "Frame" | "HalfFrame" | "Corner" | "DiagonalStripe" | "Chord" | "Arc" | "LeftBracket" | "RightBracket" | "LeftBrace" | "RightBrace" | "BracketPair" | "BracePair" | "Callout1" | "Callout2" | "Callout3" | "AccentCallout1" | "AccentCallout2" | "AccentCallout3" | "BorderCallout1" | "BorderCallout2" | "BorderCallout3" | "AccentBorderCallout1" | "AccentBorderCallout2" | "AccentBorderCallout3" | "WedgeRectCallout" | "WedgeRRectCallout" | "WedgeEllipseCallout" | "CloudCallout" | "Cloud" | "Ribbon" | "Ribbon2" | "EllipseRibbon" | "EllipseRibbon2" | "LeftRightRibbon" | "VerticalScroll" | "HorizontalScroll" | "Wave" | "DoubleWave" | "Plus" | "FlowChartProcess" | "FlowChartDecision" | "FlowChartInputOutput" | "FlowChartPredefinedProcess" | "FlowChartInternalStorage" | "FlowChartDocument" | "FlowChartMultidocument" | "FlowChartTerminator" | "FlowChartPreparation" | "FlowChartManualInput" | "FlowChartManualOperation" | "FlowChartConnector" | "FlowChartPunchedCard" | "FlowChartPunchedTape" | "FlowChartSummingJunction" | "FlowChartOr" | "FlowChartCollate" | "FlowChartSort" | "FlowChartExtract" | "FlowChartMerge" | "FlowChartOfflineStorage" | "FlowChartOnlineStorage" | "FlowChartMagneticTape" | "FlowChartMagneticDisk" | "FlowChartMagneticDrum" | "FlowChartDisplay" | "FlowChartDelay" | "FlowChartAlternateProcess" | "FlowChartOffpageConnector" | "ActionButtonBlank" | "ActionButtonHome" | "ActionButtonHelp" | "ActionButtonInformation" | "ActionButtonForwardNext" | "ActionButtonBackPrevious" | "ActionButtonEnd" | "ActionButtonBeginning" | "ActionButtonReturn" | "ActionButtonDocument" | "ActionButtonSound" | "ActionButtonMovie" | "Gear6" | "Gear9" | "Funnel" | "MathPlus" | "MathMinus" | "MathMultiply" | "MathDivide" | "MathEqual" | "MathNotEqual" | "CornerTabs" | "SquareTabs" | "PlaqueTabs" | "ChartX" | "ChartStar" | "ChartPlus";

プロパティ値

Excel.GeometricShapeType | "LineInverse" | "Triangle" | "RightTriangle" | "Rectangle" | "Diamond" | "Parallelogram" | "Trapezoid" | "NonIsoscelesTrapezoid" | "Pentagon" | "Hexagon" | "Heptagon" | "Octagon" | "Decagon" | "Dodecagon" | "Star4" | "Star5" | "Star6" | "Star7" | "Star8" | "Star10" | "Star12" | "Star16" | "Star24" | "Star32" | "RoundRectangle" | "Round1Rectangle" | "Round2SameRectangle" | "Round2DiagonalRectangle" | "SnipRoundRectangle" | "Snip1Rectangle" | "Snip2SameRectangle" | "Snip2DiagonalRectangle" | "Plaque" | "Ellipse" | "Teardrop" | "HomePlate" | "Chevron" | "PieWedge" | "Pie" | "BlockArc" | "Donut" | "NoSmoking" | "RightArrow" | "LeftArrow" | "UpArrow" | "DownArrow" | "StripedRightArrow" | "NotchedRightArrow" | "BentUpArrow" | "LeftRightArrow" | "UpDownArrow" | "LeftUpArrow" | "LeftRightUpArrow" | "QuadArrow" | "LeftArrowCallout" | "RightArrowCallout" | "UpArrowCallout" | "DownArrowCallout" | "LeftRightArrowCallout" | "UpDownArrowCallout" | "QuadArrowCallout" | "BentArrow" | "UturnArrow" | "CircularArrow" | "LeftCircularArrow" | "LeftRightCircularArrow" | "CurvedRightArrow" | "CurvedLeftArrow" | "CurvedUpArrow" | "CurvedDownArrow" | "SwooshArrow" | "Cube" | "Can" | "LightningBolt" | "Heart" | "Sun" | "Moon" | "SmileyFace" | "IrregularSeal1" | "IrregularSeal2" | "FoldedCorner" | "Bevel" | "Frame" | "HalfFrame" | "Corner" | "DiagonalStripe" | "Chord" | "Arc" | "LeftBracket" | "RightBracket" | "LeftBrace" | "RightBrace" | "BracketPair" | "BracePair" | "Callout1" | "Callout2" | "Callout3" | "AccentCallout1" | "AccentCallout2" | "AccentCallout3" | "BorderCallout1" | "BorderCallout2" | "BorderCallout3" | "AccentBorderCallout1" | "AccentBorderCallout2" | "AccentBorderCallout3" | "WedgeRectCallout" | "WedgeRRectCallout" | "WedgeEllipseCallout" | "CloudCallout" | "Cloud" | "Ribbon" | "Ribbon2" | "EllipseRibbon" | "EllipseRibbon2" | "LeftRightRibbon" | "VerticalScroll" | "HorizontalScroll" | "Wave" | "DoubleWave" | "Plus" | "FlowChartProcess" | "FlowChartDecision" | "FlowChartInputOutput" | "FlowChartPredefinedProcess" | "FlowChartInternalStorage" | "FlowChartDocument" | "FlowChartMultidocument" | "FlowChartTerminator" | "FlowChartPreparation" | "FlowChartManualInput" | "FlowChartManualOperation" | "FlowChartConnector" | "FlowChartPunchedCard" | "FlowChartPunchedTape" | "FlowChartSummingJunction" | "FlowChartOr" | "FlowChartCollate" | "FlowChartSort" | "FlowChartExtract" | "FlowChartMerge" | "FlowChartOfflineStorage" | "FlowChartOnlineStorage" | "FlowChartMagneticTape" | "FlowChartMagneticDisk" | "FlowChartMagneticDrum" | "FlowChartDisplay" | "FlowChartDelay" | "FlowChartAlternateProcess" | "FlowChartOffpageConnector" | "ActionButtonBlank" | "ActionButtonHome" | "ActionButtonHelp" | "ActionButtonInformation" | "ActionButtonForwardNext" | "ActionButtonBackPrevious" | "ActionButtonEnd" | "ActionButtonBeginning" | "ActionButtonReturn" | "ActionButtonDocument" | "ActionButtonSound" | "ActionButtonMovie" | "Gear6" | "Gear9" | "Funnel" | "MathPlus" | "MathMinus" | "MathMultiply" | "MathDivide" | "MathEqual" | "MathNotEqual" | "CornerTabs" | "SquareTabs" | "PlaqueTabs" | "ChartX" | "ChartStar" | "ChartPlus"

注釈

[ API セット: ExcelApi 1.9 ]

group

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

readonly group: Excel.ShapeGroup;

プロパティ値

Excel.ShapeGroup

注釈

[ API セット: ExcelApi 1.9 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-groups.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");

    const shapeGroup = sheet.shapes.getItem("Group").group;
    shapeGroup.ungroup();
    console.log("Shapes ungrouped");

    await context.sync();
});

height

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

height: number;

プロパティ値

number

注釈

[ API セット: ExcelApi 1.9 ]

id

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

readonly id: string;

プロパティ値

string

注釈

[ API セット: ExcelApi 1.9 ]

image

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

readonly image: Excel.Image;

プロパティ値

Excel.Image

注釈

[ API セット: ExcelApi 1.9 ]

left

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

left: number;

プロパティ値

number

注釈

[ API セット: ExcelApi 1.9 ]

level

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

readonly level: number;

プロパティ値

number

注釈

[ API セット: ExcelApi 1.9 ]

line

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

readonly line: Excel.Line;

プロパティ値

Excel.Line

注釈

[ API セット: ExcelApi 1.9 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-lines.yaml

await Excel.run(async (context) => {
    const shapes = context.workbook.worksheets.getItem("Shapes").shapes;
    const line = shapes.getItem("StraightLine").line;
    line.beginArrowheadLength = Excel.ArrowheadLength.long;
    line.beginArrowheadWidth = Excel.ArrowheadWidth.wide;
    line.beginArrowheadStyle = Excel.ArrowheadStyle.oval;

    line.endArrowheadLength = Excel.ArrowheadLength.long;
    line.endArrowheadWidth = Excel.ArrowheadWidth.wide;
    line.endArrowheadStyle = Excel.ArrowheadStyle.triangle;

    await context.sync();
});

lineFormat

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

readonly lineFormat: Excel.ShapeLineFormat;

プロパティ値

Excel.ShapeLineFormat

注釈

[ API セット: ExcelApi 1.9 ]

lockAspectRatio

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

lockAspectRatio: boolean;

プロパティ値

boolean

注釈

[ API セット: ExcelApi 1.9 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.lockAspectRatio = true;
    shape.scaleHeight(1.25, Excel.ShapeScaleType.currentSize);
    await context.sync();
});

name

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

name: string;

プロパティ値

string

注釈

[ API セット: ExcelApi 1.9 ]

parentGroup

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

readonly parentGroup: Excel.Shape;

プロパティ値

Excel.Shape

注釈

[ API セット: ExcelApi 1.9 ]

placement

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

placement: Excel.Placement | "TwoCell" | "OneCell" | "Absolute";

プロパティ値

Excel.Placement | "TwoCell" | "OneCell" | "Absolute"

注釈

[ API セット: ExcelApi 1.10 ]

rotation

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

rotation: number;

プロパティ値

number

注釈

[ API セット: ExcelApi 1.9 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.addGeometricShape(Excel.GeometricShapeType.triangle);
    shape.left = 100;
    shape.top = 300;
    shape.height = 150;
    shape.width = 200;
    shape.rotation = 45;
    shape.fill.clear();
    await context.sync();
});

textFrame

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

readonly textFrame: Excel.TextFrame;

プロパティ値

Excel.TextFrame

注釈

[ API セット: ExcelApi 1.9 ]

top

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

top: number;

プロパティ値

number

注釈

[ API セット: ExcelApi 1.9 ]

type

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

readonly type: Excel.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line";

プロパティ値

Excel.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line"

注釈

[ API セット: ExcelApi 1.9 ]

visible

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

visible: boolean;

プロパティ値

boolean

注釈

[ API セット: ExcelApi 1.9 ]

width

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

width: number;

プロパティ値

number

注釈

[ API セット: ExcelApi 1.9 ]

zOrderPosition

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

readonly zOrderPosition: number;

プロパティ値

number

注釈

[ API セット: ExcelApi 1.9 ]

メソッドの詳細

copyTo(destinationSheet)

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

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

パラメーター

destinationSheet

Excel.Worksheet | string

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

戻り値

Excel.Shape

注釈

[ API セット: ExcelApi 1.10 ]

delete()

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

delete(): void;

戻り値

void

注釈

[ API セット: ExcelApi 1.9 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-create-and-delete.yaml

await Excel.run(async (context) => {
    context.workbook.worksheets.getItemOrNullObject("Shapes").delete();
    const sheet = context.workbook.worksheets.add("Shapes");

    const shapes = sheet.shapes;

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

    shapes.items.forEach((shape) => shape.delete());
    await context.sync();
});

getAsImage(format)

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

getAsImage(format: Excel.PictureFormat): OfficeExtension.ClientResult<string>;

パラメーター

format

Excel.PictureFormat

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

戻り値

OfficeExtension.ClientResult<string>

注釈

[ API セット: ExcelApi 1.9 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-images.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Image");
    const result = shape.getAsImage(Excel.PictureFormat.png);
    await context.sync();

    const imageString = result.value;
    // Your add-in would save this string as a .png file.
    console.log("The image's Base64-encoded string: " + imageString);
});

getAsImage(formatString)

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

getAsImage(formatString: "UNKNOWN" | "BMP" | "JPEG" | "GIF" | "PNG" | "SVG"): OfficeExtension.ClientResult<string>;

パラメーター

formatString

"UNKNOWN" | "BMP" | "JPEG" | "GIF" | "PNG" | "SVG"

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

戻り値

OfficeExtension.ClientResult<string>

注釈

[ API セット: ExcelApi 1.9 ]

incrementLeft(increment)

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

incrementLeft(increment: number): void;

パラメーター

increment

number

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

戻り値

void

注釈

[ API セット: ExcelApi 1.9 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Square")
    shape.incrementLeft(-25);
    await context.sync();
});

incrementRotation(increment)

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

incrementRotation(increment: number): void;

パラメーター

increment

number

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

戻り値

void

注釈

[ API セット: ExcelApi 1.9 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-images.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Image");
    shape.incrementRotation(180);
    await context.sync();
});

incrementTop(increment)

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

incrementTop(increment: number): void;

パラメーター

increment

number

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

戻り値

void

注釈

[ API セット: ExcelApi 1.9 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Pentagon")
    shape.incrementTop(25);
    await context.sync();
});

load(options)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

load(options?: Excel.Interfaces.ShapeLoadOptions): Excel.Shape;

パラメーター

options

Excel.Interfaces.ShapeLoadOptions

読み込むオブジェクトのプロパティのオプションを提供します。

戻り値

Excel.Shape

load(propertyNames)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

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

パラメーター

propertyNames

string | string[]

読み込むプロパティを指定するコンマ区切り文字列または文字列の配列。

戻り値

Excel.Shape

load(propertyNamesAndPaths)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Shape;

パラメーター

propertyNamesAndPaths

{ select?: string; expand?: string; }

propertyNamesAndPaths.select は、読み込むプロパティを指定するコンマ区切り文字列で propertyNamesAndPaths.expand 、読み込むナビゲーション プロパティを指定するコンマ区切りの文字列です。

戻り値

Excel.Shape

scaleHeight(scaleFactor, scaleType, scaleFrom)

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

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

パラメーター

scaleFactor

number

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

scaleType

Excel.ShapeScaleType

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

scaleFrom

Excel.ShapeScaleFrom

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

戻り値

void

注釈

[ API セット: ExcelApi 1.9 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.lockAspectRatio = true;
    shape.scaleHeight(1.25, Excel.ShapeScaleType.currentSize);
    await context.sync();
});

scaleHeight(scaleFactor, scaleTypeString, scaleFromString)

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

scaleHeight(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): void;

パラメーター

scaleFactor

number

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

scaleTypeString

"CurrentSize" | "OriginalSize"

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

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

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

戻り値

void

注釈

[ API セット: ExcelApi 1.9 ]

scaleWidth(scaleFactor, scaleType, scaleFrom)

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

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

パラメーター

scaleFactor

number

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

scaleType

Excel.ShapeScaleType

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

scaleFrom

Excel.ShapeScaleFrom

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

戻り値

void

注釈

[ API セット: ExcelApi 1.9 ]

scaleWidth(scaleFactor, scaleTypeString, scaleFromString)

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

scaleWidth(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"): void;

パラメーター

scaleFactor

number

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

scaleTypeString

"CurrentSize" | "OriginalSize"

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

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

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

戻り値

void

注釈

[ API セット: ExcelApi 1.9 ]

set(properties, options)

オブジェクトの複数のプロパティを同時に設定します。 適切なプロパティを持つプレーン オブジェクトまたは同じ型の別の API オブジェクトを渡すことができます。

set(properties: Interfaces.ShapeUpdateData, options?: OfficeExtension.UpdateOptions): void;

パラメーター

properties

Excel.Interfaces.ShapeUpdateData

メソッドが呼び出されるオブジェクトのプロパティに等形的に構造化されたプロパティを持つ JavaScript オブジェクト。

options

OfficeExtension.UpdateOptions

properties オブジェクトが読み取り専用プロパティを設定しようとした場合にエラーを抑制するオプションを提供します。

戻り値

void

set(properties)

既存の読み込まれたオブジェクトに基づいて、オブジェクトに複数のプロパティを同時に設定します。

set(properties: Excel.Shape): void;

パラメーター

properties

Excel.Shape

戻り値

void

setZOrder(position)

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

setZOrder(position: Excel.ShapeZOrder): void;

パラメーター

position

Excel.ShapeZOrder

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

戻り値

void

注釈

[ API セット: ExcelApi 1.9 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/44-shape/shape-move-and-order.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Shapes");
    const shape = sheet.shapes.getItem("Octagon")
    shape.setZOrder(Excel.ShapeZOrder.sendBackward);
    await context.sync();
});

setZOrder(positionString)

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

setZOrder(positionString: "BringToFront" | "BringForward" | "SendToBack" | "SendBackward"): void;

パラメーター

positionString

"BringToFront" | "BringForward" | "SendToBack" | "SendBackward"

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

戻り値

void

注釈

[ API セット: ExcelApi 1.9 ]

toJSON()

API オブジェクトが に渡されたときにより便利な出力を提供するために、JavaScript toJSON() メソッドを JSON.stringify()オーバーライドします。 (JSON.stringifyさらに、渡される オブジェクトの メソッドを呼び出 toJSON します)。元の Excel.Shape オブジェクトは API オブジェクトですが、メソッドは、元の toJSON オブジェクトから読み込まれた子プロパティの浅いコピーを含むプレーンな JavaScript オブジェクト (として Excel.Interfaces.ShapeData型指定) を返します。

toJSON(): Excel.Interfaces.ShapeData;

戻り値

Excel.Interfaces.ShapeData

イベントの詳細

onActivated

図形がアクティブになったときに発生します。

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

イベントの種類

OfficeExtension.EventHandlers<Excel.ShapeActivatedEventArgs>

注釈

[ API セット: ExcelApi 1.9 ]

onDeactivated

図形が非アクティブになると発生します。

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

イベントの種類

OfficeExtension.EventHandlers<Excel.ShapeDeactivatedEventArgs>

注釈

[ API セット: ExcelApi 1.9 ]