@microsoft/teams-js/dist/esm/packages/teams-js/dts/public/pages/pages.d.ts

Microsoft Client SDK for building app for Microsoft hosts

/**
 * Navigation-specific part of the SDK.
 * @module
 */
import { AppId } from '../appId';
import { FrameInfo, ShareDeepLinkParameters } from '../interfaces';
import * as appButton from './appButton';
import * as backStack from './backStack';
import * as config from './config';
import * as currentApp from './currentApp';
import * as fullTrust from './fullTrust';
import * as tabs from './tabs';
/** Callback function */
export type handlerFunctionType = () => void;
/** Full screen function */
export type fullScreenChangeFunctionType = (isFullScreen: boolean) => void;
/** Back button handler function */
export type backButtonHandlerFunctionType = () => boolean;
/** Save event function */
export type saveEventType = (evt: config.SaveEvent) => void;
/** Remove event function */
export type removeEventType = (evt: config.RemoveEvent) => void;
/**
 * @hidden
 * List of enter focus action items
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare enum EnterFocusType {
    /**
     * Determines the previous direction to focus in app when hot keys entered.
     */
    PreviousLandmark = 0,
    /**
     * Determines the next direction to focus in app when hot keys entered.
     */
    NextLandmark = 1,
    /**
     * Determines if the focus should go to the particular content of the app.
     * Read - Focus should go to the content of the app.
     */
    Read = 2,
    /**
     * Determines if the focus should go to the particular content of the app.
     * Compose - Focus should go to the compose area (such as textbox) of the app.
     */
    Compose = 3
}
/**
 * Return focus action items
 */
export declare enum ReturnFocusType {
    /**
     * Determines the direction to focus in host for previous landmark.
     */
    PreviousLandmark = 0,
    /**
     * Determines the direction to focus in host for next landmark.
     */
    NextLandmark = 1,
    /**
     * Determines if the focus should go to the host's activity feed
     */
    GoToActivityFeed = 2
}
/**
 * @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.
 * @param navigateForward - Determines the direction to focus in host.
 */
export declare function returnFocus(navigateForward?: boolean): void;
/**
 * 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.
 * @param returnFocusType - Determines the type of focus to return to in the host.
 */
export declare function returnFocus(returnFocusType: ReturnFocusType): void;
/**
 * @hidden
 *
 * Registers a handler for specifying focus when it passes from the host to the application.
 * On mobile hosts or hosts where there is no UI notion of "focus" the handler registered with
 * this function will never be called.
 *
 * @param handler - The handler for placing focus within the application.
 *
 * @internal
 * Limited to Microsoft-internal use
 */
export declare function registerFocusEnterHandler(handler: (navigateForward: boolean, enterFocusType?: EnterFocusType) => void): void;
/**
 * Sets/Updates the current frame with new information
 *
 * @param frameInfo - Frame information containing the URL used in the iframe on reload and the URL for when the
 * user clicks 'Go To Website'
 */
export declare function setCurrentFrame(frameInfo: FrameInfo): void;
/**
 * Initializes the library with context information for the frame
 *
 * @param frameInfo - Frame information containing the URL used in the iframe on reload and the URL for when the
 *  user clicks 'Go To Website'
 * @param callback - An optional callback that is executed once the application has finished initialization.
 * @param validMessageOrigins - An optional list of cross-frame message origins. They must have
 * https: protocol otherwise they will be ignored. Example: https:www.example.com
 */
export declare function initializeWithFrameContext(frameInfo: FrameInfo, callback?: handlerFunctionType, validMessageOrigins?: string[]): void;
/**
 * Defines the configuration of the current or desired instance
 */
export interface InstanceConfig {
    /**
     * A suggested display name for the new content.
     * In the settings for an existing instance being updated, this call has no effect.
     */
    suggestedDisplayName?: string;
    /**
     * Sets the URL to use for the content of this instance.
     */
    contentUrl: string;
    /**
     * Sets the URL for the removal configuration experience.
     */
    removeUrl?: string;
    /**
     * Sets the URL to use for the external link to view the underlying resource in a browser.
     */
    websiteUrl?: string;
    /**
     * The developer-defined unique ID for the entity to which this content points.
     */
    entityId?: string;
}
/**
 * Gets the config for the current instance.
 * @returns Promise that resolves with the {@link InstanceConfig} object.
 */
