pages module

Package:

@microsoft/teams-js

Navigation-specific part of the SDK.

Interfaces

InstanceConfig	Defines the configuration of the current or desired instance
NavigateToAppParams	Parameters for the NavigateToApp API

Type Aliases

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

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)	Navigates the frame to a new cross-domain URL. The domain of this URL must match at least one of the valid domains specified in the validDomains block of the manifest; otherwise, an exception will be thrown. This function needs to be used only when navigating the frame to a URL in a different domain than the current one in a way that keeps the application informed of the change and allows the SDK to continue working.
navigateToApp(NavigateToAppParams)	Navigate to the given application ID and page ID, with optional parameters for a WebURL (if the application cannot be navigated to, such as if it is not installed), Channel ID (for applications installed as a channel tab), and sub-page ID (for navigating to specific content within the page). This is equivalent to navigating to a deep link with the above data, but does not require the application to build a URL or worry about different deep link formats for different hosts.
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)	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.
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)

Navigates the frame to a new cross-domain URL. The domain of this URL must match at least one of the valid domains specified in the validDomains block of the manifest; otherwise, an exception will be thrown. This function needs to be used only when navigating the frame to a URL in a different domain than the current one in a way that keeps the application informed of the change and allows the SDK to continue working.

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(NavigateToAppParams)

Navigate to the given application ID and page ID, with optional parameters for a WebURL (if the application cannot be navigated to, such as if it is not installed), Channel ID (for applications installed as a channel tab), and sub-page ID (for navigating to specific content within the page). This is equivalent to navigating to a deep link with the above data, but does not require the application to build a URL or worry about different deep link formats for different hosts.

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

Parameters

params

NavigateToAppParams

Parameters for the navigation

Returns

Promise<void>

a promise that will resolve if the navigation was successful

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)

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.

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.