Power Point. Shape class

altTextDescription

図形の代替テキストの説明。

代替テキストは、図形に含まれる情報の代替テキストベースの表現を提供します。この情報は、視覚障碍や認知障碍を持つユーザーが、その形を確認または理解できない場合に役立ちます。

altTextDescription: string;

プロパティ値

string

注釈

altTextTitle

図形の代替テキストタイトル。

代替テキストは、図形に含まれる情報の代替テキストベースの表現を提供します。この情報は、視覚障碍や認知障碍を持つユーザーが、その形を確認または理解できない場合に役立ちます。タイトルは、障害のある人に読み取ることができ、コンテンツの説明を聞きたいかどうかを判断するために使用されます。

altTextTitle: string;

プロパティ値

string

注釈

context

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

context: RequestContext;

プロパティ値

PowerPoint.RequestContext

creationId

図形の作成 ID を取得します。図形に作成 ID がない場合は、 null を返します。

readonly creationId: string | null;

プロパティ値

string | null

注釈

customXmlParts

図形内のカスタム XML パーツのコレクションを返します。

readonly customXmlParts: PowerPoint.CustomXmlPartCollection;

プロパティ値

PowerPoint.CustomXmlPartCollection

注釈

[ API set: PowerPointApi 1.7 ]

fill

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

readonly fill: PowerPoint.ShapeFill;

プロパティ値

PowerPoint.ShapeFill

注釈

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Changes the selected shapes fill color to red.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items/fill/type");
  await context.sync();
  shapes.items.map((shape) => {
    const shapeFillType = shape.fill.type as PowerPoint.ShapeFillType;
    console.log(`Shape ID ${shape.id} original fill type: ${shapeFillType}`);
    shape.fill.setSolidColor("red");
  });
  await context.sync();
});

group

図形に関連付けられている ShapeGroup を返します。図形の種類が groupされていない場合、このメソッドは GeneralException エラーを返します。

readonly group: PowerPoint.ShapeGroup;

プロパティ値

PowerPoint.ShapeGroup

注釈

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/group-ungroup-shapes.yaml

await PowerPoint.run(async (context) => {
  // Ungroups the first shape group on the current slide.

  // Get the shapes on the current slide.
  context.presentation.load("slides");
  const slide: PowerPoint.Slide = context.presentation.getSelectedSlides().getItemAt(0);
  slide.load("shapes/items/type,shapes/items/id");
  await context.sync();

  const shapes: PowerPoint.ShapeCollection = slide.shapes;
  const shapeGroups = shapes.items.filter((item) => item.type === PowerPoint.ShapeType.group);
  if (shapeGroups.length === 0) {
    console.warn("No shape groups on the current slide, so nothing to ungroup.");
    return;
  }

  // Ungroup the first grouped shapes.
  const firstGroupId = shapeGroups[0].id;
  const shapeGroupToUngroup = shapes.getItem(firstGroupId);
  shapeGroupToUngroup.group.ungroup();
  await context.sync();

  console.log(`Ungrouped shapes with group ID: ${firstGroupId}`);
});

height

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

height: number;

プロパティ値

number

注釈

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

id

図形の一意の ID を取得します。

readonly id: string;

プロパティ値

string

注釈

[ API セット: PowerPointApi 1.3 ]

isDecorative

図形が装飾的かどうかを表します。

装飾的なオブジェクトは視覚的な興味を引きますが、情報的ではありません (文体の境界線など)。スクリーンリーダーを使用するPeopleは、重要な情報が見つからないことを知っているので、これらは装飾的だと聞こえます。

isDecorative: boolean;

プロパティ値

boolean

注釈

left

図形の左側からスライドの左側までの距離をポイント単位で指定します。

left: number;

プロパティ値

number

注釈

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

level

指定した図形のレベルを返します。

レベル 0 は、図形がグループの一部ではないことを意味します。
レベル 1 は、図形が最上位グループの一部であることを意味します。
1 より大きいレベルは、図形が入れ子になったグループであることを示します。

readonly level: number;

プロパティ値

number

注釈

lineFormat

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

readonly lineFormat: PowerPoint.ShapeLineFormat;

プロパティ値

PowerPoint.ShapeLineFormat

注釈

name

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

