• ReactXP چیست؟ (بخش سوم)

Reactxp-بخش چهارم

در مقاله های قبل راجع به اینکه Reactxp چیست توضیح دادیم و همچنین تمام کامپوننت های آن را نیز معرفی کردیم و یک فیلم آموزشی نیز در اختیار شما عزیزان قرار دادیم. در این مقاله می خواهیم به تمام API های مورد استفاده در Reactxp بپردازیم. بنابراین با ما همراه باشید.

• Accessibility

این رابط تمام متدها و حوادث را نشان می دهد. گاهی ممکن است تغییراتی پیش بیاید که این رابط آن را به اطلاع کاربر می رساند.

Events

newAnnouncementReadyEvent: SubscribableEvent<(announcement: string) => void>;

Methods

announceForAccessibility(announcement: string): void;

// Indicates whether a screen reader is currently enabled.
isScreenReaderEnabled(): boolean;

// Inidicates whether the OS-level "high-contrast" setting is enabled.
isHighContrastEnabled(): boolean;

• Alert

این رابط یک هشدار ویژه سیستم عامل را در بالای صفحه کنونی نشان می دهد. ظاهر هشدار توسط پلت فرم سیستم عامل اساسی است. بعضی از سیستم عامل ها هشدارها را نمایش می دهند حتی زمانی که برنامه در پیش زمینه نیست.

Types

		

  // Button text
    text?: string;

    // Invoked when button is pressed
    onPress?: () => void;

    // Alert style to use (supported on some platforms)
    style?: 'default' | 'cancel' | 'destructive';
}

interface AlertModalTheme {
    // Modal background style
    bodyStyle?: StyleRuleSet;
    
    // Style for title text
    titleTextStyle?: StyleRuleSet;
    
    // Style for message text
    messageTextStyle?: StyleRuleSet;
    
    // Style for button control
    buttonStyle?: StyleRuleSet;
    
    // Style applied when hovering over button
    buttonHoverStyle?: StyleRuleSet;

    // Style for button text
    buttonTextStyle?: StyleRuleSet;
    
    // Override style for cancel button
    cancelButtonStyle?: StyleRuleSet;
    
    // Override style for cancel button hover state
    cancelButtonHoverStyle?: StyleRuleSet;

    // Override style for cancel button
    cancelButtonTextStyle?: StyleRuleSet;;
}

interface AlertOptions {
    // Optional icon (web only)
    icon?: string;

    // Optional theme (web only)
    theme?: AlertModalTheme;
}

Methods

// provided for web only and is ignored on other platforms.
show(title: string, message?: string, buttons? AlertButtonSpec[], options?: AlertOptions): void;

• App

این رابط روش های اصلی در ارتباط با برنامه فراهم می کند. همچنین رویدادهایی را برای شرایط کم حافظه و تغییرات وضعیت فعالیت نشان می دهد.

Types

// Indicates whether the app is active or inactive
enum AppActivationState {
    // App is active and in foreground
    Active = 1,

    // App is active and in background
    Background = 2,

    // App is inactive (not actively running)
    Inactive = 3,

    // iOS specific activation state for extensions implemented 
    // with react-native
    Extension = 4
}

Methods

// Initializes the app. This should be one of the first calls made.
// Specifies whether app is running in "debug" mode, typically with 
// asserts and unminified code. Also specifies whether in "development"
// mode, which can indicate that additional logging or fewer security
// checks are appropriate.
initialize(debug: boolean, development: boolean): void;

// Indicates whether the app was initialized in debug and/or
// development mode
isDebugMode(): boolean;
isDevelopmentMode(): boolean;

// Returns the current activitation state for the app
getActivationState(): AppActivationState;

Events

	



// Triggered when the activation state changes
activationStateChangedEvent: SubscribableEvent<
    (state: AppActivationState) => void>;

// Triggered when a low-memory warning occurs
memoryWarningEvent: SubscribableEvent<() => void>;

• Clipboard

این رابط دسترسی به کلیپ بورد سیستم را فراهم می کند.

Methods

// Places the specified text on the clipboard
setText(text: string): void;

• Input

این رابط زمانی رخ می دهد که رویدادهای ورودی خاص کاربر رخ می دهد.

