Wersja: 0.77

Obraz

Nieoficjalne Tłumaczenie Beta

Ta strona została przetłumaczona przez PageTurner AI (beta). Nie jest oficjalnie zatwierdzona przez projekt. Znalazłeś błąd? Zgłoś problem →

Komponent React do wyświetlania różnych typów obrazów, w tym zdjęć z sieci, zasobów statycznych, tymczasowych obrazów lokalnych oraz obrazów z dysku lokalnego, takich jak galeria aparatu.

Ten przykład pokazuje pobieranie i wyświetlanie obrazu z lokalnej pamięci, z sieci oraz nawet z danych dostarczonych w schemacie URI 'data:'.

Uwaga: W przypadku obrazów sieciowych i danych należy ręcznie określić wymiary obrazu!

Przykłady

Możesz również dodać style do obrazu:

Obsługa GIF i WebP na Androidzie

Podczas budowania własnego kodu natywnego, GIF i WebP nie są domyślnie obsługiwane na Androidzie.

Będziesz musiał dodać opcjonalne moduły w android/app/build.gradle, w zależności od potrzeb twojej aplikacji.

groovy
dependencies {
  // If your app supports Android versions before Ice Cream Sandwich (API level 14)
  implementation 'com.facebook.fresco:animated-base-support:1.3.0'

  // For animated GIF support
  implementation 'com.facebook.fresco:animated-gif:3.4.0'

  // For WebP support, including animated WebP
  implementation 'com.facebook.fresco:animated-webp:3.4.0'
  implementation 'com.facebook.fresco:webpsupport:3.4.0'

  // For WebP support, without animations
  implementation 'com.facebook.fresco:webpsupport:3.4.0'
}

Uwaga: Podana wersja może nie być aktualna. Sprawdź plik packages/react-native/gradle/libs.versions.toml w głównym repozytorium, aby zobaczyć, która wersja Fresco jest używana w konkretnej wersji.

Dokumentacja

Właściwości

Właściwości widoku

Dziedziczy właściwości widoku.

`accessible`

Gdy true, wskazuje że obraz jest elementem dostępności.

Type	Default
bool	`false`

`accessibilityLabel`

Tekst odczytywany przez czytnik ekranu, gdy użytkownik wchodzi w interakcję z obrazem.

Type
string

`alt`

Ciąg znaków definiujący alternatywny opis tekstowy obrazu, który zostanie odczytany przez czytnik ekranu podczas interakcji użytkownika. Użycie tej właściwości automatycznie oznacza element jako dostępny.

Type
string

`blurRadius`

blurRadius: promień rozmycia filtra dodanego do obrazu.

Type
number

Wskazówka: Na iOS należy zwiększyć blurRadius o wartość większą niż 5.

`capInsets`
iOS

Podczas zmiany rozmiaru obrazu, narożniki o rozmiarze określonym przez capInsets zachowają stały rozmiar, podczas gdy środek i krawędzie obrazu zostaną rozciągnięte. Przydatne przy tworzeniu przycisków z zaokrąglonymi rogami, cieni i innych skalowalnych zasobów. Więcej informacji w dokumentacji Apple.

Type
Rect

`crossOrigin`

Ciąg kluczowy określający tryb CORS używany podczas pobierania zasobu obrazu. Działa podobnie jak atrybut crossorigin w HTML.

anonymous: Brak wymiany danych uwierzytelniających użytkownika w żądaniu obrazu.
use-credentials: Ustawia wartość nagłówka Access-Control-Allow-Credentials na true w żądaniu obrazu.

Type	Default
enum(`'anonymous'`, `'use-credentials'`)	`'anonymous'`

`defaultSource`

Statyczny obraz wyświetlany podczas ładowania źródła obrazu.

Type
ImageSource

Uwaga: Na Androidzie właściwość defaultSource jest ignorowana w wersjach debugowych.

`fadeDuration`
Android

Czas trwania animacji przejścia (w milisekundach).

Type	Default
number	`300`

`height`

Wysokość komponentu obrazu.

Type
number

`loadingIndicatorSource`

