excel.worksheet.yml

### YamlMime:TSType
name: Excel.Worksheet
uid: 'excel!Excel.Worksheet:class'
package: excel!
fullName: Excel.Worksheet
summary: >-
  An Excel worksheet is a grid of cells. It can contain data, tables, charts, etc. To learn more about the worksheet
  object model, read [Work with worksheets using the Excel JavaScript
  API](https://learn.microsoft.com/office/dev/add-ins/excel/excel-add-ins-worksheets)<!-- -->.
remarks: |-
  \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

  #### Examples

  ```TypeScript
  // Get a Worksheet object by its name and activate it.
  await Excel.run(async (context) => { 
      const wSheetName = 'Sheet1';
      const worksheet = context.workbook.worksheets.getItem(wSheetName);
      worksheet.activate();
      await context.sync(); 
  });
  ```
isPreview: false
isDeprecated: false
type: class
properties:
  - name: autoFilter
    uid: 'excel!Excel.Worksheet#autoFilter:member'
    package: excel!
    fullName: autoFilter
    summary: Represents the `AutoFilter` object of the worksheet.
    remarks: >-
      \[ [API set: ExcelApi 1.9](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-auto-filter.yaml


      // This function adds a percentage AutoFilter to the active worksheet 

      // and applies the filter to a column of the used range.

      await Excel.run(async (context) => {
          // Retrieve the active worksheet and the used range on that worksheet.
          const sheet = context.workbook.worksheets.getActiveWorksheet();
          const farmData = sheet.getUsedRange();

          // Add a filter that will only show the rows with the top 50% of values in column 3.
          sheet.autoFilter.apply(farmData, 3, {
              criterion1: "50",
              filterOn: Excel.FilterOn.topPercent
          });

          await context.sync();
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly autoFilter: Excel.AutoFilter;'
      return:
        type: '<xref uid="excel!Excel.AutoFilter:class" />'
  - name: charts
    uid: 'excel!Excel.Worksheet#charts:member'
    package: excel!
    fullName: charts
    summary: Returns a collection of charts that are part of the worksheet.
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly charts: Excel.ChartCollection;'
      return:
        type: '<xref uid="excel!Excel.ChartCollection:class" />'
  - name: comments
    uid: 'excel!Excel.Worksheet#comments:member'
    package: excel!
    fullName: comments
    summary: Returns a collection of all the Comments objects on the worksheet.
    remarks: '\[ [API set: ExcelApi 1.10](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly comments: Excel.CommentCollection;'
      return:
        type: '<xref uid="excel!Excel.CommentCollection:class" />'
  - name: context
    uid: 'excel!Excel.Worksheet#context:member'
    package: excel!
    fullName: context
    summary: >-
      The request context associated with the object. This connects the add-in's process to the Office host
      application's process.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'context: RequestContext;'
      return:
        type: '<xref uid="excel!Excel.RequestContext:class" />'
  - name: customProperties
    uid: 'excel!Excel.Worksheet#customProperties:member'
    package: excel!
    fullName: customProperties
    summary: Gets a collection of worksheet-level custom properties.
    remarks: >-
      \[ [API set: ExcelApi 1.12](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/26-document/custom-properties.yaml


      await Excel.run(async (context) => {
        // Load the keys and values of all custom properties in the current worksheet.
        const customWorksheetProperties = context.workbook.worksheets.getActiveWorksheet().customProperties;
        customWorksheetProperties.load(["key", "value"]);
        await context.sync();

        // Log each custom property to the console.
        // Note that your document may have more properties than those you have set using this snippet.
        customWorksheetProperties.items.forEach((property) => {
          console.log(`${property.key}:${property.value}`);
        });
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly customProperties: Excel.WorksheetCustomPropertyCollection;'
      return:
        type: '<xref uid="excel!Excel.WorksheetCustomPropertyCollection:class" />'
  - name: enableCalculation
    uid: 'excel!Excel.Worksheet#enableCalculation:member'
    package: excel!
    fullName: enableCalculation
    summary: >-
      Determines if Excel should recalculate the worksheet when necessary. True if Excel recalculates the worksheet when
      necessary. False if Excel doesn't recalculate the sheet.
    remarks: '\[ [API set: ExcelApi 1.9](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'enableCalculation: boolean;'
      return:
        type: boolean
  - name: freezePanes
    uid: 'excel!Excel.Worksheet#freezePanes:member'
    package: excel!
    fullName: freezePanes
    summary: Gets an object that can be used to manipulate frozen panes on the worksheet.
    remarks: '\[ [API set: ExcelApi 1.7](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly freezePanes: Excel.WorksheetFreezePanes;'
      return:
        type: '<xref uid="excel!Excel.WorksheetFreezePanes:class" />'
  - name: horizontalPageBreaks
    uid: 'excel!Excel.Worksheet#horizontalPageBreaks:member'
    package: excel!
    fullName: horizontalPageBreaks
    summary: Gets the horizontal page break collection for the worksheet. This collection only contains manual page breaks.
    remarks: '\[ [API set: ExcelApi 1.9](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly horizontalPageBreaks: Excel.PageBreakCollection;'
      return:
        type: '<xref uid="excel!Excel.PageBreakCollection:class" />'
  - name: id
    uid: 'excel!Excel.Worksheet#id:member'
    package: excel!
    fullName: id
    summary: >-
      Returns a value that uniquely identifies the worksheet in a given workbook. The value of the identifier remains
      the same even when the worksheet is renamed or moved.
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly id: string;'
      return:
        type: string
  - name: name
    uid: 'excel!Excel.Worksheet#name:member'
    package: excel!
    fullName: name
    summary: The display name of the worksheet. The name must be fewer than 32 characters.
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'name: string;'
      return:
        type: string
  - name: names
    uid: 'excel!Excel.Worksheet#names:member'
    package: excel!
    fullName: names
    summary: Collection of names scoped to the current worksheet.
    remarks: '\[ [API set: ExcelApi 1.4](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly names: Excel.NamedItemCollection;'
      return:
        type: '<xref uid="excel!Excel.NamedItemCollection:class" />'
  - name: pageLayout
    uid: 'excel!Excel.Worksheet#pageLayout:member'
    package: excel!
    fullName: pageLayout
    summary: Gets the `PageLayout` object of the worksheet.
    remarks: '\[ [API set: ExcelApi 1.9](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly pageLayout: Excel.PageLayout;'
      return:
        type: '<xref uid="excel!Excel.PageLayout:class" />'
  - name: pivotTables
    uid: 'excel!Excel.Worksheet#pivotTables:member'
    package: excel!
    fullName: pivotTables
    summary: Collection of PivotTables that are part of the worksheet.
    remarks: >-
      \[ [API set: ExcelApi 1.3](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-get-pivottables.yaml


      await Excel.run(async (context) => {
        // Get the names of all the PivotTables in the current worksheet.
        const pivotTables = context.workbook.worksheets.getActiveWorksheet().pivotTables;
        pivotTables.load("name");
        await context.sync();

        // Display the names in the console.
        console.log("PivotTables in the current worksheet:")
        pivotTables.items.forEach((pivotTable) => {
          console.log(`\t${pivotTable.name}`);
        });
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly pivotTables: Excel.PivotTableCollection;'
      return:
        type: '<xref uid="excel!Excel.PivotTableCollection:class" />'
  - name: position
    uid: 'excel!Excel.Worksheet#position:member'
    package: excel!
    fullName: position
    summary: The zero-based position of the worksheet within the workbook.
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      // Set worksheet position.
      await Excel.run(async (context) => { 
          const wSheetName = 'Sheet1';
          const worksheet = context.workbook.worksheets.getItem(wSheetName);
          worksheet.position = 2;
          await context.sync(); 
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'position: number;'
      return:
        type: number
  - name: protection
    uid: 'excel!Excel.Worksheet#protection:member'
    package: excel!
    fullName: protection
    summary: Returns the sheet protection object for a worksheet.
    remarks: |-
      \[ [API set: ExcelApi 1.2](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      // Unprotecting a worksheet with unprotect() will remove all 
      // WorksheetProtectionOptions options applied to a worksheet.
      // To remove only a subset of WorksheetProtectionOptions use the 
      // protect() method and set the options you wish to remove to true.
      await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getItem("Sheet1");
        sheet.protection.protect({
          allowInsertRows: false, // Protect row insertion
          allowDeleteRows: true // Unprotect row deletion
        });
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly protection: Excel.WorksheetProtection;'
      return:
        type: '<xref uid="excel!Excel.WorksheetProtection:class" />'
  - name: shapes
    uid: 'excel!Excel.Worksheet#shapes:member'
    package: excel!
    fullName: shapes
    summary: Returns the collection of all the Shape objects on the worksheet.
    remarks: '\[ [API set: ExcelApi 1.9](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly shapes: Excel.ShapeCollection;'
      return:
        type: '<xref uid="excel!Excel.ShapeCollection:class" />'
  - name: showGridlines
    uid: 'excel!Excel.Worksheet#showGridlines:member'
    package: excel!
    fullName: showGridlines
    summary: Specifies if gridlines are visible to the user.
    remarks: >-
      \[ [API set: ExcelApi 1.8](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/gridlines.yaml


      await Excel.run(async (context) => {
          const sheet = context.workbook.worksheets.getActiveWorksheet();
          sheet.showGridlines = true;

          await context.sync();
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'showGridlines: boolean;'
      return:
        type: boolean
  - name: showHeadings
    uid: 'excel!Excel.Worksheet#showHeadings:member'
    package: excel!
    fullName: showHeadings
    summary: Specifies if headings are visible to the user.
    remarks: '\[ [API set: ExcelApi 1.8](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'showHeadings: boolean;'
      return:
        type: boolean
  - name: slicers
    uid: 'excel!Excel.Worksheet#slicers:member'
    package: excel!
    fullName: slicers
    summary: Returns a collection of slicers that are part of the worksheet.
    remarks: >-
      \[ [API set: ExcelApi 1.10](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-slicer.yaml


      await Excel.run(async (context) => {
          const sheet = context.workbook.worksheets.getItem("Pivot");
          const slicer = sheet.slicers.add(
              "Farm Sales", /* The slicer data source. For PivotTables, this can be the PivotTable object reference or name. */
              "Type" /* The field in the data source to filter by. For PivotTables, this can be a PivotField object reference or ID. */
          );
          slicer.name = "Fruit Slicer";
          await context.sync();
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly slicers: Excel.SlicerCollection;'
      return:
        type: '<xref uid="excel!Excel.SlicerCollection:class" />'
  - name: standardHeight
    uid: 'excel!Excel.Worksheet#standardHeight:member'
    package: excel!
    fullName: standardHeight
    summary: 'Returns the standard (default) height of all the rows in the worksheet, in points.'
    remarks: '\[ [API set: ExcelApi 1.7](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly standardHeight: number;'
      return:
        type: number
  - name: standardWidth
    uid: 'excel!Excel.Worksheet#standardWidth:member'
    package: excel!
    fullName: standardWidth
    summary: >-
      Specifies the standard (default) width of all the columns in the worksheet. One unit of column width is equal to
      the width of one character in the Normal style. For proportional fonts, the width of the character 0 (zero) is
      used.
    remarks: '\[ [API set: ExcelApi 1.7](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'standardWidth: number;'
      return:
        type: number
  - name: tabColor
    uid: 'excel!Excel.Worksheet#tabColor:member'
    package: excel!
    fullName: tabColor
    summary: >-
      The tab color of the worksheet. When retrieving the tab color, if the worksheet is invisible, the value will be
      `null`<!-- -->. If the worksheet is visible but the tab color is set to auto, an empty string will be returned.
      Otherwise, the property will be set to a color, in the form \#RRGGBB (e.g., "FFA500"). When setting the color, use
      an empty-string to set an "auto" color, or a real color otherwise.
    remarks: >-
      \[ [API set: ExcelApi 1.7](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/tab-color.yaml


      await Excel.run(async (context) => {
          const activeSheet = context.workbook.worksheets.getActiveWorksheet();
          activeSheet.tabColor = "#FF0000";

          await context.sync();
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'tabColor: string;'
      return:
        type: string
  - name: tabId
    uid: 'excel!Excel.Worksheet#tabId:member'
    package: excel!
    fullName: tabId
    summary: >-
      Returns a value representing this worksheet that can be read by Open Office XML. This is an integer value, which
      is different from `worksheet.id` (which returns a globally unique identifier) and `worksheet.name` (which returns
      a value such as "Sheet1").
    remarks: '\[ [API set: ExcelApi 1.14](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly tabId: number;'
      return:
        type: number
  - name: tables
    uid: 'excel!Excel.Worksheet#tables:member'
    package: excel!
    fullName: tables
    summary: Collection of tables that are part of the worksheet.
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly tables: Excel.TableCollection;'
      return:
        type: '<xref uid="excel!Excel.TableCollection:class" />'
  - name: verticalPageBreaks
    uid: 'excel!Excel.Worksheet#verticalPageBreaks:member'
    package: excel!
    fullName: verticalPageBreaks
    summary: Gets the vertical page break collection for the worksheet. This collection only contains manual page breaks.
    remarks: '\[ [API set: ExcelApi 1.9](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly verticalPageBreaks: Excel.PageBreakCollection;'
      return:
        type: '<xref uid="excel!Excel.PageBreakCollection:class" />'
  - name: visibility
    uid: 'excel!Excel.Worksheet#visibility:member'
    package: excel!
    fullName: visibility
    summary: The visibility of the worksheet.
    remarks: >-
      \[ [API set: ExcelApi 1.1 for reading visibility; 1.2 for setting
      it.](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'visibility: Excel.SheetVisibility | "Visible" | "Hidden" | "VeryHidden";'
      return:
        type: '<xref uid="excel!Excel.SheetVisibility:enum" /> | "Visible" | "Hidden" | "VeryHidden"'
methods:
  - name: activate()
    uid: 'excel!Excel.Worksheet#activate:member(1)'
    package: excel!
    fullName: activate()
    summary: Activate the worksheet in the Excel UI.
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => { 
          const wSheetName = 'Sheet1';
          const worksheet = context.workbook.worksheets.getItem(wSheetName);
          worksheet.activate();
          await context.sync(); 
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'activate(): void;'
      return:
        type: void
        description: ''
  - name: calculate(markAllDirty)
    uid: 'excel!Excel.Worksheet#calculate:member(1)'
    package: excel!
    fullName: calculate(markAllDirty)
    summary: Calculates all cells on a worksheet.
    remarks: '\[ [API set: ExcelApi 1.6](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'calculate(markAllDirty: boolean): void;'
      parameters:
        - id: markAllDirty
          description: 'True, to mark all as dirty.'
          type: boolean
      return:
        type: void
        description: ''
  - name: 'copy(positionType, relativeTo)'
    uid: 'excel!Excel.Worksheet#copy:member(1)'
    package: excel!
    fullName: 'copy(positionType, relativeTo)'
    summary: Copies a worksheet and places it at the specified position.
    remarks: >-
      \[ [API set: ExcelApi 1.7](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-copy.yaml


      await Excel.run(async (context) => {

          let myWorkbook = context.workbook;
          let sampleSheet = myWorkbook.worksheets.getActiveWorksheet();
          let copiedSheet = sampleSheet.copy("End")

          sampleSheet.load("name");
          copiedSheet.load("name");

          await context.sync();

          console.log("'" + sampleSheet.name + "' was copied to '" + copiedSheet.name + "'")
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'copy(positionType?: Excel.WorksheetPositionType, relativeTo?: Excel.Worksheet): Excel.Worksheet;'
      parameters:
        - id: positionType
          description: >-
            The location in the workbook to place the newly created worksheet. The default value is "None", which
            inserts the worksheet at the beginning of the worksheet.
          type: '<xref uid="excel!Excel.WorksheetPositionType:enum" />'
        - id: relativeTo
          description: >-
            The existing worksheet which determines the newly created worksheet's position. This is only needed if
            `positionType` is "Before" or "After".
          type: '<xref uid="excel!Excel.Worksheet:class" />'
      return:
        type: '<xref uid="excel!Excel.Worksheet:class" />'
        description: The newly created worksheet.
  - name: 'copy(positionTypeString, relativeTo)'
    uid: 'excel!Excel.Worksheet#copy:member(2)'
    package: excel!
    fullName: 'copy(positionTypeString, relativeTo)'
    summary: Copies a worksheet and places it at the specified position.
    remarks: '\[ [API set: ExcelApi 1.7](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        copy(positionTypeString?: "None" | "Before" | "After" | "Beginning" | "End", relativeTo?: Excel.Worksheet):
        Excel.Worksheet;
      parameters:
        - id: positionTypeString
          description: >-
            The location in the workbook to place the newly created worksheet. The default value is "None", which
            inserts the worksheet at the beginning of the worksheet.
          type: '"None" | "Before" | "After" | "Beginning" | "End"'
        - id: relativeTo
          description: >-
            The existing worksheet which determines the newly created worksheet's position. This is only needed if
            `positionType` is "Before" or "After".
          type: '<xref uid="excel!Excel.Worksheet:class" />'
      return:
        type: '<xref uid="excel!Excel.Worksheet:class" />'
        description: The newly created worksheet.
  - name: delete()
    uid: 'excel!Excel.Worksheet#delete:member(1)'
    package: excel!
    fullName: delete()
    summary: >-
      Deletes the worksheet from the workbook. Note that if the worksheet's visibility is set to "VeryHidden", the
      delete operation will fail with an `InvalidOperation` exception. You should first change its visibility to hidden
      or visible before deleting it.
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => { 
          const wSheetName = 'Sheet1';
          const worksheet = context.workbook.worksheets.getItem(wSheetName);
          worksheet.delete();
          await context.sync(); 
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'delete(): void;'
      return:
        type: void
        description: ''
  - name: 'findAll(text, criteria)'
    uid: 'excel!Excel.Worksheet#findAll:member(1)'
    package: excel!
    fullName: 'findAll(text, criteria)'
    summary: >-
      Finds all occurrences of the given string based on the criteria specified and returns them as a `RangeAreas`
      object, comprising one or more rectangular ranges.
    remarks: '\[ [API set: ExcelApi 1.9](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'findAll(text: string, criteria: Excel.WorksheetSearchCriteria): Excel.RangeAreas;'
      parameters:
        - id: text
          description: The string to find.
          type: string
        - id: criteria
          description: >-
            Additional search criteria, including whether the search needs to match the entire cell or be
            case-sensitive.
          type: '<xref uid="excel!Excel.WorksheetSearchCriteria:interface" />'
      return:
        type: '<xref uid="excel!Excel.RangeAreas:class" />'
        description: >-
          A `RangeAreas` object, comprising one or more rectangular ranges, that matches the search criteria. If no
          cells meet this criteria, an `ItemNotFound` error will be thrown.
  - name: 'findAllOrNullObject(text, criteria)'
    uid: 'excel!Excel.Worksheet#findAllOrNullObject:member(1)'
    package: excel!
    fullName: 'findAllOrNullObject(text, criteria)'
    summary: >-
      Finds all occurrences of the given string based on the criteria specified and returns them as a `RangeAreas`
      object, comprising one or more rectangular ranges.
    remarks: >-
      \[ [API set: ExcelApi 1.9](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-find-all.yaml


      await Excel.run(async (context) => {
          const sheet = context.workbook.worksheets.getItem("Sample");
          const foundRanges = sheet.findAllOrNullObject("Complete", {
              completeMatch: true,
              matchCase: false
          });

          await context.sync();

          if (foundRanges.isNullObject) {
              console.log("No complete projects");
          } else {
              foundRanges.format.fill.color = "green"
          }
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'findAllOrNullObject(text: string, criteria: Excel.WorksheetSearchCriteria): Excel.RangeAreas;'
      parameters:
        - id: text
          description: The string to find.
          type: string
        - id: criteria
          description: >-
            Additional search criteria, including whether the search needs to match the entire cell or be
            case-sensitive.
          type: '<xref uid="excel!Excel.WorksheetSearchCriteria:interface" />'
      return:
        type: '<xref uid="excel!Excel.RangeAreas:class" />'
        description: >-
          A `RangeAreas` object, comprising one or more rectangular ranges, that matches the search criteria. If there
          are no matches, then this method returns an object with its `isNullObject` property set to `true`<!-- -->. For
          further information, see [*OrNullObject methods and
          properties](https://learn.microsoft.com/office/dev/add-ins/develop/application-specific-api-model#ornullobject-methods-and-properties)<!--
          -->.
  - name: 'getCell(row, column)'
    uid: 'excel!Excel.Worksheet#getCell:member(1)'
    package: excel!
    fullName: 'getCell(row, column)'
    summary: >-
      Gets the `Range` object containing the single cell based on row and column numbers. The cell can be outside the
      bounds of its parent range, so long as it stays within the worksheet grid.
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => { 
          const sheetName = "Sheet1";
          const rangeAddress = "A1:F8";
          const worksheet = context.workbook.worksheets.getItem(sheetName);
          const cell = worksheet.getCell(0,0);
          cell.load('address');
          await context.sync();

          console.log(cell.address);
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getCell(row: number, column: number): Excel.Range;'
      parameters:
        - id: row
          description: The row number of the cell to be retrieved. Zero-indexed.
          type: number
        - id: column
          description: The column number of the cell to be retrieved. Zero-indexed.
          type: number
      return:
        type: '<xref uid="excel!Excel.Range:class" />'
        description: ''
  - name: getNext(visibleOnly)
    uid: 'excel!Excel.Worksheet#getNext:member(1)'
    package: excel!
    fullName: getNext(visibleOnly)
    summary: >-
      Gets the worksheet that follows this one. If there are no worksheets following this one, this method will throw an
      error.
    remarks: >-
      \[ [API set: ExcelApi 1.5](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/reference-worksheets-by-relative-position.yaml


      await Excel.run(async (context) => {
          const sheets = context.workbook.worksheets;

          // We don't want to include the default worksheet that was created
          // when the workbook was created, so our "firstSheet" will be the one
          // after the literal first. Note chaining of navigation methods.
          const firstSheet = sheets.getFirst().getNext();
          const lastSheet = sheets.getLast();
          const firstTaxRateRange = firstSheet.getRange("B2");
          const lastTaxRateRange = lastSheet.getRange("B2");

          firstSheet.load("name");
          lastSheet.load("name");
          firstTaxRateRange.load("text");
          lastTaxRateRange.load("text");

          await context.sync();

          let firstYear = firstSheet.name.substr(5, 4);
          let lastYear = lastSheet.name.substr(5, 4);
          console.log(`Tax Rate change from ${firstYear} to ${lastYear}`, `Tax rate for ${firstYear}: ${firstTaxRateRange.text[0][0]}\nTax rate for ${lastYear}: ${lastTaxRateRange.text[0][0]}`)

          await context.sync();
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getNext(visibleOnly?: boolean): Excel.Worksheet;'
      parameters:
        - id: visibleOnly
          description: 'Optional. If `true`<!-- -->, considers only visible worksheets, skipping over any hidden ones.'
          type: boolean
      return:
        type: '<xref uid="excel!Excel.Worksheet:class" />'
        description: ''
  - name: getNextOrNullObject(visibleOnly)
    uid: 'excel!Excel.Worksheet#getNextOrNullObject:member(1)'
    package: excel!
    fullName: getNextOrNullObject(visibleOnly)
    summary: >-
      Gets the worksheet that follows this one. If there are no worksheets following this one, then this method returns
      an object with its `isNullObject` property set to `true`<!-- -->. For further information, see [*OrNullObject
      methods and
      properties](https://learn.microsoft.com/office/dev/add-ins/develop/application-specific-api-model#ornullobject-methods-and-properties)<!--
      -->.
    remarks: '\[ [API set: ExcelApi 1.5](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getNextOrNullObject(visibleOnly?: boolean): Excel.Worksheet;'
      parameters:
        - id: visibleOnly
          description: 'Optional. If `true`<!-- -->, considers only visible worksheets, skipping over any hidden ones.'
          type: boolean
      return:
        type: '<xref uid="excel!Excel.Worksheet:class" />'
        description: ''
  - name: getPrevious(visibleOnly)
    uid: 'excel!Excel.Worksheet#getPrevious:member(1)'
    package: excel!
    fullName: getPrevious(visibleOnly)
    summary: 'Gets the worksheet that precedes this one. If there are no previous worksheets, this method will throw an error.'
    remarks: >-
      \[ [API set: ExcelApi 1.5](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/reference-worksheets-by-relative-position.yaml


      await Excel.run(async (context) => {
          const sheets = context.workbook.worksheets;
          const currentSheet = sheets.getActiveWorksheet();
          const previousYearSheet = currentSheet.getPrevious();
          const currentTaxDueRange = currentSheet.getRange("C2");
          const previousTaxDueRange = previousYearSheet.getRange("C2");

          currentSheet.load("name");
          previousYearSheet.load("name");
          currentTaxDueRange.load("text");
          previousTaxDueRange.load("text");

          await context.sync();

          let currentYear = currentSheet.name.substr(5, 4);
          let previousYear = previousYearSheet.name.substr(5, 4);
          console.log("Two Year Tax Due Comparison", `Tax due for ${currentYear} was ${currentTaxDueRange.text[0][0]}\nTax due for ${previousYear} was ${previousTaxDueRange.text[0][0]}`)

          await context.sync();
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getPrevious(visibleOnly?: boolean): Excel.Worksheet;'
      parameters:
        - id: visibleOnly
          description: 'Optional. If `true`<!-- -->, considers only visible worksheets, skipping over any hidden ones.'
          type: boolean
      return:
        type: '<xref uid="excel!Excel.Worksheet:class" />'
        description: ''
  - name: getPreviousOrNullObject(visibleOnly)
    uid: 'excel!Excel.Worksheet#getPreviousOrNullObject:member(1)'
    package: excel!
    fullName: getPreviousOrNullObject(visibleOnly)
    summary: >-
      Gets the worksheet that precedes this one. If there are no previous worksheets, then this method returns an object
      with its `isNullObject` property set to `true`<!-- -->. For further information, see [*OrNullObject methods and
      properties](https://learn.microsoft.com/office/dev/add-ins/develop/application-specific-api-model#ornullobject-methods-and-properties)<!--
      -->.
    remarks: '\[ [API set: ExcelApi 1.5](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getPreviousOrNullObject(visibleOnly?: boolean): Excel.Worksheet;'
      parameters:
        - id: visibleOnly
          description: 'Optional. If `true`<!-- -->, considers only visible worksheets, skipping over any hidden ones.'
          type: boolean
      return:
        type: '<xref uid="excel!Excel.Worksheet:class" />'
        description: ''
  - name: getRange(address)
    uid: 'excel!Excel.Worksheet#getRange:member(1)'
    package: excel!
    fullName: getRange(address)
    summary: 'Gets the `Range` object, representing a single rectangular block of cells, specified by the address or name.'
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      // Use the range address to get the range object.
      await Excel.run(async (context) => { 
          const sheetName = "Sheet1";
          const rangeAddress = "A1:F8";
          const worksheet = context.workbook.worksheets.getItem(sheetName);
          const range = worksheet.getRange(rangeAddress);
          range.load('cellCount');
          await context.sync();
          
          console.log(range.cellCount);
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getRange(address?: string): Excel.Range;'
      parameters:
        - id: address
          description: >-
            Optional. The string representing the address or name of the range. For example, "A1:B2". If not specified,
            the entire worksheet range is returned.
          type: string
      return:
        type: '<xref uid="excel!Excel.Range:class" />'
        description: ''
  - name: 'getRangeByIndexes(startRow, startColumn, rowCount, columnCount)'
    uid: 'excel!Excel.Worksheet#getRangeByIndexes:member(1)'
    package: excel!
    fullName: 'getRangeByIndexes(startRow, startColumn, rowCount, columnCount)'
    summary: >-
      Gets the `Range` object beginning at a particular row index and column index, and spanning a certain number of
      rows and columns.
    remarks: '\[ [API set: ExcelApi 1.7](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getRangeByIndexes(startRow: number, startColumn: number, rowCount: number, columnCount: number): Excel.Range;'
      parameters:
        - id: startRow
          description: Start row (zero-indexed).
          type: number
        - id: startColumn
          description: Start column (zero-indexed).
          type: number
        - id: rowCount
          description: Number of rows to include in the range.
          type: number
        - id: columnCount
          description: Number of columns to include in the range.
          type: number
      return:
        type: '<xref uid="excel!Excel.Range:class" />'
        description: ''
  - name: getRanges(address)
    uid: 'excel!Excel.Worksheet#getRanges:member(1)'
    package: excel!
    fullName: getRanges(address)
    summary: >-
      Gets the `RangeAreas` object, representing one or more blocks of rectangular ranges, specified by the address or
      name.
    remarks: >-
      \[ [API set: ExcelApi 1.9](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-areas.yaml


      await Excel.run(async (context) => {

          const sheet = context.workbook.worksheets.getActiveWorksheet();
          const specifiedRanges = sheet.getRanges("D3:D5, G3:G5");
          specifiedRanges.format.fill.color = "pink";

          await context.sync();
      })

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getRanges(address?: string): Excel.RangeAreas;'
      parameters:
        - id: address
          description: >-
            Optional. A string containing the comma-separated or semicolon-separated addresses or names of the
            individual ranges. For example, "A1:B2, A5:B5" or "A1:B2; A5:B5". If not specified, a `RangeAreas` object
            for the entire worksheet is returned.
          type: string
      return:
        type: '<xref uid="excel!Excel.RangeAreas:class" />'
        description: ''
  - name: getUsedRange(valuesOnly)
    uid: 'excel!Excel.Worksheet#getUsedRange:member(1)'
    package: excel!
    fullName: getUsedRange(valuesOnly)
    summary: >-
      The used range is the smallest range that encompasses any cells that have a value or formatting assigned to them.
      If the entire worksheet is blank, this function will return the top left cell (i.e. it will *not* throw an
      error).
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => { 
          const wSheetName = 'Sheet1';
          const worksheet = context.workbook.worksheets.getItem(wSheetName);
          const usedRange = worksheet.getUsedRange();
          usedRange.load('address');
          await context.sync();
          
          console.log(usedRange.address);
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getUsedRange(valuesOnly?: boolean): Excel.Range;'
      parameters:
        - id: valuesOnly
          description: >-
            Optional. If `true`<!-- -->, considers only cells with values as used cells (ignoring formatting). \[Api
            set: ExcelApi 1.2\]
          type: boolean
      return:
        type: '<xref uid="excel!Excel.Range:class" />'
        description: ''
  - name: getUsedRangeOrNullObject(valuesOnly)
    uid: 'excel!Excel.Worksheet#getUsedRangeOrNullObject:member(1)'
    package: excel!
    fullName: getUsedRangeOrNullObject(valuesOnly)
    summary: >-
      The used range is the smallest range that encompasses any cells that have a value or formatting assigned to them.
      If the entire worksheet is blank, then this method returns an object with its `isNullObject` property set to
      `true`<!-- -->. For further information, see [*OrNullObject methods and
      properties](https://learn.microsoft.com/office/dev/add-ins/develop/application-specific-api-model#ornullobject-methods-and-properties)<!--
      -->.
    remarks: '\[ [API set: ExcelApi 1.4](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'getUsedRangeOrNullObject(valuesOnly?: boolean): Excel.Range;'
      parameters:
        - id: valuesOnly
          description: Optional. Considers only cells with values as used cells.
          type: boolean
      return:
        type: '<xref uid="excel!Excel.Range:class" />'
        description: ''
  - name: load(options)
    uid: 'excel!Excel.Worksheet#load:member(1)'
    package: excel!
    fullName: load(options)
    summary: >-
      Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading
      the properties.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'load(options?: Excel.Interfaces.WorksheetLoadOptions): Excel.Worksheet;'
      parameters:
        - id: options
          description: Provides options for which properties of the object to load.
          type: '<xref uid="excel!Excel.Interfaces.WorksheetLoadOptions:interface" />'
      return:
        type: '<xref uid="excel!Excel.Worksheet:class" />'
        description: ''
  - name: load(propertyNames)
    uid: 'excel!Excel.Worksheet#load:member(2)'
    package: excel!
    fullName: load(propertyNames)
    summary: >-
      Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading
      the properties.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'load(propertyNames?: string | string[]): Excel.Worksheet;'
      parameters:
        - id: propertyNames
          description: A comma-delimited string or an array of strings that specify the properties to load.
          type: 'string | string[]'
      return:
        type: '<xref uid="excel!Excel.Worksheet:class" />'
        description: |-


          #### Examples

          ```TypeScript
          // Get worksheet properties based on sheet name.
          await Excel.run(async (context) => { 
              const wSheetName = 'Sheet1';
              const worksheet = context.workbook.worksheets.getItem(wSheetName);
              worksheet.load('position')
              await context.sync();
              
              console.log(worksheet.position);
          });
          ```
  - name: load(propertyNamesAndPaths)
    uid: 'excel!Excel.Worksheet#load:member(3)'
    package: excel!
    fullName: load(propertyNamesAndPaths)
    summary: >-
      Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading
      the properties.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: |-
        load(propertyNamesAndPaths?: {
                    select?: string;
                    expand?: string;
                }): Excel.Worksheet;
      parameters:
        - id: propertyNamesAndPaths
          description: >-
            `propertyNamesAndPaths.select` is a comma-delimited string that specifies the properties to load, and
            `propertyNamesAndPaths.expand` is a comma-delimited string that specifies the navigation properties to load.
          type: |-
            {
                        select?: string;
                        expand?: string;
                    }
      return:
        type: '<xref uid="excel!Excel.Worksheet:class" />'
        description: ''
  - name: 'replaceAll(text, replacement, criteria)'
    uid: 'excel!Excel.Worksheet#replaceAll:member(1)'
    package: excel!
    fullName: 'replaceAll(text, replacement, criteria)'
    summary: Finds and replaces the given string based on the criteria specified within the current worksheet.
    remarks: '\[ [API set: ExcelApi 1.9](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        replaceAll(text: string, replacement: string, criteria: Excel.ReplaceCriteria):
        OfficeExtension.ClientResult<number>;
      parameters:
        - id: text
          description: String to find.
          type: string
        - id: replacement
          description: The string that replaces the original string.
          type: string
        - id: criteria
          description: Additional replacement criteria.
          type: '<xref uid="excel!Excel.ReplaceCriteria:interface" />'
      return:
        type: '<xref uid="office!OfficeExtension.ClientResult:class" />&lt;number&gt;'
        description: The number of replacements performed.
  - name: 'set(properties, options)'
    uid: 'excel!Excel.Worksheet#set:member(1)'
    package: excel!
    fullName: 'set(properties, options)'
    summary: >-
      Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate
      properties, or another API object of the same type.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'set(properties: Interfaces.WorksheetUpdateData, options?: OfficeExtension.UpdateOptions): void;'
      parameters:
        - id: properties
          description: >-
            A JavaScript object with properties that are structured isomorphically to the properties of the object on
            which the method is called.
          type: '<xref uid="excel!Excel.Interfaces.WorksheetUpdateData:interface" />'
        - id: options
          description: Provides an option to suppress errors if the properties object tries to set any read-only properties.
          type: '<xref uid="office!OfficeExtension.UpdateOptions:interface" />'
      return:
        type: void
        description: |-


          #### Examples

          ```TypeScript
          // Set the color and name of the current worksheet.
          await Excel.run(async (context) => {
            const activeSheet = context.workbook.worksheets.getActiveWorksheet();
            activeSheet.set({
              tabColor: "yellow",
              name: "MySheet"
            });

            await context.sync();
          });
          ```
  - name: set(properties)
    uid: 'excel!Excel.Worksheet#set:member(2)'
    package: excel!
    fullName: set(properties)
    summary: 'Sets multiple properties on the object at the same time, based on an existing loaded object.'
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'set(properties: Excel.Worksheet): void;'
      parameters:
        - id: properties
          description: ''
          type: '<xref uid="excel!Excel.Worksheet:class" />'
      return:
        type: void
        description: ''
  - name: 'showOutlineLevels(rowLevels, columnLevels)'
    uid: 'excel!Excel.Worksheet#showOutlineLevels:member(1)'
    package: excel!
    fullName: 'showOutlineLevels(rowLevels, columnLevels)'
    summary: >-
      Shows row or column groups by their outline levels. Outlines groups and summarizes a list of data in the
      worksheet. The `rowLevels` and `columnLevels` parameters specify how many levels of the outline will be displayed.
      The acceptable argument range is between 0 and 8. A value of 0 does not change the current display. A value
      greater than the current number of levels displays all the levels.
    remarks: >-
      \[ [API set: ExcelApi 1.10](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/outline.yaml


      Excel.run(async (context) => {
          const sheet = context.workbook.worksheets.getActiveWorksheet();

          // This shows the top 3 outline levels; collapsing any additional sublevels.
          sheet.showOutlineLevels(3, 3);
          await context.sync();
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'showOutlineLevels(rowLevels: number, columnLevels: number): void;'
      parameters:
        - id: rowLevels
          description: The number of row levels of an outline to display.
          type: number
        - id: columnLevels
          description: The number of column levels of an outline to display.
          type: number
      return:
        type: void
        description: ''
  - name: toJSON()
    uid: 'excel!Excel.Worksheet#toJSON:member(1)'
    package: excel!
    fullName: toJSON()
    summary: >-
      Overrides the JavaScript `toJSON()` method in order to provide more useful output when an API object is passed to
      `JSON.stringify()`<!-- -->. (`JSON.stringify`<!-- -->, in turn, calls the `toJSON` method of the object that is
      passed to it.) Whereas the original `Excel.Worksheet` object is an API object, the `toJSON` method returns a plain
      JavaScript object (typed as `Excel.Interfaces.WorksheetData`<!-- -->) that contains shallow copies of any loaded
      child properties from the original object.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'toJSON(): Excel.Interfaces.WorksheetData;'
      return:
        type: '<xref uid="excel!Excel.Interfaces.WorksheetData:interface" />'
        description: ''
events:
  - name: onActivated
    uid: 'excel!Excel.Worksheet#onActivated:member'
    package: excel!
    fullName: onActivated
    summary: Occurs when the worksheet is activated.
    remarks: |-
      \[ [API set: ExcelApi 1.7](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => {
          const sheet = context.workbook.worksheets.getItem("Sample");
          sheet.onActivated.add(function (event) {
              return Excel.run(async (context) => {
                  console.log("The activated worksheet ID is: " + event.worksheetId);
                  await context.sync();
              });
          });
          await context.sync();
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onActivated: OfficeExtension.EventHandlers<Excel.WorksheetActivatedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.WorksheetActivatedEventArgs:interface" />&gt;
  - name: onCalculated
    uid: 'excel!Excel.Worksheet#onCalculated:member'
    package: excel!
    fullName: onCalculated
    summary: Occurs when the worksheet is calculated.
    remarks: |-
      \[ [API set: ExcelApi 1.8](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => {
          const sheet = context.workbook.worksheets.getItem("Sample");
          sheet.onCalculated.add(function (event) {
              return Excel.run(async (context) => {
                  console.log("The worksheet has recalculated.");
                  await context.sync();
              });
          });
          await context.sync();
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onCalculated: OfficeExtension.EventHandlers<Excel.WorksheetCalculatedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.WorksheetCalculatedEventArgs:interface" />&gt;
  - name: onChanged
    uid: 'excel!Excel.Worksheet#onChanged:member'
    package: excel!
    fullName: onChanged
    summary: Occurs when data changes in a specific worksheet.
    remarks: >-
      \[ [API set: ExcelApi 1.7](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-worksheet.yaml


      await Excel.run(async (context) => {
          let sheet = context.workbook.worksheets.getItem("Sample");
          sheet.onChanged.add(onChange);
          await context.sync();

          console.log("Added a worksheet-level data-changed event handler.");
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onChanged: OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.WorksheetChangedEventArgs:interface" />&gt;
  - name: onColumnSorted
    uid: 'excel!Excel.Worksheet#onColumnSorted:member'
    package: excel!
    fullName: onColumnSorted
    summary: Occurs when one or more columns have been sorted. This happens as the result of a left to right sort operation.
    remarks: >-
      \[ [API set: ExcelApi 1.10](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-column-and-row-sort.yaml


      await Excel.run(async (context) => {
          console.log("Adding column handler");
          const sheet = context.workbook.worksheets.getActiveWorksheet();

          // This will fire whenever a column has been moved as the result of a sort action.
          sheet.onColumnSorted.add((event) => {
              return Excel.run((context) => {
                  console.log("Column sorted: " + event.address);
                  const sheet = context.workbook.worksheets.getActiveWorksheet();

                  // Clear formatting for section, then highlight the sorted area.
                  sheet.getRange("A1:E5").format.fill.clear();
                  if (event.address !== "") {
                      sheet.getRanges(event.address).format.fill.color = "yellow";
                  }

                  return context.sync();
              });
          });
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onColumnSorted: OfficeExtension.EventHandlers<Excel.WorksheetColumnSortedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.WorksheetColumnSortedEventArgs:interface" />&gt;
  - name: onDeactivated
    uid: 'excel!Excel.Worksheet#onDeactivated:member'
    package: excel!
    fullName: onDeactivated
    summary: Occurs when the worksheet is deactivated.
    remarks: |-
      \[ [API set: ExcelApi 1.7](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => {
          const sheet = context.workbook.worksheets.getItem("Sample");
          sheet.onDeactivated.add(function (event) {
              return Excel.run(async (context) => {
                  console.log("The deactivated worksheet is: " + event.worksheetId);
                  await context.sync();
              });
          });
          await context.sync();
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onDeactivated: OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.WorksheetDeactivatedEventArgs:interface" />&gt;
  - name: onFormatChanged
    uid: 'excel!Excel.Worksheet#onFormatChanged:member'
    package: excel!
    fullName: onFormatChanged
    summary: Occurs when format changed on a specific worksheet.
    remarks: '\[ [API set: ExcelApi 1.9](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onFormatChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.WorksheetFormatChangedEventArgs:interface" />&gt;
  - name: onFormulaChanged
    uid: 'excel!Excel.Worksheet#onFormulaChanged:member'
    package: excel!
    fullName: onFormulaChanged
    summary: >-
      Occurs when one or more formulas are changed in this worksheet. This event is for when the formula itself changes,
      not the data value resulting from the formula's calculation.
    remarks: >-
      \[ [API set: ExcelApi 1.13](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-formula-changed.yaml


      await Excel.run(async (context) => {
        // Retrieve the worksheet named "Sample".
        let sheet = context.workbook.worksheets.getItem("Sample");
        
        // Register the formula changed event handler for this worksheet.
        sheet.onFormulaChanged.add(formulaChangeHandler);
        await context.sync();
        
        console.log("Registered a formula changed event handler for this worksheet.");
      });


      ...


      async function formulaChangeHandler(event: Excel.WorksheetFormulaChangedEventArgs) {
        await Excel.run(async (context) => {
          // Retrieve details about the formula change event.
          const cellAddress = event.formulaDetails[0].cellAddress;
          const previousFormula = event.formulaDetails[0].previousFormula;
          const source = event.source;
          
          // Print out the change event details.
          console.log(
            `The formula in cell ${cellAddress} changed. 
            The previous formula was: ${previousFormula}. 
            The source of the change was: ${source}.`
          );
        });
      }

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onFormulaChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormulaChangedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.WorksheetFormulaChangedEventArgs:interface" />&gt;
  - name: onProtectionChanged
    uid: 'excel!Excel.Worksheet#onProtectionChanged:member'
    package: excel!
    fullName: onProtectionChanged
    summary: Occurs when the worksheet protection state is changed.
    remarks: >-
      \[ [API set: ExcelApi 1.14](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-worksheet-protection.yaml


      // This function registers an event handler for the onProtectionChanged event of a worksheet.

      await Excel.run(async (context) => {
          // Set "Sample" as the active worksheet.
          context.workbook.worksheets.getItemOrNullObject("Sample").delete();
          const sheet = context.workbook.worksheets.add("Sample");
          sheet.activate();

          // Register the onProtectionChanged event handler.
          sheet.onProtectionChanged.add(checkProtection);
          await context.sync();
          console.log("Added a worksheet protection change event handler.");
      });


      ...


      async function checkProtection(event: Excel.WorksheetProtectionChangedEventArgs) {
          // This function is an event handler that returns the protection status of a worksheet
          // and information about the changed worksheet.
          await Excel.run(async (context) => {
              const protectionStatus = event.isProtected;
              const worksheetId = event.worksheetId;
              const source = event.source;
              console.log("Protection status changed. Protection status is now: " + protectionStatus + ".");
              console.log("    ID of changed worksheet: " + worksheetId + ".");
              console.log("    Source of change event: " + source + ".");
          });
      }

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onProtectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetProtectionChangedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.WorksheetProtectionChangedEventArgs:interface" />&gt;
  - name: onRowHiddenChanged
    uid: 'excel!Excel.Worksheet#onRowHiddenChanged:member'
    package: excel!
    fullName: onRowHiddenChanged
    summary: Occurs when the hidden state of one or more rows has changed on a specific worksheet.
    remarks: |-
      \[ [API set: ExcelApi 1.11](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => {
          const sheet = context.workbook.worksheets.getActiveWorksheet();
          sheet.onRowHiddenChanged.add(function (event) {
              return Excel.run(async (context) => {
                  console.log(`Row ${event.address} is now ${event.changeType}`);
                  await context.sync();
              });
          });
          await context.sync();
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onRowHiddenChanged: OfficeExtension.EventHandlers<Excel.WorksheetRowHiddenChangedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.WorksheetRowHiddenChangedEventArgs:interface" />&gt;
  - name: onRowSorted
    uid: 'excel!Excel.Worksheet#onRowSorted:member'
    package: excel!
    fullName: onRowSorted
    summary: Occurs when one or more rows have been sorted. This happens as the result of a top-to-bottom sort operation.
    remarks: >-
      \[ [API set: ExcelApi 1.10](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-column-and-row-sort.yaml


      await Excel.run(async (context) => {
          console.log("Adding row handler");
          const sheet = context.workbook.worksheets.getActiveWorksheet();

          // This will fire whenever a row has been moved as the result of a sort action.
          sheet.onRowSorted.add((event) => {
              return Excel.run((context) => {
                  console.log("Row sorted: " + event.address);
                  const sheet = context.workbook.worksheets.getActiveWorksheet();

                  // Clear formatting for section, then highlight the sorted area.
                  sheet.getRange("A1:E5").format.fill.clear();
                  if (event.address !== "") {
                      sheet.getRanges(event.address).format.fill.color = "yellow";
                  }

                  return context.sync();
              });
          });
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onRowSorted: OfficeExtension.EventHandlers<Excel.WorksheetRowSortedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.WorksheetRowSortedEventArgs:interface" />&gt;
  - name: onSelectionChanged
    uid: 'excel!Excel.Worksheet#onSelectionChanged:member'
    package: excel!
    fullName: onSelectionChanged
    summary: Occurs when the selection changes on a specific worksheet.
    remarks: |-
      \[ [API set: ExcelApi 1.7](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => {
          const sheet = context.workbook.worksheets.getItem("Sample");
          sheet.onSelectionChanged.add(function (event) {
              return Excel.run(async (context) => {
                  console.log("The selected range has changed to: " + event.address);
                  await context.sync();
              });
          });
          await context.sync();
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onSelectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.WorksheetSelectionChangedEventArgs:interface" />&gt;
  - name: onSingleClicked
    uid: 'excel!Excel.Worksheet#onSingleClicked:member'
    package: excel!
    fullName: onSingleClicked
    summary: >-
      Occurs when a left-clicked/tapped action happens in the worksheet. This event will not be fired when clicking in
      the following cases:


      - The user drags the mouse for multi-selection.


      - The user selects a cell in the mode when cell arguments are selected for formula references.
    remarks: >-
      \[ [API set: ExcelApi 1.10](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]


      #### Examples


      ```TypeScript

      // Link to full sample:
      https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-worksheet-single-click.yaml


      await Excel.run(async (context) => {
          const sheet = context.workbook.worksheets.getActiveWorksheet();
          sheet.onSingleClicked.add((event) => {
              return Excel.run((context) => {
                  console.log(`Click detected at ${event.address} (pixel offset from upper-left cell corner: ${event.offsetX}, ${event.offsetY})`);
                  return context.sync();
              });
          });

          console.log("The worksheet click handler is registered.");

          await context.sync();
      });

      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly onSingleClicked: OfficeExtension.EventHandlers<Excel.WorksheetSingleClickedEventArgs>;'
      return:
        type: >-
          <xref uid="office!OfficeExtension.EventHandlers:class" />&lt;<xref
          uid="excel!Excel.WorksheetSingleClickedEventArgs:interface" />&gt;
extends: '<xref uid="office!OfficeExtension.ClientObject:class" />'