Events

// Triggered when the hardware back button is pressed (Android only).
// Events are triggered in the reverse order in which they were registered.
// Pass true to stop propagation.
backButtonEvent: SubscribableEvent<() => boolean>();

// Triggered when a hardware key up/down event occurs. Events are triggered 
// in the reverse order in which they were registered. Pass true to stop
// propagation.
keyDownEvent: SubscribableEvent<(e: Types.KeyboardEvent) => boolean>();
keyUpEvent: SubscribableEvent<(e: Types.KeyboardEvent) => boolean>();

• International

این رابط، رابط های مربوط به جهانی سازی (g11n) و بین المللی سازی (i18n) را فراهم می کند که اجازه میدهد برنامه ها بتوانند از جهت یابی (راست به چپ و یا چپ به راست) استفاده کنند.

Methods

// By default, right-to-left mirroring is enabled based on the
// OS or browser settings. This method allows the app to disable
// right-to-left mirroring.
allowRTL(allow: boolean): void;

// This method overrides the right-to-left setting of the system
// or browser, forcing right-to-left mirroring behavior if true.
forceRTL(force: boolean): void;

// Indicates whether the app is currently running in right-to-left mode.
isRTL(): boolean;

• Linking

این رابط، رابط عمیق در هر دو جهت ورودی و خروجی را مدیریت می کند. لینک های عمیق ورودی و خروجی برنامه را دستور می دهد تا اقداماتی را که توسط برنامه های دیگر درخواست شده باشد را انجام دهد.

Types

// Information used to invoke the default SMS app
interface SmsInfo {
    phoneNumber?: string;
    body?: string;
}

// Information used to invoke the default email app
interface EmailInfo {
    to?: string[];
    cc?: string[];
    bcc?: string[];
    subject?: string;
    body?: string;
}

// Error returned by promise if the request fails
interface LinkingErrorInfo {
    code: LinkingError;
    url: string;
    error?: string;
}

enum LinkingErrorCode {
    NoAppFound = 0,
    UnexpectedFailure = 1,
    Blocked = 2,
    InitialUrlNotFound = 3
}

Methods

getInitialUrl(): SyncTasks.Promise;

// Requests the URL to be opened by the default app for that protocol
// (e.g. http or https would typically open the system browser)
openUrl(url: string): SyncTasks.Promise;

// Requests the default SMS app to be invoked
launchSms(smsData: SmsInfo): SyncTasks.Promise;

// Requests the default mail app to be invoked
launchEmail(emailData: EmailInfo): SyncTasks.Promise;

Events

// Triggered when a new deep link request arrives
deepLinkRequestEvent: SubscribableEvent<(url: string) => void>;

• Location

این رابط دسترسی به اطلاعات موقعیت جغرافیایی را فراهم می کند.

Types

 // User has not granted the app access to location data
    PermissionDenied,
    
    // Geolocation information is not currently available
    PositionUnavailable,

    // Geolocation request has timed out
    Timeout
}

interface PositionOptions {
    // Enable high-accuracy mode; consumes more battery
    enableHighAccuracy?: boolean;

    // Number of milliseconds before timeout
    timeout?: number;

    // Max age (in milliseconds) before cached location is invalidated
    maximumAge?: number;
}

// ID for a pending "watch" request
type LocationWatchId = number;

// Delegates that are invoked when call succeeds or fails
type LocationSuccessCallback = (position: Position) => void;
type LocationFailureCallback = (error: LocationErrorType) => void;

Methods

// Indicates whether geolocation services are available on this platform
isAvailable(): boolean;

// Returns the current location
getCurrentPosition(options?: PositionOptions): SyncTasks.Promise;

// Requests a callback when the position changes; useful for geofencing
watchPosition(successCallback: LocationSuccessCallback, 
    errorCallback?: LocationFailureCallback,
    options?: PositionOptions): SyncTasks.Promise;

// Clears a location watch request
clearWatch(watchID: LocationWatchId): void;

• Modal

این رابط یک نمایه ای را نشان می دهد که تمام نظرات دیگر ارائه شده توسط برنامه را پوشش می دهد و مانع از هر گونه تعامل کاربر مستقیم با نمایش های پوشش می شود.

