Word.ShapeCollection class
Enthält eine Sammlung von Word. Gestalten von Objekten. Derzeit werden nur die folgenden Formen unterstützt: Textfelder, geometrische Formen, Gruppen, Bilder und Leinwände.
- Extends
Hinweise
Verwendet von
- Word. Textkörper: Formen
- Word. Leinwand: Formen
- Word. Absatz: Formen
- Word. Bereich: Formen
- Word. ShapeGroup: Formen, Gruppierung aufheben
Beispiele
// 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 boxes in the main document.
const shapes: Word.ShapeCollection = context.document.body.shapes;
shapes.load();
await context.sync();
if (shapes.items.length > 0) {
console.log(`Number of shapes found in the main document: ${shapes.items.length}`);
shapes.items.forEach(function (shape, index) {
if (shape.type === Word.ShapeType.textBox) {
console.log(`Shape ${index} in the main document has a text box. Properties:`, shape);
} else {
console.log(`Shape ${index} in the main document doesn't have a text box.`);
}
});
} else {
console.log("No shapes found in the main document.");
}
});
Eigenschaften
| context | Der dem Objekt zugeordnete Anforderungskontext. Dadurch wird der Prozess des Add-Ins mit dem Prozess der Office-Hostanwendung verbunden. |
| items | Ruft die geladenen untergeordneten Elemente in dieser Sammlung ab. |
Methoden
| get |
Ruft die Shapes ab, die die angegebenen geometrischen Typen aufweisen. Wird nur auf geometrische Formen angewendet. |
| get |
Ruft eine Form anhand ihres Bezeichners ab. Gibt einen |
| get |
Ruft eine Form anhand ihres Bezeichners ab. Wenn es in dieser Auflistung keine Form mit dem Bezeichner gibt, gibt diese Methode ein Objekt zurück, dessen |
| get |
Ruft die Formen anhand der Bezeichner ab. |
| get |
Ruft die Shapes mit den angegebenen Namen ab. |
| get |
Ruft die Shapes mit den angegebenen Typen ab. |
| get |
Erhält die erste Form in dieser Sammlung. Gibt einen |
| get |
Erhält die erste Form in dieser Sammlung. Wenn diese Sammlung leer ist, gibt diese Methode ein Objekt zurück, dessen |
| group() | Gruppiert schwebende Formen in dieser Sammlung, Inline-Formen werden übersprungen. Gibt ein |
| load(options) | Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie " |
| load(property |
Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie " |
| load(property |
Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie " |
| toJSON() | Überschreibt die JavaScript-Methode |
| track() | Nachverfolgung des Objekts zwecks automatischer Anpassung auf der Grundlage der umgebenden Änderungen im Dokument. Dieser Aufruf ist eine Kurzform für context.trackedObjects.add(thisObject). Wenn Sie dieses Objekt aufrufübergreifend |
| untrack() | Gibt den diesem Objekt zugewiesenen Arbeitsspeicher frei, wenn das Objekt zuvor nachverfolgt wurde. Dieser Aufruf ist die Kurzform für context.trackedObjects.remove(thisObject). Viele nachverfolgte Objekte verlangsamen die Ausführung der Hostanwendung, also achten Sie darauf, alle hinzugefügten Objekte nach abgeschlossener Verwendung freizugeben. Sie müssen einen Aufruf durchführen |
Details zur Eigenschaft
context
Der dem Objekt zugeordnete Anforderungskontext. Dadurch wird der Prozess des Add-Ins mit dem Prozess der Office-Hostanwendung verbunden.
context: RequestContext;Eigenschaftswert
items
Ruft die geladenen untergeordneten Elemente in dieser Sammlung ab.
readonly items: Word.Shape[];Eigenschaftswert
Details zur Methode
getByGeometricTypes(types)
Ruft die Shapes ab, die die angegebenen geometrischen Typen aufweisen. Wird nur auf geometrische Formen angewendet.
getByGeometricTypes(types: Word.GeometricShapeType[]): Word.ShapeCollection;Parameter
- types
Ein Array von Untertypen geometrischer Formen.
Gibt zurück
Hinweise
Beispiele
// 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);
});
getById(id)
Ruft eine Form anhand ihres Bezeichners ab. Gibt einen ItemNotFound Fehler aus, wenn in dieser Auflistung keine Form mit dem Bezeichner vorhanden ist.
getById(id: number): Word.Shape;Parameter
- id
-
number
Ein Formbezeichner.
Gibt zurück
Hinweise
getByIdOrNullObject(id)
Ruft eine Form anhand ihres Bezeichners ab. Wenn es in dieser Auflistung keine Form mit dem Bezeichner gibt, gibt diese Methode ein Objekt zurück, dessen isNullObject Eigenschaft auf festgelegt ist true. Weitere Informationen finden Sie unter *OrNullObject-Methoden und -Eigenschaften.
getByIdOrNullObject(id: number): Word.Shape;Parameter
- id
-
number
Ein Formbezeichner.
Gibt zurück
Hinweise
getByIds(ids)
Ruft die Formen anhand der Bezeichner ab.
getByIds(ids: number[]): Word.ShapeCollection;Parameter
- ids
-
number[]
Ein Array von Formbezeichnern.
Gibt zurück
Hinweise
getByNames(names)
Ruft die Shapes mit den angegebenen Namen ab.
getByNames(names: string[]): Word.ShapeCollection;Parameter
- names
-
string[]
Ein Array von Formnamen.
Gibt zurück
Hinweise
getByTypes(types)
Ruft die Shapes mit den angegebenen Typen ab.
getByTypes(types: Word.ShapeType[]): Word.ShapeCollection;Parameter
- types
Ein Array von Formtypen.
Gibt zurück
Hinweise
Beispiele
// 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);
});
getFirst()
Erhält die erste Form in dieser Sammlung. Gibt einen ItemNotFound Fehler aus, wenn diese Sammlung leer ist.
getFirst(): Word.Shape;Gibt zurück
Hinweise
Beispiele
// 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);
});
getFirstOrNullObject()
Erhält die erste Form in dieser Sammlung. Wenn diese Sammlung leer ist, gibt diese Methode ein Objekt zurück, dessen isNullObject Eigenschaft auf festgelegt ist true. Weitere Informationen finden Sie unter *OrNullObject-Methoden und -Eigenschaften.
getFirstOrNullObject(): Word.Shape;Gibt zurück
Hinweise
Beispiele
// 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}`
);
});
group()
Gruppiert schwebende Formen in dieser Sammlung, Inline-Formen werden übersprungen. Gibt ein Shape Objekt zurück, das die neue Gruppe von Formen darstellt.
group(): Word.Shape;Gibt zurück
Hinweise
Beispiele
// 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();
});
load(options)
Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "context.sync()" aufrufen.
load(options?: Word.Interfaces.ShapeCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions): Word.ShapeCollection;Parameter
Stellt Optionen für die zu ladenden Eigenschaften des Objekts bereit.
Gibt zurück
load(propertyNames)
Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "context.sync()" aufrufen.
load(propertyNames?: string | string[]): Word.ShapeCollection;Parameter
- propertyNames
-
string | string[]
Eine durch Trennzeichen getrennte Zeichenfolge oder ein Array von Zeichenfolgen, die die zu ladenden Eigenschaften angeben.
Gibt zurück
load(propertyNamesAndPaths)
Stellt einen Befehl zum Laden der angegebenen Eigenschaften des Objekts in die Warteschlange ein. Vor dem Lesen der Eigenschaften müssen Sie "context.sync()" aufrufen.
load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Word.ShapeCollection;Parameter
- propertyNamesAndPaths
- OfficeExtension.LoadOption
propertyNamesAndPaths.select ist eine durch Kommas getrennte Zeichenfolge, die die zu ladenden Eigenschaften angibt, und propertyNamesAndPaths.expand eine durch Kommas getrennte Zeichenfolge, die die zu ladenden Navigationseigenschaften angibt.
Gibt zurück
toJSON()
Überschreibt die JavaScript-Methode toJSON() , um eine nützlichere Ausgabe bereitzustellen, wenn ein API-Objekt an JSON.stringify()übergeben wird. (JSON.stringifyruft wiederum die toJSON Methode des Objekts auf, das an sie übergeben wird.) Während das ursprüngliche Word.ShapeCollection Objekt ein API-Objekt ist, gibt die toJSON Methode ein einfaches JavaScript-Objekt (typisiert als Word.Interfaces.ShapeCollectionData) zurück, das ein "items"-Array mit flachen Kopien aller geladenen Eigenschaften aus den Elementen der Sammlung enthält.
toJSON(): Word.Interfaces.ShapeCollectionData;Gibt zurück
track()
Nachverfolgung des Objekts zwecks automatischer Anpassung auf der Grundlage der umgebenden Änderungen im Dokument. Dieser Aufruf ist eine Kurzform für context.trackedObjects.add(thisObject). Wenn Sie dieses Objekt aufrufübergreifend .sync und außerhalb der sequenziellen Ausführung eines ".run"-Batches verwenden und beim Festlegen einer Eigenschaft oder beim Aufrufen einer Methode für das Objekt ein "InvalidObjectPath"-Fehler angezeigt wird, müssen Sie das Objekt der nachverfolgten Objektsammlung hinzufügen, wenn das Objekt zum ersten Mal erstellt wurde. Wenn dieses Objekt Teil einer Sammlung ist, sollten Sie auch die übergeordnete Sammlung nachverfolgen.
track(): Word.ShapeCollection;Gibt zurück
untrack()
Gibt den diesem Objekt zugewiesenen Arbeitsspeicher frei, wenn das Objekt zuvor nachverfolgt wurde. Dieser Aufruf ist die Kurzform für context.trackedObjects.remove(thisObject). Viele nachverfolgte Objekte verlangsamen die Ausführung der Hostanwendung, also achten Sie darauf, alle hinzugefügten Objekte nach abgeschlossener Verwendung freizugeben. Sie müssen einen Aufruf durchführen context.sync() , bevor die Speicherfreigabe wirksam wird.
untrack(): Word.ShapeCollection;