1/**
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 *
4 * This source code is licensed under the MIT license found in the
5 * LICENSE file in the root directory of this source tree.
6 *
7 * @format
8 */
9
10import * as React from 'react';
11import {Constructor} from '../../types/private/Utilities';
12import {AccessibilityProps} from '../Components/View/ViewAccessibility';
13import {Insets} from '../../types/public/Insets';
14import {NativeMethods} from '../../types/public/ReactNativeTypes';
15import {StyleProp} from '../StyleSheet/StyleSheet';
16import {ImageStyle, ViewStyle} from '../StyleSheet/StyleSheetTypes';
17import {LayoutChangeEvent, NativeSyntheticEvent} from '../Types/CoreEventTypes';
18import {ImageResizeMode} from './ImageResizeMode';
19import {ImageRequireSource, ImageURISource} from './ImageSource';
20
21/**
22 * @see ImagePropsIOS.onProgress
23 */
24export interface ImageProgressEventDataIOS {
25  loaded: number;
26  total: number;
27}
28
29export interface ImagePropsIOS {
30  /**
31   * blurRadius: the blur radius of the blur filter added to the image
32   * @platform ios
33   */
34  blurRadius?: number | undefined;
35
36  /**
37   * When the image is resized, the corners of the size specified by capInsets will stay a fixed size,
38   * but the center content and borders of the image will be stretched.
39   * This is useful for creating resizable rounded buttons, shadows, and other resizable assets.
40   * More info on Apple documentation
41   */
42  capInsets?: Insets | undefined;
43
44  /**
45   * Invoked on download progress with {nativeEvent: {loaded, total}}
46   */
47  onProgress?:
48    | ((event: NativeSyntheticEvent<ImageProgressEventDataIOS>) => void)
49    | undefined;
50
51  /**
52   * Invoked when a partial load of the image is complete. The definition of
53   * what constitutes a "partial load" is loader specific though this is meant
54   * for progressive JPEG loads.
55   * @platform ios
56   */
57  onPartialLoad?: (() => void) | undefined;
58}
59
60interface ImagePropsAndroid {
61  /**
62   * The mechanism that should be used to resize the image when the image's dimensions
63   * differ from the image view's dimensions. Defaults to auto.
64   *
65   * 'auto': Use heuristics to pick between resize and scale.
66   *
67   * 'resize': A software operation which changes the encoded image in memory before it gets decoded.
68   * This should be used instead of scale when the image is much larger than the view.
69   *
70   * 'scale': The image gets drawn downscaled or upscaled. Compared to resize, scale is faster (usually hardware accelerated)
71   * and produces higher quality images. This should be used if the image is smaller than the view.
72   * It should also be used if the image is slightly bigger than the view.
73   */
74  resizeMethod?: 'auto' | 'resize' | 'scale' | undefined;
75
76  /**
77   * Duration of fade in animation in ms. Defaults to 300
78   *
79   * @platform android
80   */
81  fadeDuration?: number | undefined;
82}
83
84/**
85 * @see https://reactnative.dev/docs/image#source
86 */
87export type ImageSourcePropType =
88  | ImageURISource
89  | ImageURISource[]
90  | ImageRequireSource;
91
92export interface ImageLoadEventData {
93  source: {
94    height: number;
95    width: number;
96    uri: string;
97  };
98}
99
100export interface ImageErrorEventData {
101  error: any;
102}
103
104/**
105 * @see https://reactnative.dev/docs/image#resolveassetsource
106 */
107export interface ImageResolvedAssetSource {
108  height: number;
109  width: number;
110  scale: number;
111  uri: string;
112}
113
114/**
115 * @see https://reactnative.dev/docs/image
116 */
117export interface ImagePropsBase
118  extends ImagePropsIOS,
119    ImagePropsAndroid,
120    AccessibilityProps {
121  /**
122   * Used to reference react managed images from native code.
123   */
124  id?: string | undefined;
125
126  /**
127   * onLayout function
128   *
129   * Invoked on mount and layout changes with
130   *
131   * {nativeEvent: { layout: {x, y, width, height} }}.
132   */
133  onLayout?: ((event: LayoutChangeEvent) => void) | undefined;
134
135  /**
136   * Invoked on load error with {nativeEvent: {error}}
137   */
138  onError?:
139    | ((error: NativeSyntheticEvent<ImageErrorEventData>) => void)
140    | undefined;
141
142  /**
143   * Invoked when load completes successfully
144   * { source: { uri, height, width } }.
145   */
146  onLoad?:
147    | ((event: NativeSyntheticEvent<ImageLoadEventData>) => void)
148    | undefined;
149
150  /**
151   * Invoked when load either succeeds or fails
152   */
153  onLoadEnd?: (() => void) | undefined;
154
155  /**
156   * Invoked on load start
157   */
158  onLoadStart?: (() => void) | undefined;
159
160  progressiveRenderingEnabled?: boolean | undefined;
161
162  borderRadius?: number | undefined;
163
164  borderTopLeftRadius?: number | undefined;
165
166  borderTopRightRadius?: number | undefined;
167
168  borderBottomLeftRadius?: number | undefined;
169
170  borderBottomRightRadius?: number | undefined;
171
172  /**
173   * Determines how to resize the image when the frame doesn't match the raw
174   * image dimensions.
175   *
176   * 'cover': Scale the image uniformly (maintain the image's aspect ratio)
177   * so that both dimensions (width and height) of the image will be equal
178   * to or larger than the corresponding dimension of the view (minus padding).
179   *
180   * 'contain': Scale the image uniformly (maintain the image's aspect ratio)
181   * so that both dimensions (width and height) of the image will be equal to
182   * or less than the corresponding dimension of the view (minus padding).
183   *
184   * 'stretch': Scale width and height independently, This may change the
185   * aspect ratio of the src.
186   *
187   * 'repeat': Repeat the image to cover the frame of the view.
188   * The image will keep it's size and aspect ratio. (iOS only)
189   *
190   * 'center': Scale the image down so that it is completely visible,
191   * if bigger than the area of the view.
192   * The image will not be scaled up.
193   */
194  resizeMode?: ImageResizeMode | undefined;
195
196  /**
197   * The mechanism that should be used to resize the image when the image's dimensions
198   * differ from the image view's dimensions. Defaults to `auto`.
199   *
200   * - `auto`: Use heuristics to pick between `resize` and `scale`.
201   *
202   * - `resize`: A software operation which changes the encoded image in memory before it
203   * gets decoded. This should be used instead of `scale` when the image is much larger
204   * than the view.
205   *
206   * - `scale`: The image gets drawn downscaled or upscaled. Compared to `resize`, `scale` is
207   * faster (usually hardware accelerated) and produces higher quality images. This
208   * should be used if the image is smaller than the view. It should also be used if the
209   * image is slightly bigger than the view.
210   *
211   * More details about `resize` and `scale` can be found at http://frescolib.org/docs/resizing-rotating.html.
212   *
213   * @platform android
214   */
215  resizeMethod?: 'auto' | 'resize' | 'scale' | undefined;
216
217  /**
218   * The image source (either a remote URL or a local file resource).
219   *
220   * This prop can also contain several remote URLs, specified together with their width and height and potentially with scale/other URI arguments.
221   * The native side will then choose the best uri to display based on the measured size of the image container.
222   * A cache property can be added to control how networked request interacts with the local cache.
223   *
224   * The currently supported formats are png, jpg, jpeg, bmp, gif, webp (Android only), psd (iOS only).
225   */
226  source: ImageSourcePropType;
227
228  /**
229   * similarly to `source`, this property represents the resource used to render
230   * the loading indicator for the image, displayed until image is ready to be
231   * displayed, typically after when it got downloaded from network.
232   */
233  loadingIndicatorSource?: ImageURISource | undefined;
234
235  /**
236   * A unique identifier for this element to be used in UI Automation testing scripts.
237   */
238  testID?: string | undefined;
239
240  /**
241   * Used to reference react managed images from native code.
242   */
243  nativeID?: string | undefined;
244
245  /**
246   * A static image to display while downloading the final image off the network.
247   */
248  defaultSource?: ImageURISource | number | undefined;
249
250  /**
251   * The text that's read by the screen reader when the user interacts with
252   * the image.
253   *
254   * See https://reactnative.dev/docs/image#alt
255   */
256  alt?: string | undefined;
257}
258
259export interface ImageProps extends ImagePropsBase {
260  /**
261   *
262   * Style
263   */
264  style?: StyleProp<ImageStyle> | undefined;
265}
266
267declare class ImageComponent extends React.Component<ImageProps> {}
268declare const ImageBase: Constructor<NativeMethods> & typeof ImageComponent;
269export class Image extends ImageBase {
270  static getSize(
271    uri: string,
272    success: (width: number, height: number) => void,
273    failure?: (error: any) => void,
274  ): any;
275  static getSizeWithHeaders(
276    uri: string,
277    headers: {[index: string]: string},
278    success: (width: number, height: number) => void,
279    failure?: (error: any) => void,
280  ): any;
281  static prefetch(url: string): Promise<boolean>;
282  static prefetchWithMetadata(
283    url: string,
284    queryRootName: string,
285    rootTag?: number,
286  ): Promise<boolean>;
287  static abortPrefetch?(requestId: number): void;
288  static queryCache?(
289    urls: string[],
290  ): Promise<{[url: string]: 'memory' | 'disk' | 'disk/memory'}>;
291
292  /**
293   * @see https://reactnative.dev/docs/image#resolveassetsource
294   */
295  static resolveAssetSource(
296    source: ImageSourcePropType,
297  ): ImageResolvedAssetSource;
298}
299
300export interface ImageBackgroundProps extends ImagePropsBase {
301  children?: React.ReactNode;
302  imageStyle?: StyleProp<ImageStyle> | undefined;
303  style?: StyleProp<ViewStyle> | undefined;
304  imageRef?(image: Image): void;
305}
306
307declare class ImageBackgroundComponent extends React.Component<ImageBackgroundProps> {}
308declare const ImageBackgroundBase: Constructor<NativeMethods> &
309  typeof ImageBackgroundComponent;
310export class ImageBackground extends ImageBackgroundBase {
311  resizeMode: ImageResizeMode;
312  getSize(
313    uri: string,
314    success: (width: number, height: number) => void,
315    failure: (error: any) => void,
316  ): any;
317  prefetch(url: string): any;
318  abortPrefetch?(requestId: number): void;
319  queryCache?(
320    urls: string[],
321  ): Promise<{[url: string]: 'memory' | 'disk' | 'disk/memory'}>;
322}
323