{"id":6140,"date":"2021-03-26T10:14:33","date_gmt":"2021-03-26T18:14:33","guid":{"rendered":"https:\/\/officedevblogs.wpengine.com\/?p=6140"},"modified":"2021-03-26T10:14:33","modified_gmt":"2021-03-26T18:14:33","slug":"tips-for-using-the-shared-javascript-runtime-in-your-office-add-in%e2%80%af","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/tips-for-using-the-shared-javascript-runtime-in-your-office-add-in%e2%80%af\/","title":{"rendered":"Tips for using the shared JavaScript runtime in your Office Add-in\u202f\u00a0"},"content":{"rendered":"

This blog is the\u202fsecond\u202fof a series highlighting the shared runtime feature of the Office Add-ins platform.<\/span><\/i>\u202f<\/span>\u00a0<\/span><\/p>\n

The\u202fshared\u202fJavaScript runtime\u202fallows your Office Add-in JavaScript code to run in a single JavaScript runtime.<\/span>\u00a0<\/span>Using a shared JavaScript runtime can simplify your code<\/span>:<\/span>\u00a0D<\/span>ata and functionality\u00a0<\/span>i<\/span>s<\/span>\u00a0shared across all the code files in your project<\/span>.\u00a0<\/span>Your project can access the\u00a0<\/span>task pane\u2019s DOM from any code file<\/span>, including ribbon commands, and custom functions.<\/span>\u00a0<\/span>Y<\/span>ou<\/span>r<\/span>\u00a0<\/span>code\u202f<\/span>will continue\u00a0<\/span>running even if the task pane is closed. And\u202fthere are many newer\u00a0<\/span>UX<\/span>\u00a0features, such as keyboard shortcuts, that are enabled when you use the shared runtime.<\/span>\u00a0<\/span><\/p>\n

\"shared<\/p>\n

Configure your project\u00a0<\/span>to use<\/span>\u00a0the shared\u00a0<\/span>runtime<\/span>\u00a0<\/span><\/h3>\n

C<\/span>onvert any existing project to use the shared\u202fruntime\u202fby applying a few changes to the manifest.xml file.\u202fWe recommend following the\u202fsteps\u202fin\u202f<\/span>Configure your Office Add-in to use a shared JavaScript runtime.<\/a><\/span><\/p>\n

After you configure your project, b<\/span>e sure to specify the correct requirements for the shared\u00a0<\/span>runtime<\/span>. You want to specify the\u202f<\/span>SharedRuntime<\/span><\/b>\u202frequirement in your manifest as shown in the following XML.<\/span>\u202f<\/span><\/p>\n

<Requirements>\n\u202f\u202f<Sets\u202fDefaultMinVersion=\"1.1\">\n\u202f\u202f\u202f\u202f<Set Name=\"SharedRuntime\"\u202fMinVersion=\"1.1\"\/>\n\u202f\u202f<\/Sets>\n<\/Requirements><\/pre>\n
If your add-in also implements custom functions for Excel, you need to specify both\u202f<\/span>SharedRuntime<\/span><\/b>\u202fand\u202f<\/span>CustomFunctionsRuntime<\/span><\/b>\u202fas shown in the following XML.<\/span>\u202f<\/span>\u00a0<\/span><\/p>\n
<Requirements>\n\u202f\u202f<Sets\u202fDefaultMinVersion=\"1.1\">\n\u202f\u202f\u202f\u202f<Set Name=\"SharedRuntime\"\u202fMinVersion=\"1.1\"\/>\n\u202f\u202f\u202f\u202f<Set Name=\"CustomFunctionsRuntime\"\u202fMinVersion=\"1.1\"\/>\n\u202f\u202f<\/Sets>\n<\/Requirements><\/pre>\n
Share data and\u00a0<\/span>functionality<\/span>\u00a0in\u202fyour\u202f<\/span>code<\/span>\u202f<\/span>\u00a0<\/span><\/h3>\n
Once you<\/span>r\u00a0<\/span>Office Add-in project\u00a0<\/span>is set up to\u00a0<\/span>use the shared runtime,\u202f<\/span>all\u00a0<\/span>parts\u00a0<\/span>of<\/span>\u202fyour code\u202fwill run in the same JavaScript\u00a0<\/span>runtime<\/span>\u00a0and<\/span>\u00a0can share\u202fdata.<\/span>\u00a0JavaScript f<\/span>unctions\u202fin one file can call functions in another file<\/span>\u00a0\u2014<\/span>\u00a0<\/span>t<\/span>here\u202fare\u202fno boundaries\u202fbetween your code files.\u202fFor example, functions in commands.js can call functions\u00a0<\/span>in<\/span>\u00a0<\/span>taskpane<\/span>.js.<\/span>\u202f<\/span>\u00a0<\/span><\/p>\n
The following code sample shows how to set up and store a global variable\u202fwhen the user presses a\u00a0<\/span>Reset\u00a0<\/span><\/b>i<\/span><\/b>mage\u202f<\/span><\/b>l<\/span><\/b>ength<\/span><\/b>\u00a0button.<\/span>\u202f<\/span>\u00a0<\/span><\/p>\n
\/\/ commands.js file\u202f\u00a0\n\/\/ Import functions\u202ffrom taskpane.js.\u202f\nimport {taskPaneUpdateImageMetrics} from \"..\/taskpane\/taskpane.js\";\u202f \u202f\u00a0\n\n\/\/ Handle the button press event, set global variable, and call task\u00a0\u00a0\n\/\/ pane to update its UI.\u202f\u00a0\nfunction\u202fbtnResetImageLength(event)\n{\u202f\u00a0\n\u202f \/\/ getglobal() is a helper function\u202fyo\u202foffice builds into the project.\n  let g =\u202fgetGlobal();\n\u202f\u202f g.imageLength=100;\u202f\u00a0\n\u202f \u202ftaskPaneUpdateImageMetrics();\u202f\u00a0\n\u202f \u202fevent.completed();\u202f\u00a0\n}\u202f\u00a0\n...\u202f \n\n\/\/ taskpane.js file\u202f\u00a0\n\/\/ Import functions\u202ffrom commands.js.\u202f\nimport {getGlobal} from \"..\/commands\/commands.js\";\u202f\u00a0\n\n\/\/ Update element in the DOM by reading global variable value\u202f\u00a0\nexport function\u202ftaskPaneUpdateImageMetrics()\u00a0\u00a0\n{\u202f\u00a0\n  const g =\u202fgetGlobal();\n  document.getElementById(\"imageLength\").textContent=g.imageLength;\u202f\u00a0\n}<\/pre>\n
Run code even when\u00a0<\/span>the\u00a0<\/span>task pane\u00a0<\/span>is\u00a0<\/span>closed<\/span>\u00a0<\/span><\/h3>\n
The shared runtime continues\u00a0<\/span>to run\u00a0<\/span>even if the task pane is closed. This means you can create global variables and not lose state when the user\u00a0<\/span>close<\/span>s<\/span>\u00a0the task pane window.<\/span>\u202f<\/span>\u00a0<\/span><\/p>\n
\/\/ You can rely on this\u202fvariable to\u202fpersist\u202feven if\u202fthe\u202ftask pane is closed\u202f\u00a0\nvar\u202fuserName;\u202f\u00a0\nfunction\u202fsetUserName(name)\u00a0\u00a0\n{\u202f\u00a0\n  userName\u202f=\u202fname;\u202f\u00a0\n}<\/pre>\n
Also,<\/span>\u00a0t<\/span>he shared runtime sends events w<\/span>hen\u00a0<\/span>the task pane is opened or closed<\/span>.\u00a0<\/span>H<\/span>andle these events to\u00a0<\/span>take\u00a0<\/span>an action<\/span>\u00a0when the user opens or closes the task pane. For example, you may want to\u00a0<\/span>load or refresh data when the task pane is opened<\/span>.<\/span>\u00a0For more information,\u00a0<\/span>see<\/span>\u00a0<\/span>Show or hide the task pane of your Office Add-in<\/span>.<\/span>\u00a0<\/span><\/p>\n
Office.addin.onVisibilityModeChanged(function(args)\n{\u00a0\n    if\u00a0(args.visibilityMode\u00a0= \"Taskpane\");\n    {\u00a0\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/ Code that runs whenever the task pane is made visible.\u00a0\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/ For example, an\u00a0Excel.run() that loads the names of\u00a0\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/ all worksheets and\u00a0passes\u00a0them to the task pane UI.\u00a0\n\u00a0\u00a0\u00a0 }\u00a0\n}\n);<\/pre>\n
Access the task pa<\/span>ne DOM from\u202f<\/span>anywhere<\/span>\u202f<\/span>\u00a0<\/span><\/h3>\n
Using shared runtime all<\/span>ows you\u00a0<\/span>to<\/span>\u00a0access the DOM of your task pane from any code file.\u202fFor example,\u00a0<\/span>say\u00a0<\/span>your add-in\u00a0<\/span>has<\/span>\u00a0a button to set the\u00a0add-in to use metric units. The code needs to update the task pane UI to reflect the state change.\u202fThe following example shows how\u00a0<\/span>to<\/span>\u00a0handle a\u00a0<\/span>button<\/span>\u00a0press event\u202fin commands.js and update a checkbox on the task pane.\u202f<\/span>\u202f<\/span>\u00a0<\/span><\/p>\n
function\u202fbtnSetMetric(event)\u00a0\n{\u202f\u00a0\n\u202f\u202fdocument.getElementById('metric').checked=\"true\";\u202f\u00a0\n\u202f\u202fevent.completed();\u202f\u00a0\n}<\/pre>\n
Handle events\u00a0<\/span>anywhere<\/span>\u202f<\/span>\u00a0<\/span><\/h3>\n
Code\u202fto handle events\u202f<\/span>doesn\u2019t<\/span>\u202f<\/span>need<\/span>\u00a0<\/span>to be in a specific file.\u00a0<\/span>F<\/span>or example,\u00a0<\/span>you can\u00a0<\/span>handle\u00a0<\/span>command<\/span>\u00a0events from the ribbon in the\u00a0<\/span>taskpane<\/span>.<\/span>js<\/span>\u00a0file.\u202f<\/span>Or<\/span>\u00a0move custom functions from\u202ffunctions.<\/span>js<\/span>\u00a0to a different file.<\/span>\u00a0<\/span>N<\/span>ote that if you move custom functions<\/span>,<\/span>\u00a0you need to be sure the custom functions metadata generator points to the correct file location\u00a0<\/span>in<\/span>\u00a0webpack.config.js. For more information,\u00a0<\/span>see<\/span>\u202fthe README.md in\u00a0OfficeDev\/Office-Addin-Scripts (github.com)<\/a><\/span>.<\/span><\/p>\n
\u202f<\/span>Features\u00a0<\/span>enabled<\/span>\u00a0<\/span>in<\/span>\u00a0shared\u202f<\/span>runtime<\/span>\u202f<\/span>\u00a0<\/span><\/h3>\n
There are many features that are enabled when you use the shared\u202fruntime.\u202fSee the following documents for more information about any feature you are interested in, or\u00a0<\/span>require<\/span>d<\/span>\u00a0in your Office Add-in.<\/span>\u202f<\/span>\u00a0<\/span><\/p>\n