یک مودال توسط یک شناسه مودال ارائه شده توسط تماس گیرنده شناسایی شده است. این باید منحصر به فرد باشد.

فقط یک مودال می تواند در یک زمان نمایش داده شود. اگر یک مودال در حال حاضر نمایش داده شده است، یک مودال تازه نمایش داده شده به پشته مدال تحت فشار قرار داده است. هنگامی که یک مودال اخراج می شود، از پشته خارج می شود و حالت بعدی قابل مشاهده می شود.

یک Modal را می توان با استفاده از روش ها در فضای نام ReactXP.App نمایش داده و رد کرد.

مودال تمام صفحه را پوشش می دهد اما شفاف است. فرزندان آن محتوای قابل مشاهده و موقعیت خود را بر روی صفحه نمایش تعریف می کنند.

Types

// Android & iOS only.
    // The id of the root view this modal is associated with.
    // Defaults to the view set by UserInterface.setMainView();
    rootViewId?: string;
}

Methods

// on the top of the stack and showing the next modal in the stack.
dismiss(modalId: string);

// Removes all modals from the modal stack.
dismissAll();

// Indicates whether the specified modal is in the modal stack.
isDisplayed(modalId: string): boolean;

// Pushes the modal onto the modal stack.
show(modal: React.ReactElement, modalId: string, options?: ModalOptions);

مثال:

showDialog() {
    let dialog = (
        
            
                'An error occurred'
            
            
                
                    'OK'
                
            
        
    );

    RX.Modal.show(dialog, _modalId);
}

private _onOkButtonPress = (e: RX.Types.SyntheticEvent) => {
    RX.Modal.dismiss(_modalId);
};

• Network

این رابط اطلاعات مربوط به اتصال شبکه را فراهم می کند.

Types

  Unknown,
    None,
    Wifi,
    Mobile2G,
    Mobile3G,
    Mobile4G
}

Methods

// Returns a promise that specifies whether the device currently 
// has network connectivity
isConnected(): SyncTasks.Promise;

// Returns the type of network
getType(): SyncTasks.Promise;

Events

connectivityChangedEvent: SubscribableEvent<(isConnected: boolean) => void>;

• Platform

این رابط اطلاعاتی در مورد پلت فرم سیستم عامل یا زمان اجرا ارائه می دهد که برنامه در حال اجرا است.

Methods

getType(): Types.PlatformType;

• Popup

Popup از لحاظ فنی یک کامپوننت نیست. در عوض، این مجموعه ای از متد ها در فضای نام ReactXP.App است که به برنامه اجازه می دهد تا یک نمایه را که بخشی از صفحه را پوشش می دهد، نمایش دهد. پنجره ها می توانند به اجزای نصب شده " anchored" شوند و هنگام حرکت در اطراف صفحه (به عنوان مثال در واکنش به رویدادهای اسکرول) آنها را دنبال کنید.

هنگامی که یک پنجره نمایش داده می شود، تماس گیرنده یک ساختار PopupOptions را که شامل چندین فراخوانی، از جمله یک متد RenderPopup است، مشخص می کند.

به طور پیش فرض Popup ها مانند یک جابجایی عمل نمی کنند. وقتی Popup.show فراخوانی می شود، همیشه Popup را نشان می دهد. اگر Popup مورد نیاز است مانند یک جابجایی عمل کند، PopupOptions.dismissIfShown باید به درستی تنظیم شود. در این مورد، اگر Popup.show یکبار برای یک کتمپوننت نامیده شود، پنجره ظاهر می شود.

Popup ها توسط یک شناسه مشخص شده توسط تماس گیرنده مشخص می شود که باید منحصر به فرد باشد.

Types

type PopupPosition  = 'top' | 'right' | 'bottom' | 'left';

interface PopupOptions {
    // Returns a mounted component instance that serves as the
    // "anchor" for the popup. Often a button.
    getAnchor: () => React.Component;

    // Renders the contents of the popup.
    renderPopup: (anchorPosition: PopupPosition, anchorOffset: number,
        popupWidth: number, popupHeight: number) => ReactNode;