name: string;

プロパティ値

string

注釈

parentGroup

この図形の親グループを返します。図形がグループの一部でない場合、このメソッドは GeneralException エラーを返します。

readonly parentGroup: PowerPoint.Shape;

プロパティ値

PowerPoint.Shape

注釈

placeholderFormat

このプレースホルダーに特に適用されるプロパティを返します。図形の種類が placeholderされていない場合、このメソッドは GeneralException エラーを返します。

readonly placeholderFormat: PowerPoint.PlaceholderFormat;

プロパティ値

PowerPoint.PlaceholderFormat

注釈

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-shapes-by-type.yaml

// Gets the placeholder shapes in the slide.
await PowerPoint.run(async (context) => {
  // Get properties for every shape in the collection.
  const shapes: PowerPoint.ShapeCollection = context.presentation.slides.getItemAt(0).shapes;
  shapes.load("type,name");
  await context.sync();

  const placeholderShapes = [];
  console.log(`Number of shapes found: ${shapes.items.length}`);
  shapes.items.forEach((shape) => {
    if (shape.type === PowerPoint.ShapeType.placeholder) {
      // Load placeholderFormat property.
      // PowerPoint throws an exception if you try to load this property on a shape that isn't a placeholder type.
      shape.load("placeholderFormat");
      placeholderShapes.push(shape);
    }
  });
  await context.sync();

  console.log(`Number of placeholder shapes found: ${placeholderShapes.length}`);
  for (let i = 0; i < placeholderShapes.length; i++) {
    let currentPlaceholder: PowerPoint.PlaceholderFormat = placeholderShapes[i].placeholderFormat;
    let placeholderType = currentPlaceholder.type as PowerPoint.PlaceholderType;
    let placeholderContainedType = currentPlaceholder.containedType as PowerPoint.ShapeType;
    console.log(`Shape "${placeholderShapes[i].name}" placeholder properties:`);
    console.log(`\ttype: ${placeholderType}`);
    console.log(`\tcontainedType: ${placeholderContainedType}`);
  }
});

rotation

z 軸を中心とする図形の回転を度単位で指定します。正の値は時計回りの回転を示し、負の値は反時計回りの回転を示します。

rotation: number;

プロパティ値

number

注釈

textFrame

このShapeの PowerPoint.TextFrame オブジェクトを返します。図形がTextFrameをサポートしていない場合は、InvalidArgument例外をスローします。

readonly textFrame: PowerPoint.TextFrame;

プロパティ値

PowerPoint.TextFrame

注釈

top

図形の上端からスライドの上端までの距離をポイント単位で指定します。

top: number;

プロパティ値

number

注釈

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

type

この図形の種類を返します。詳細については、「PowerPoint.ShapeType 」を参照してください。

readonly type: PowerPoint.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line" | "Table" | "Callout" | "Chart" | "ContentApp" | "Diagram" | "Freeform" | "Graphic" | "Ink" | "Media" | "Model3D" | "Ole" | "Placeholder" | "SmartArt" | "TextBox";

プロパティ値

注釈

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-shapes-by-type.yaml

// Changes the transparency of every geometric shape in the slide.
await PowerPoint.run(async (context) => {
  // Get the type of shape for every shape in the collection.
  const shapes: PowerPoint.ShapeCollection = context.presentation.slides.getItemAt(0).shapes;
  shapes.load("type");
  await context.sync();

  // Change the shape transparency to be halfway transparent.
  shapes.items.forEach((shape) => {
    if (shape.type === PowerPoint.ShapeType.geometricShape) {
      shape.fill.transparency = 0.5;
    }
  });
  await context.sync();
});

visible

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

visible: boolean;

プロパティ値

boolean

注釈

width

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

width: number;

プロパティ値

number

注釈

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

zOrderPosition

図形の z オーダー位置を返し、0 は注文スタックの下部を表します。スライド上のすべての図形には一意の z オーダーがありますが、各スライドには一意の z オーダースタックもあります。そのため、個別のスライド上の 2 つの図形は同じ z オーダー番号を持つことができます。

readonly zOrderPosition: number;

プロパティ値

number

注釈

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/binding-to-shapes.yaml

