Add-OfficeExcelImage

Aliases: ExcelImage

Namespace PSWriteOffice

Aliases

ExcelImage

Inputs

OfficeIMO.Excel.ExcelDocument

Source

Sources/PSWriteOffice/Cmdlets/Excel/AddOfficeExcelImageCommand.cs:31 Edit on GitHub

Adds an image anchored to a worksheet cell or range.

Remarks

Adds an image anchored to a worksheet cell or range.

Examples

Authored help example

Example 1: Insert a scaled image from disk at B2.

PS>


ExcelSheet 'Data' { Add-OfficeExcelImage -Address 'B2' -Path .\logo.png -ScalePercent 20 -Name Logo -AltText 'Company logo' }

Anchors the image to cell B2 and sizes it to 20 percent of the original image dimensions.

Example 2: Pin an image to a worksheet range.

PS>


ExcelSheet 'Data' { Add-OfficeExcelImage -Range 'A1:C15' -Path .\logo.png -Name HeaderLogo -Placement MoveAndSize }

Uses Excel's two-cell anchor so the picture moves and resizes with the cells in A1:C15.

Example 3: Insert and rotate an image from a URL.

PS>


ExcelSheet 'Data' { Add-OfficeExcelImage -Row 1 -Column 1 -Url 'https://example.org/logo.png' -WidthPixels 96 -HeightPixels 32 -RotationDegrees 12 }

Downloads, sizes, rotates, and anchors the image to cell A1.

Common Parameters

This command supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.

For more information, see about_CommonParameters.

Syntax

