Tekst

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 tekstu.

Text obsługuje zagnieżdżanie, stylowanie oraz obsługę dotyku.

W poniższym przykładzie zagnieżdżony tytuł i treść odziedziczą właściwość fontFamily z styles.baseText, ale tytuł dostarcza własne dodatkowe style. Tytuł i treść ułożą się jeden pod drugim z powodu literalnych znaków nowej linii:

Zagnieżdżony tekst

Zarówno Android, jak i iOS pozwalają na wyświetlanie sformatowanego tekstu poprzez adnotowanie zakresów ciągu znaków konkretnym formatowaniem, takim jak pogrubienie czy kolor (NSAttributedString w iOS, SpannableString w Androidzie). W praktyce jest to bardzo żmudne. W React Native postanowiliśmy użyć paradygmatu znanego z sieci, gdzie można zagnieżdżać tekst, aby osiągnąć ten sam efekt.

W tle React Native konwertuje to do płaskiego NSAttributedString lub SpannableString, który zawiera następujące informacje:

"I am bold and red"
0-9: bold
9-17: bold, red

Kontenery

Element <Text> jest unikalny pod względem układu: wszystko wewnątrz niego nie używa już układu Flexbox, lecz układu tekstowego. Oznacza to, że elementy wewnątrz <Text> nie są już prostokątami, lecz zawijają się przy końcu linii.

tsx
<Text>
  <Text>First part and </Text>
  <Text>second part</Text>
</Text>
// Text container: the text will be inline, if the space allows it
// |First part and second part|

// otherwise, the text will flow as if it was one
// |First part |
// |and second |
// |part       |

<View>
  <Text>First part and </Text>
  <Text>second part</Text>
</View>
// View container: each text is its own block
// |First part and|
// |second part   |

// otherwise, the text will flow in its own block
// |First part |
// |and        |
// |second part|

Ograniczone dziedziczenie stylów

W sieci, zwykłym sposobem ustawienia rodziny czcionek i rozmiaru dla całego dokumentu jest skorzystanie z dziedziczonych właściwości CSS:

css
html {
  font-family:
    'lucida grande', tahoma, verdana, arial, sans-serif;
  font-size: 11px;
  color: #141823;
}

Wszystkie elementy w dokumencie odziedziczą tę czcionkę, chyba że one lub któryś z ich rodziców określi nową regułę.

W React Native jesteśmy bardziej rygorystyczni: musisz zawinąć wszystkie węzły tekstowe w komponencie <Text>. Nie możesz mieć węzła tekstowego bezpośrednio pod <View>.

tsx
// BAD: will raise exception, can't have a text node as child of a <View>
<View>
  Some text
</View>

// GOOD
<View>
  <Text>
    Some text
  </Text>
</View>

Tracisz także możliwość ustawienia domyślnej czcionki dla całego poddrzewa. Tymczasem fontFamily akceptuje tylko pojedynczą nazwę czcionki, co różni się od font-family w CSS. Zalecanym sposobem na używanie spójnych czcionek i rozmiarów w całej aplikacji jest utworzenie komponentu MyAppText, który je zawiera, i użycie tego komponentu w całej aplikacji. Możesz także użyć tego komponentu do tworzenia bardziej specyficznych komponentów, takich jak MyAppHeaderText dla innych rodzajów tekstu.

tsx
<View>
  <MyAppText>
    Text styled with the default font for the entire application
  </MyAppText>
  <MyAppHeaderText>Text styled as a header</MyAppHeaderText>
</View>

Zakładając, że MyAppText jest komponentem, który renderuje swoje dzieci w komponencie Text ze stylami, to MyAppHeaderText można zdefiniować następująco:

tsx
const MyAppHeaderText = ({children}) => {
  return (
    <MyAppText>
      <Text style={{fontSize: 20}}>{children}</Text>
    </MyAppText>
  );
};

Komponowanie MyAppText w ten sposób zapewnia, że otrzymujemy style z komponentu najwyższego poziomu, ale pozostawia nam możliwość dodawania lub nadpisywania ich w konkretnych przypadkach użycia.

React Native wciąż ma koncepcję dziedziczenia stylów, ale ograniczonego do poddrzew tekstowych. W tym przypadku druga część będzie zarówno pogrubiona, jak i czerwona.

tsx
<Text style={{fontWeight: 'bold'}}>
  I am bold
  <Text style={{color: 'red'}}>and red</Text>
