@lynx-js/types 3.5.11 → 3.6.1-alpha.0

package/CHANGELOG.md

@@ -1,10 +1,25 @@
 # CHANGELOG
-## 3.5.11
-- Fix `AppearanceEvent` type being deprecated.
 
-## 3.5.10
+## 3.6.0
+
+### Minor Changes
+
+- Add new reporting fields for `ImageLoadEvent`
+
+- Add `lynx.stopExposure` and `lynx.resumeExposure` APIs.
+
 - Fix list-type to avoid incompatible type error.
 
+- Introduce `item-key` on `list.scrollToPosition`.
+
+- Introduce `enable-scroll-bar` property for `<textarea>` element.
+
+- Support `bindload` on `frame` element.
+
+- Introduce `<overlay>` element.
+
+- Introduce `global-props` property for `<frame>` element.
+
 ## 3.5.9
 - Update `list` and `list-item` typings.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynx-js/types",
-  "version": "3.5.11",
+  "version": "3.6.1-alpha.0",
   "description": "",
   "keywords": [
     "lynx",

package/types/background-thread/lynx-performance-entry.d.ts

@@ -88,6 +88,10 @@ export interface MetricFspEntry extends PerformanceEntry {
     fsp: PerformanceMetric;
     lynxFsp: PerformanceMetric;
     totalFsp: PerformanceMetric;
+    fspStatus: string;
+    contentFillRatioX: number;
+    contentFillRatioY: number;
+    contentFillRatioTotalArea: number;
 }
 
 export interface MetricActualFmpEntry extends PerformanceEntry {

package/types/common/element/element.d.ts

@@ -16,6 +16,7 @@ import { ViewProps } from './view';
 import { InputProps, InputUIMethods } from './input';
 import { TextAreaProps, TextAreaUIMethods } from './textarea';
 import { FrameProps } from './frame';
+import { OverlayProps} from './overlay';
 
 
 export interface UIMethods {
@@ -48,6 +49,7 @@ export interface IntrinsicElements {
   'input': InputProps;
   'textarea': TextAreaProps;
   'frame': FrameProps;
+  'overlay': OverlayProps;
 }
 
 declare module 'react' {
@@ -71,6 +73,7 @@ declare module 'react' {
       'input': InputProps;
       'textarea': TextAreaProps;
       'frame': FrameProps;
+      'overlay': OverlayProps;
     }
   }
 }

package/types/common/element/frame.d.ts

@@ -3,11 +3,11 @@
 // LICENSE file in the root directory of this source tree.
 
 import { StandardProps } from '../props';
+import { BaseEvent, BaseEventOrig, Target } from '../events';
 
 export interface FrameProps extends StandardProps {
   /**
    * Sets the loading path for the frame resource.
-   * @defaultValue undefined
    * @iOS
    * @Android
    * @since 3.4
@@ -16,10 +16,53 @@ export interface FrameProps extends StandardProps {
 
   /**
    * Passes data to the nested Lynx page within the frame.
-   * @defaultValue undefined
    * @iOS
    * @Android
    * @since 3.4
    */
   data?: Record<string, unknown> | undefined;
-}
+
+  /**
+   * Bind frame load event callback.
+   * @iOS
+   * @Android
+   * @since 3.6
+   */
+  bindload?: (e: FrameLoadEvent) => void;
+
+  /**
+   * Pass global props to the nested Lynx page within the frame.
+   * @iOS
+   * @Android
+   * @since 3.6
+   */
+  'global-props'?: Record<string, unknown>;
+}
+
+export interface BaseFrameLoadInfo {
+  /**
+   * The loaded url of the frame.
+   * @Android
+   * @iOS
+   * @since 3.6
+   */
+  url: string;
+
+  /**
+   * Frame loaded status code.
+   * @Android
+   * @iOS
+   * @since 3.6
+   */
+  statusCode: number;
+
+  /**
+   * Frame loaded status message.
+   * @Android
+   * @iOS
+   * @since 3.6
+   */
+  statusMessage: string;
+}
+
+export type FrameLoadEvent = BaseEvent<'bindload', BaseFrameLoadInfo>;

package/types/common/element/image.d.ts

@@ -119,8 +119,8 @@ export interface ImageProps extends StandardProps {
   'prefetch-height'?: string;
 
   /**
-   * When set to true and the <image> element has no width or height,
-   * the size of the <image> will be automatically adjusted
+   * When set to true and the `<image>` element has no width or height,
+   * the size of the `<image>` will be automatically adjusted
    * to match the image's original dimensions after the image is successfully loaded,
    * ensuring that the aspect ratio is maintained.
    * @defaultValue false
@@ -133,7 +133,7 @@ export interface ImageProps extends StandardProps {
   'auto-size'?: boolean;
 
   /**
-   * When set to true, the <image> will only clear the previously displayed image resource after a new image has successfully loaded.
+   * When set to true, the `<image>` will only clear the previously displayed image resource after a new image has successfully loaded.
    * The default behavior is to clear the image resource before starting a new load.
    * This can resolve flickering issues when the image src is switched and reloaded. It is not recommended to enable this in scenarios where there is node reuse in views like lists.
    * @defaultValue false
@@ -157,7 +157,7 @@ export interface ImageProps extends StandardProps {
   'autoplay'?: boolean;
 
   /**
-   * Changes the color of all non-transparent pixels to the tint-color specified. The value is a <color>.
+   * Changes the color of all non-transparent pixels to the tint-color specified. The value is a `<color>`.
    * @iOS
    * @Android
    * @Harmony

package/types/common/element/index.d.ts

@@ -18,3 +18,4 @@ export * from './methods';
 export * from './attributes';
 export * from './common';
 export * from './frame';
+export * from './overlay';

package/types/common/element/list.d.ts

@@ -661,6 +661,15 @@ export interface ScrollToPositionParams {
    */
   offset?: number;
 
+  /**
+   * Specify the unique identifier of the node to scroll to. If `item-key` is specified, `index` will be ignored.
+   * @Android
+   * @iOS
+   * @Harmony
+   * @since 3.6
+   */
+  itemKey?: string;
+
   /**
    * Enable scroll animation during scroll.
    * @defaultValue  false

package/types/common/element/overlay.d.ts

@@ -0,0 +1,131 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+import { StandardProps } from '../props';
+import { BaseEvent } from '../events';
+
+export enum OverlayTouchState {
+  OverlayTouchStateDown = 0,
+  OverlayTouchStateMove = 1,
+  OverlayTouchStateUp = 2,
+  OverlayTouchStateCancel = 3,
+}
+
+export interface OverlayError {
+  /**
+   * Error code: 0 - Display normally; non-0 - Unable to display, you can try to solve it by using the preloading scheme mentioned below for adapting containers.
+   * @Android
+   */
+  errorCode: string;
+  /**
+   * Error message
+   * @Android
+   */
+  errorMsg: string;
+}
+
+export interface OverlayTouch {
+  /**
+   * x position relative to the window, in px
+   * @Android
+   * @iOS
+   * @PC
+   */
+  x: number;
+  /**
+   * y position relative to the window, in px
+   * @Android
+   * @iOS
+   * @PC
+   */
+  y: number;
+  /**
+   * Touch state
+   * @Android
+   * @iOS
+   * @PC
+   */
+  state: OverlayTouchState;
+}
+
+export interface OverlayProps extends Omit<StandardProps, 'binderror'> {
+  
+  /**
+   * Control whether the overlay is displayed
+   * @Android
+   * @iOS
+   * @Harmony
+   * @PC
+   * @defaultValue false
+   */
+  visible?: boolean;
+
+  /**
+   * Introduces the concept of layers, which are divided into four levels. The larger the layer, the closer it is to the bottom. By default, it is the first level. The layers are arranged in order from 1 to 4. The displayed layer is specified and is not affected by the order of display. Within each layer, the arrangement is based on the 'last in, first out' logic. The layer cannot be dynamically adjusted when the overlay is displayed, and can only be adjusted when it is hidden.     * @Android
+   * @iOS
+   * @Android
+   * @Harmony
+   * @PC
+   * @defaultValue 1
+   */
+  level?: 1 | 2 | 3 | 4;
+
+  /**
+   * When overlay is displayed, 'true' allows swiping right to close the current page, 'false' does not allow it
+   * @iOS
+   * @defaultValue false
+   */
+  'ios-enable-swipe-back'?: boolean;
+
+  /**
+   * Specifies the level at which the overlay content resides on iOS. window: Mounted on the window, the top level of the app; top: Mounted on the topViewController; page: Mounted on UINavigationController; others: customize the name of class in the client.
+   * @iOS
+   * @defaultValue 'window'
+   */
+  mode?: 'window' | 'top' | 'page' | string;
+  
+  /**
+   * Callback when the overlay is displayed
+   * @Android
+   * @iOS
+   * @Harmony
+   * @PC
+   */
+  bindshowoverlay?: (e: BaseEvent) => void;
+
+  /**
+   * Callback when the overlay is hidden.
+   * @Android
+   * @iOS
+   * @Harmony
+   * @PC
+   */
+  binddismissoverlay?: (e: BaseEvent) => void;
+
+  /**
+   * Callback when the back button is clicked.
+   * @Android
+   * @Harmony
+   * @PC
+   */
+  bindrequestclose?: (e: BaseEvent) => void;
+
+  /**
+   * Callback when touch on the overlay
+   * @Android
+   * @iOS
+   * @PC
+   */
+  bindoverlaytouch?: (e: OverlayTouchEvent) => void;
+
+  /**
+   * Callback when touch on the overlay
+   * @Android
+   * @since 2.18
+   */
+  binderror?: (e: OverlayErrorEvent) => void;
+}
+
+export type OverlayTouchEvent = BaseEvent<'bindoverlaytouch', OverlayTouch>;
+export type OverlayErrorEvent = BaseEvent<'binderror', OverlayError>;

package/types/common/element/scroll-view.d.ts

@@ -2,7 +2,7 @@
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
 
-import { BaseEvent, BaseMethod, EventHandler } from '../events';
+import { BaseEvent, BaseMethod, EventHandler, Callback } from '../events';
 import { StandardProps } from '../props';
 import {
   ContentSizeChangedEvent,
@@ -232,4 +232,41 @@ export interface ScrollViewAutoScrollMethod extends BaseMethod {
   };
 }
 
-export type ScrollViewUIMethods = ScrollViewScrollToMethod | ScrollViewScrollByMethod | ScrollViewAutoScrollMethod;
+/**
+ * Get scroll info
+ * @Android
+ * @iOS
+ * @Harmony
+ * @PC
+ */
+export interface ScrollViewGetScrollInfoMethod extends BaseMethod {
+  method: 'getScrollInfo';
+  success?: Callback<{
+    /**
+     * Content offset on X-axis, in PX
+     * @Android
+     * @iOS
+     * @Harmony
+     * @PC
+     */
+    scrollX: number;
+    /**
+     * Content offset on Y-axis, in PX
+     * @Android
+     * @iOS
+     * @Harmony
+     * @PC
+     */
+    scrollY: number;
+    /**
+     * Total scrollable range along orientation, in PX
+     * @Android
+     * @iOS
+     * @Harmony
+     * @PC
+     */
+    scrollRange: number;
+  }>;
+}
+
+export type ScrollViewUIMethods = ScrollViewScrollToMethod | ScrollViewScrollByMethod | ScrollViewAutoScrollMethod | ScrollViewGetScrollInfoMethod;

package/types/common/element/textarea.d.ts

@@ -192,6 +192,15 @@ export interface TextAreaProps extends Omit<StandardProps, 'bindfocus' | 'bindbl
    */
   'input-filter'?: string;
 
+  /** 
+   * Whether to show scroll bar, on HarmonyOS, the scroll bar will always be shown
+   * @defaultValue false
+   * @Android
+   * @iOS
+   * @since 3.6
+   */
+  'enable-scroll-bar'?: boolean;
+
   /**
    * Input content type
    * @defaultValue "text"

package/types/common/events.d.ts

@@ -64,18 +64,6 @@ export interface ChangedTouch {
 export interface BaseCommonEvent<T> extends BaseEventOrig<any, T> {}
 export interface CommonEvent extends BaseCommonEvent<Target | MainThreadElement> {}
 
-/**
- * Node appearance event.
- * @deprecated Unexpectedly exported.
- */
-export interface AppearanceEvent {
-  type: 'nodeappear' | 'nodedisappear';
-  detail: {
-    position: number;
-    key: string;
-  };
-}
-
 export interface BaseTouchEvent<T> extends BaseEventOrig<any, T> {
   /** 
    * Collection of touch points currently on the touch plane.
@@ -128,8 +116,14 @@ export interface BaseMouseEvent<T> extends BaseEventOrig<{}, T> {
    * @PC
    */
   buttons: number;
-  /** 
-   * clientX 
+
+  /**
+   * Current scale factor. Greater than 1 means zoom in. Less than 1 means zoom out.
+   * @PC
+   */
+  scale: number;
+  /**
+   * clientX
    * @PC
    */
   x: number;
@@ -295,8 +289,69 @@ export interface BaseImageLoadEvent<T> extends BaseEventOrig<{}, T> {
 }
 
 export interface ImageLoadEvent extends BaseImageLoadEvent<Target> {
-    width: number;
-    height: number;
+  /**
+   * Image start loading timestamp, Unit (ms).
+   * @Android
+   * @iOS
+   * @since 3.6
+   */
+  load_start?: number;
+
+  /**
+   * Image loading completion timestamp, Unit (ms). It mainly includes image downloading and image decoding.
+   * @Android
+   * @iOS
+   * @since 3.6
+   */
+  load_finish?: number;
+
+  /**
+   * Image loading duration (load_finish - load_start), Unit (ms).
+   * @Android
+   * @iOS
+   * @since 3.6
+   */
+  cost?: number;
+
+  /**
+   * image URI.
+   * @Android
+   * @iOS
+   * @since 3.6
+   */
+  src?: string;
+
+  /**
+   * image view width. Unit: (px)
+   * @Android
+   * @iOS
+   * @since 3.6
+   */
+  view_width?: number,
+
+  /**
+   * image view height. Unit: (px)
+   * @Android
+   * @iOS
+   * @since 3.6
+   */
+  view_height?: number;
+
+  /**
+   * Image memory size, Unit: Byte (B).
+   * @Android
+   * @iOS
+   * @since 3.6
+   */
+  memory_cost?: number;
+
+  /**
+   * Source of image, network download, memory cache or disk cache.
+   * @Android
+   * @iOS
+   * @since 3.6
+   */
+  origin?: number;
 }
 
 
@@ -732,7 +787,13 @@ export interface LynxEvent<T> {
    */
   Wheel?: EventHandler<BaseWheelEvent<T>>;
 
-  /** 
+  /**
+   * Zoom gesture in the trackpaad
+   * @PC
+   */
+  Zoom?: EventHandler<BaseMouseEvent<T>>;
+
+  /**
    * Keyboard (or remote control) button pressed.
    * @PC
    */
@@ -847,6 +908,7 @@ interface MouseClickProps<T> { bindmouseclick?: LynxEvent<T>['MouseClick']; catc
 interface MouseDblClickProps<T> { bindmousedblclick?: LynxEvent<T>['MouseDblClick']; catchmousedblclick?: LynxEvent<T>['MouseDblClick']; 'capture-bindmousedblclick'?: LynxEvent<T>['MouseDblClick']; 'capture-catchmousedblclick'?: LynxEvent<T>['MouseDblClick']; 'global-bindmousedblclick'?: LynxEvent<T>['MouseDblClick']; }
 interface MouseLongPressProps<T> { bindmouselongpress?: LynxEvent<T>['MouseLongPress']; catchmouselongpress?: LynxEvent<T>['MouseLongPress']; 'capture-bindmouselongpress'?: LynxEvent<T>['MouseLongPress']; 'capture-catchmouselongpress'?: LynxEvent<T>['MouseLongPress']; 'global-bindmouselongpress'?: LynxEvent<T>['MouseLongPress']; }
 interface WheelProps<T> { bindwheel?: LynxEvent<T>['Wheel']; catchwheel?: LynxEvent<T>['Wheel']; 'capture-bindwheel'?: LynxEvent<T>['Wheel']; 'capture-catchwheel'?: LynxEvent<T>['Wheel']; 'global-bindwheel'?: LynxEvent<T>['Wheel']; }
+interface ZoomProps<T> { bindzoom?: LynxEvent<T>['Zoom']; catchzoom?: LynxEvent<T>['Zoom']; 'capture-bindzoom'?: LynxEvent<T>['Zoom']; 'capture-catchzoom'?: LynxEvent<T>['Zoom']; 'global-bindzoom'?: LynxEvent<T>['Zoom']; }
 interface KeyDownProps<T> { bindkeydown?: LynxEvent<T>['KeyDown']; catchkeydown?: LynxEvent<T>['KeyDown']; 'capture-bindkeydown'?: LynxEvent<T>['KeyDown']; 'capture-catchkeydown'?: LynxEvent<T>['KeyDown']; 'global-bindkeydown'?: LynxEvent<T>['KeyDown']; }
 interface KeyUpProps<T> { bindkeyup?: LynxEvent<T>['KeyUp']; catchkeyup?: LynxEvent<T>['KeyUp']; 'capture-bindkeyup'?: LynxEvent<T>['KeyUp']; 'capture-catchkeyup'?: LynxEvent<T>['KeyUp']; 'global-bindkeyup'?: LynxEvent<T>['KeyUp']; }
 interface FocusProps<T> { bindfocus?: LynxEvent<T>['Focus']; catchfocus?: LynxEvent<T>['Focus']; 'capture-bindfocus'?: LynxEvent<T>['Focus']; 'capture-catchfocus'?: LynxEvent<T>['Focus']; 'global-bindfocus'?: LynxEvent<T>['Focus']; }
@@ -883,6 +945,7 @@ export type LynxEventPropsBase<T> = BGLoadProps<T> &
   MouseDblClickProps<T> &
   MouseLongPressProps<T> &
   WheelProps<T> &
+  ZoomProps<T> &
   KeyDownProps<T> &
   KeyUpProps<T> &
   FocusProps<T> &

package/types/common/lynx.d.ts

@@ -92,4 +92,6 @@ export interface CommonLynx {
   getNative(): ContextProxy;
   getEngine(): ContextProxy;
   fetchBundle(url: string, options?: {}): ResponseHandler;
+  stopExposure(options?: { sendEvent: boolean }): void;
+  resumeExposure(): void;
 }