Podobnie jak source, ta właściwość reprezentuje zasób używany do renderowania wskaźnika ładowania obrazu. Wskaźnik ładowania jest wyświetlany aż obraz będzie gotowy do wyświetlenia, zwykle po jego pobraniu.

Type
ImageSource (`uri` only), number

`onError`

Wywoływane przy błędzie ładowania.

Type
(`{nativeEvent: {error} }`) => void

`onLayout`

Wywoływane przy montowaniu i zmianach układu.

Type
`({nativeEvent: LayoutEvent} => void`

`onLoad`

Wywoływane przy pomyślnym zakończeniu ładowania.

Przykład: onLoad={({nativeEvent: {source: {width, height}}}) => setImageRealSize({width, height})}

Type
`({nativeEvent: ImageLoadEvent} => void`

`onLoadEnd`

Wywoływana, gdy ładowanie zakończy się sukcesem lub niepowodzeniem.

Type
() => void

`onLoadStart`

Wywoływana na początku ładowania.

Przykład: onLoadStart={() => this.setState({loading: true})}

Type
() => void

`onPartialLoad`
iOS

Wywoływana, gdy częściowe ładowanie obrazu zostanie zakończone. Definicja "częściowego ładowania" zależy od ładowarki, ale zwykle odnosi się do progresywnego ładowania JPEG.

Type
() => void

`onProgress`

Wywoływana podczas postępu pobierania.

Type
(`{nativeEvent: {loaded, total} }`) => void

`progressiveRenderingEnabled`
Android

Gdy true, włącza przesyłanie progresywne JPEG - https://frescolib.org/docs/progressive-jpegs.

Type	Default
bool	`false`

`referrerPolicy`

Ciąg znaków określający, który referrer użyć podczas pobierania zasobu. Ustawia wartość nagłówka Referrer-Policy w żądaniu obrazu. Działa podobnie jak atrybut referrerpolicy w HTML.

Type	Default
enum(`'no-referrer'`, `'no-referrer-when-downgrade'`, `'origin'`, `'origin-when-cross-origin'`, `'same-origin'`, `'strict-origin'`, `'strict-origin-when-cross-origin'`, `'unsafe-url'`)	`'strict-origin-when-cross-origin'`

`resizeMethod`
Android

Mechanizm używany do zmiany rozmiaru obrazu, gdy jego wymiary różnią się od wymiarów widoku obrazu. Domyślnie auto.

auto: Używa heurystyk do wyboru między resize a scale.
resize: Operacja programowa zmieniająca zakodowany obraz w pamięci przed dekodowaniem. Używaj zamiast scale, gdy obraz jest znacznie większy niż widok.
scale: Obraz jest rysowany pomniejszony lub powiększony. W porównaniu do resize, scale jest szybsze (zwykle przyspieszane sprzętowo) i daje obrazy wyższej jakości. Używaj, gdy obraz jest mniejszy niż widok lub nieznacznie większy.
none: Brak próbkowania - obraz wyświetlany w pełnej rozdzielczości. Używaj tylko w rzadkich przypadkach, gdyż może powodować wyjątki na Androidzie przy zbyt dużym zużyciu pamięci.

Więcej szczegółów o resize i scale: https://frescolib.org/docs/resizing.

Type	Default
enum(`'auto'`, `'resize'`, `'scale'`, `'none'`)	`'auto'`

`resizeMode`

Określa sposób zmiany rozmiaru obrazu, gdy ramka nie pasuje do oryginalnych wymiarów. Domyślnie cover.

cover: Skaluje obraz jednolicie (zachowując proporcje) tak, że:
- oba wymiary (szerokość i wysokość) obrazu będą równe lub większe od odpowiednich wymiarów widoku (minus padding)
- co najmniej jeden wymiar przeskalowanego obrazu będzie równy odpowiedniemu wymiarowi widoku (minus padding)
contain: Skaluje obraz jednolicie (zachowując proporcje) tak, że oba wymiary będą równe lub mniejsze od odpowiednich wymiarów widoku (minus padding).
stretch: Skaluje szerokość i wysokość niezależnie, co może zmienić proporcje obrazu.
repeat: Powtarza obraz, aby wypełnić ramkę widoku. Obraz zachowa rozmiar i proporcje, chyba że jest większy niż widok - wtedy zostanie jednolicie pomniejszony.
center: Wyśrodkowuje obraz w widoku w obu wymiarach. Jeśli obraz jest większy niż widok, pomniejsza go jednolicie.

