Excel.Shape class

Representa um objeto Shape genérico na planilha. Uma forma pode ser uma forma geométrica, uma linha, um grupo de formas, etc. Para saber mais sobre o modelo de objeto Shape, leia trabalhar com formas usando a API JavaScript do Excel.

[Conjunto de APIs: ExcelApi 1,9]

Extends

Propriedades

altTextDescription

Especifica o texto de descrição alternativa para um objeto Shape.

[Conjunto de APIs: ExcelApi 1,9]

altTextTitle

Especifica o texto de título alternativo para um objeto Shape.

[Conjunto de APIs: ExcelApi 1,9]

connectionSiteCount

Retorna o número de locais de conexão nessa forma.

[Conjunto de APIs: ExcelApi 1,9]

context

O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host do Office.

fill

Retorna a formatação de preenchimento dessa forma.

[Conjunto de APIs: ExcelApi 1,9]

geometricShape

Retorna a forma geométrica associada à forma. Um erro será lançado, se o tipo de forma não for "GeometricShape".

[Conjunto de APIs: ExcelApi 1,9]

geometricShapeType

Especifica o tipo de forma geométrica dessa forma geométrica. Para saber detalhes, confira Excel.GeometricShapeType. Retorna nulo se o tipo de forma não for "GeometricShape".

[Conjunto de APIs: ExcelApi 1,9]

group

Retorna o grupo de forma associado à forma. Um erro será lançado, se o tipo de forma não for "GroupShape".

[Conjunto de APIs: ExcelApi 1,9]

height

Especifica a altura, em pontos, da forma. Gera uma exceção de argumento inválida quando definida com um valor negativo ou zero como entrada.

[Conjunto de APIs: ExcelApi 1,9]

id

Especifica o identificador da forma.

[Conjunto de APIs: ExcelApi 1,9]

image

Retorna a imagem associada à forma. Um erro será lançado, se o tipo de forma não for "Imagem".

[Conjunto de APIs: ExcelApi 1,9]

left

A distância, em pontos, da lateral esquerda da forma do lado esquerdo da planilha. Gera uma exceção de argumento inválida quando definida com um valor negativo como entrada.

[Conjunto de APIs: ExcelApi 1,9]

level

Especifica o nível da forma especificada. Por exemplo, um nível de 0 significa que a forma não faz parte de nenhum grupo, um nível de 1 significa que a forma é parte de um grupo de nível superior e um nível 2 significa que a forma faz parte de um subgrupo do nível superior.

[Conjunto de APIs: ExcelApi 1,9]

line

Retorna a linha associada à forma. Um erro será lançado, se o tipo de forma não for "Linha".

[Conjunto de APIs: ExcelApi 1,9]

lineFormat

Retorna a formatação de linha do objeto de forma.

[Conjunto de APIs: ExcelApi 1,9]

lockAspectRatio

Especifica se a taxa de proporção desta forma está bloqueada.

[Conjunto de APIs: ExcelApi 1,9]

name

Especifica o nome da forma.

[Conjunto de APIs: ExcelApi 1,9]

parentGroup

Especifica o grupo pai desta forma.

[Conjunto de APIs: ExcelApi 1,9]

placement

Representa como o objeto é anexado às células abaixo dela.

[Conjunto de APIs: ExcelApi 1,10]

rotation

Especifica a rotação, em graus, da forma.

[Conjunto de APIs: ExcelApi 1,9]

textFrame

Retorna o objeto text frame de uma forma. Somente leitura.

[Conjunto de APIs: ExcelApi 1,9]

top

A distância, em pontos, da borda superior da forma até a borda superior da planilha. Gera uma exceção de argumento inválida quando definida com um valor negativo como entrada.

[Conjunto de APIs: ExcelApi 1,9]

type

Retorna o tipo dessa forma. Para saber detalhes, confira Excel.ShapeType.

[Conjunto de APIs: ExcelApi 1,9]

visible

Especifica se a forma está visível.

[Conjunto de APIs: ExcelApi 1,9]