</Text>

Uważamy, że ten bardziej ograniczony sposób stylowania tekstu przyniesie lepsze aplikacje:

(Deweloper) Komponenty React są projektowane z myślą o silnej izolacji: Powinieneś móc umieścić komponent w dowolnym miejscu aplikacji, ufając, że o ile właściwości są takie same, będzie on wyglądał i zachowywał się tak samo. Właściwości tekstu, które mogłyby dziedziczyć spoza właściwości, złamałyby tę izolację.
(Implementujący) Implementacja React Native jest także uproszczona. Nie musimy mieć pola fontFamily na każdym pojedynczym elemencie i nie musimy potencjalnie przeszukiwać drzewa aż do korzenia za każdym razem, gdy wyświetlamy węzeł tekstowy. Dziedziczenie stylów jest zakodowane tylko wewnątrz natywnego komponentu Text i nie wycieka do innych komponentów ani samego systemu.

Dokumentacja

Właściwości

`accessibilityHint`

Podpowiedź ułatwień dostępu pomaga użytkownikom zrozumieć, co się stanie, gdy wykonają akcję na elemencie ułatwień dostępu, gdy wynik nie jest jasny z etykiety ułatwień dostępu.

Type
string

`accessibilityLanguage`
iOS

Wartość określająca język używany przez czytnik ekranu podczas interakcji użytkownika z elementem. Powinna być zgodna ze specyfikacją BCP 47.

Więcej informacji znajdziesz w dokumentacji accessibilityLanguage dla iOS.

Type
string

`accessibilityLabel`

Nadpisuje tekst odczytywany przez czytnik ekranu, gdy użytkownik wchodzi w interakcję z elementem. Domyślnie etykieta jest konstruowana poprzez przejście wszystkich dzieci i zebranie wszystkich węzłów Text oddzielonych spacją.

Type
string

`accessibilityRole`

Nakazuje czytnikowi ekranu traktować aktualnie fokusowany element jako posiadający konkretną rolę.

Na iOS te role są mapowane na odpowiednie cechy ułatwień dostępu. Przycisk obrazkowy ma taką samą funkcjonalność jak ustawienie cechy na 'image' i 'button' jednocześnie. Więcej informacji znajdziesz w przewodniku o ułatwieniach dostępu.

Na Androidzie te role mają podobną funkcjonalność w TalkBack jak dodawanie cech ułatwień dostępu w Voiceover na iOS.

Type
AccessibilityRole

`accessibilityState`

Nakazuje czytnikowi ekranu traktować aktualnie fokusowany element jako będący w określonym stanie.

Możesz podać jeden stan, brak stanu lub wiele stanów. Stany muszą być przekazane jako obiekt, np. {selected: true, disabled: true}.

Type
AccessibilityState

`accessibilityActions`

Akcje ułatwień dostępu pozwalają technologiom asystującym na programowe wywoływanie akcji komponentu. Właściwość accessibilityActions powinna zawierać listę obiektów akcji. Każdy obiekt akcji powinien zawierać pola name i label.

Więcej informacji znajdziesz w przewodniku o ułatwieniach dostępu.

Type	Required
array	No

`onAccessibilityAction`

Wywoływana, gdy użytkownik wykonuje akcje ułatwień dostępu. Jedynym argumentem tej funkcji jest zdarzenie zawierające nazwę akcji do wykonania.

Więcej informacji znajdziesz w przewodniku o ułatwieniach dostępu.

Type	Required
function	No

`accessible`

Gdy ustawione na true, wskazuje że widok jest elementem ułatwień dostępu.

Więcej informacji znajdziesz w przewodniku o ułatwieniach dostępu.

Type	Default
boolean	`true`

`adjustsFontSizeToFit`

Określa, czy czcionki powinny być automatycznie skalowane w dół, aby dopasować się do ograniczeń stylu.

Type	Default
boolean	`false`

`allowFontScaling`

Określa, czy czcionki powinny skalować się zgodnie z ustawieniami dostępności Rozmiaru Tekstu.

Type	Default
boolean	`true`

`android_hyphenationFrequency`
Android

Ustawia częstotliwość automatycznego dzielenia wyrazów przy określaniu podziałów słów na Androidzie w wersji API Level 23+.

Type	Default
enum(`'none'`, `'normal'`,`'full'`)	`'none'`

`aria-busy`

