Text

テキストを表示するためのReactコンポーネントです。

Textは、ネスト、スタイリング、タッチハンドリングをサポートしています。

次の例では、ネストされたタイトルと本文のテキストはstyles.baseTextからfontFamilyを継承しますが、タイトルは独自の追加スタイルを提供します。タイトルと本文は、リテラルの改行により、互いに積み重なります。

ネストされたテキスト

AndroidとiOSの両方で、文字列の範囲に太字や色付きテキストなどの特定のフォーマットを注釈付けすることで、フォーマットされたテキストを表示できます（iOSではNSAttributedString、AndroidではSpannableString）。実際には、これは非常に面倒です。React Nativeでは、このためにWebのパラダイムを使用することにしました。テキストをネストすることで同じ効果を得ることができます。

舞台裏では、React Nativeはこれを以下の情報を含むフラットなNSAttributedStringまたはSpannableStringに変換します。

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

コンテナ

<Text>要素はレイアウトに関してユニークです。内部のすべてはもはやFlexboxレイアウトを使用せず、テキストレイアウトを使用します。これは、<Text>内の要素がもはや長方形ではなく、行の終わりに達すると折り返すことを意味します。

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|

限定的なスタイルの継承

Webでは、ドキュメント全体にフォントファミリーとサイズを設定する通常の方法は、次のように継承されたCSSプロパティを利用することです。

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

ドキュメント内のすべての要素は、それらかその親のいずれかが新しいルールを指定しない限り、このフォントを継承します。

React Nativeでは、これについてより厳格です。すべてのテキストノードを<Text>コンポーネントで囲む必要があります。テキストノードを<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>

また、サブツリー全体にデフォルトのフォントを設定する機能も失われます。一方、fontFamilyはCSSのfont-familyとは異なり、単一のフォント名しか受け付けません。アプリケーション全体で一貫したフォントとサイズを使用する推奨方法は、それらを含むコンポーネントMyAppTextを作成し、このコンポーネントをアプリ全体で使用することです。また、このコンポーネントを使用して、他の種類のテキスト用にMyAppHeaderTextのようなより具体的なコンポーネントを作成することもできます。

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

MyAppTextが、子をスタイリング付きのTextコンポーネントにレンダリングするだけのコンポーネントであると仮定すると、MyAppHeaderTextは次のように定義できます。

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

この方法でMyAppTextを構成することで、トップレベルのコンポーネントからスタイルを取得しつつ、特定のユースケースでそれらを追加/上書きする能力を維持できます。

React Nativeにはまだスタイルの継承の概念がありますが、テキストのサブツリーに限定されています。この場合、2番目の部分は太字かつ赤色になります。

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

このより制約のあるテキストのスタイリング方法が、より良いアプリを生み出すと信じています。

（開発者）Reactコンポーネントは、強力な分離を念頭に置いて設計されています。propsが同じである限り、同じように見え、同じように動作すると信じて、アプリケーションのどこにでもコンポーネントを配置できるはずです。propsの外部から継承できるテキストプロパティは、この分離を破壊します。
（実装者）React Nativeの実装も簡素化されています。すべての要素にfontFamilyフィールドを持つ必要はなく、テキストノードを表示するたびにルートまでツリーを遡る必要もありません。スタイルの継承はネイティブのTextコンポーネント内にのみエンコードされ、他のコンポーネントやシステム自体には漏れません。

リファレンス

Props

`accessibilityHint`

アクセシビリティヒントは、アクセシビリティラベルから結果が明確でない場合に、ユーザーがアクセシビリティ要素に対してアクションを実行したときに何が起こるかを理解するのに役立ちます。

型
string

`accessibilityLanguage`
iOS

ユーザーが要素を操作する際にスクリーンリーダーが使用すべき言語を示す値です。BCP 47仕様に従う必要があります。

詳細はiOSの `accessibilityLanguage` ドキュメントを参照してください。

型
string

`accessibilityLabel`

ユーザーが要素を操作したときにスクリーンリーダーによって読み上げられるテキストを上書きします。デフォルトでは、ラベルはすべての子を走査し、すべてのTextノードをスペースで区切って蓄積することによって構築されます。

