次の方法で共有

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」をご覧ください。 図形の種類が "GeometrShape" でない場合は、 null を返します。
group

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

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

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

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

メソッド

copyTo(destinationSheet)

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

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

図形をイメージに変換し、イメージを Base64 でエンコードされた文字列として返します。 DPI は 96 です。 サポートされている形式は、 Excel.PictureFormat.BMP、 Excel.PictureFormat.PNG、 Excel.PictureFormat.JPEG、 Excel.PictureFormat.GIFのみです。
getAsImage(formatString)

図形をイメージに変換し、イメージを Base64 でエンコードされた文字列として返します。 DPI は 96 です。 サポートされている形式は、 Excel.PictureFormat.BMP、 Excel.PictureFormat.PNG、 Excel.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 オブジェクトがJSON.stringify()に渡されたときにより便利な出力を提供するために、JavaScript toJSON() メソッドをオーバーライドします。 (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」をご覧ください。 図形の種類が "GeometrShape" でない場合は、 null を返します。

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

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

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

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

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)

図形をイメージに変換し、イメージを Base64 でエンコードされた文字列として返します。 DPI は 96 です。 サポートされている形式は、 Excel.PictureFormat.BMP、 Excel.PictureFormat.PNG、 Excel.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)

図形をイメージに変換し、イメージを Base64 でエンコードされた文字列として返します。 DPI は 96 です。 サポートされている形式は、 Excel.PictureFormat.BMP、 Excel.PictureFormat.PNG、 Excel.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 オブジェクトがJSON.stringify()に渡されたときにより便利な出力を提供するために、JavaScript toJSON() メソッドをオーバーライドします。 (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 ]