    // Returns a mounted component instance that controls the triggering
    // of the popup. In the majority of cases, "anchor" of popup has
    // handlers to control when the popup will be seen and this function
    // is not required. In a few cases, where anchor is not the same as
    // the whole component that triggers when the popup wil be seen,
    // this can be used. For instance, a button combined with a chevron
    // icon, which on click triggers a popup below the chevron icon. In
    // this example, getElementTriggeringPopup() can return the container
    // with button and chevron icon.
    getElementTriggeringPopup?: () => React.Component;

    // Called when the popup is dismissed.
    onDismiss?: () => void;

    // Prioritized order of positions. Popup is positioned
    // relative to the anchor such that it remains on screen.
    // Default is ['bottom', 'right', 'top', 'left'].
    positionPriorities?: string[];

    // Position the popup inside its anchor.
    // In this mode only the first position priority will be used.
    useInnerPositioning?: boolean;

    // On pressed handler to notify whoever wanted to create the popup
    // that its anchor has been pressed.
    // IMPORTANT NOTE: This handler may be called when the component is
    // already unmounted as it uses a time delay accommodate 
    // fade-out animations.
    onAnchorPressed?: (e: SyntheticEvent) => void;

    // Determines if the anchor invoking the popup should behave like a toggle. 
    // If true, calling Popup.show will show the popup. A subsequent call
    // will hide the popup. If false or undefined (default), calling Popup.show 
    // will always show the popup.
    dismissIfShown?: boolean;

    // By default, clicks or taps outside of a popup (unless they are on the
    // anchor) will not dismiss the active popup. If true, this overrides the
    // default behavior, in which case the popup must be dismissed explicitly.
    preventDismissOnPress?: boolean;

    // Android & iOS only.
    // The id of the root view this popup is associated with.
    // Defaults to the view set by UserInterface.setMainView();
    rootViewId?: string;
}

Methods

// Dismisses an already-displayed popup after a specified number
// of milliseconds
autoDismiss(popupId: string, dismissDelay: number = 0): void;

// Dismisses an already-displayed popup immediately
dismiss(popupId: string): void;

// Dismisses all popups immediately
dismissAll(): void;

// Displays a popup. Returns true if successful, false if the popup is
// already displayed
show(options: PopupOptions, popupId: string, showDelay: number = 0): boolean;

مثال:

const _popupId = 'myPopup';
let _popupDisplayed = false;

onHoverStart() {
    if (!this._popupDisplayed) {
        this.displayPopup();
    }
};

onHoverEnd() {
    RX.Popup.autoDismiss(_popupId, 2000);
};

displayPopup() {
    let popupOptions: RX.Types.PopupOptions = {
        getAnchor: () => {
            return this.refs['myButton'];
        },
        renderPopup: (anchorPosition: Types.PopupPosition, anchorOffset: number,
                popupWidth: number, popupHeight: number) => {
            return this._renderPopupView(anchorPosition,
                anchorOffset, popupWidth, popupHeight);
        },
        positionPriorities: ['right', 'left', 'bottom', 'top'],
        onDismiss: () => {
            this._popupDisplayed = false;
        }
    };

    RX.Popup.show(popupOptions, _popupId, 500);
    this._popupDisplayed = true;
}

• StatusBar

این رابط کنترل نوار وضعیت سیستم را در بالای صفحه در سیستم عامل های تلفن همراه کنترل می کند.

Methods

// Indicates whether the status bar overlays the app's main view (e.g. on iOS)
isOverlay(): boolean;

// Hides or shows the status bar with an optional animation
setHidden(hidden: boolean, showHideTransition: 'fade' | 'slide'): void;

// Specifies the status bar visual style
setBarStyle(style: 'default' | 'light-content' | 'dark-content',
    animated: boolean): void;

// Specifies whether the network activity indicator is visible.
setNetworkActivityIndicatorVisible(value: boolean): void;

// Specifies the background color of the status bar (applies on Android only)
setBackgroundColor(color: string, animated: boolean): void;

// Specifies whether the status bar is transluscent or transparent
setTranslucent(translucent: boolean): void;

• Storage

این رابط یک مکانیزم ذخیره سازی محلی مبتنی بر کلید را فراهم می کند.