Type	Default
enum(`'cover'`, `'contain'`, `'stretch'`, `'repeat'`, `'center'`)	`'cover'`

`resizeMultiplier`
Android

Gdy resizeMethod jest ustawione na resize, docelowe wymiary są mnożone przez tę wartość. Metoda scale obsługuje resztę zmiany rozmiaru. Wartość domyślna 1.0 oznacza dopasowanie do wymiarów docelowych. Mnożnik > 1.0 ustawia większe opcje zmiany rozmiaru, a wynikowa bitmapa jest skalowana w dół z rozmiaru sprzętowego. Domyślnie 1.0.

Ta właściwość jest szczególnie przydatna w sytuacjach, gdy docelowe wymiary są bardzo małe, a źródłowy obraz znacznie większy. Metoda zmiany rozmiaru resize wykonuje dółpróbkowanie, co prowadzi do znacznej utraty jakości między rozmiarami obrazu źródłowego i docelowego, często skutkując rozmytym obrazem. Używając mnożnika, dekodowany obraz jest nieco większy niż docelowy rozmiar, ale mniejszy niż obraz źródłowy (jeśli obraz źródłowy jest wystarczająco duży). Pozwala to artefaktom antyaliasingu stworzyć pozorną jakość poprzez operacje skalowania na powiększonym obrazie.

Jeśli masz obraz źródłowy o wymiarach 200x200 i docelowych wymiarach 24x24, resizeMultiplier o wartości 2.0 spowoduje, że Fresco zmniejszy próbkowanie obrazu do 48x48. Fresco wybiera najbliższą potęgę dwójki (czyli 50x50) i dekoduje obraz do bitmapy o tym rozmiarze. Bez mnożnika najbliższą potęgą dwójki byłoby 25x25. Wynikowy obraz jest następnie skalowany w dół przez system.

Type	Default
number	`1.0`

`source`

Źródło obrazu (zdalny URL lub lokalny zasób plikowy).

Ta właściwość może również zawierać kilka zdalnych URLi, określonych wraz z ich szerokością, wysokością oraz potencjalnie skalą/innymi argumentami URI. Natywna strona wybierze wtedy najlepszy uri do wyświetlenia na podstawie zmierzonego rozmiaru kontenera obrazu. Właściwość cache może zostać dodana, aby kontrolować interakcję żądań sieciowych z lokalną pamięcią podręczną (więcej informacji w Kontrola pamięci podręcznej dla obrazów).

