|
| 1 | +--- |
| 2 | +title: Adjust worksheet display settings |
| 3 | +description: How to adjust some worksheet display settings to make reports easier to read. |
| 4 | +ms.date: 04/03/2025 |
| 5 | +ms.localizationpriority: medium |
| 6 | +--- |
| 7 | + |
| 8 | +# Adjust worksheet display settings |
| 9 | + |
| 10 | +Excel is often used for reporting scenarios where you want to share worksheet data with others. Your Office Add-in can reduce visual clutter and help focus attention by controlling the appearance of the worksheet. The Office JavaScript API supports changing several visual aspects of the worksheet. |
| 11 | + |
| 12 | +## Turn data type icons on or off |
| 13 | + |
| 14 | +Data types can have an icon next to the value in the cell. When you have large tables with many data types, this can appear cluttered. |
| 15 | + |
| 16 | +:::image type="content" source="../images/data-types-icon-table.png" alt-text="An Excel table with three data types showing the same icon next to each data type."::: |
| 17 | + |
| 18 | +Use the [Worksheet.showDataTypeIcons](/javascript/api/excel/excel.worksheet#excel-excel-worksheet-showdatatypeicons-member) property to toggle data type icons on or off. For more information about data types, see [Overview of data types in Excel add-ins](excel-data-types-overview.md). The `showDataTypeIcons` property performs the same action as the user toggling data icons by using the **View** > **Data Type Icons** checkbox. The visibility settings for data type icons are saved with the worksheet and are also seen by anyone co-authoring at the time they are changed. |
| 19 | + |
| 20 | +The following code sample shows how to turn off data type icons on a worksheet. |
| 21 | + |
| 22 | +```js |
| 23 | +await Excel.run(async (context) => { |
| 24 | + const sheet = context.workbook.worksheets.getActiveWorksheet(); |
| 25 | + sheet.showDataTypeIcons = false; |
| 26 | + await context.sync(); |
| 27 | +}); |
| 28 | +``` |
| 29 | + |
| 30 | +> [!NOTE] |
| 31 | +> If a linked data type displays a **?** icon, this can’t be toggled on or off. Excel needs the user to disambiguate the cell value to find the correct data type. For more information, see [Excel data types: Stocks and geography](https://support.microsoft.com/office/61a33056-9935-484f-8ac8-f1a89e210877). |
| 32 | +
|
| 33 | +## Show or hide the worksheet gridlines |
| 34 | + |
| 35 | +Gridlines are the faint lines that appear between cells on a worksheet. These can be distracting if you use shapes, icons, or have specific line and border formats on data. |
| 36 | + |
| 37 | +:::image type="content" source="../images/excel-gridlines.png" alt-text="An infographic where the gridlines are distracting."::: |
| 38 | + |
| 39 | +Turn the gridlines on or off with the [Worksheet.showGridlines](/javascript/api/excel/excel.worksheet#excel-excel-worksheet-showgridlines-member) property. This is the same as using the **View** > **Gridlines** checkbox. The visibility settings for gridlines are saved with the worksheet and are also seen by anyone co-authoring at the time they are changed. |
| 40 | + |
| 41 | +The following example shows how to turn off gridlines on a worksheet. |
| 42 | + |
| 43 | +```js |
| 44 | +await Excel.run(async (context) => { |
| 45 | + const sheet = context.workbook.worksheets.getActiveWorksheet(); |
| 46 | + sheet.showGridlines = false; |
| 47 | + await context.sync(); |
| 48 | +}); |
| 49 | +``` |
| 50 | + |
| 51 | +## Toggle headings |
| 52 | + |
| 53 | +Headings are the Excel row numbers that appear on the left side of the worksheet (1, 2, 3) and the column letters that appear at the top of the worksheet (A, B, C). The user may not want these in their report. |
| 54 | + |
| 55 | +:::image type="content" source="../images/excel-heading-label.png" alt-text="A spreadsheet section highlighting the column heading A and the row heading 2."::: |
| 56 | + |
| 57 | +Turn the headings on or off with the [Worksheet.showHeadings](/javascript/api/excel/excel.worksheet#excel-excel-worksheet-showheadings-member) property. This is the same as using the **View** > **Headings** checkbox. The following example shows how to turn headings off on a worksheet. |
| 58 | + |
| 59 | +```js |
| 60 | +await Excel.run(async (context) => { |
| 61 | + const sheet = context.workbook.worksheets.getActiveWorksheet(); |
| 62 | + sheet.showHeadings = false; |
| 63 | + await context.sync(); |
| 64 | +}); |
| 65 | +``` |
| 66 | + |
| 67 | +## Page layout and print settings |
| 68 | + |
| 69 | +Add-ins have access to page layout settings at a worksheet level. These control how the sheet is printed. A `Worksheet` object has three layout-related properties: `horizontalPageBreaks`, `verticalPageBreaks`, `pageLayout`. |
| 70 | + |
| 71 | +`Worksheet.horizontalPageBreaks` and `Worksheet.verticalPageBreaks` are [PageBreakCollections](/javascript/api/excel/excel.pagebreakcollection). These are collections of [PageBreaks](/javascript/api/excel/excel.pagebreak), which specify ranges where manual page breaks are inserted. The following code sample adds a horizontal page break above row **21**. |
| 72 | + |
| 73 | +```js |
| 74 | +await Excel.run(async (context) => { |
| 75 | + let sheet = context.workbook.worksheets.getActiveWorksheet(); |
| 76 | + sheet.horizontalPageBreaks.add("A21:E21"); // The page break is added above this range. |
| 77 | + await context.sync(); |
| 78 | +}); |
| 79 | +``` |
| 80 | + |
| 81 | +`Worksheet.pageLayout` is a [PageLayout](/javascript/api/excel/excel.pagelayout) object. This object contains layout and print settings that are not dependent any printer-specific implementation. These settings include margins, orientation, page numbering, title rows, and print area. |
| 82 | + |
| 83 | +The following code sample centers the page (both vertically and horizontally), sets a title row that will be printed at the top of every page, and sets the printed area to a subsection of the worksheet. |
| 84 | + |
| 85 | +```js |
| 86 | +await Excel.run(async (context) => { |
| 87 | + let sheet = context.workbook.worksheets.getActiveWorksheet(); |
| 88 | + |
| 89 | + // Center the page in both directions. |
| 90 | + sheet.pageLayout.centerHorizontally = true; |
| 91 | + sheet.pageLayout.centerVertically = true; |
| 92 | + |
| 93 | + // Set the first row as the title row for every page. |
| 94 | + sheet.pageLayout.setPrintTitleRows("$1:$1"); |
| 95 | + |
| 96 | + // Limit the area to be printed to the range "A1:D100". |
| 97 | + sheet.pageLayout.setPrintArea("A1:D100"); |
| 98 | + |
| 99 | + await context.sync(); |
| 100 | +}); |
| 101 | +``` |
| 102 | + |
| 103 | +## See also |
| 104 | + |
| 105 | +- [Excel JavaScript object model in Office Add-ins](excel-add-ins-core-concepts.md) |
| 106 | +- [Work with worksheets using the Excel JavaScript API](excel-add-ins-worksheets.md) |
0 commit comments