async function changeZOrder(operation: PowerPoint.ShapeZOrder) {
  // Changes the z-order position of the selected shapes.
  return PowerPoint.run(async (context) => {
    const selectedShapes = context.presentation.getSelectedShapes();
    selectedShapes.load();
    await context.sync();

    if (selectedShapes.items.length === 0) {
      console.log("No shapes are selected.");
    } else {
      let direction = 1; // Start with bottom-most (lowest number).

      // Start with top-most when sending to back or bringing forward.

      switch (operation) {
        case PowerPoint.ShapeZOrder.bringForward:

        case PowerPoint.ShapeZOrder.sendToBack:
          direction = -1; // Reverse direction.

          break;
      }

      // Change the z-order position for each of the selected shapes,

      // starting with the bottom-most when bringing to front or sending backward,

      // or top-most when sending to back or bringing forward,

      // so the selected shapes retain their relative z-order positions after they're changed.

      selectedShapes.items
        .sort((a, b) => (a.zOrderPosition - b.zOrderPosition) * direction)
        .forEach((shape) => {
          try {
            const originalZOrderPosition = shape.zOrderPosition;
            shape.setZOrder(operation);

            console.log(`Changed z-order of shape ${shape.id}.`);
          } catch (err) {
            console.log(`Unable to change z-order of shape ${shape.id}. ${err.message}`);
          }
        });

      await context.sync();
    }
  });
}

メソッドの詳細

delete()

図形コレクションから図形を削除します。図形が存在しない場合は何も行いません。

delete(): void;

戻り値

void

注釈

