Word.ShapeCollection class

与 对象关联的请求上下文。 这会将加载项的进程连接到 Office 主机应用程序的进程。

context: RequestContext;

属性值

获取此集合中已加载的子项。

readonly items: Word.Shape[];

属性值

获取具有指定几何类型的形状。 仅适用于几何形状。

getByGeometricTypes(types: Word.GeometricShapeType[]): Word.ShapeCollection;

参数

返回

注解

[ API 集：WordApiDesktop 1.2 ]

示例

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

await Word.run(async (context) => {
  // Gets the moon geometric shapes from the document body.
  const moons: Word.ShapeCollection = context.document.body.shapes.getByGeometricTypes([
    Word.GeometricShapeType.moon,
  ]);
  moons.load();
  await context.sync();

  console.log("Moons found in the document body:", moons);
});

按标识符获取形状。 ItemNotFound如果此集合中没有带有标识符的形状，则引发错误。

getById(id: number): Word.Shape;

参数

返回

注解

[ API 集：WordApiDesktop 1.2 ]

按标识符获取形状。 如果此集合中没有具有标识符的形状，则此方法将返回其属性设置为 true的对象isNullObject。 有关详细信息，请参阅 *OrNullObject 方法和属性。

getByIdOrNullObject(id: number): Word.Shape;

参数

返回

注解

[ API 集：WordApiDesktop 1.2 ]

按标识符获取形状。

getByIds(ids: number[]): Word.ShapeCollection;

参数

返回

注解

[ API 集：WordApiDesktop 1.2 ]

获取具有指定名称的形状。

getByNames(names: string[]): Word.ShapeCollection;

参数

返回

注解

[ API 集：WordApiDesktop 1.2 ]

获取具有指定类型的形状。

getByTypes(types: Word.ShapeType[]): Word.ShapeCollection;

参数

返回

注解

[ API 集：WordApiDesktop 1.2 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/45-shapes/manage-shapes-text-boxes.yaml

await Word.run(async (context) => {
  // Sets the properties of the first text box.
  const firstShapeWithTextBox: Word.Shape = context.document.body.shapes
    .getByTypes([Word.ShapeType.textBox])
    .getFirst();
  firstShapeWithTextBox.top = 115;
  firstShapeWithTextBox.left = 0;
  firstShapeWithTextBox.width = 50;
  firstShapeWithTextBox.height = 50;
  await context.sync();

  console.log("The first text box's properties were updated:", firstShapeWithTextBox);
});

获取此集合中的第一个形状。 如果此集合为空， ItemNotFound 则引发错误。

getFirst(): Word.Shape;

返回

注解

[ API 集：WordApiDesktop 1.2 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/45-shapes/manage-shapes-text-boxes.yaml

await Word.run(async (context) => {
  // Inserts a content control into the first paragraph in the first text box.
  const firstShapeWithTextBox: Word.Shape = context.document.body.shapes
    .getByTypes([Word.ShapeType.textBox])
    .getFirst();
  firstShapeWithTextBox.load("type/body");
  await context.sync();

  const firstParagraphInTextBox: Word.Paragraph = firstShapeWithTextBox.body.paragraphs.getFirst();
  const newControl: Word.ContentControl = firstParagraphInTextBox.insertContentControl();
  newControl.load();
  await context.sync();

  console.log("New content control properties:", newControl);
});

获取此集合中的第一个形状。 如果此集合为空，则此方法将返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。

getFirstOrNullObject(): Word.Shape;

返回

注解

[ API 集：WordApiDesktop 1.2 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/45-shapes/manage-shapes-text-boxes.yaml

await Word.run(async (context) => {
  // Gets text from the first text box in the main document.
  const shape: Word.Shape = context.document.body.shapes.getByTypes([Word.ShapeType.textBox]).getFirstOrNullObject();
  shape.load("body/text");
  await context.sync();

  console.log(
    shape.isNullObject
      ? "No shapes with text boxes found in the main document."
      : `Text in first text box: ${shape.body.text}`
  );
});

在此集合中对浮动形状进行分组，将跳过内联形状。 返回一个 Shape 对象，该对象代表新的形状组。

group(): Word.Shape;

返回

注解

[ API 集：WordApiDesktop 1.2 ]

示例

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

await Word.run(async (context) => {
  // Groups the shapes (including text boxes and pictures) found in the document body.
  const shapes: Word.ShapeCollection = context.document.body.shapes.getByTypes([
    Word.ShapeType.geometricShape,
    Word.ShapeType.textBox,
    Word.ShapeType.picture,
  ]);
  shapes.load("items");
  await context.sync();

  const numShapes = shapes.items.length;
  if (numShapes === 0) {
    console.log("No shapes found in the document body.");
    return;
  }

  console.log(`Number of shapes to group: ${numShapes}`);

  const groupedShape: Word.Shape = shapes.group();
  groupedShape.load("shapeGroup/shapes");
  await context.sync();

  const shapeGroup: Word.ShapeGroup = groupedShape.shapeGroup;
  console.log("Shapes grouped:", shapeGroup.shapes);
  groupedShape.select();
});

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(options?: Word.Interfaces.ShapeCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions): Word.ShapeCollection;

参数

返回

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(propertyNames?: string | string[]): Word.ShapeCollection;

参数

返回

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Word.ShapeCollection;

参数

返回

重写 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 JSON.stringify (，反过来，调用toJSON传递给它的 对象的 方法。) 而原始Word.ShapeCollection对象是 API 对象，toJSON该方法返回一个纯 JavaScript 对象， (类型为 Word.Interfaces.ShapeCollectionData) ，其中包含一个“items”数组，其中包含集合项中任何已加载属性的浅表副本。

toJSON(): Word.Interfaces.ShapeCollectionData;

返回

根据文档中的相应更改来跟踪对象，以便进行自动调整。 此调用是 context.trackedObjects.add (thisObject) 的简写。 如果跨 .sync 调用和“.run”批处理的顺序执行外部使用此对象，并在设置属性或调用对象方法时收到“InvalidObjectPath”错误，则需要在首次创建对象时将该对象添加到跟踪的对象集合。 如果此对象是集合的一部分，则还应跟踪父集合。

track(): Word.ShapeCollection;

返回

释放与此对象关联的内存（如果先前已跟踪过）。 此调用是 context.trackedObjects.remove (thisObject) 的简写。 拥有许多跟踪对象会降低主机应用程序的速度，因此请在使用完毕后释放所添加的任何对象。 在内存发布生效之前，需要调用 context.sync() 。

untrack(): Word.ShapeCollection;

返回