width

Especifica a largura, em pontos, da forma. Gera uma exceção de argumento inválida quando definida com um valor negativo ou zero como entrada.

[Conjunto de APIs: ExcelApi 1,9]

zOrderPosition

Retorna a posição da forma especificada na ordem z, com 0 representando a parte inferior da pilha do pedido.

[Conjunto de APIs: ExcelApi 1,9]

Métodos

copyTo(destinationSheet)

Copia e cola um objeto Forma. A forma colada é copiada para o mesmo local de pixel que esta forma.

[Conjunto de APIs: ExcelApi 1,10]

delete()

Remove a forma da planilha.

[Conjunto de APIs: ExcelApi 1,9]

getAsImage(format)

Converte a forma em uma imagem e retorna a imagem como uma cadeia de caracteres de base 64. O DPI é 96. Os únicos formatos suportados sãoExcel.PictureFormat.BMP, Excel.PictureFormat.PNG, Excel.PictureFormat.JPEG, eExcel.PictureFormat.GIF.

[Conjunto de APIs: ExcelApi 1,9]

getAsImage(formatString)

Converte a forma em uma imagem e retorna a imagem como uma cadeia de caracteres de base 64. O DPI é 96. Os únicos formatos suportados sãoExcel.PictureFormat.BMP, Excel.PictureFormat.PNG, Excel.PictureFormat.JPEG, eExcel.PictureFormat.GIF.

[Conjunto de APIs: ExcelApi 1,9]

incrementLeft(increment)

Move a forma horizontalmente pelo número especificado de pontos.

[Conjunto de APIs: ExcelApi 1,9]

incrementRotation(increment)

O formato é girado em sentido horário ao redor do eixo z pelo número especificado de graus. Use a rotation propriedade para definir a rotação absoluta da forma.

[Conjunto de APIs: ExcelApi 1,9]

incrementTop(increment)

Move a forma verticalmente pelo número especificado de pontos.

[Conjunto de APIs: ExcelApi 1,9]

load(options)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNames)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNamesAndPaths)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

scaleHeight(scaleFactor, scaleType, scaleFrom)

Dimensiona a altura da forma por um fator especificado. Para imagens, é possível indicar se você deseja dimensionar a forma em relação ao tamanho original ou ao tamanho atual. As formas que não são figuras serão sempre dimensionadas em relação à sua altura atual.

[Conjunto de APIs: ExcelApi 1,9]

scaleHeight(scaleFactor, scaleTypeString, scaleFrom)

Dimensiona a altura da forma por um fator especificado. Para imagens, é possível indicar se você deseja dimensionar a forma em relação ao tamanho original ou ao tamanho atual. As formas que não são figuras serão sempre dimensionadas em relação à sua altura atual.

[Conjunto de APIs: ExcelApi 1,9]

scaleWidth(scaleFactor, scaleType, scaleFrom)

Dimensiona a largura da forma por um fator especificado. Para imagens, é possível indicar se você deseja dimensionar a forma em relação ao tamanho original ou ao tamanho atual. As formas que não são figuras serão sempre dimensionadas em relação à sua largura atual.

[Conjunto de APIs: ExcelApi 1,9]

scaleWidth(scaleFactor, scaleTypeString, scaleFrom)

Dimensiona a largura da forma por um fator especificado. Para imagens, é possível indicar se você deseja dimensionar a forma em relação ao tamanho original ou ao tamanho atual. As formas que não são figuras serão sempre dimensionadas em relação à sua largura atual.

[Conjunto de APIs: ExcelApi 1,9]

set(properties, options)

Define várias propriedades de um objeto ao mesmo tempo. Você pode passar um objeto simples com as propriedades apropriadas ou outro objeto API do mesmo tipo.

set(properties)

Define várias propriedades no objeto ao mesmo tempo, com base em um objeto carregado existente.

setZOrder(position)

Move a forma especificada para cima ou para baixo na ordem z da coleção, que a desloca para frente ou para trás de outras formas.

[Conjunto de APIs: ExcelApi 1,9]

