@nativescript/core/ui/transition/shared-transition.d.ts

A JavaScript library providing an easy to use api for interacting with iOS and Android platform APIs.

import type { Transition, TransitionNavigationType, SharedTransitionTagPropertiesToMatch } from '.';
import { Observable } from '../../data/observable';
import { ViewBase } from '../core/view-base';
import type { View } from '../core/view';
import type { PanGestureEventData } from '../gestures';
export declare enum SharedTransitionAnimationType {
    present = 0,
    dismiss = 1
}
type SharedTransitionEventAction = 'present' | 'dismiss' | 'interactiveStart' | 'interactiveFinish';
export type SharedTransitionEventDataPayload = {
    id: number;
    type: TransitionNavigationType;
    action?: SharedTransitionEventAction;
    percent?: number;
};
export type SharedTransitionEventData = {
    eventName: string;
    data: SharedTransitionEventDataPayload;
};
export type SharedRect = {
    x?: number;
    y?: number;
    width?: number;
    height?: number;
};
export type SharedProperties = SharedRect & {
    opacity?: number;
    scale?: {
        x?: number;
        y?: number;
    };
};
/**
 * Properties which can be set on individual Shared Elements
 */
export type SharedTransitionTagProperties = SharedProperties & {
    /**
     * The visual stacking order where 0 is at the bottom.
     * Shared elements are stacked one on top of the other during each transition.
     * By default they are not ordered in any particular fashion.
     */
    zIndex?: number;
    /**
     * Collection of properties to match and animate on each shared element.
     *
     * Defaults to: 'backgroundColor', 'cornerRadius', 'borderWidth', 'borderColor'
     *
     * Tip: Using an empty array, [], for view or layer will avoid copying any properties if desired.
     */
    propertiesToMatch?: SharedTransitionTagPropertiesToMatch;
    /**
     *
     */
    callback?: (view: View, action: SharedTransitionEventAction) => Promise<void>;
};
export type SharedSpringProperties = {
    tension?: number;
    friction?: number;
    mass?: number;
    delay?: number;
    velocity?: number;
    animateOptions?: any;
};
type SharedTransitionPageProperties = SharedProperties & {
    /**
     * (iOS Only) Allow "independent" elements found only on one of the screens to take part in the animation.
     * Note: This feature will be brought to Android in a future release.
     */
    sharedTransitionTags?: {
        [key: string]: SharedTransitionTagProperties;
    };
    /**
     * Spring animation settings.
     * Defaults to 140 tension with 10 friction.
     */
    spring?: SharedSpringProperties;
};
type SharedTransitionPageWithDurationProperties = SharedTransitionPageProperties & {
    /**
     * Linear duration in milliseconds
     * Note: When this is defined, it will override spring options and use only linear animation.
     */
    duration?: number | undefined | null;
};
export interface SharedTransitionInteractiveOptions {
    /**
     * When the pan exceeds this percentage and you let go, finish the transition.
     * Default 0.5
     */
    finishThreshold?: number;
    /**
     * You can create your own percent formula used for determing the interactive value.
     * By default, we handle this via a formula like this for an interactive page back transition:
     * - return eventData.deltaX / (eventData.ios.view.bounds.size.width / 2);
     * @param eventData PanGestureEventData
     * @returns The percentage value to be used as the finish/cancel threshold
     */
    percentFormula?: (eventData: PanGestureEventData) => number;
}
export interface SharedTransitionConfig {
    /**
     * Interactive transition settings. (iOS only at the moment)
     */
    interactive?: {
        /**
         * Whether you want to allow interactive dismissal.
         * Defaults to using 'pan' gesture for dismissal however you can customize your own.
         */
        dismiss?: SharedTransitionInteractiveOptions;
    };
    /**
     * View settings applied to the incoming page to start your transition with.
     */
    pageStart?: SharedTransitionPageProperties;
    /**
     * View settings applied to the incoming page to end your transition with.
     */
    pageEnd?: SharedTransitionPageWithDurationProperties;
    /**
     * View settings applied to the outgoing page in your transition.
     */
    pageOut?: SharedTransitionPageWithDurationProperties;
    /**
     * View settings to return to the original page with.
     */
    pageReturn?: SharedTransitionPageWithDurationProperties & {
        /**
         * In some cases you may want the returning animation to start with the original opacity,
         * instead of beginning where it ended up on pageEnd.
         * Note: you can try enabling this property in cases where your return animation doesn't appear correct.
         */
        useStartOpacity?: boolean;
    };
}
export interface SharedTransitionState extends SharedTransitionConfig {
    /**
     * (Internally used) Preconfigured transition or your own custom configured one.
     */
    instance?: Transition;
    /**
     * Page which will start the transition.
     */
    page?: ViewBase;
    activeType?: SharedTransitionAnimationType;
    toPage?: ViewBase;
    /**
     * Whether interactive transition has began.
     */
    interactiveBegan?: boolean;
    /**
     * Whether interactive transition was cancelled.
     */
    interactiveCancelled?: boolean;
}
declare class SharedTransitionObservable extends Observable {
    on(eventNames: string, callback: (data: SharedTransitionEventData) => void, thisArg?: any): void;
}
/**
 * Shared Element Transitions (preview)
 * Allows you to auto animate between shared elements on two different screesn to create smooth navigational experiences.
 * View components can define sharedTransitionTag="name" alone with a transition through this API.
 */
