pages module

Package:

@microsoft/teams-js

Navigation-specific part of the SDK.

Interfaces

AppNavigationParameters	Type-safer version of parameters for the navigateToApp function
InstanceConfig	Defines the configuration of the current or desired instance
NavigateToAppParams

Type Aliases

backButtonHandlerFunctionType	Back button handler function
fullScreenChangeFunctionType	Full screen function
handlerFunctionType	Callback function
removeEventType	Remove event function
saveEventType	Save event function

Enums

ReturnFocusType

Return focus action items

Functions

getConfig()	Gets the config for the current instance.
initializeWithFrameContext(FrameInfo, handlerFunctionType, string[])	Initializes the library with context information for the frame
isSupported()	Checks if the pages capability is supported by the host
navigateCrossDomain(string)
navigateToApp(AppNavigationParameters | NavigateToAppParams)	Used to navigate to apps other than your own. If you are looking to navigate within your own app, use navigateToDefaultPage or navigateTo
registerFullScreenHandler(fullScreenChangeFunctionType)	Registers a handler for changes from or to full-screen view for a tab. Only one handler can be registered at a time. A subsequent registration replaces an existing registration. On hosts where there is no support for making an app full screen, the handler registered with this function will never be called.
returnFocus(boolean)
returnFocus(ReturnFocusType)	Return focus to the host. Will attempt to send focus to the appropriate part of the host (as specified by returnFocusType) based on where the application container falls in the F6/tab order in the host. On mobile hosts or hosts where there is no keyboard interaction or UI notion of "focus" this function has no effect and will be a no-op when called.
setCurrentFrame(FrameInfo)	Sets/Updates the current frame with new information
shareDeepLink(ShareDeepLinkParameters)	Shares a deep link that a user can use to navigate back to a specific state in this page. Please note that this method does not yet work on mobile hosts.

Function Details

getConfig()

Gets the config for the current instance.

function getConfig(): Promise<InstanceConfig>

Returns

Promise<InstanceConfig>

Promise that resolves with the InstanceConfig object.

initializeWithFrameContext(FrameInfo, handlerFunctionType, string[])

Initializes the library with context information for the frame

function initializeWithFrameContext(frameInfo: FrameInfo, callback?: handlerFunctionType, validMessageOrigins?: string[])

Parameters

frameInfo

FrameInfo

Frame information containing the URL used in the iframe on reload and the URL for when the user clicks 'Go To Website'

callback

handlerFunctionType

An optional callback that is executed once the application has finished initialization.

validMessageOrigins

string[]

An optional list of cross-frame message origins. They must have https: protocol otherwise they will be ignored. Example: https:www.example.com

isSupported()

Checks if the pages capability is supported by the host

function isSupported(): boolean

Returns

boolean

boolean to represent whether the appEntity capability is supported

navigateCrossDomain(string)

Warning

This API is now deprecated.

As of 2.0.0, this API is deprecated and can be replaced by the standard JavaScript API, window.location.href, when navigating the app to a new cross-domain URL. Any URL that is redirected to must be listed in the validDomains block of the manifest. Please remove any calls to this API.

function navigateCrossDomain(url: string): Promise<void>

Parameters

url

string

The URL to navigate the frame to.

Returns

Promise<void>

Promise that resolves when the navigation has completed.

navigateToApp(AppNavigationParameters | NavigateToAppParams)

Used to navigate to apps other than your own.

If you are looking to navigate within your own app, use navigateToDefaultPage or navigateTo

function navigateToApp(params: AppNavigationParameters | NavigateToAppParams): Promise<void>

Parameters

params

AppNavigationParameters | NavigateToAppParams

Parameters for the navigation

Returns

Promise<void>

a Promise that will resolve if the navigation was successful or reject if it was not

registerFullScreenHandler(fullScreenChangeFunctionType)

Registers a handler for changes from or to full-screen view for a tab. Only one handler can be registered at a time. A subsequent registration replaces an existing registration. On hosts where there is no support for making an app full screen, the handler registered with this function will never be called.

function registerFullScreenHandler(handler: fullScreenChangeFunctionType)

Parameters

handler

fullScreenChangeFunctionType

The handler to invoke when the user toggles full-screen view for a tab.

returnFocus(boolean)

Warning

This API is now deprecated.

Return focus to the host. Will move focus forward or backward based on where the application container falls in the F6/tab order in the host. On mobile hosts or hosts where there is no keyboard interaction or UI notion of "focus" this function has no effect and will be a no-op when called.

function returnFocus(navigateForward?: boolean)

Parameters

navigateForward

boolean

Determines the direction to focus in host.

returnFocus(ReturnFocusType)

Return focus to the host. Will attempt to send focus to the appropriate part of the host (as specified by returnFocusType) based on where the application container falls in the F6/tab order in the host. On mobile hosts or hosts where there is no keyboard interaction or UI notion of "focus" this function has no effect and will be a no-op when called.

function returnFocus(returnFocusType: ReturnFocusType)

Parameters

returnFocusType

ReturnFocusType

Determines the type of focus to return to in the host.

setCurrentFrame(FrameInfo)

Sets/Updates the current frame with new information

function setCurrentFrame(frameInfo: FrameInfo)

Parameters

frameInfo

FrameInfo

Frame information containing the URL used in the iframe on reload and the URL for when the user clicks 'Go To Website'

shareDeepLink(ShareDeepLinkParameters)

Shares a deep link that a user can use to navigate back to a specific state in this page. Please note that this method does not yet work on mobile hosts.

function shareDeepLink(deepLinkParameters: ShareDeepLinkParameters)

Parameters

deepLinkParameters

ShareDeepLinkParameters

ID and label for the link and fallback URL.