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.
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.JPEG`e `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.JPEG`e `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.stringify`por 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

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

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

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)

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)

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)

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 ]

Compartilhar via

Excel.Shape class

Comentários

Propriedades

Métodos

Eventos

Detalhes da propriedade

altTextDescription

Valor da propriedade

Comentários

altTextTitle

Valor da propriedade

Comentários

connectionSiteCount

Valor da propriedade

Comentários

context

Valor da propriedade

fill

Valor da propriedade

Comentários

Exemplos

geometricShape

Valor da propriedade

Comentários

geometricShapeType

Valor da propriedade

Comentários

group

Valor da propriedade

Comentários

Exemplos

height

Valor da propriedade

Comentários

id

Valor da propriedade

Comentários

image

Valor da propriedade

Comentários

left

Valor da propriedade

Comentários

level

Valor da propriedade

Comentários

line

Valor da propriedade

Comentários

Exemplos

lineFormat

Valor da propriedade

Comentários

lockAspectRatio

Valor da propriedade

Comentários

Exemplos

name

Valor da propriedade

Comentários

parentGroup

Valor da propriedade

Comentários

placement

Valor da propriedade

Comentários

rotation

Valor da propriedade

Comentários

Exemplos

textFrame

Valor da propriedade

Comentários

top

Valor da propriedade

Comentários

type

Valor da propriedade

Comentários