Share via

Excel.Shape class

  • Referência
Pacote:
excel

Representa um objeto de forma genérica 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 de forma, leia Trabalhar com formas usando a API JavaScript do Excel.

Extends
OfficeExtension.ClientObject

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Propriedades

altTextDescription

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

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

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

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

Obtém o nome de exibição da forma. Uma forma recém-criada tem um nome gerado que é localizado e pode não corresponder ao seu name. Nesse cenário, você pode usar essa API para obter o nome exibido na interface do usuário.
fill

Retorna a formatação de preenchimento dessa forma.
geometricShape

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

Especifica o tipo de forma geométrica dessa forma geométrica. Confira Excel.GeometricShapeType detalhes. Retorna null se o tipo de forma não for "GeometricShape".
group

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

Especifica a altura, em pontos, da forma. Gera uma exceção InvalidArgument quando definida com um valor negativo ou zero como uma entrada.
id

Especifica o identificador de forma.
image

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

A distância, em pontos, da lateral esquerda da forma do lado esquerdo da planilha. Gera uma exceção InvalidArgument quando definida com um valor negativo como uma entrada.
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.
line

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

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

Especifica se a proporção dessa forma está bloqueada.
name

Especifica o nome da forma.
parentGroup

Especifica o grupo pai dessa forma.
placement

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

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

Retorna o objeto text frame de uma forma.
top

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

Retorna o tipo dessa forma. Confira Excel.ShapeType detalhes.
visible

Especifica se a forma está visível.
width

Especifica a largura, em pontos, da forma. Gera uma exceção InvalidArgument quando definida com um valor negativo ou zero como uma entrada.
zOrderPosition

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

Métodos

copyTo(destinationSheet)

Copia e cola um Shape objeto. A forma colada é copiada para o mesmo local de pixel que essa forma.
delete()

Remove a forma da planilha.
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 com suporte são Excel.PictureFormat.BMP,Excel.PictureFormat.PNG , , Excel.PictureFormat.JPEGe .Excel.PictureFormat.GIF
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 com suporte são Excel.PictureFormat.BMP,Excel.PictureFormat.PNG , , Excel.PictureFormat.JPEGe .Excel.PictureFormat.GIF
incrementLeft(increment)

Move a forma horizontalmente pelo número especificado de pontos.
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.
incrementTop(increment)

Move a forma verticalmente pelo número especificado de pontos.
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.
scaleHeight(scaleFactor, scaleTypeString, scaleFromString)

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.
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.
scaleWidth(scaleFactor, scaleTypeString, scaleFromString)

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.
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 de 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.
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.
toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é passado para JSON.stringify(). (JSON.stringifypor 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 como Excel.Interfaces.ShapeData) que contém cópias rasas de quaisquer propriedades filho carregadas do objeto original.

Eventos

onActivated

Ocorre quando a forma é ativada.
onDeactivated

Ocorre quando a forma é desativada.

Detalhes da propriedade

altTextDescription

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

altTextDescription: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

altTextTitle

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

altTextTitle: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

connectionSiteCount

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

readonly connectionSiteCount: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: 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.

context: RequestContext;

Valor da propriedade

Excel.RequestContext

displayName

Obtém o nome de exibição da forma. Uma forma recém-criada tem um nome gerado que é localizado e pode não corresponder ao seu name. Nesse cenário, você pode usar essa API para obter o nome exibido na interface do usuário.

readonly displayName: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: ExcelApi 1.15 ]

fill

Retorna a formatação de preenchimento dessa forma.

readonly fill: Excel.ShapeFill;

Valor da propriedade

Excel.ShapeFill

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// 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

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

readonly geometricShape: Excel.GeometricShape;

Valor da propriedade

Excel.GeometricShape

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

geometricShapeType

Especifica o tipo de forma geométrica dessa forma geométrica. Confira Excel.GeometricShapeType detalhes. Retorna null se o tipo de forma não for "GeometricShape".

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"

Comentários