Add-OfficeExcelImage [-Address <String>] [-AltText <String>] [-Column <Nullable`1>] [-Decorative] [-EndOffsetXPixels <Int32>] [-EndOffsetYPixels <Int32>] [-HeightPixels <Int32>] [-LockAspectRatio] [-Name <String>] [-NoLockAspectRatio] [-OffsetXPixels <Int32>] [-OffsetYPixels <Int32>] [-PassThru] -Path <String> [-Placement <MoveAndSize|MoveOnly|FreeFloating>] [-Range <String>] [-RotationDegrees <Double>] [-Row <Nullable`1>] [-ScalePercent <Nullable`1>] [-Title <String>] [-WidthPixels <Int32>] [<CommonParameters>]

Parameter set: ContextPath

Parameters

Address String optionalposition: namedpipeline: Falsealiases: Cell: A1-style cell address (e.g., A1, C5).
AltText String optionalposition: namedpipeline: False: Optional alternative text description for accessibility.
Column Nullable`1 optionalposition: namedpipeline: False: 1-based column index.
Decorative SwitchParameter optionalposition: namedpipeline: False: Marks the image as decorative by clearing alternative text metadata.
EndOffsetXPixels Int32 optionalposition: namedpipeline: False: Horizontal offset in pixels for the range end marker when using Range.
EndOffsetYPixels Int32 optionalposition: namedpipeline: False: Vertical offset in pixels for the range end marker when using Range.
HeightPixels Int32 optionalposition: namedpipeline: Falsealiases: Height: Image height in pixels.
LockAspectRatio SwitchParameter optionalposition: namedpipeline: False: Lock the image aspect ratio in Excel. This is the default unless NoLockAspectRatio is used.
Name String optionalposition: namedpipeline: False: Optional drawing name used by Excel's selection pane.
NoLockAspectRatio SwitchParameter optionalposition: namedpipeline: False: Do not lock the image aspect ratio in Excel.
OffsetXPixels Int32 optionalposition: namedpipeline: False: Horizontal offset in pixels from the cell origin.
OffsetYPixels Int32 optionalposition: namedpipeline: False: Vertical offset in pixels from the cell origin.
PassThru SwitchParameter optionalposition: namedpipeline: False: Emit the worksheet after inserting the image.
Path String requiredposition: 0pipeline: False: Image file path.
Placement ExcelImagePlacement optionalposition: namedpipeline: Falsevalues: 3: How a range-anchored image behaves when cells move or resize. Possible values: MoveAndSize, MoveOnly, FreeFloating; Possible values: MoveAndSize, MoveOnly, FreeFloating
Range String optionalposition: namedpipeline: False: A1-style range (for example, A1:C15) for a two-cell anchor that can move and resize with cells.
RotationDegrees Double optionalposition: namedpipeline: False: Clockwise image rotation in degrees.
Row Nullable`1 optionalposition: namedpipeline: False: 1-based row index.
ScalePercent Nullable`1 optionalposition: namedpipeline: False: Percentage of the original image size. Cannot be combined with WidthPixels or HeightPixels.
Title String optionalposition: namedpipeline: False: Optional alternative text title.
WidthPixels Int32 optionalposition: namedpipeline: Falsealiases: Width: Image width in pixels.

Add-OfficeExcelImage [-Address <String>] [-AltText <String>] [-Column <Nullable`1>] [-Decorative] -Document <ExcelDocument> [-EndOffsetXPixels <Int32>] [-EndOffsetYPixels <Int32>] [-HeightPixels <Int32>] [-LockAspectRatio] [-Name <String>] [-NoLockAspectRatio] [-OffsetXPixels <Int32>] [-OffsetYPixels <Int32>] [-PassThru] -Path <String> [-Placement <MoveAndSize|MoveOnly|FreeFloating>] [-Range <String>] [-RotationDegrees <Double>] [-Row <Nullable`1>] [-ScalePercent <Nullable`1>] [-Sheet <String>] [-SheetIndex <Nullable`1>] [-Title <String>] [-WidthPixels <Int32>] [<CommonParameters>]

Parameter set: DocumentPath

Parameters

Address String optionalposition: namedpipeline: Falsealiases: Cell: A1-style cell address (e.g., A1, C5).
AltText String optionalposition: namedpipeline: False: Optional alternative text description for accessibility.
Column Nullable`1 optionalposition: namedpipeline: False: 1-based column index.
Decorative SwitchParameter optionalposition: namedpipeline: False: Marks the image as decorative by clearing alternative text metadata.
Document ExcelDocument requiredposition: namedpipeline: True (ByValue): Workbook to operate on outside the DSL context.
EndOffsetXPixels Int32 optionalposition: namedpipeline: False: Horizontal offset in pixels for the range end marker when using Range.
EndOffsetYPixels Int32 optionalposition: namedpipeline: False: Vertical offset in pixels for the range end marker when using Range.
HeightPixels Int32 optionalposition: namedpipeline: Falsealiases: Height: Image height in pixels.
LockAspectRatio SwitchParameter optionalposition: namedpipeline: False: Lock the image aspect ratio in Excel. This is the default unless NoLockAspectRatio is used.
Name String optionalposition: namedpipeline: False: Optional drawing name used by Excel's selection pane.
NoLockAspectRatio SwitchParameter optionalposition: namedpipeline: False: Do not lock the image aspect ratio in Excel.
OffsetXPixels Int32 optionalposition: namedpipeline: False: Horizontal offset in pixels from the cell origin.
OffsetYPixels Int32 optionalposition: namedpipeline: False: Vertical offset in pixels from the cell origin.
PassThru SwitchParameter optionalposition: namedpipeline: False: Emit the worksheet after inserting the image.
Path String requiredposition: 0pipeline: False: Image file path.
Placement ExcelImagePlacement optionalposition: namedpipeline: Falsevalues: 3: How a range-anchored image behaves when cells move or resize. Possible values: MoveAndSize, MoveOnly, FreeFloating; Possible values: MoveAndSize, MoveOnly, FreeFloating
Range String optionalposition: namedpipeline: False: A1-style range (for example, A1:C15) for a two-cell anchor that can move and resize with cells.
RotationDegrees Double optionalposition: namedpipeline: False: Clockwise image rotation in degrees.
Row Nullable`1 optionalposition: namedpipeline: False: 1-based row index.
ScalePercent Nullable`1 optionalposition: namedpipeline: False: Percentage of the original image size. Cannot be combined with WidthPixels or HeightPixels.
Sheet String optionalposition: namedpipeline: False: Worksheet name when using Document.
SheetIndex Nullable`1 optionalposition: namedpipeline: False: Worksheet index (0-based) when using Document.
Title String optionalposition: namedpipeline: False: Optional alternative text title.
WidthPixels Int32 optionalposition: namedpipeline: Falsealiases: Width: Image width in pixels.

Add-OfficeExcelImage [-Address <String>] [-AltText <String>] [-Column <Nullable`1>] [-Decorative] -Document <ExcelDocument> [-EndOffsetXPixels <Int32>] [-EndOffsetYPixels <Int32>] [-HeightPixels <Int32>] [-LockAspectRatio] [-Name <String>] [-NoLockAspectRatio] [-OffsetXPixels <Int32>] [-OffsetYPixels <Int32>] [-PassThru] [-Placement <MoveAndSize|MoveOnly|FreeFloating>] [-Range <String>] [-RotationDegrees <Double>] [-Row <Nullable`1>] [-ScalePercent <Nullable`1>] [-Sheet <String>] [-SheetIndex <Nullable`1>] [-Title <String>] -Url <String> [-WidthPixels <Int32>] [<CommonParameters>]

Parameter set: DocumentUrl

Parameters

Address String optionalposition: namedpipeline: Falsealiases: Cell: A1-style cell address (e.g., A1, C5).
AltText String optionalposition: namedpipeline: False: Optional alternative text description for accessibility.
Column Nullable`1 optionalposition: namedpipeline: False: 1-based column index.
Decorative SwitchParameter optionalposition: namedpipeline: False: Marks the image as decorative by clearing alternative text metadata.
Document ExcelDocument requiredposition: namedpipeline: True (ByValue): Workbook to operate on outside the DSL context.
EndOffsetXPixels Int32 optionalposition: namedpipeline: False: Horizontal offset in pixels for the range end marker when using Range.
EndOffsetYPixels Int32 optionalposition: namedpipeline: False: Vertical offset in pixels for the range end marker when using Range.
HeightPixels Int32 optionalposition: namedpipeline: Falsealiases: Height: Image height in pixels.
LockAspectRatio SwitchParameter optionalposition: namedpipeline: False: Lock the image aspect ratio in Excel. This is the default unless NoLockAspectRatio is used.
Name String optionalposition: namedpipeline: False: Optional drawing name used by Excel's selection pane.
NoLockAspectRatio SwitchParameter optionalposition: namedpipeline: False: Do not lock the image aspect ratio in Excel.
OffsetXPixels Int32 optionalposition: namedpipeline: False: Horizontal offset in pixels from the cell origin.
OffsetYPixels Int32 optionalposition: namedpipeline: False: Vertical offset in pixels from the cell origin.
PassThru SwitchParameter optionalposition: namedpipeline: False: Emit the worksheet after inserting the image.
Placement ExcelImagePlacement optionalposition: namedpipeline: Falsevalues: 3: How a range-anchored image behaves when cells move or resize. Possible values: MoveAndSize, MoveOnly, FreeFloating; Possible values: MoveAndSize, MoveOnly, FreeFloating
Range String optionalposition: namedpipeline: False: A1-style range (for example, A1:C15) for a two-cell anchor that can move and resize with cells.
RotationDegrees Double optionalposition: namedpipeline: False: Clockwise image rotation in degrees.
Row Nullable`1 optionalposition: namedpipeline: False: 1-based row index.
ScalePercent Nullable`1 optionalposition: namedpipeline: False: Percentage of the original image size. Cannot be combined with WidthPixels or HeightPixels.
Sheet String optionalposition: namedpipeline: False: Worksheet name when using Document.
SheetIndex Nullable`1 optionalposition: namedpipeline: False: Worksheet index (0-based) when using Document.
Title String optionalposition: namedpipeline: False: Optional alternative text title.
Url String requiredposition: 0pipeline: False: Image URL to download.
WidthPixels Int32 optionalposition: namedpipeline: Falsealiases: Width: Image width in pixels.

Add-OfficeExcelImage [-Address <String>] [-AltText <String>] [-Column <Nullable`1>] [-Decorative] [-EndOffsetXPixels <Int32>] [-EndOffsetYPixels <Int32>] [-HeightPixels <Int32>] [-LockAspectRatio] [-Name <String>] [-NoLockAspectRatio] [-OffsetXPixels <Int32>] [-OffsetYPixels <Int32>] [-PassThru] [-Placement <MoveAndSize|MoveOnly|FreeFloating>] [-Range <String>] [-RotationDegrees <Double>] [-Row <Nullable`1>] [-ScalePercent <Nullable`1>] [-Title <String>] -Url <String> [-WidthPixels <Int32>] [<CommonParameters>]

Parameter set: ContextUrl

Parameters

Address String optionalposition: namedpipeline: Falsealiases: Cell: A1-style cell address (e.g., A1, C5).
AltText String optionalposition: namedpipeline: False: Optional alternative text description for accessibility.
Column Nullable`1 optionalposition: namedpipeline: False: 1-based column index.
Decorative SwitchParameter optionalposition: namedpipeline: False: Marks the image as decorative by clearing alternative text metadata.
EndOffsetXPixels Int32 optionalposition: namedpipeline: False: Horizontal offset in pixels for the range end marker when using Range.
EndOffsetYPixels Int32 optionalposition: namedpipeline: False: Vertical offset in pixels for the range end marker when using Range.
HeightPixels Int32 optionalposition: namedpipeline: Falsealiases: Height: Image height in pixels.
LockAspectRatio SwitchParameter optionalposition: namedpipeline: False: Lock the image aspect ratio in Excel. This is the default unless NoLockAspectRatio is used.
Name String optionalposition: namedpipeline: False: Optional drawing name used by Excel's selection pane.
NoLockAspectRatio SwitchParameter optionalposition: namedpipeline: False: Do not lock the image aspect ratio in Excel.
OffsetXPixels Int32 optionalposition: namedpipeline: False: Horizontal offset in pixels from the cell origin.
OffsetYPixels Int32 optionalposition: namedpipeline: False: Vertical offset in pixels from the cell origin.
PassThru SwitchParameter optionalposition: namedpipeline: False: Emit the worksheet after inserting the image.
Placement ExcelImagePlacement optionalposition: namedpipeline: Falsevalues: 3: How a range-anchored image behaves when cells move or resize. Possible values: MoveAndSize, MoveOnly, FreeFloating; Possible values: MoveAndSize, MoveOnly, FreeFloating
Range String optionalposition: namedpipeline: False: A1-style range (for example, A1:C15) for a two-cell anchor that can move and resize with cells.
RotationDegrees Double optionalposition: namedpipeline: False: Clockwise image rotation in degrees.
Row Nullable`1 optionalposition: namedpipeline: False: 1-based row index.
ScalePercent Nullable`1 optionalposition: namedpipeline: False: Percentage of the original image size. Cannot be combined with WidthPixels or HeightPixels.
Title String optionalposition: namedpipeline: False: Optional alternative text title.
Url String requiredposition: 0pipeline: False: Image URL to download.
WidthPixels Int32 optionalposition: namedpipeline: Falsealiases: Width: Image width in pixels.