Wskazuje, że element jest modyfikowany, a technologie asystujące powinny zaczekać z powiadomieniem użytkownika do zakończenia zmian.

Type	Default
boolean	false

`aria-checked`

Wskazuje stan elementu z możliwością zaznaczenia. Przyjmuje wartość logiczną lub ciąg "mixed" dla pól wyboru w stanie mieszanym.

Type	Default
boolean, 'mixed'	false

`aria-disabled`

Wskazuje, że element jest widoczny, ale wyłączony - nie można go edytować ani obsługiwać.

Type	Default
boolean	false

`aria-expanded`

Wskazuje, czy rozwijany element jest aktualnie rozwinięty czy zwinięty.

Type	Default
boolean	false

`aria-label`

Definiuje wartość tekstową etykietującą interaktywny element.

Type
string

`aria-selected`

Wskazuje, czy wybieralny element jest aktualnie zaznaczony.

Type
boolean

`dataDetectorType`
Android

Określa typy danych konwertowane na klikalne adresy URL w elemencie tekstowym. Domyślnie nie wykrywa się żadnych typów danych.

Można podać tylko jeden typ.

Type	Default
enum(`'phoneNumber'`, `'link'`, `'email'`, `'none'`, `'all'`)	`'none'`

`disabled`
Android

Określa wyłączony stan widoku tekstowego do celów testowych.

Type	Default
bool	`false`

`dynamicTypeRamp`
iOS

Skala Dynamic Type do zastosowania dla tego elementu na iOS.

Type	Default
enum(`'caption2'`, `'caption1'`, `'footnote'`, `'subheadline'`, `'callout'`, `'body'`, `'headline'`, `'title3'`, `'title2'`, `'title1'`, `'largeTitle'`)	`'body'`

`ellipsizeMode`

Gdy ustawiono numberOfLines, ta właściwość definiuje sposób obcięcia tekstu. numberOfLines musi być ustawione razem z tą właściwością.

Może przyjmować następujące wartości:

head - Linia jest wyświetlana tak, że koniec mieści się w kontenerze, a brakujący tekst na początku linii jest oznaczony wielokropkiem, np. "...wxyz"
middle - Linia jest wyświetlana tak, że początek i koniec mieszczą się w kontenerze, a brakujący tekst w środku jest oznaczony wielokropkiem, np. "ab...yz"
tail - Linia jest wyświetlana tak, że początek mieści się w kontenerze, a brakujący tekst na końcu linii jest oznaczony wielokropkiem, np. "abcd..."
clip - Linie nie są rysowane poza krawędzią kontenera tekstu.

uwaga

Na Androidzie, gdy numberOfLines jest ustawione na wartość wyższą niż 1, tylko wartość tail będzie działać poprawnie.

Type	Default
enum(`'head'`, `'middle'`, `'tail'`, `'clip'`)	`tail`

`id`

Używane do lokalizowania tego widoku z kodu natywnego. Ma pierwszeństwo przed właściwością nativeID.

Type
string

`maxFontSizeMultiplier`

Określa maksymalną skalę, jaką może osiągnąć czcionka gdy allowFontScaling jest włączone. Możliwe wartości:

null/undefined: dziedziczy z węzła nadrzędnego lub globalnej wartości domyślnej (0)
0: brak limitu, ignoruj ustawienia nadrzędne/globalne
>= 1: ustawia maxFontSizeMultiplier dla tego węzła na podaną wartość

Type	Default
number	`undefined`

`minimumFontScale`

Określa minimalną skalę, jaką może osiągnąć czcionka gdy adjustsFontSizeToFit jest włączone (wartości 0.01-1.0).

Type
number

`nativeID`

Używane do lokalizowania tego widoku z kodu natywnego.

Type
string

`numberOfLines`

Używane do obcięcia tekstu wielokropkiem po obliczeniu układu tekstu, w tym zawijania wierszy, tak aby całkowita liczba wierszy nie przekroczyła tej wartości. Ustawienie tej właściwości na 0 spowoduje usunięcie ograniczenia liczby wierszy.

Ta właściwość jest często używana z ellipsizeMode.

Type	Default
number	`0`

`onLayout`

Wywoływane przy montowaniu i zmianach układu.

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

`onLongPress`

Ta funkcja jest wywoływana przy długim przyciśnięciu.

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

`onMoveShouldSetResponder`