setZOrder(positionString)

Move a forma especificada para cima ou para baixo na ordem z da coleção, que a desloca para frente ou para trás de outras formas.

[Conjunto de APIs: ExcelApi 1,9]

toJSON()

Substitui o toJSON() método JavaScript para fornecer uma saída mais útil quando um objeto API é passado paraJSON.stringify(). (JSON.stringify, por sua vez, chama o toJSON método do objeto que é passado para ele.) Enquanto o objeto Excel. Shape original é um objeto API, o toJSON método retorna um objeto JavaScript simples (digitado comoExcel.Interfaces.ShapeData) que contém cópias superficiais de qualquer propriedade filho carregada do objeto original.

Eventos

onActivated

Ocorre quando a forma é ativada.

[Conjunto de APIs: ExcelApi 1,9]

onDeactivated

Ocorre quando a forma é desativada.

[Conjunto de APIs: ExcelApi 1,9]

Detalhes da propriedade

altTextDescription

Especifica o texto de descrição alternativa para um objeto Shape.

[Conjunto de APIs: ExcelApi 1,9]

altTextDescription: string;

Valor da propriedade

string

altTextTitle

Especifica o texto de título alternativo para um objeto Shape.

[Conjunto de APIs: ExcelApi 1,9]

altTextTitle: string;

Valor da propriedade

string

connectionSiteCount

Retorna o número de locais de conexão nessa forma.

[Conjunto de APIs: ExcelApi 1,9]

readonly connectionSiteCount: number;

Valor da propriedade

number

context

O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host do Office.

context: RequestContext;

Valor da propriedade

fill

Retorna a formatação de preenchimento dessa forma.

[Conjunto de APIs: ExcelApi 1,9]

readonly fill: Excel.ShapeFill;

Valor da propriedade

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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

Retorna a forma geométrica associada à forma. Um erro será lançado, se o tipo de forma não for "GeometricShape".

[Conjunto de APIs: ExcelApi 1,9]

readonly geometricShape: Excel.GeometricShape;

Valor da propriedade

geometricShapeType

Especifica o tipo de forma geométrica dessa forma geométrica. Para saber detalhes, confira Excel.GeometricShapeType. Retorna nulo se o tipo de forma não for "GeometricShape".

[Conjunto de APIs: ExcelApi 1,9]

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";

Valor da propriedade

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"

group

Retorna o grupo de forma associado à forma. Um erro será lançado, se o tipo de forma não for "GroupShape".

[Conjunto de APIs: ExcelApi 1,9]

readonly group: Excel.ShapeGroup;

Valor da propriedade

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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

Especifica a altura, em pontos, da forma. Gera uma exceção de argumento inválida quando definida com um valor negativo ou zero como entrada.

[Conjunto de APIs: ExcelApi 1,9]

height: number;

Valor da propriedade

number

id

Especifica o identificador da forma.

[Conjunto de APIs: ExcelApi 1,9]

readonly id: string;

Valor da propriedade

string

image

Retorna a imagem associada à forma. Um erro será lançado, se o tipo de forma não for "Imagem".

[Conjunto de APIs: ExcelApi 1,9]

readonly image: Excel.Image;

Valor da propriedade

left

A distância, em pontos, da lateral esquerda da forma do lado esquerdo da planilha. Gera uma exceção de argumento inválida quando definida com um valor negativo como entrada.

[Conjunto de APIs: ExcelApi 1,9]

left: number;

Valor da propriedade

number

level

Especifica o nível da forma especificada. Por exemplo, um nível de 0 significa que a forma não faz parte de nenhum grupo, um nível de 1 significa que a forma é parte de um grupo de nível superior e um nível 2 significa que a forma faz parte de um subgrupo do nível superior.

[Conjunto de APIs: ExcelApi 1,9]

readonly level: number;

Valor da propriedade

number

line

Retorna a linha associada à forma. Um erro será lançado, se o tipo de forma não for "Linha".

[Conjunto de APIs: ExcelApi 1,9]