型
string

`accessibilityRole`

スクリーンリーダーに、現在フォーカスされている要素を特定の役割を持つものとして扱うように伝えます。

iOSでは、これらの役割は対応するアクセシビリティ特性にマッピングされます。イメージボタンは、特性が「image」と「button」の両方に設定されている場合と同じ機能を持ちます。詳細については、アクセシビリティガイドを参照してください。

Androidでは、これらの役割は、iOSのVoiceoverでアクセシビリティ特性を追加するのと同様の機能をTalkBackで持ちます。

型
AccessibilityRole

`accessibilityState`

スクリーンリーダーに、現在フォーカスされている要素が特定の状態にあるものとして扱うように伝えます。

1つの状態、状態なし、または複数の状態を提供できます。状態はオブジェクトを介して渡す必要があります。例：{selected: true, disabled: true}。

型
AccessibilityState

`accessibilityActions`

アクセシビリティアクションを使用すると、支援技術がコンポーネントのアクションをプログラムで呼び出すことができます。accessibilityActionsプロパティには、アクションオブジェクトのリストを含める必要があります。各アクションオブジェクトには、フィールド名とラベルを含める必要があります。

詳細はアクセシビリティガイドを参照してください。

型	必須
array	No

`onAccessibilityAction`

ユーザーがアクセシビリティアクションを実行したときに呼び出されます。この関数への唯一の引数は、実行するアクションの名前を含むイベントです。

詳細はアクセシビリティガイドを参照してください。

型	必須
function	No

`accessible`

trueに設定すると、ビューがアクセシビリティ要素であることを示します。

詳細については、アクセシビリティガイドを参照してください。

型	デフォルト
boolean	`true`

`adjustsFontSizeToFit`

与えられたスタイル制約に収まるようにフォントを自動的に縮小するかどうかを指定します。

型	デフォルト
boolean	`false`

`allowFontScaling`

テキストサイズのアクセシビリティ設定を尊重してフォントをスケーリングするかどうかを指定します。

型	デフォルト
boolean	`true`

`android_hyphenationFrequency`
Android

Android APIレベル23以降で単語の区切りを決定する際に使用する自動ハイフネーションの頻度を設定します。

型	デフォルト
enum(`'none'`, `'normal'`,`'full'`)	`'none'`

`aria-busy`

要素が変更中であり、支援技術がユーザーに更新を通知する前に変更が完了するのを待つ可能性があることを示します。

型	デフォルト
boolean	false

`aria-checked`

チェック可能な要素の状態を示します。このフィールドは、混合チェックボックスを表すためにブール値または「mixed」文字列のいずれかを取ることができます。

型	デフォルト
boolean, 'mixed'	false

`aria-disabled`

要素が知覚可能であるが無効であり、編集またはその他の操作ができないことを示します。

型	デフォルト
boolean	false

`aria-expanded`

展開可能な要素が現在展開されているか折りたたまれているかを示します。

型	デフォルト
boolean	false

`aria-label`

インタラクティブな要素にラベルを付ける文字列値を定義します。

型
string

`aria-selected`

選択可能な要素が現在選択されているかどうかを示します。

型
boolean

`dataDetectorType`
Android

テキスト要素内でクリック可能なURLに変換されるデータの種類を決定します。デフォルトでは、データ型は検出されません。

1つのタイプのみを提供できます。

型	デフォルト
enum(`'phoneNumber'`, `'link'`, `'email'`, `'none'`, `'all'`)	`'none'`

`disabled`
Android

テスト目的でテキストビューの無効状態を指定します。

型	デフォルト
bool	`false`

`dynamicTypeRamp`
iOS

iOSでこの要素に適用するダイナミックタイプランプ。

型	デフォルト
enum(`'caption2'`, `'caption1'`, `'footnote'`, `'subheadline'`, `'callout'`, `'body'`, `'headline'`, `'title3'`, `'title2'`, `'title1'`, `'largeTitle'`)	`'body'`

`ellipsizeMode`

numberOfLinesが設定されている場合、このプロパティはテキストがどのように切り捨てられるかを定義します。numberOfLinesはこのプロパティと組み合わせて設定する必要があります。

