Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 18 additions & 8 deletions Samples/office-keyboard-shortcuts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ page_type: sample
urlFragment: office-add-in-keyboard-shortcuts
products:
- office-excel
- office-powerpoint
- office-word
- office
- m365
Expand All @@ -22,11 +23,16 @@ description: "This sample shows how to add keyboard shortcuts to your Office Add

This sample shows how to create custom keyboard shortcuts for an Office Add-in. Keyboard shortcuts let power users quickly use your add-in's features and give accessibility options to avoid using a mouse. In this sample, the following shortcuts are configured.

- <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Up arrow key</kbd>: Opens the add-in's task pane.
- <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Down arrow key</kbd>: Hides the add-in's task pane.
- <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Q</kbd>: Performs an action that's specific to the current Office host.
- <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Up arrow key</kbd> (Windows) or <kbd>Command</kbd>+<kbd>Option</kbd>+<kbd>Up arrow key</kbd> (Mac): Opens the add-in's task pane.
- <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Down arrow key</kbd> (Windows) or <kbd>Command</kbd>+<kbd>Option</kbd>+<kbd>Down arrow key</kbd> (Mac): Hides the add-in's task pane.
- <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Q</kbd> (Windows) or <kbd>Command</kbd>+<kbd>Option</kbd>+<kbd>Q</kbd> (Mac): Performs an action that's specific to the current Office host.
- **Excel**: Cycles through colors in the currently selected cell.
- **Word**: Adds text to the document.
- **PowerPoint**: Adds a text box to the selected slide.
- <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>N</kbd> (Windows) or <kbd>Command</kbd>+<kbd>Option</kbd>+<kbd>Shift</kbd>+<kbd>N</kbd> (Mac): Adds a new item based on the current Office host.
- **Excel**: Adds a new worksheet.
- **Word**: Adds a page break.
- **PowerPoint**: Adds a new slide.

Keyboard shortcuts can be used to achieve any action within the add-in runtime.

Expand All @@ -41,15 +47,18 @@ Keyboard shortcuts can be used to achieve any action within the add-in runtime.

- Office on the web
- Excel
- PowerPoint
- Word