[ API セット: PowerPointApi 1.3 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/shapes.yaml

// This function gets the collection of shapes on the first slide,
// and then iterates through them, deleting each one.
await PowerPoint.run(async (context) => {
  const slide: PowerPoint.Slide = context.presentation.slides.getItemAt(0);
  const shapes: PowerPoint.ShapeCollection = slide.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();
});

getImageAsBase64(options)

図形のイメージをレンダリングします。

getImageAsBase64(options?: PowerPoint.ShapeGetImageOptions): OfficeExtension.ClientResult<string>;

パラメーター

options: PowerPoint.ShapeGetImageOptions

省略可能。目的の出力イメージプロパティを指定するオプション。

戻り値

OfficeExtension.ClientResult<string>

指定した形式の図形イメージの Base64 でエンコードされた文字列。

注釈

getParentSlide()

このShapeを保持する親PowerPoint.Slide オブジェクトを返します。この図形が Slideに属していない場合は、例外をスローします。

getParentSlide(): PowerPoint.Slide;

戻り値

PowerPoint.Slide

注釈

getParentSlideLayout()

このShapeを保持する親PowerPoint.SlideLayout オブジェクトを返します。この図形が SlideLayoutに属していない場合は、例外をスローします。

getParentSlideLayout(): PowerPoint.SlideLayout;

戻り値

PowerPoint.SlideLayout

注釈

getParentSlideLayoutOrNullObject()

このShapeを保持する親PowerPoint.SlideLayout オブジェクトを返します。この図形が SlideLayoutに属していない場合は、 isNullObject プロパティが true に設定されたオブジェクトが返されます。詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。

getParentSlideLayoutOrNullObject(): PowerPoint.SlideLayout;

戻り値

PowerPoint.SlideLayout

注釈

getParentSlideMaster()

このShapeを保持する親PowerPoint.SlideMaster オブジェクトを返します。この図形が SlideMasterに属していない場合は、例外をスローします。

getParentSlideMaster(): PowerPoint.SlideMaster;

戻り値

PowerPoint.SlideMaster

注釈

getParentSlideMasterOrNullObject()

このShapeを保持する親PowerPoint.SlideMaster オブジェクトを返します。この図形が SlideMasterに属していない場合は、 isNullObject プロパティが true に設定されたオブジェクトが返されます。詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。

getParentSlideMasterOrNullObject(): PowerPoint.SlideMaster;

戻り値

PowerPoint.SlideMaster

注釈

getParentSlideOrNullObject()

このShapeを保持する親PowerPoint.Slide オブジェクトを返します。この図形が Slideに属していない場合は、 isNullObject プロパティが true に設定されたオブジェクトが返されます。詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。

getParentSlideOrNullObject(): PowerPoint.Slide;

戻り値

PowerPoint.Slide

注釈

getTable()

この図形がテーブルの場合は、 Table オブジェクトを返します。

getTable(): PowerPoint.Table;

戻り値

PowerPoint.Table

注釈

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/add-modify-tables.yaml

// Gets the table from a shape.
await PowerPoint.run(async (context) => {
  const shapes = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();

  if (shapeCount.value > 0) {
    const shape = shapes.getItemAt(0);
    shape.load("type");
    await context.sync();

    // The shape type can indicate whether the shape is a table.
    const isTable = shape.type === PowerPoint.ShapeType.table;

    if (isTable) {
      // Get the Table object for the Shape which is a table.
      const table = shape.getTable();
      table.load();
      await context.sync();

      // Get the Table row and column count.
      console.log("Table RowCount: " + table.rowCount + " and columnCount: " + table.columnCount);
    } else console.log("Selected shape isn't table.");
  } else console.log("No shape selected.");
});

getTextFrameOrNullObject()

このShapeの PowerPoint.TextFrame オブジェクトを返します。図形が TextFrameをサポートしていない場合は、 isNullObject プロパティが true に設定されたオブジェクトが返されます。詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。

getTextFrameOrNullObject(): PowerPoint.TextFrame;

戻り値

PowerPoint.TextFrame

注釈

load(options)

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

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

パラメーター

options: PowerPoint.Interfaces.ShapeLoadOptions

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

戻り値

PowerPoint.Shape

load(propertyNames)

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

パラメーター

propertyNames: string | string[]

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

戻り値

PowerPoint.Shape

load(propertyNamesAndPaths)

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

パラメーター

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

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

戻り値

PowerPoint.Shape

setHyperlink(options)

指定したオプションを使用して、この Shape のハイパーリンクを設定します。これにより、この Shape上の既存のハイパーリンクが削除されます。

setHyperlink(options?: PowerPoint.HyperlinkAddOptions): PowerPoint.Hyperlink;

パラメーター

options: PowerPoint.HyperlinkAddOptions

省略可能。ハイパーリンクのオプション。

戻り値

PowerPoint.Hyperlink

新しく作成された PowerPoint.Hyperlink オブジェクト。

注釈

setZOrder(position)

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

setZOrder(position: PowerPoint.ShapeZOrder): void;

パラメーター

position: PowerPoint.ShapeZOrder

z オーダースタック内で図形を移動する方法を指定します。 ShapeZOrder列挙型を使用します。

戻り値

void

注釈

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/binding-to-shapes.yaml

async function changeZOrder(operation: PowerPoint.ShapeZOrder) {
  // Changes the z-order position of the selected shapes.
  return PowerPoint.run(async (context) => {
    const selectedShapes = context.presentation.getSelectedShapes();
    selectedShapes.load();
    await context.sync();

    if (selectedShapes.items.length === 0) {
      console.log("No shapes are selected.");
    } else {
      let direction = 1; // Start with bottom-most (lowest number).

      // Start with top-most when sending to back or bringing forward.

      switch (operation) {
        case PowerPoint.ShapeZOrder.bringForward:

        case PowerPoint.ShapeZOrder.sendToBack:
          direction = -1; // Reverse direction.

          break;
      }

      // Change the z-order position for each of the selected shapes,

      // starting with the bottom-most when bringing to front or sending backward,

      // or top-most when sending to back or bringing forward,

      // so the selected shapes retain their relative z-order positions after they're changed.

      selectedShapes.items
        .sort((a, b) => (a.zOrderPosition - b.zOrderPosition) * direction)
        .forEach((shape) => {
          try {
            const originalZOrderPosition = shape.zOrderPosition;
            shape.setZOrder(operation);

            console.log(`Changed z-order of shape ${shape.id}.`);
          } catch (err) {
            console.log(`Unable to change z-order of shape ${shape.id}. ${err.message}`);
          }
        });

      await context.sync();
    }
  });
}

setZOrder(position)

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

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

パラメーター

position: "BringForward" | "BringToFront" | "SendBackward" | "SendToBack"

z オーダースタック内で図形を移動する方法を指定します。 ShapeZOrder列挙型を使用します。

戻り値

void

注釈