Obecnie obsługiwane formaty to png, jpg, jpeg, bmp, gif, webp, psd (tylko iOS). Dodatkowo iOS obsługuje kilka formatów obrazów RAW. Aktualną listę obsługiwanych modeli aparatów znajdziesz w dokumentacji Apple (dla iOS 12 patrz https://support.apple.com/en-ca/HT208967).

Uwaga: format webp jest obsługiwany na iOS tylko w przypadku dołączania go w kodzie JavaScript.

Type
ImageSource

`src`

Łańcuch znaków reprezentujący zdalny URL obrazu. Ta właściwość ma pierwszeństwo przed właściwością source.

Przykład: src={'https://reactnative.dev/img/tiny_logo.png'}

Type
string

`srcSet`

Łańcuch znaków reprezentujący rozdzieloną przecinkami listę potencjalnych kandydatów na źródło obrazu. Każde źródło obrazu zawiera URL obrazu i deskryptor gęstości pikseli. Jeśli deskryptor nie jest określony, domyślnie przyjmuje wartość 1x.

Jeśli srcSet nie zawiera deskryptora 1x, wartość z src jest używana jako źródło obrazu z deskryptorem 1x (jeśli podano).

Ta właściwość ma pierwszeństwo przed właściwościami src i source.

Przykład: srcSet={'https://reactnative.dev/img/tiny_logo.png 1x, https://reactnative.dev/img/header_logo.svg 2x'}

Type
string

`style`

Type
Image Style Props, Layout Props, Shadow Props, Transforms

`testID`

Unikalny identyfikator tego elementu do użycia w skryptach testów automatyzacji interfejsu.

Type
string

`tintColor`

Zmienia kolor wszystkich nieprzezroczystych pikseli na tintColor.

Type
color

`width`

Szerokość komponentu obrazu.

Type
number

Metody

`abortPrefetch()`
Android

tsx
static abortPrefetch(requestId: number);

Przerwij żądanie wstępnego pobierania.

Parametry:

Name	Type	Description
requestId Required	number	Request id as returned by `prefetch()`.

`getSize()`

tsx
static getSize(uri: string): Promise<{width: number, height: number}>;

Pobierz szerokość i wysokość (w pikselach) obrazu przed jego wyświetleniem. Ta metoda może zakończyć się niepowodzeniem, jeśli obraz nie zostanie znaleziony lub nie pobierze się.

Aby pobrać wymiary obrazu, może być konieczne najpierw załadowanie lub pobranie obrazu, który następnie zostanie zapisany w pamięci podręcznej. Oznacza to, że w zasadzie można użyć tej metody do wstępnego ładowania obrazów, jednak nie jest ona zoptymalizowana do tego celu i w przyszłości może zostać zaimplementowana w sposób, który nie ładuje/pobiera w pełni danych obrazu. Właściwy, wspierany sposób wstępnego ładowania obrazów zostanie udostępniony jako osobne API.

Parametry:

Name	Type	Description
uri Required	string	The location of the image.

`getSizeWithHeaders()`

tsx
static getSizeWithHeaders(
  uri: string,
  headers: {[index: string]: string}
): Promise<{width: number, height: number}>;

Pobiera szerokość i wysokość (w pikselach) obrazu przed jego wyświetleniem, z możliwością dostarczenia nagłówków żądania. Ta metoda może zakończyć się niepowodzeniem, jeśli obraz nie zostanie znaleziony lub nie uda się go pobrać. Nie działa również dla statycznych zasobów obrazów.

Parametry:

Name	Type	Description
uri Required	string	The location of the image.
headers Required	object	The headers for the request.

`prefetch()`

tsx
await Image.prefetch(url);

Pobiera zdalny obraz do późniejszego użycia, zapisując go w pamięci podręcznej dysku. Zwraca obietnicę (promise), która rozwiązuje się do wartości logicznej (boolean).

Parametry:

Name	Type	Description
url Required	string	The remote location of the image.
callback	function Android	The function that will be called with the `requestId`.

`queryCache()`

tsx
static queryCache(
  urls: string[],
): Promise<Record<string, 'memory' | 'disk' | 'disk/memory'>>;

Przeprowadza interrogację pamięci podręcznej. Zwraca obietnicę (promise), która rozwiązuje się do odwzorowania z adresu URL na stan pamięci podręcznej, taki jak "disk", "memory" lub "disk/memory". Jeśli żądany adres URL nie znajduje się w odwzorowaniu, oznacza to, że nie ma go w pamięci podręcznej.

Parametry:

Name	Type	Description
urls Required	array	List of image URLs to check the cache for.

`resolveAssetSource()`

tsx
static resolveAssetSource(source: ImageSourcePropType): {
  height: number;
  width: number;
  scale: number;
  uri: string;
};

Rozwiązuje odwołanie do zasobu na obiekt, który ma właściwości uri, scale, width i height.

Parametry:

Name	Type	Description
source Required	ImageSource, number	A number (opaque type returned by `require('./foo.png')`) or an ImageSource.

Definicje Typów

ImageCacheEnum
iOS

Wyliczenie (enum), które może zostać użyte do ustawienia sposobu obsługi pamięci podręcznej lub strategii dla potencjalnie buforowanych odpowiedzi.

Type	Default
enum(`'default'`, `'reload'`, `'force-cache'`, `'only-if-cached'`)	`'default'`

default: Użyj domyślnej strategii natywnej platformy.
reload: Dane dla adresu URL zostaną załadowane z oryginalnego źródła. Żadne istniejące dane z pamięci podręcznej nie powinny być użyte do obsłużenia żądania załadowania adresu URL.
force-cache: Istniejące dane z pamięci podręcznej zostaną użyte do obsłużenia żądania, niezależnie od ich wieku lub daty wygaśnięcia. Jeśli w pamięci podręcznej nie ma danych odpowiadających żądaniu, dane zostaną załadowane z oryginalnego źródła.
only-if-cached: Istniejące dane z pamięci podręcznej zostaną użyte do obsłużenia żądania, niezależnie od ich wieku lub daty wygaśnięcia. Jeśli w pamięci podręcznej nie ma danych odpowiadających żądaniu załadowania adresu URL, nie podejmuje się próby załadowania danych z oryginalnego źródła, a ładowanie jest uznawane za nieudane.

ImageLoadEvent

Obiekt zwracany w wywołaniu zwrotnym onLoad.

Type
object

Właściwości:

Name	Type	Description
source	object	The source object

Source Object

Właściwości:

Name	Type	Description
width	number	The width of loaded image.
height	number	The height of loaded image.
uri	string	A string representing the resource identifier for the image.

ImageSource

Type
object, array of objects, number

Właściwości (jeśli przekazywany jako obiekt lub tablica obiektów):

Name	Type	Description
uri	string	A string representing the resource identifier for the image, which could be an http address, a local file path, or the name of a static image resource.
width	number	Can be specified if known at build time, in which case the value will be used to set the default `<Image/>` component dimension.
height	number	Can be specified if known at build time, in which case the value will be used to set the default `<Image/>` component dimension.
scale	number	Used to indicate the scale factor of the image. Defaults to `1.0` if unspecified, meaning that one image pixel equates to one display point / DIP.
bundle iOS	string	The iOS asset bundle which the image is included in. This will default to `[NSBundle mainBundle]` if not set.
method	string	The HTTP Method to use. Defaults to `'GET'` if not specified.
headers	object	An object representing the HTTP headers to send along with the request for a remote image.
body	string	The HTTP body to send with the request. This must be a valid UTF-8 string, and will be sent exactly as specified, with no additional encoding (e.g. URL-escaping or base64) applied.
cache iOS	ImageCacheEnum	Determines how the requests handles potentially cached responses.

Jeśli przekazywana jest liczba:

number - typ nieprzezroczysty (opaque) zwracany przez coś takiego jak require('./image.jpg').

Przykłady​

Obsługa GIF i WebP na Androidzie​

Dokumentacja

Właściwości​

Właściwości widoku​

accessible​

accessibilityLabel​

alt​

blurRadius​

capInsets iOS​

crossOrigin​

defaultSource​

fadeDuration Android​

height​

loadingIndicatorSource​

onError​

onLayout​

onLoad​

onLoadEnd​

onLoadStart​

onPartialLoad iOS​

onProgress​

progressiveRenderingEnabled Android​

referrerPolicy​

resizeMethod Android​

resizeMode​

resizeMultiplier Android​

source​

src​

srcSet​

style​

testID​

tintColor​

width​

Metody​

abortPrefetch() Android​

getSize()​

getSizeWithHeaders()​

prefetch()​

queryCache()​

resolveAssetSource()​

Definicje Typów​

ImageCacheEnum iOS​

ImageLoadEvent​

Source Object​

ImageSource​

Przykłady

Obsługa GIF i WebP na Androidzie

Właściwości

Właściwości widoku

`accessible`

`accessibilityLabel`

`alt`

`blurRadius`

`capInsets`
iOS

`crossOrigin`

`defaultSource`

`fadeDuration`
Android

`height`

`loadingIndicatorSource`

`onError`

`onLayout`

`onLoad`

`onLoadEnd`

`onLoadStart`

`onPartialLoad`
iOS

`onProgress`

`progressiveRenderingEnabled`
Android

`referrerPolicy`

`resizeMethod`
Android

`resizeMode`

`resizeMultiplier`
Android

`source`

`src`

`srcSet`

`style`

`testID`

`tintColor`

`width`

Metody

`abortPrefetch()`
Android

`getSize()`

`getSizeWithHeaders()`

`prefetch()`

`queryCache()`

`resolveAssetSource()`

Definicje Typów

ImageCacheEnum
iOS

ImageLoadEvent

Source Object

ImageSource