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 {ColorValue, 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   * A string representing the resource identifier for the image. Similar to
230   * src from HTML.
231   *
232   * See https://reactnative.dev/docs/image#src
233   */
234  src?: string | undefined;
235
236  /**
237   * Similar to srcset from HTML.
238   *
239   * See https://reactnative.dev/docs/image#srcset
240   */
241  srcSet?: string | undefined;
242
243  /**
244   * similarly to `source`, this property represents the resource used to render
245   * the loading indicator for the image, displayed until image is ready to be
246   * displayed, typically after when it got downloaded from network.
247   */
248  loadingIndicatorSource?: ImageURISource | undefined;
249
250  /**
251   * A unique identifier for this element to be used in UI Automation testing scripts.
252   */
253  testID?: string | undefined;
254
255  /**
256   * Used to reference react managed images from native code.
257   */
258  nativeID?: string | undefined;
259
260  /**
261   * A static image to display while downloading the final image off the network.
262   */
263  defaultSource?: ImageURISource | number | undefined;
264
265  /**
266   * The text that's read by the screen reader when the user interacts with
267   * the image.
268   *
269   * See https://reactnative.dev/docs/image#alt
270   */
271  alt?: string | undefined;
272
273  /**
274   * Height of the image component.
275   *
276   * See https://reactnative.dev/docs/image#height
277   */
278  height?: number | undefined;
279
280  /**
281   * Width of the image component.
282   *
283   * See https://reactnative.dev/docs/image#width
284   */
285  width?: number | undefined;
286
287  /**
288   * Adds the CORS related header to the request.
289   * Similar to crossorigin from HTML.
290   *
291   * See https://reactnative.dev/docs/image#crossorigin
292   */
293  crossOrigin?: 'anonymous' | 'use-credentials' | undefined;
294
295  /**
296   * Changes the color of all the non-transparent pixels to the tintColor.
297   *
298   * See https://reactnative.dev/docs/image#tintcolor
299   */
300  tintColor?: ColorValue | undefined;
301
302  /**
303   * A string indicating which referrer to use when fetching the resource.
304   * Similar to referrerpolicy from HTML.
305   *
306   * See https://reactnative.dev/docs/image#referrerpolicy
307   */
308  referrerPolicy?:
309    | 'no-referrer'
310    | 'no-referrer-when-downgrade'
311    | 'origin'
312    | 'origin-when-cross-origin'
313    | 'same-origin'
314    | 'strict-origin'
315    | 'strict-origin-when-cross-origin'
316    | 'unsafe-url'
317    | undefined;
318}
319
320export interface ImageProps extends ImagePropsBase {
321  /**
322   *
323   * Style
324   */
325  style?: StyleProp<ImageStyle> | undefined;
326}
327
328declare class ImageComponent extends React.Component<ImageProps> {}
329declare const ImageBase: Constructor<NativeMethods> & typeof ImageComponent;
330export class Image extends ImageBase {
331  static getSize(
332    uri: string,
333    success: (width: number, height: number) => void,
334    failure?: (error: any) => void,
335  ): any;
336  static getSizeWithHeaders(
337    uri: string,
338    headers: {[index: string]: string},
339    success: (width: number, height: number) => void,
340    failure?: (error: any) => void,
341  ): any;
342  static prefetch(url: string): Promise<boolean>;
343  static prefetchWithMetadata(
344    url: string,
345    queryRootName: string,
346    rootTag?: number,
347  ): Promise<boolean>;
348  static abortPrefetch?(requestId: number): void;
349  static queryCache?(
350    urls: string[],
351  ): Promise<{[url: string]: 'memory' | 'disk' | 'disk/memory'}>;
352
353  /**
354   * @see https://reactnative.dev/docs/image#resolveassetsource
355   */
356  static resolveAssetSource(
357    source: ImageSourcePropType,
358  ): ImageResolvedAssetSource;
359}
360
361export interface ImageBackgroundProps extends ImagePropsBase {
362  children?: React.ReactNode | undefined;
363  imageStyle?: StyleProp<ImageStyle> | undefined;
364  style?: StyleProp<ViewStyle> | undefined;
365  imageRef?(image: Image): void;
366}
367
368declare class ImageBackgroundComponent extends React.Component<ImageBackgroundProps> {}
369declare const ImageBackgroundBase: Constructor<NativeMethods> &
370  typeof ImageBackgroundComponent;
371export class ImageBackground extends ImageBackgroundBase {
372  resizeMode: ImageResizeMode;
373  getSize(
374    uri: string,
375    success: (width: number, height: number) => void,
376    failure: (error: any) => void,
377  ): any;
378  prefetch(url: string): any;
379  abortPrefetch?(requestId: number): void;
380  queryCache?(
381    urls: string[],
382  ): Promise<{[url: string]: 'memory' | 'disk' | 'disk/memory'}>;
383}
384