[ Conjunto de API: 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".

readonly group: Excel.ShapeGroup;

Valor da propriedade

Excel.ShapeGroup

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// 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

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

height: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

id

Especifica o identificador de forma.

readonly id: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

image

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

readonly image: Excel.Image;

Valor da propriedade

Excel.Image

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

left

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

left: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: 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.

readonly level: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

line

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

readonly line: Excel.Line;

Valor da propriedade

Excel.Line

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// 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

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

readonly lineFormat: Excel.ShapeLineFormat;

Valor da propriedade

Excel.ShapeLineFormat

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

lockAspectRatio

Especifica se a proporção dessa forma está bloqueada.

lockAspectRatio: boolean;

Valor da propriedade

boolean

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// 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

Especifica o nome da forma.

name: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

parentGroup

Especifica o grupo pai dessa forma.

readonly parentGroup: Excel.Shape;

Valor da propriedade

Excel.Shape

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

placement

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

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

Valor da propriedade

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

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

rotation

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

rotation: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// 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

Retorna o objeto text frame de uma forma.

readonly textFrame: Excel.TextFrame;

Valor da propriedade

Excel.TextFrame

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

top

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

top: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

type

Retorna o tipo dessa forma. Confira Excel.ShapeType detalhes.

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

Valor da propriedade

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

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

visible

Especifica se a forma está visível.

visible: boolean;

Valor da propriedade

boolean

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

width

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

width: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

zOrderPosition

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

readonly zOrderPosition: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Detalhes do método

copyTo(destinationSheet)

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

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

Parâmetros

destinationSheet

Excel.Worksheet | string

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

Retornos

Excel.Shape

Comentários

[ Conjunto de API: ExcelApi 1.10 ]

delete()

Remove a forma da planilha.

delete(): void;

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// 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)

Converte a forma em uma imagem e retorna a imagem como uma cadeia de caracteres de base 64. O DPI é 96. Os únicos formatos com suporte são Excel.PictureFormat.BMP,Excel.PictureFormat.PNG , , Excel.PictureFormat.JPEGe .Excel.PictureFormat.GIF

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

Parâmetros

format
Excel.PictureFormat

Especifica o formato da imagem.

Retornos

OfficeExtension.ClientResult<string>

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// 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)

Converte a forma em uma imagem e retorna a imagem como uma cadeia de caracteres de base 64. O DPI é 96. Os únicos formatos com suporte são Excel.PictureFormat.BMP,Excel.PictureFormat.PNG , , Excel.PictureFormat.JPEGe .Excel.PictureFormat.GIF

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

OfficeExtension.ClientResult<string>

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

incrementLeft(increment)

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

incrementLeft(increment: number): void;

Parâmetros

increment

number

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

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// 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)

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.

incrementRotation(increment: number): void;

Parâmetros

increment

number

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

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// 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)

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

incrementTop(increment: number): void;

Parâmetros

increment

number

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

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// 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)

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 quais propriedades do objeto carregar.

Retornos

Excel.Shape

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írgulas ou uma matriz de cadeias de caracteres que especificam as propriedades a serem carregadas.

Retornos

Excel.Shape

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írgulas que especifica as propriedades a serem carregadas e propertyNamesAndPaths.expand é uma cadeia de caracteres delimitada por vírgulas que especifica as propriedades de navegação a serem carregadas.

Retornos

Excel.Shape

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.

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 tamanho original ou atual. A opção de dimensionamento 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 omitido, ele representa o canto superior esquerdo da forma mantém sua posição.

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// 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)

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.

scaleHeight(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "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 tamanho original ou atual. A opção de dimensionamento de tamanho original só funciona para imagens.

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

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

Retornos

void

Comentários

[ Conjunto de API: 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.

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 tamanho original ou atual. A opção de dimensionamento 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 omitido, ele representa o canto superior esquerdo da forma mantém sua posição.

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

scaleWidth(scaleFactor, scaleTypeString, scaleFromString)

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.

scaleWidth(scaleFactor: number, scaleTypeString: "CurrentSize" | "OriginalSize", scaleFromString?: "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 tamanho original ou atual. A opção de dimensionamento de tamanho original só funciona para imagens.

scaleFromString

"ScaleFromTopLeft" | "ScaleFromMiddle" | "ScaleFromBottomRight"

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

Retornos

void

Comentários

[ Conjunto de API: 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 de API do mesmo tipo.

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

Parâmetros

properties
Excel.Interfaces.ShapeUpdateData

Um objeto JavaScript com propriedades estruturadas isomorficamente 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 quaisquer propriedades somente leitura.

Retornos

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.

setZOrder(position: Excel.ShapeZOrder): void;

Parâmetros

position
Excel.ShapeZOrder

Para onde mover a forma na pilha de ordem z em relação às outras formas. Confira Excel.ShapeZOrder detalhes.

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Exemplos

// 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)

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.

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

Parâmetros

positionString

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

Para onde mover a forma na pilha de ordem z em relação às outras formas. Confira Excel.ShapeZOrder detalhes.

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é passado para JSON.stringify(). (JSON.stringifypor 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 como Excel.Interfaces.ShapeData) que contém cópias rasas de quaisquer propriedades filho carregadas do objeto original.

toJSON(): Excel.Interfaces.ShapeData;

Retornos

Excel.Interfaces.ShapeData

Detalhes do evento

onActivated

Ocorre quando a forma é ativada.

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

Tipo de evento

OfficeExtension.EventHandlers<Excel.ShapeActivatedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

onDeactivated

Ocorre quando a forma é desativada.

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

Tipo de evento

OfficeExtension.EventHandlers<Excel.ShapeDeactivatedEventArgs>

Comentários

[ Conjunto de API: ExcelApi 1.9 ]