readonly line: Excel.Line;

Valor da propriedade

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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

Retorna a formatação de linha do objeto de forma.

[Conjunto de APIs: ExcelApi 1,9]

readonly lineFormat: Excel.ShapeLineFormat;

Valor da propriedade

lockAspectRatio

Especifica se a taxa de proporção desta forma está bloqueada.

[Conjunto de APIs: ExcelApi 1,9]

lockAspectRatio: boolean;

Valor da propriedade

boolean

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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

Especifica o nome da forma.

[Conjunto de APIs: ExcelApi 1,9]

name: string;

Valor da propriedade

string

parentGroup

Especifica o grupo pai desta forma.

[Conjunto de APIs: ExcelApi 1,9]

readonly parentGroup: Excel.Shape;

Valor da propriedade

placement

Representa como o objeto é anexado às células abaixo dela.

[Conjunto de APIs: ExcelApi 1,10]

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

Valor da propriedade

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

rotation

Especifica a rotação, em graus, da forma.

[Conjunto de APIs: ExcelApi 1,9]

rotation: number;

Valor da propriedade

number

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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

Retorna o objeto text frame de uma forma. Somente leitura.

[Conjunto de APIs: ExcelApi 1,9]

readonly textFrame: Excel.TextFrame;

Valor da propriedade

top

A distância, em pontos, da borda superior da forma até a borda superior da planilha. Gera uma exceção de argumento inválida quando definida com um valor negativo como entrada.

[Conjunto de APIs: ExcelApi 1,9]

top: number;

Valor da propriedade

number

type

Retorna o tipo dessa forma. Para saber detalhes, confira Excel.ShapeType.

[Conjunto de APIs: ExcelApi 1,9]

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

Valor da propriedade

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

visible

Especifica se a forma está visível.

[Conjunto de APIs: ExcelApi 1,9]

visible: boolean;

Valor da propriedade

boolean

width

Especifica a largura, em pontos, da forma. Gera uma exceção de argumento inválida quando definida com um valor negativo ou zero como entrada.

[Conjunto de APIs: ExcelApi 1,9]

width: number;

Valor da propriedade

number

zOrderPosition

Retorna a posição da forma especificada na ordem z, com 0 representando a parte inferior da pilha do pedido.

[Conjunto de APIs: ExcelApi 1,9]

readonly zOrderPosition: number;

Valor da propriedade

number

Detalhes do método

copyTo(destinationSheet)

Copia e cola um objeto Forma. A forma colada é copiada para o mesmo local de pixel que esta forma.

[Conjunto de APIs: ExcelApi 1,10]

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

Parâmetros

destinationSheet
Worksheet | string

A planilha à qual o objeto Shape será colado. O valor padrão é a planilha da forma copiada.

Retornos

delete()

Remove a forma da planilha.

[Conjunto de APIs: ExcelApi 1,9]

delete(): void;

Retornos

void

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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)

Converte a forma em uma imagem e retorna a imagem como uma cadeia de caracteres de base 64. O DPI é 96. Os únicos formatos suportados sãoExcel.PictureFormat.BMP, Excel.PictureFormat.PNG, Excel.PictureFormat.JPEG, eExcel.PictureFormat.GIF.

[Conjunto de APIs: ExcelApi 1,9]

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

Parâmetros

format
Excel.PictureFormat

Especifica o formato da imagem.

Retornos

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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)

Converte a forma em uma imagem e retorna a imagem como uma cadeia de caracteres de base 64. O DPI é 96. Os únicos formatos suportados sãoExcel.PictureFormat.BMP, Excel.PictureFormat.PNG, Excel.PictureFormat.JPEG, eExcel.PictureFormat.GIF.

[Conjunto de APIs: ExcelApi 1,9]

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

Parâmetros

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

Especifica o formato da imagem.

Retornos

incrementLeft(increment)

Move a forma horizontalmente pelo número especificado de pontos.

[Conjunto de APIs: ExcelApi 1,9]

incrementLeft(increment: number): void;

Parâmetros