Methods

clear(): SyncTasks.Promise;

// Returns an item by key
getItem(key: string): SyncTasks.Promise;

// Deletes an item by key
removeItem(key: string): SyncTasks.Promise;

// Sets or replaces the value of an item by key
setItem(key: string, value: string): SyncTasks.Promise;

• UserInterface

این رابط انواع روش های مرتبط با UI را فراهم می کند.

Types

	

x: number;
    y: number;
    width: number;
    height: number;
}

Methods

// screen beneath any open modals or popups
setMainView(element: React.ReactElement): void;

// Android & iOS only.
// Wrapper around RN.AppRegistry.registerComponent();
// IMPORTANT: Some APIs, e.g. Popup & Modal, require a string `reactxp_rootViewId`
// prop to be set on the component from the native-side.
registerRootView(viewKey: string, getComponentFunc: Function);

// Specifies whether custom scrollbars should be enabled (applies
// to web only)
useCustomScrollbars(enable: boolean): void;

// Indicates whether the screen is "high density" (e.g. retina displays)
isHighPixelDensityScreen(): boolean;

// Measure the location and dimensions of a mounted component relative
// to the window or one of its other containing views
measureLayoutRelativeToWindow(component: React.Component):
    SyncTasks.Promise;
measureLayoutRelativeToAncestor(component: React.Component,
    ancestor: React.Component): SyncTasks.Promise;

// Measures the dimension of the full window (or screen, in the case
// of mobile devices); the dimensions can also be obtained for any
// view (including your app's top-level view) using the onLayout
// callback
measureWindow(): Types.Dimensions;

// Indicates the "size multiplier" for text increase or decrease, which
// can be adjusted by users on some platforms; defaults to 1.0
getContentSizeMultiplier(): SyncTasks.Promise;

// Indicates the default maximum "size multiplier" for text increase.
// Defaults to 0 which indicates there is no max.
// Note: Older versions of React Native don’t support this interface.
getMaxContentSizeMultiplier(): SyncTasks.Promise;

// Sets the default maximum "size multiplier" for text increase.
// Values must be 0 or >=1. The default is 0 which indicates that
// there is no max.
// Note: Older versions of React Native don’t support this interface.
setMaxContentSizeMultiplier(maxContentSizeMultiplier: number): void;

// Dismisses the on-screen keyboard (applies to mobile only)
dismissKeyboard(): void;

// Enables native -> script touch event latency diagnostic events.
// When latency greater than latencyThresholdMs is observed, the
// touchLatencyEvent will fire. (applies to mobile only)
enableTouchLatencyEvents(latencyThresholdMs: number): void;

// Returns true if the application is in the keyboard navigation state,
// when the user is using Tab key to navigate through the focusable
// elements. (applies to web only)
isNavigatingWithKeyboard(): boolean;

Events

// Triggered when the content size multiplier changes while the
// app is running
contentSizeMultiplierChangedEvent: SubscribableEvent<
    (multiplier: number) => void>();

// Triggered when enableTouchLatencyEvents has been called and
// native -> script touch latency exceeding the threshold has
// been observed. (applies to mobile only)
touchLatencyEvent: SubscribableEvent<
    (observedLatencyMs: number) => void>();

// Triggered when the keyboard navigation state is changed.
// (applies to web only)
keyboardNavigationEvent: SubscribableEvent<
    (isNavigatingWithKeyboard: boolean) => void>();

• UserPresence

این رابط اطلاعاتی را در مورد اینکه آیا کاربر در حال حاضر حضور دارد فراهم می کند. تکنیک تشخیص حضور با پلت فرم متفاوت است. در سیستم عامل های تلفن همراه، کاربر فرض می شود تا زمانی که برنامه در پیش زمینه حضور داشته باشد. در سیستم عامل های وب، فرض می شود که کاربر در صورت وجود پنجره در پیش زمینه حضور داشته باشد و برخی فعالیت های ماوس یا صفحه کلید درون پنجره در دقیقه گذشته مشاهده شده است.

Methods

	

isUserPresent(): boolean;

Events

userPresenceChangedEvent: SubscribableEvent<
    (isPresent: boolean) => void>();