export declare function getConfig(): Promise<InstanceConfig>;
/**
 * @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.
 * @param url - The URL to navigate the frame to.
 * @returns Promise that resolves when the navigation has completed.
 */
export declare function navigateCrossDomain(url: string): Promise<void>;
/**
 * Used to navigate to apps other than your own.
 *
 * If you are looking to navigate within your own app, use {@link pages.currentApp.navigateToDefaultPage} or {@link pages.currentApp.navigateTo}
 *
 * @param params Parameters for the navigation
 * @returns a `Promise` that will resolve if the navigation was successful or reject if it was not
 * @throws `Error` if the app ID is not valid or `params.webUrl` is defined but not a valid URL
 */
export declare function navigateToApp(params: AppNavigationParameters | NavigateToAppParams): Promise<void>;
/**
 * 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.
 *
 * @param deepLinkParameters - ID and label for the link and fallback URL.
 */
export declare function shareDeepLink(deepLinkParameters: ShareDeepLinkParameters): void;
/**
 * 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.
 * @param handler - The handler to invoke when the user toggles full-screen view for a tab.
 */
export declare function registerFullScreenHandler(handler: fullScreenChangeFunctionType): void;
/**
 * Checks if the pages capability is supported by the host
 * @returns boolean to represent whether the appEntity capability is supported
 *
 * @throws Error if {@linkcode app.initialize} has not successfully completed
 */
export declare function isSupported(): boolean;
/**
 * @deprecated
 * This interface has been deprecated in favor of a more type-safe interface using {@link AppNavigationParameters}
 *
 * Parameters for the {@link navigateToApp} function
 */
export interface NavigateToAppParams {
    /**
     * ID of the app to navigate to
     */
    appId: string;
    /**
     * Developer-defined ID of the page to navigate to within the app (formerly called `entityId`)
     */
    pageId: string;
    /**
     * Fallback URL to open if the navigation cannot be completed within the host (e.g. if the target app is not installed)
     */
    webUrl?: string;
    /**
     * Developer-defined ID describing the content to navigate to within the page. This ID is passed to the application
     * via the {@link app.PageInfo.subPageId} property on the {@link app.Context} object (retrieved by calling {@link app.getContext})
     */
    subPageId?: string;
    /**
     * For apps installed as a channel tab, this ID can be supplied to indicate in which Teams channel the app should be opened
     */
    channelId?: string;
    /**
     * Optional ID of the chat or meeting where the app should be opened
  
     */
    chatId?: string;
}
/**
 * Type-safer version of parameters for the {@link navigateToApp} function
 */
export interface AppNavigationParameters {
    /**
     * ID of the app to navigate to
     */
    appId: AppId;
    /**
     * Developer-defined ID of the page to navigate to within the app (formerly called `entityId`)
     */
    pageId: string;
    /**
     * Fallback URL to open if the navigation cannot be completed within the host (e.g., if the target app is not installed)
     */
    webUrl?: URL;
    /**
     * Developer-defined ID describing the content to navigate to within the page. This ID is passed to the application
     * via the {@link app.PageInfo.subPageId} property on the {@link app.Context} object (retrieved by calling {@link app.getContext})
     */
    subPageId?: string;
    /**
     * For apps installed as a channel tab, this ID can be supplied to indicate in which Teams channel the app should be opened
     * This property has no effect in hosts where apps cannot be opened in channels
     */
    channelId?: string;
    /**
     * Optional ID of the chat or meeting where the app should be opened
     * This property has no effect in hosts where apps cannot be opened in chats or meetings
     */
    chatId?: string;
}
export { appButton, backStack, config, currentApp, fullTrust, tabs };