Excel.WebImageCellValue interface

Package:

excel

Represents the value of a cell containing an image downloaded from the internet.

Remarks

[ API set: ExcelApi 1.16 ]

Properties

address	Represents the URL from which the image will be downloaded. This image must be hosted on a server that supports HTTPS.
altText	Represents the alternate text that can be used in accessibility scenarios to describe what the image represents.
attribution	Represents attribution information to describe the source and license requirements for using this image.
basicType	Represents the value that would be returned by Range.valueTypes for a cell with this value.
basicValue	Represents the value that would be returned by Range.values for a cell with this value. When accessed through a valuesAsJson property, this string value aligns with the en-US locale. When accessed through a valuesAsJsonLocal property, this string value aligns with the user's display locale.
provider	Represents information that describes the entity or individual who provided the image. This information can be used for branding in image cards.
relatedImagesAddress	Represents the URL of a webpage with images that are considered related to this WebImageCellValue.
type	Represents the type of this cell value.

Property Details

address

Represents the URL from which the image will be downloaded. This image must be hosted on a server that supports HTTPS.

address: string;

Property Value

string

Remarks

[ API set: ExcelApi 1.16 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/20-data-types/data-types-web-image.yaml

// This function retrieves the image URL from the selected cell and opens that image in a new browser tab.
await Excel.run(async (context) => {
  // Load the active cell information.
  const activeCell = context.workbook.getActiveCell();
  activeCell.load("valuesAsJson");
  await context.sync();

  // Get image URL from the active cell.
  const values = activeCell.valuesAsJson;
  const webImageData = values[0][0] as Excel.WebImageCellValue;
  const webImageUrl = webImageData.address;

  if (!webImageUrl) {
    console.log("The selected cell is missing an image URL. Select a cell that contains an image.");
    return;
  }

  // Open the image URL in a new browser tab.
  const tab = window.open(webImageData.address, "_blank");
});

altText

Represents the alternate text that can be used in accessibility scenarios to describe what the image represents.

altText?: string;

Property Value

string

Remarks

[ API set: ExcelApi 1.16 ]

attribution

Represents attribution information to describe the source and license requirements for using this image.

attribution?: CellValueAttributionAttributes[];

Property Value

Excel.CellValueAttributionAttributes[]

Remarks

[ API set: ExcelApi 1.16 ]

basicType

Represents the value that would be returned by Range.valueTypes for a cell with this value.

basicType?: RangeValueType.error | "Error";

Property Value

error | "Error"

Remarks

[ API set: ExcelApi 1.16 ]

basicValue

Represents the value that would be returned by Range.values for a cell with this value. When accessed through a valuesAsJson property, this string value aligns with the en-US locale. When accessed through a valuesAsJsonLocal property, this string value aligns with the user's display locale.

basicValue?: "#VALUE!" | string;

Property Value

"#VALUE!" | string

Remarks

[ API set: ExcelApi 1.16 ]

provider

Represents information that describes the entity or individual who provided the image. This information can be used for branding in image cards.

provider?: CellValueProviderAttributes;

Property Value

Excel.CellValueProviderAttributes

Remarks

[ API set: ExcelApi 1.16 ]

relatedImagesAddress

Represents the URL of a webpage with images that are considered related to this WebImageCellValue.

relatedImagesAddress?: string;

Property Value

string

Remarks

[ API set: ExcelApi 1.16 ]

type

Represents the type of this cell value.

type: CellValueType.webImage | "WebImage";

Property Value

webImage | "WebImage"

Remarks

[ API set: ExcelApi 1.16 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/20-data-types/data-types-web-image.yaml

// This function inserts a web image into the currently selected cell.
await Excel.run(async (context) => {
  // Retrieve image data from the task pane and then clear the input fields.
  const imageUrl = $("#url").val() as string;
  const imageAltText = $("#alt-text").val() as string;
  clearForm();

  // Load the active cell.
  const activeCell = context.workbook.getActiveCell();
  activeCell.load();
  await context.sync();

  if (!imageUrl) {
    console.log("Please enter an image URL.");
    return;
  }

  // Create a web image object and assign the image details.
  const webImage: Excel.WebImageCellValue = {
    type: "WebImage", /* The string equivalent of `Excel.CellValueType.webImage`. */
    address: imageUrl,
    altText: imageAltText     
  };

  // Insert web image into the active cell.
  activeCell.valuesAsJson = [[webImage]];

  await context.sync();
});