Czy ten widok chce „przejąć” odpowiedzialność za dotyk? Wywoływane dla każdego ruchu dotyku na View, gdy nie jest on aktualnym responderem.

Type
`({nativeEvent: PressEvent}) => boolean`

`onPress`

Funkcja wywoływana przy naciśnięciu przez użytkownika, uruchamiana po onPressOut.

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

`onPressIn`

Wywoływany natychmiast po rozpoczęciu dotyku, przed onPressOut i onPress.

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

`onPressOut`

Wywoływany po zwolnieniu dotyku.

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

`onResponderGrant`

Widok rozpoczął reagowanie na zdarzenia dotykowe. To moment na podświetlenie i pokazanie użytkownikowi, co się dzieje.

W systemie Android zwróć true z tego callbacku, aby uniemożliwić innym natywnym komponentom przejęcie roli respondera do czasu zakończenia działania tego respondera.

Type
`({nativeEvent: PressEvent}) => void ｜ boolean`

`onResponderMove`

Użytkownik porusza palcem.

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

`onResponderRelease`

Wywoływane przy zakończeniu dotyku.

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

`onResponderTerminate`

Responder został odebrany temu View. Mógł zostać przejęty przez inne widoki po wywołaniu onResponderTerminationRequest lub przez system bez pytania (np. przy otwieraniu Centrum sterowania/Powiadomień w iOS).

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

`onResponderTerminationRequest`

Inny View chce zostać responderem i prosi ten View o zwolnienie roli respondera. Zwrócenie true pozwala na zwolnienie.

Type
`({nativeEvent: PressEvent}) => boolean`

`onStartShouldSetResponderCapture`

Jeżeli nadrzędny View chce uniemożliwić dziecku View przejęcie roli respondera przy rozpoczęciu dotyku, powinien mieć tę funkcję zwracającą true.

Type
`({nativeEvent: PressEvent}) => boolean`

`onTextLayout`

Wywoływana przy zmianie układu tekstu.

Type
(`TextLayoutEvent`) => mixed

`pressRetentionOffset`

Gdy przewijanie jest wyłączone, określa jak daleko można przesunąć palec poza przycisk przed jego dezaktywacją. Po dezaktywacji, przesuń palec z powrotem – przycisk zostanie ponownie aktywowany! Przesuwaj wielokrotnie tam i z powrotem przy wyłączonym przewijaniu. Przekaż stałą wartość, aby zmniejszyć alokację pamięci.

Type
Rect, number

`ref`

Funkcja settera ref, która otrzyma węzeł elementu po zamontowaniu.

Uwaga: komponenty Text nie dostarczają węzłów tekstowych w taki sposób, jak elementy akapitu (<p>) w sieci, które są węzłami elementów. Węzły tekstowe znajdują się jako ich węzły potomne.

`role`

role komunikuje cel komponentu użytkownikowi technologii asystujących. Ma pierwszeństwo przed właściwością accessibilityRole.

Type
Role

`selectable`

Pozwala użytkownikowi zaznaczać tekst do użycia z natywną funkcjonalnością kopiowania i wklejania.

Type	Default
boolean	`false`

`selectionColor`
Android

Kolor podświetlenia tekstu.

Type
color

`style`

Type
Text Style, View Style Props

`suppressHighlighting`
iOS

Gdy true, naciśnięcie tekstu nie powoduje wizualnej zmiany. Domyślnie przy naciśnięciu tekst jest podświetlany szarą owalną ramką.

Type	Default
boolean	`false`

`testID`

Używany do lokalizowania tego widoku w testach end-to-end.

Type
string

`textBreakStrategy`
Android

Ustawia strategię łamania tekstu w Androidzie API Level 23+. Możliwe wartości: simple, highQuality, balanced.

Type	Default
enum(`'simple'`, `'highQuality'`, `'balanced'`)	`highQuality`

`lineBreakStrategyIOS`
iOS

Ustawia strategię łamania wierszy na iOS 14+. Możliwe wartości: none, standard, hangul-word, push-out.

Type	Default
enum(`'none'`, `'standard'`, `'hangul-word'`, `'push-out'`)	`'none'`

Definicje Typów

TextLayout

Układ tekstu

Obiekt TextLayout jest częścią callbacku TextLayoutEvent i zawiera dane pomiarowe dla linii tekstu Text.

Przykład