> **Note**: The keyboard shortcut feature is currently being rolled out to Word on the web. If you test the feature in Word on the web at this time, the shortcuts may not work if they're activated from within the add-in's task pane. We recommend to periodically check [Keyboard Shortcuts requirement sets](https://learn.microsoft.com/javascript/api/requirement-sets/common/keyboard-shortcuts-requirement-sets) to find out when the feature is fully supported.

- Office on Windows
- Excel: Version 2111 (Build 14701.10000)
- PowerPoint: Version 2601 (Build 19628.20150)
- Word: Version 2408 (Build 17928.20114)
- Office on Mac
- Excel: Version 16.55 (21111400)
- PowerPoint: Version 16.105 (26012530)
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be Version 16.105.2?

- Word: Version 16.88 (24081116)

## Prerequisites
Expand All @@ -70,6 +79,7 @@ Keyboard shortcuts can be used to achieve any action within the add-in runtime.
| 1.1 | May 11, 2021 | Removed yo office and modified to be GitHub hosted |
| 2.0 | September 27, 2024 | Added support for Word |
| 2.1 | December 5, 2024 | Updated keyboard shortcuts |
| 3.0 | February 5, 2026 | Added support for PowerPoint |

## Disclaimer

Expand All @@ -79,10 +89,10 @@ Keyboard shortcuts can be used to achieve any action within the add-in runtime.

### Run the sample from GitHub

Run this sample in Excel or Word. The add-in web files are served from this repository on GitHub.
Run this sample in Excel, PowerPoint, or Word. The add-in web files are served from this repository on GitHub.

1. Download the **manifest.xml** file from this sample to a folder on your computer.
1. Sideload the manifest file in Excel or Word. The sideloading process varies depending on your platform.
1. Sideload the manifest file in Excel, PowerPoint, or Word. The sideloading process varies depending on your platform.

- **Office on the web**: [Manually sideload an add-in to Office on the web](https://learn.microsoft.com/office/dev/add-ins/testing/sideload-office-add-ins-for-testing#manually-sideload-an-add-in-to-office-on-the-web)
- **Office on Windows**: [Sideload Office Add-ins for testing from a network share](https://learn.microsoft.com/office/dev/add-ins/testing/create-a-network-shared-folder-catalog-for-task-pane-and-content-add-ins)
Expand Down Expand Up @@ -125,7 +135,7 @@ If you prefer to host the web server for the sample on your computer, follow the

The http-server will run and host the current folder's files on localhost:3000.

1. Sideload the **manifest-localhost.xml** file in Excel or Word. The sideloading process varies depending on your platform.
1. Sideload the **manifest-localhost.xml** file in Excel, PowerPoint, or Word. The sideloading process varies depending on your platform.

- **Office on the web**: [Manually sideload an add-in to Office on the web](https://learn.microsoft.com/office/dev/add-ins/testing/sideload-office-add-ins-for-testing#manually-sideload-an-add-in-to-office-on-the-web)
- **Office on Windows**: [Sideload Office Add-ins for testing from a network share](https://learn.microsoft.com/office/dev/add-ins/testing/create-a-network-shared-folder-catalog-for-task-pane-and-content-add-ins)
Expand All @@ -137,10 +147,10 @@ If you prefer to host the web server for the sample on your computer, follow the

Once the add-in is loaded, try out its functionality.

1. Press <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Up arrow key</kbd> on your keyboard to open the add-in's task pane.
1. Press <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Up arrow key</kbd> (Windows) or <kbd>Command</kbd>+<kbd>Option</kbd>+<kbd>Up arrow key</kbd> (Mac) on your keyboard to open the add-in's task pane.

> [!NOTE]
> If the keyboard shortcut is already in use in Excel or Word, a dialog will be shown so that you can select which action you'd like to map to the shortcut. Once you select an action, you can change your preference by invoking the **Reset Office Add-in Shortcut Preferences** command from the search field.
> If the keyboard shortcut is already in use in Excel, PowerPoint, or Word, a dialog will be shown so that you can select which action you'd like to map to the shortcut. Once you select an action, you can change your preference by invoking the **Reset Office Add-in Shortcut Preferences** command from the search field.
>
> ![The Reset Office Add-in Shortcut Preferences option in Excel.](./assets/office-keyboard-shortcuts-reset.png)

Expand Down
2 changes: 1 addition & 1 deletion Samples/office-keyboard-shortcuts/assets/sample.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"url": "https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/office-keyboard-shortcuts",
"longDescription": "This sample shows how to create custom keyboard shortcuts for your add-in. Keyboard shortcuts can be used to achieve any action within the add-in runtime.",
"creationDateTime": "2020-11-05",
"updateDateTime": "2024-09-27",
"updateDateTime": "2026-02-05",
"products": [
"Office"
],
Expand Down
42 changes: 42 additions & 0 deletions Samples/office-keyboard-shortcuts/manifest-localhost.xml
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
</AppDomains>
<Hosts>
<Host Name="Document"/>
<Host Name="Presentation"/>
<Host Name="Workbook"/>
</Hosts>
<DefaultSettings>
Expand Down Expand Up @@ -66,6 +67,47 @@
</ExtensionPoint>
</DesktopFormFactor>
</Host>
<Host xsi:type="Presentation">
<Runtimes>
<Runtime resid="ContosoAddin.Url" lifetime="long" />
</Runtimes>
<DesktopFormFactor>
<GetStarted>
<Title resid="GetStarted.Title"/>
<Description resid="GetStarted.Description"/>
<LearnMoreUrl resid="GetStarted.LearnMoreUrl"/>
</GetStarted>
<FunctionFile resid="ContosoAddin.Url" />
<ExtensionPoint xsi:type="PrimaryCommandSurface">
<OfficeTab id="TabHome">
<Group id="CommandsGroup">
<Label resid="CommandsGroup.Label" />
<Icon>
<bt:Image size="16" resid="Icon.16x16" />
<bt:Image size="32" resid="Icon.32x32" />
<bt:Image size="80" resid="Icon.80x80" />
</Icon>
<Control xsi:type="Button" id="TaskpaneButton">
<Label resid="TaskpaneButton.Label" />
<Supertip>
<Title resid="TaskpaneButton.Label" />
<Description resid="TaskpaneButton.Tooltip" />
</Supertip>
<Icon>
<bt:Image size="16" resid="Icon.16x16" />
<bt:Image size="32" resid="Icon.32x32" />
<bt:Image size="80" resid="Icon.80x80" />
</Icon>
<Action xsi:type="ShowTaskpane">
<TaskpaneId>ShowTaskpaneButton</TaskpaneId>
<SourceLocation resid="ContosoAddin.Url" />
</Action>
</Control>
</Group>
</OfficeTab>
</ExtensionPoint>
</DesktopFormFactor>
</Host>
<Host xsi:type="Workbook">
<Runtimes>
<Runtime resid="ContosoAddin.Url" lifetime="long" />
Expand Down
42 changes: 42 additions & 0 deletions Samples/office-keyboard-shortcuts/manifest.xml
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
</AppDomains>
<Hosts>
<Host Name="Document"/>
<Host Name="Presentation"/>
<Host Name="Workbook"/>
</Hosts>
<DefaultSettings>
Expand Down Expand Up @@ -66,6 +67,47 @@
</ExtensionPoint>
</DesktopFormFactor>
</Host>
<Host xsi:type="Presentation">
<Runtimes>
<Runtime resid="ContosoAddin.Url" lifetime="long" />
</Runtimes>
<DesktopFormFactor>
<GetStarted>
<Title resid="GetStarted.Title"/>
<Description resid="GetStarted.Description"/>
<LearnMoreUrl resid="GetStarted.LearnMoreUrl"/>
</GetStarted>
<FunctionFile resid="ContosoAddin.Url" />
<ExtensionPoint xsi:type="PrimaryCommandSurface">
<OfficeTab id="TabHome">
<Group id="CommandsGroup">
<Label resid="CommandsGroup.Label" />
<Icon>
<bt:Image size="16" resid="Icon.16x16" />
<bt:Image size="32" resid="Icon.32x32" />
<bt:Image size="80" resid="Icon.80x80" />
</Icon>
<Control xsi:type="Button" id="TaskpaneButton">
<Label resid="TaskpaneButton.Label" />
<Supertip>
<Title resid="TaskpaneButton.Label" />
<Description resid="TaskpaneButton.Tooltip" />
</Supertip>
<Icon>
<bt:Image size="16" resid="Icon.16x16" />
<bt:Image size="32" resid="Icon.32x32" />
<bt:Image size="80" resid="Icon.80x80" />
</Icon>
<Action xsi:type="ShowTaskpane">
<TaskpaneId>ShowTaskpaneButton</TaskpaneId>
<SourceLocation resid="ContosoAddin.Url" />
</Action>
</Control>
</Group>
</OfficeTab>
</ExtensionPoint>
</DesktopFormFactor>
</Host>
<Host xsi:type="Workbook">
<Runtimes>
<Runtime resid="ContosoAddin.Url" lifetime="long" />
Expand Down
24 changes: 20 additions & 4 deletions Samples/office-keyboard-shortcuts/src/shortcuts.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,32 +19,48 @@
"id": "TestConflict",
"type": "ExecuteFunction",
"name": "Test the conflict dialog"
},
{
"id": "AddNew",
"type": "ExecuteFunction",
"name": "Add a new item based on the Office host"
}

],
"shortcuts": [
{
"action": "ShowTaskpane",
"key": {
"default": "Ctrl+Alt+Up"
"default": "Ctrl+Alt+Up",
"mac": "Command+Option+Up"
}
},
{
"action": "HideTaskpane",
"key": {
"default": "Ctrl+Alt+Down"
"default": "Ctrl+Alt+Down",
"mac": "Command+Option+Down"
}
},
{
"action": "RunAction",
"key": {
"default": "Ctrl+Alt+Q"
"default": "Ctrl+Alt+Q",
"mac": "Command+Option+Q"
}
},
{
"action": "TestConflict",
"key": {
"default": "Ctrl+R"
"default": "Ctrl+A",
"mac": "Command+A"
}
},
{
"action": "AddNew",
"key": {
"default": "Ctrl+Alt+Shift+N",
"mac": "Command+Option+Shift+N"
}
}
]
Expand Down
23 changes: 19 additions & 4 deletions Samples/office-keyboard-shortcuts/src/taskpane.html
Original file line number Diff line number Diff line change
Expand Up @@ -39,16 +39,31 @@ <h2 class="ms-font-xl">Please sideload your add-in to see app body.</h2>
<p class="ms-font-m"> Try the following keyboard shortcuts.</p>
<ul class="ms-List ms-welcome__features">
<li class="ms-ListItem">
<span class="ms-font-m"><kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Up arrow key</kbd>: Open the add-in's task pane.</span>
<span class="ms-font-m"><kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Up arrow key</kbd> (Windows) or <kbd>Command</kbd>+<kbd>Option</kbd>+<kbd>Up arrow key</kbd> (Mac):
<br><br>
Open the add-in's task pane.</span>
</li>
<li class="ms-ListItem">
<span class="ms-font-m"><kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Down arrow key</kbd>: Hide the add-in's task pane.</span>
<span class="ms-font-m"><kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Down arrow key</kbd> (Windows) or <kbd>Command</kbd>+<kbd>Option</kbd>+<kbd>Down arrow key</kbd> (Mac):
<br><br>
Hide the add-in's task pane.</span>
</li>
<li class="ms-ListItem">
<span class="ms-font-m">
<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Q</kbd>: Run an action that's specific to the current Office host.
<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Q</kbd> (Windows) or <kbd>Command</kbd>+<kbd>Option</kbd>+<kbd>Q</kbd> (Mac): Run an action that's specific to the current Office host.
<br><br>
In Excel, this shortcut cycles through colors in the currently selected cell.
In Word, this shortcut adds text to the document.
In PowerPoint, this shortcut adds a text box to the selected slide.
</span>
</li>
<li class="ms-ListItem">
<span class="ms-font-m">
<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>N</kbd> (Windows) or <kbd>Command</kbd>+<kbd>Option</kbd>+<kbd>Shift</kbd>+<kbd>N</kbd> (Mac): Add a new item based on the current Office host.
<br><br>
In Excel, this shortcut adds a new worksheet.
In Word, this shortcut adds a page break.
In PowerPoint, this shortcut adds a new slide.
</span>
</li>
</ul>
Expand All @@ -57,7 +72,7 @@ <h2 class="ms-font-xl">Please sideload your add-in to see app body.</h2>
If a custom shortcut conflicts with an existing shortcut that's defined in the host application or in another add-in, a dialog will be shown.
This dialog will ask you to confirm which action you want to be mapped to the keyboard shortcut.
</p>
<p class="ms-font-m">To test this now, press <kbd>Ctrl</kbd>+<kbd>R</kbd>.</p>
<p class="ms-font-m">To test this now, press <kbd>Ctrl</kbd>+<kbd>A</kbd> (Windows) or <kbd>Command</kbd>+<kbd>A</kbd> (Mac).</p>
<p class="ms-font-m">After you select an action, you can change your preference by invoking <b>Reset Office Add-in Shortcut Preferences</b> from the search field.</p>
</div>
</main>
Expand Down
43 changes: 42 additions & 1 deletion Samples/office-keyboard-shortcuts/src/taskpane.js
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
* See LICENSE in the project root for license information.
*/

/* global console, document, Excel, Office */
/* global console, document, Excel, Word, PowerPoint, Office */

// Initialize the Office JavaScript API library.
Office.onReady(() => {
Expand Down Expand Up @@ -75,10 +75,51 @@ if (host === Office.HostType.Excel) {
);
return context.sync();
});
} else if (host === Office.HostType.PowerPoint) {
// Insert a text box into the PowerPoint slide.
return PowerPoint.run(async (context) => {
const slide = context.presentation.getSelectedSlides().getItemAt(0);
const textBox = slide.shapes.addTextBox("Added using a custom keyboard shortcut.");
textBox.left = 100;
textBox.top = 100;
textBox.height = 50;
textBox.width = 300;
await context.sync();
});
}
});

// Display the shortcut conflict dialog for testing.
Office.actions.associate("TestConflict", () => {
console.log("Display the shortcut conflict dialog for testing.");
});

// Configure the keyboard shortcut to add a new item based on the Office host.
Office.actions.associate("AddNew", () => {
const host = Office.context.host;

// Add a new worksheet in Excel.
if (host === Office.HostType.Excel) {
const context = new Excel.RequestContext();
return context.sync().then(() => {
const sheets = context.workbook.worksheets;
const newSheet = sheets.add();
newSheet.activate();
return context.sync();
});
} else if (host === Office.HostType.Word) {
// Insert a page break in Word.
const context = new Word.RequestContext();
return context.sync().then(() => {
const range = context.document.getSelection();
range.insertBreak(Word.BreakType.page, Word.InsertLocation.after);
return context.sync();
});
} else if (host === Office.HostType.PowerPoint) {
// Add a new slide in PowerPoint.
return PowerPoint.run(async (context) => {
context.presentation.slides.add();
await context.sync();
});
}
});