increment
number

O incremento, em pontos, a forma será horizontalmente movida. Um valor positivo move a forma para a direita e um valor negativo a move para a esquerda. Se a planilha for orientada da direita para a esquerda, ela será revertida: os valores positivos moverão a forma para a esquerda e os valores negativos a moverão para a direita.

Retornos

void

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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)

O formato é girado em sentido horário ao redor do eixo z pelo número especificado de graus. Use a rotation propriedade para definir a rotação absoluta da forma.

[Conjunto de APIs: ExcelApi 1,9]

incrementRotation(increment: number): void;

Parâmetros

increment
number

Quantos graus a forma será girada. Um valor positivo gira a forma no sentido horário; um valor negativo a gira no sentido anti-horário.

Retornos

void

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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)

Move a forma verticalmente pelo número especificado de pontos.

[Conjunto de APIs: ExcelApi 1,9]

incrementTop(increment: number): void;

Parâmetros

increment
number

O incremento, em pontos, a forma será movida verticalmente. em pontos. Um valor positivo move a forma para baixo e um valor negativo a move para cima.

Retornos

void

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

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

Parâmetros

options
Excel.Interfaces.ShapeLoadOptions

Fornece opções para as propriedades do objeto a ser carregado.

Retornos

load(propertyNames)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

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

Parâmetros

propertyNames
string | string[]

Uma cadeia de caracteres delimitada por vírgula ou uma matriz de cadeias de caracteres que especificam as propriedades a serem carregadas.

Retornos

load(propertyNamesAndPaths)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

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

Parâmetros

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

propertyNamesAndPaths.selecté uma cadeia de caracteres delimitada por vírgula que especifica as propriedades a serem carregadas e propertyNamesAndPaths.expand é uma cadeia de caracteres delimitada por vírgula que especifica as propriedades de navegação a serem carregadas.

Retornos

scaleHeight(scaleFactor, scaleType, scaleFrom)

Dimensiona a altura da forma por um fator especificado. Para imagens, é possível indicar se você deseja dimensionar a forma em relação ao tamanho original ou ao tamanho atual. As formas que não são figuras serão sempre dimensionadas em relação à sua altura atual.

[Conjunto de APIs: ExcelApi 1,9]

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

Parâmetros

scaleFactor
number

Especifica a proporção entre a altura da forma após você redimensioná-la e a altura atual ou original.

scaleType
Excel.ShapeScaleType

Especifica se a forma é dimensionada em relação ao seu tamanho original ou atual. A opção de escala de tamanho original só funciona para imagens.

scaleFrom
Excel.ShapeScaleFrom

Opcional. Especifica qual parte da forma mantém sua posição quando a forma é dimensionada. Se for omitido, representará o canto superior esquerdo da forma mantém sua posição.

Retornos

void

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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, scaleFrom)

Dimensiona a altura da forma por um fator especificado. Para imagens, é possível indicar se você deseja dimensionar a forma em relação ao tamanho original ou ao tamanho atual. As formas que não são figuras serão sempre dimensionadas em relação à sua altura atual.

[Conjunto de APIs: ExcelApi 1,9]

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

Parâmetros

scaleFactor
number

Especifica a proporção entre a altura da forma após você redimensioná-la e a altura atual ou original.

scaleTypeString
"CurrentSize" | "OriginalSize"

Especifica se a forma é dimensionada em relação ao seu tamanho original ou atual. A opção de escala de tamanho original só funciona para imagens.

scaleFrom
"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

Opcional. Especifica qual parte da forma mantém sua posição quando a forma é dimensionada. Se for omitido, representará o canto superior esquerdo da forma mantém sua posição.

Retornos

void

scaleWidth(scaleFactor, scaleType, scaleFrom)

Dimensiona a largura da forma por um fator especificado. Para imagens, é possível indicar se você deseja dimensionar a forma em relação ao tamanho original ou ao tamanho atual. As formas que não são figuras serão sempre dimensionadas em relação à sua largura atual.

[Conjunto de APIs: ExcelApi 1,9]

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