js
{
    capHeight: 10.496,
    ascender: 14.624,
    descender: 4,
    width: 28.224,
    height: 18.624,
    xHeight: 6.048,
    x: 0,
    y: 0
}

Właściwości

Name	Type	Optional	Description
ascender	number	No	The line ascender height after the text layout changes.
capHeight	number	No	Height of capital letter above the baseline.
descender	number	No	The line descender height after the text layout changes.
height	number	No	Height of the line after the text layout changes.
width	number	No	Width of the line after the text layout changes.
x	number	No	Line X coordinate inside the Text component.
xHeight	number	No	Distance between the baseline and median of the line (corpus size).
y	number	No	Line Y coordinate inside the Text component.

TextLayoutEvent

Zdarzenie układu tekstu

Obiekt TextLayoutEvent jest zwracany w wywołaniu zwrotnym w wyniku zmiany układu komponentu. Zawiera klucz lines z wartością będącą tablicą zawierającą obiekty TextLayout odpowiadające każdej wyrenderowanej linii tekstu.

Przykład

js
{
  lines: [
    TextLayout,
    TextLayout,
    // ...
  ];
  target: 1127;
}

Właściwości

Name	Type	Optional	Description
lines	array of TextLayouts	No	Provides the TextLayout data for every rendered line.
target	number	No	The node id of the element.

Zagnieżdżony tekst
Kontenery
Ograniczone dziedziczenie stylów
Właściwości
Definicje Typów

Zagnieżdżony tekst​

Kontenery​

Ograniczone dziedziczenie stylów​

Dokumentacja

Właściwości​

accessibilityHint​

accessibilityLanguage iOS​

accessibilityLabel​

accessibilityRole​

accessibilityState​

accessibilityActions​

onAccessibilityAction​

accessible​

adjustsFontSizeToFit​

allowFontScaling​

android_hyphenationFrequency Android​

aria-busy​

aria-checked​

aria-disabled​

aria-expanded​

aria-label​

aria-selected​

dataDetectorType Android​

disabled Android​

dynamicTypeRamp iOS​

ellipsizeMode​

id​

maxFontSizeMultiplier​

minimumFontScale​

nativeID​

numberOfLines​

onLayout​

onLongPress​

onMoveShouldSetResponder​

onPress​

onPressIn​

onPressOut​

onResponderGrant​

onResponderMove​

onResponderRelease​

onResponderTerminate​

onResponderTerminationRequest​

onStartShouldSetResponderCapture​

onTextLayout​

pressRetentionOffset​

ref​

role​

selectable​

selectionColor Android​

style​

suppressHighlighting iOS​

testID​

textBreakStrategy Android​

lineBreakStrategyIOS iOS​

Definicje Typów​

TextLayout​

Układ tekstu​

Przykład​

Właściwości​

TextLayoutEvent​

Zdarzenie układu tekstu​

Przykład​

Właściwości​

Zagnieżdżony tekst

Kontenery

Ograniczone dziedziczenie stylów

Właściwości

`accessibilityHint`

`accessibilityLanguage`
iOS

`accessibilityLabel`

`accessibilityRole`

`accessibilityState`

`accessibilityActions`

`onAccessibilityAction`

`accessible`

`adjustsFontSizeToFit`

`allowFontScaling`

`android_hyphenationFrequency`
Android

`aria-busy`

`aria-checked`

`aria-disabled`

`aria-expanded`

`aria-label`

`aria-selected`

`dataDetectorType`
Android

`disabled`
Android

`dynamicTypeRamp`
iOS

`ellipsizeMode`

`id`

`maxFontSizeMultiplier`

`minimumFontScale`

`nativeID`

`numberOfLines`

`onLayout`

`onLongPress`

`onMoveShouldSetResponder`

`onPress`

`onPressIn`

`onPressOut`

`onResponderGrant`

`onResponderMove`

`onResponderRelease`

`onResponderTerminate`

`onResponderTerminationRequest`

`onStartShouldSetResponderCapture`

`onTextLayout`

`pressRetentionOffset`

`ref`

`role`

`selectable`

`selectionColor`
Android

`style`

`suppressHighlighting`
iOS

`testID`

`textBreakStrategy`
Android

`lineBreakStrategyIOS`
iOS

Definicje Typów

TextLayout

Układ tekstu

Przykład

Właściwości

TextLayoutEvent

Zdarzenie układu tekstu

Przykład

Właściwości