Obraz
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:'.
Dla obrazów sieciowych i danych musisz 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.
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.6.0'
// For WebP support, including animated WebP
implementation 'com.facebook.fresco:animated-webp:3.6.0'
implementation 'com.facebook.fresco:webpsupport:3.6.0'
// For WebP support, without animations
implementation 'com.facebook.fresco:webpsupport:3.6.0'
}
Wersja wymieniona powyżej może nie być aktualna. Sprawdź packages/react-native/gradle/libs.versions.toml w głównym repozytorium, aby zobaczyć, która wersja fresco jest używana w konkretnej oznakowanej 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 |
Na iOS musisz zwiększyć blurRadius o więcej 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łówkaAccess-Control-Allow-Credentialsnatruew żądaniu obrazu.
| Type | Default |
|---|---|
enum('anonymous', 'use-credentials') | 'anonymous' |
defaultSource
Statyczny obraz wyświetlany podczas ładowania źródła obrazu.
| Type |
|---|
| ImageSource |
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' |
ref
Funkcja settera ref, która otrzyma węzeł elementu po zamontowaniu.
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ędzyresizeascale. -
resize: Operacja programowa zmieniająca zakodowany obraz w pamięci przed dekodowaniem. Używaj zamiastscale, gdy obraz jest znacznie większy niż widok. -
scale: Obraz jest rysowany pomniejszony lub powiększony. W porównaniu doresize,scalejest 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
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
static abortPrefetch(requestId: number);
Przerwij żądanie wstępnego pobierania.
Parametry:
| Name | Type | Description |
|---|---|---|
| requestId Required | number | Request id as returned by prefetch(). |
getSize()
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()
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.
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. |
| headers Required | object | The headers for the request. |
prefetch()
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()
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()
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 jakrequire('./image.jpg').