Compartilhar via

Excel.Shape class

  • Referência
Pacote:
excel

Representa um objeto de forma genérico na folha de cálculo. 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 com a API JavaScript do Excel.

Extends
OfficeExtension.ClientObject

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

Propriedades

altTextDescription

Especifica o texto de descrição alternativo de 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 do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.
displayName

Obtém o nome a apresentar da forma. Uma forma recentemente criada tem um nome gerado que é localizado e pode não corresponder ao respetivo name. Neste cenário, pode utilizar esta API para obter o nome que é apresentado na IU.
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 desta forma geométrica. Veja Excel.GeometricShapeType para obter detalhes. Devolve null se o tipo de forma não for "Forma Geométrica".
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 entrada.
id

Especifica o identificador da 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. Lança uma exceção InvalidArgument quando definida com um valor negativo como 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 desta forma está bloqueada.
name

Especifica o nome da forma.
parentGroup

Especifica o grupo principal desta 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. Lança uma exceção InvalidArgument quando definida com um valor negativo como entrada.
type

Retorna o tipo dessa forma. Veja Excel.ShapeType para obter 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 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 a mesma localização de píxeis que esta forma.
delete()

Remove a forma da planilha.
getAsImage(format)

Converte a forma numa imagem e devolve a imagem como uma cadeia codificada em Base64. O DPI é 96. Os únicos formatos suportados são Excel.PictureFormat.BMP, Excel.PictureFormat.PNG, Excel.PictureFormat.JPEGe Excel.PictureFormat.GIF.
getAsImage(formatString)

Converte a forma numa imagem e devolve a imagem como uma cadeia codificada em Base64. O DPI é 96. Os únicos formatos suportados 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. Utilize 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. Pode transmitir um objeto simples com as propriedades adequadas ou outro objeto de API do mesmo tipo.
set(properties)

Define várias propriedades no objeto ao mesmo tempo, com base num 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 é transmitido para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que lhe é transmitido.) Enquanto o objeto original Excel.Shape é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Excel.Interfaces.ShapeData) que contém cópias rasas de quaisquer propriedades subordinadas 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 alternativo de 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 do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.

context: RequestContext;

Valor da propriedade

Excel.RequestContext

displayName

Obtém o nome a apresentar da forma. Uma forma recentemente criada tem um nome gerado que é localizado e pode não corresponder ao respetivo name. Neste cenário, pode utilizar esta API para obter o nome que é apresentado na IU.

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 desta forma geométrica. Veja Excel.GeometricShapeType para obter detalhes. Devolve null se o tipo de forma não for "Forma Geométrica".

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 entrada.

height: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

id

Especifica o identificador da 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. Lança uma exceção InvalidArgument quando definida com um valor negativo como 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 desta 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 principal desta 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. Lança uma exceção InvalidArgument quando definida com um valor negativo como entrada.

top: number;

Valor da propriedade

number

Comentários

[ Conjunto de API: ExcelApi 1.9 ]

type

Retorna o tipo dessa forma. Veja Excel.ShapeType para obter 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 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 a mesma localização de píxeis que esta forma.

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

Parâmetros

destinationSheet

Excel.Worksheet | string

A folha à qual o objeto da forma será colado. O valor predefinido é a folha de cálculo 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 numa imagem e devolve a imagem como uma cadeia codificada em Base64. O DPI é 96. Os únicos formatos suportados 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 numa imagem e devolve a imagem como uma cadeia codificada em Base64. O DPI é 96. Os únicos formatos suportados 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 move-a para a esquerda. Se a folha for orientada da direita para a esquerda, isto é invertido: os valores positivos irão mover a forma para a esquerda e os valores negativos irão movê-la 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. Utilize a rotation propriedade para definir a rotação absoluta da forma.

incrementRotation(increment: number): void;

Parâmetros

increment

number

Quantos graus a forma será rodada. Um valor positivo roda a forma no sentido dos ponteiros do relógio e um valor negativo roda-a para a esquerda.

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 move-a 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 as propriedades do objeto a 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 delimitada por vírgulas ou uma matriz de cadeias que especificam as propriedades a carregar.

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

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 relativamente ao respetivo tamanho original ou atual. A opção de dimensionamento do 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, representa que o canto superior esquerdo da forma mantém a 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 relativamente ao respetivo tamanho original ou atual. A opção de dimensionamento do 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 for omitido, representa que o canto superior esquerdo da forma mantém a 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 relativamente ao respetivo tamanho original ou atual. A opção de dimensionamento do 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, representa que o canto superior esquerdo da forma mantém a 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 relativamente ao respetivo tamanho original ou atual. A opção de dimensionamento do 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 for omitido, representa que o canto superior esquerdo da forma mantém a 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. Pode transmitir um objeto simples com as propriedades adequadas 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 que são estruturadas isomorfoticamente para as propriedades do objeto no qual o método é chamado.

options
OfficeExtension.UpdateOptions

Fornece uma opção para suprimir erros se o objeto de propriedades tentar definir quaisquer propriedades só de leitura.

Retornos

void

set(properties)

Define várias propriedades no objeto ao mesmo tempo, com base num 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 ordenação z relativamente às outras formas. Veja Excel.ShapeZOrder para obter 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 ordenação z relativamente às outras formas. Veja Excel.ShapeZOrder para obter 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 é transmitido para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que lhe é transmitido.) Enquanto o objeto original Excel.Shape é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Excel.Interfaces.ShapeData) que contém cópias rasas de quaisquer propriedades subordinadas 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 ]