これは次の値のいずれかになります。

head - 行の末尾がコンテナに収まるように表示され、行の先頭の欠落したテキストは省略記号で示されます。例：「...wxyz」
middle - 行の先頭と末尾がコンテナに収まるように表示され、中央の欠落したテキストは省略記号で示されます。「ab...yz」
tail - 行の先頭がコンテナに収まるように表示され、行の末尾の欠落したテキストは省略記号で示されます。例：「abcd...」
clip - 行はテキストコンテナの端を超えて描画されません。

Androidでは、numberOfLinesが1より大きい値に設定されている場合、tail値のみが正しく機能します。

型	デフォルト
enum(`'head'`, `'middle'`, `'tail'`, `'clip'`)	`tail`

`id`

ネイティブコードからこのビューを見つけるために使用されます。nativeIDプロパティよりも優先されます。

型
string

`maxFontSizeMultiplier`

allowFontScalingが有効な場合にフォントが到達できる最大スケールを指定します。可能な値：

null/undefined：親ノードまたはグローバルデフォルト（0）から継承
0：最大値なし、親/グローバルデフォルトを無視
>= 1：このノードのmaxFontSizeMultiplierをこの値に設定

型	デフォルト
number	`undefined`

`minimumFontScale`
iOS

adjustsFontSizeToFitが有効な場合にフォントが到達できる最小スケールを指定します。（値 0.01-1.0）。

型
number

`nativeID`

ネイティブコードからこのビューを見つけるために使用されます。

型
string

`numberOfLines`

行の折り返しを含むテキストレイアウトを計算した後、行の総数がこの数を超えないようにテキストを省略記号で切り捨てるために使用されます。このプロパティを0に設定すると、この値が設定解除され、行の制限が適用されなくなります。

このプロパティは一般的にellipsizeModeと共に使用されます。

型	デフォルト
number	`0`

`onLayout`

マウント時およびレイアウト変更時に呼び出されます。

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

`onLongPress`

この関数は長押し時に呼び出されます。

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

`onMoveShouldSetResponder`

このビューはタッチ応答性を「要求」しますか？これは、レスポンダーでないView上でのすべてのタッチ移動に対して呼び出されます。

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

`onPress`

ユーザーのプレス時に呼び出される関数で、onPressOutの後にトリガーされます。

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

`onPressIn`

タッチが開始された直後、onPressOutとonPressの前に呼び出されます。

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

`onPressOut`

タッチが離されたときに呼び出されます。

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

`onResponderGrant`

ビューは現在タッチイベントに応答しています。これは、何が起こっているかをユーザーにハイライトして示す時間です。

Androidでは、このレスポンダーが終了するまで他のネイティブコンポーネントがレスポンダーになるのを防ぐために、このコールバックからtrueを返します。

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

`onResponderMove`

ユーザーが指を動かしています。

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

`onResponderRelease`

タッチの最後に発火します。

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

`onResponderTerminate`

レスポンダーがViewから奪われました。onResponderTerminationRequestの呼び出し後に他のビューによって奪われるか、OSによって尋ねられずに奪われることがあります（例：iOSのコントロールセンター/通知センターで発生）。

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

`onResponderTerminationRequest`

他のViewがレスポンダーになりたがり、このViewにレスポンダーを解放するように要求しています。trueを返すと解放が許可されます。

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

`onStartShouldSetResponderCapture`

親Viewがタッチ開始時に子Viewがレスポンダーになるのを防ぎたい場合、trueを返すこのハンドラーを持つべきです。

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

`onTextLayout`

テキストレイアウトの変更時に呼び出されます。

型
(`TextLayoutEvent`) => mixed

`pressRetentionOffset`

スクロールビューが無効な場合、ボタンを非アクティブ化する前にタッチがボタンからどれだけ離れて移動できるかを定義します。一度非アクティブ化されると、元に戻してみてください。ボタンが再びアクティブ化されるのがわかります！スクロールビューが無効な間、何度か前後に動かしてみてください。メモリ割り当てを減らすために、定数を渡すようにしてください。

型
Rect, number

`role`