export declare class SharedTransition {
    /**
     * Configure a custom transition with presentation/dismissal options.
     * @param transition The custom Transition instance.
     * @param options
     * @returns a configured SharedTransition instance for use with navigational APIs.
     */
    static custom(transition: Transition, options?: SharedTransitionConfig): {
        instance: Transition;
    };
    /**
     * Whether a transition is in progress or not.
     * Note: used internally however exposed in case custom state ordering is needed.
     * Updated when transitions start/end/cancel.
     */
    static inProgress: boolean;
    /**
     * Listen to various shared element transition events.
     * @returns Observable
     */
    static events(): SharedTransitionObservable;
    /**
     * When the transition starts.
     */
    static startedEvent: string;
    /**
     * When the transition finishes.
     */
    static finishedEvent: string;
    /**
     * When the interactive transition cancels.
     */
    static interactiveCancelledEvent: string;
    /**
     * When the interactive transition updates with the percent value.
     */
    static interactiveUpdateEvent: string;
    /**
     * Notify a Shared Transition event.
     * @param id transition instance id
     * @param eventName Shared Transition event name
     * @param type TransitionNavigationType
     * @param action SharedTransitionEventAction
     */
    static notifyEvent(eventName: string, data: SharedTransitionEventDataPayload): void;
    /**
     * Enable to see various console logging output of Shared Element Transition behavior.
     */
    static DEBUG: boolean;
    /**
     * Update transition state.
     * @param id Transition instance id
     * @param state SharedTransitionState
     */
    static updateState(id: number, state: SharedTransitionState): void;
    /**
     * Get current state for any transition.
     * @param id Transition instance id
     */
    static getState(id: number): SharedTransitionState;
    /**
     * Finish transition state.
     * @param id Transition instance id
     */
    static finishState(id: number): void;
    /**
     * Gather view collections based on sharedTransitionTag details.
     * @param fromPage Page moving away from
     * @param toPage Page moving to
     * @returns Collections of views pertaining to shared elements or particular pages
     */
    static getSharedElements(fromPage: ViewBase, toPage: ViewBase): {
        sharedElements: Array<View>;
        presented: Array<View>;
        presenting: Array<View>;
    };
}
/**
 * Get dimensional rectangle (x,y,width,height) from properties with fallbacks for any undefined values.
 * @param props combination of properties conformed to SharedTransitionPageProperties
 * @param defaults fallback properties when props doesn't contain a value for it
 * @returns { x,y,width,height }
 */
export declare function getRectFromProps(props: SharedTransitionPageProperties, defaults?: SharedRect): SharedRect;
/**
 * Get spring properties with default fallbacks for any undefined values.
 * @param props various spring related properties conforming to SharedSpringProperties
 * @returns
 */
export declare function getSpringFromProps(props: SharedSpringProperties): {
    tension: number;
    friction: number;
    mass: number;
    velocity: number;
    delay: number;
};
/**
 * Page starting defaults for provided type.
 * @param type TransitionNavigationType
 * @returns { x,y,width,height }
 */
export declare function getPageStartDefaultsForType(type: TransitionNavigationType): {
    x: number;
    y: number;
    width: number;
    height: number;
};
export {};