Text

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

Textは、ネスト、スタイル設定、タッチ処理をサポートしています。

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

ネストされたテキスト

AndroidとiOSの両方で、太字や色付きテキストなどの特定の書式設定で文字列の範囲に注釈を付けることで、書式設定されたテキストを表示できます (iOSではNSAttributedString、AndroidではSpannableString)。実際には、これは非常に面倒です。React Nativeでは、これにウェブのパラダイムを使用することにしました。これにより、テキストをネストして同じ効果を実現できます。

内部では、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|

制限されたスタイル継承

ウェブでは、ドキュメント全体のフォントファミリーとサイズを設定する通常のやり方は、次のように継承された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では、これらの役割は対応するAccessibility Traitsにマッピングされます。画像ボタンは、その特性が「image」と「button」の両方に設定されている場合と同じ機能を持っています。詳細については、アクセシビリティガイドを参照してください。

Androidでは、これらの役割はiOSのVoiceoverでのAccessibility Traitsの追加と同様の機能を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でこの要素に適用するDynamic Typeのランプです。

型	デフォルト
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`

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`

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

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`

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

型
(`TextLayoutEvent`) => mixed

`pressRetentionOffset`

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

型
Rect, number

`ref`

マウント時に要素ノードが割り当てられる ref セッター。

Textコンポーネントはテキストノードを提供しないことに注意してください。これは、ウェブの段落要素 (<p>) がテキストノードではなく要素ノードであるのと同じです。テキストノードは、その子ノードとして見つけることができます。

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

プロパティ

名前	型	任意	説明
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;
}

プロパティ

名前	型	任意	説明
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​

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​

型定義​

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`

`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

型定義

TextLayout

例

プロパティ

TextLayoutEvent

例

プロパティ