Parâmetros

scaleFactor
number

Especifica a proporção entre a largura da forma após você redimensioná-la e a largura atual ou original.

scaleType
Excel.ShapeScaleType

Especifica se a forma é dimensionada em relação ao seu tamanho original ou atual. A opção de escala de tamanho original só funciona para imagens.

scaleFrom
Excel.ShapeScaleFrom

Opcional. Especifica qual parte da forma mantém sua posição quando a forma é dimensionada. Se for omitido, representará o canto superior esquerdo da forma mantém sua posição.

Retornos

void

scaleWidth(scaleFactor, scaleTypeString, scaleFrom)

Dimensiona a largura da forma por um fator especificado. Para imagens, é possível indicar se você deseja dimensionar a forma em relação ao tamanho original ou ao tamanho atual. As formas que não são figuras serão sempre dimensionadas em relação à sua largura atual.

[Conjunto de APIs: ExcelApi 1,9]

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

Parâmetros

scaleFactor
number

Especifica a proporção entre a largura da forma após você redimensioná-la e a largura atual ou original.

scaleTypeString
"CurrentSize" | "OriginalSize"

Especifica se a forma é dimensionada em relação ao seu tamanho original ou atual. A opção de escala de tamanho original só funciona para imagens.

scaleFrom
"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

Opcional. Especifica qual parte da forma mantém sua posição quando a forma é dimensionada. Se for omitido, representará o canto superior esquerdo da forma mantém sua posição.

Retornos

void

set(properties, options)

Define várias propriedades de um objeto ao mesmo tempo. Você pode passar um objeto simples com as propriedades apropriadas ou outro objeto API do mesmo tipo.

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

Parâmetros

properties
Interfaces.ShapeUpdateData

Um objeto JavaScript com propriedades que são estruturadas isomorphically para as propriedades do objeto no qual o método é chamado.

options
OfficeExtension.UpdateOptions

Fornece uma opção para suprimir erros se o objeto Properties tentar definir qualquer propriedade somente leitura.

Retornos

void

Comentários

Este método tem a seguinte assinatura adicional:

set(properties: Excel.Shape): void

set(properties)

Define várias propriedades no objeto ao mesmo tempo, com base em um objeto carregado existente.

set(properties: Excel.Shape): void;

Parâmetros

properties
Excel.Shape

Retornos

void

setZOrder(position)

Move a forma especificada para cima ou para baixo na ordem z da coleção, que a desloca para frente ou para trás de outras formas.

[Conjunto de APIs: ExcelApi 1,9]

setZOrder(position: Excel.ShapeZOrder): void;

Parâmetros

position
Excel.ShapeZOrder

Onde mover a forma na pilha da ordem z em relação às outras formas. Consulte Excel. ShapeZOrder para obter detalhes.

Retornos

void

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/master/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)

Move a forma especificada para cima ou para baixo na ordem z da coleção, que a desloca para frente ou para trás de outras formas.

[Conjunto de APIs: ExcelApi 1,9]

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

Parâmetros

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

Onde mover a forma na pilha da ordem z em relação às outras formas. Consulte Excel. ShapeZOrder para obter detalhes.

Retornos

void

toJSON()

Substitui o toJSON() método JavaScript para fornecer uma saída mais útil quando um objeto API é passado paraJSON.stringify(). (JSON.stringify, por sua vez, chama o toJSON método do objeto que é passado para ele.) Enquanto o objeto Excel. Shape original é um objeto API, o toJSON método retorna um objeto JavaScript simples (digitado comoExcel.Interfaces.ShapeData) que contém cópias superficiais de qualquer propriedade filho carregada do objeto original.

toJSON(): Excel.Interfaces.ShapeData;

Retornos

Detalhes do evento

onActivated

Ocorre quando a forma é ativada.

[Conjunto de APIs: ExcelApi 1,9]

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

Retornos

onDeactivated

Ocorre quando a forma é desativada.

[Conjunto de APIs: ExcelApi 1,9]

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

Retornos