roleは、コンポーネントの目的を支援技術のユーザーに伝えます。accessibilityRoleプロパティよりも優先されます。

型
Role

`selectable`

ユーザーがテキストを選択し、ネイティブのコピー＆ペースト機能を使用できるようにします。

型	デフォルト
boolean	`false`

`selectionColor`
Android

テキストのハイライト色。

型
color

`style`

型
Text Style, View Style Props

`suppressHighlighting`
iOS

trueの場合、テキストが押されたときに視覚的な変化はありません。デフォルトでは、押されたときに灰色の楕円がテキストをハイライトします。

型	デフォルト
boolean	`false`

`testID`

E2Eテストでこのビューを特定するために使用されます。

型
string

`textBreakStrategy`
Android

Android APIレベル23以降でテキストの改行戦略を設定します。可能な値はsimple, highQuality, balancedです。

型	デフォルト
enum(`'simple'`, `'highQuality'`, `'balanced'`)	`highQuality`

`lineBreakStrategyIOS`
iOS

iOS 14以降で改行戦略を設定します。可能な値は none, standard, hangul-word, push-out です。

型	デフォルト
enum(`'none'`, `'standard'`, `'hangul-word'`, `'push-out'`)	`'none'`

型定義

TextLayout

TextLayoutオブジェクトはTextLayoutEventコールバックの一部であり、Text行の測定データを含みます。

使用例

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

プロパティ

名前	型	Optional	説明
ascender	number	No	テキストレイアウト変更後の行のアセンダーの高さ。
capHeight	number	No	ベースラインより上の大文字の高さ。
descender	number	No	テキストレイアウト変更後の行のディセンダーの高さ。
height	number	No	テキストレイアウト変更後の行の高さ。
width	number	No	テキストレイアウト変更後の行の幅。
x	number	No	Textコンポーネント内の行のX座標。
xHeight	number	No	ベースラインと行の中央線との間の距離（コーパスサイズ）。
y	number	No	Textコンポーネント内の行のY座標。

TextLayoutEvent

TextLayoutEventオブジェクトは、コンポーネントのレイアウト変更の結果としてコールバックで返されます。これには、レンダリングされたすべてのテキスト行に対応するTextLayoutオブジェクトを含む配列を値として持つlinesというキーが含まれています。

例

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

プロパティ

名前	型	Optional	説明
lines	TextLayoutの配列	No	レンダリングされたすべての行のTextLayoutデータを提供します。
target	number	No	要素のノードID。

ネストされたテキスト
コンテナ
限定的なスタイルの継承
Props
型定義
- TextLayout
- TextLayoutEvent

ネストされたテキスト​

コンテナ​

限定的なスタイルの継承​

リファレンス

Props​

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 iOS​

nativeID​

numberOfLines​

onLayout​

onLongPress​

onMoveShouldSetResponder​

onPress​

onPressIn​

onPressOut​

onResponderGrant​

onResponderMove​

onResponderRelease​

onResponderTerminate​

onResponderTerminationRequest​

onStartShouldSetResponderCapture​

onTextLayout​

pressRetentionOffset​

role​

selectable​

selectionColor Android​

style​

suppressHighlighting iOS​

testID​

textBreakStrategy Android​

lineBreakStrategyIOS iOS​

型定義​

TextLayout​

使用例​

プロパティ​

TextLayoutEvent​

例​

プロパティ​

ネストされたテキスト

コンテナ

限定的なスタイルの継承

Props

`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`
iOS

`nativeID`

`numberOfLines`

`onLayout`

`onLongPress`

`onMoveShouldSetResponder`

`onPress`

`onPressIn`

`onPressOut`

`onResponderGrant`

`onResponderMove`

`onResponderRelease`

`onResponderTerminate`

`onResponderTerminationRequest`

`onStartShouldSetResponderCapture`

`onTextLayout`

`pressRetentionOffset`

`role`

`selectable`

`selectionColor`
Android

`style`

`suppressHighlighting`
iOS

`testID`

`textBreakStrategy`
Android

`lineBreakStrategyIOS`
iOS

型定義

TextLayout

使用例

プロパティ

TextLayoutEvent

例

プロパティ