私のブックマーク
ブックマークを追加
ブックマークを削除インストール
モジュールをインストールします
npm install @wordpress/rich-text
このパッケージは、あなたのコードがES2015+環境で実行されることを前提としています。そのような言語機能やAPIのサポートが限られているか、まったくない環境を使用している場合は、コードに@wordpress/babel-preset-defaultで提供されるポリフィルを含める必要があります。
使用法
リッチテキストパッケージは、プレーンテキスト文字列を操作して複雑なフォーマットを表現できるように設計されています。
リッチフォーマットの例には、次のものが含まれます：- 太字、斜体、上付き文字（など）- リンク- 順不同/順序付きリスト<a name="the-richtextvalue-object"></a>### RichTextValueオブジェクト値オブジェクトは次の要素で構成されています：- `````text````` – リッチフォーマットを適用するテキストの文字列。- `````formats````` – `````text`````と同じ長さのスパース配列で、テキストがフォーマットされている位置に[フォーマット](/read/wordpress/aa300e70d029e237.md)（例：`````core/link`````、`````core/bold`````など）が埋め込まれています。- `````start````` – 現在のアクティブな選択の開始を表す`````text`````内のインデックス。- `````end````` – 現在のアクティブな選択の終了を表す`````text`````内のインデックス。独自の`````value`````オブジェクトを作成しようとしないでください。むしろ、`````@wordpress/rich-text`````パッケージの組み込みメソッドを利用してこれらを構築するべきです。値がリッチフォーマットされたテキストをどのように表すかを理解することが重要です。以下に例を示します。`````text`````が位置2-5で太字（`````core/bold`````）にフォーマットされ、位置2-8でリンク（`````core/link`````）にフォーマットされている場合、次のことがわかります：- スパース配列の位置2-5に`````core/bold`````フォーマットを含む配列- スパース配列の位置2-8に`````core/link`````フォーマットを含む配列以下のようになります：``````bash{text: 'Hello world', // length 11formats: [[], // 0[],[ // 2{type: 'core/bold',},{type: 'core/link',}],[{type: 'core/bold',},{type: 'core/link',}],[{type: 'core/bold',},{type: 'core/link',}],[{type: 'core/bold',},{type: 'core/link',}],[ // 6{type: 'core/link',}][{type: 'core/link',}],[{type: 'core/link',}],[], // 9[], // 10[], // 11]}`
選択
上記のHello worldテキストの例を考え続けましょう。
ユーザーとして、Helloという単語を選択すると、startとendがそれぞれ0と5として値オブジェクトが生成されます。
一般的に、これはどの部分のテキストが選択されているかを知るのに役立ちます。ただし、選択が「折りたたまれる」可能性も考慮する必要があります。
折りたたまれた選択
折りたたまれた選択は、startとendの値が同一である場合です（例：start: 4, end: 4）。これは、文字が選択されていないが、キャレットが存在する場合に発生します。これは、ユーザーがテキストの文字列内にカーソル/キャレットを置くが、選択を行わない場合に最もよく発生します。
選択に「範囲」がないため（すなわち、startとendインデックスの間に違いがない）、折りたたまれた値から現在選択されているテキストの部分を見つけるのは難しい場合があります。
API
applyFormat
指定されたstartIndexから指定されたendIndexまでリッチテキスト値にフォーマットオブジェクトを適用します。インデックスが提供されていない場合は、選択から取得されます。
パラメータ
- 値
RichTextValue: 修正する値。 - フォーマット
RichTextFormat: 適用するフォーマット。 - startIndex
[number]: 開始インデックス。 - endIndex
[number]: 終了インデックス。
戻り値
concat
すべてのリッチテキスト値を1つに結合します。これはString.prototype.concatに似ています。
パラメータ
- 値
...RichTextValue: 結合するオブジェクト。
戻り値
create
値は次の形状を持ち、ヘルパー関数を使用せずに変更しないことを強くお勧めします：``````bash{text: string,formats: Array,replacements: Array,?start: number,?end: number,}`
テキストとフォーマットが分離されていることがわかります。textは、オブジェクトや行の置換文字を含むテキストを保持します。formats、objects、linesはすべてtextと同じ長さのスパース配列です。関連するテキストインデックスでのフォーマットに関する情報を保持します。最後に、startとendは、どのテキストインデックスが選択されているかを示します。Rangeが指定された場合にのみ提供されます。
パラメータ
- $1
[Object]: オプションの名前付き引数。 - $1.element
[Element]: 値を作成する要素。 - $1.text
[string]: 値を作成するためのテキスト。 - $1.html
[string]: 値を作成するためのHTML。 - $1.range
[Range]: 値を作成するための範囲。 - $1.__unstableIsEditableTree
[boolean]:
戻り値
getActiveFormat
選択の開始時にフォーマットオブジェクトをタイプ別に取得します。これを使用して、現在の選択のリンクフォーマットのURLを取得したり、選択でフォーマットがアクティブかどうかを確認したりできます。選択にフォーマットがない場合はundefinedが返されます。
パラメータ
- 値
RichTextValue: 検査する値。 - formatType
string: 探すフォーマットタイプ。
戻り値
getActiveFormats
選択の開始時にすべてのフォーマットオブジェクトを取得します。
パラメータ
- 値
RichTextValue: 検査する値。 - EMPTY_ACTIVE_FORMATS
Array: アクティブフォーマットがない場合に返す配列。
戻り値
getActiveObject
アクティブオブジェクトがある場合は取得します。
パラメータ
- 値
RichTextValue: 検査する値。
戻り値
getTextContent
リッチテキスト値のテキストコンテンツを取得します。これはElement.textContentに似ています。
パラメータ
- 値
RichTextValue: 使用する値。
戻り値
insert
リッチテキスト値、HTML文字列、またはプレーンテキスト文字列を指定されたstartIndexでリッチテキスト値に挿入します。startIndexとendIndexの間のコンテンツは削除されます。インデックスが提供されていない場合は、選択から取得されます。
パラメータ
- 値
RichTextValue: 修正する値。 - 値を挿入する
RichTextValue|string: 挿入する値。 - startIndex
[number]: 開始インデックス。 - endIndex
[number]: 終了インデックス。
戻り値
insertObject
指定されたstartIndexでリッチテキスト値にオブジェクトとしてフォーマットを挿入します。startIndexとendIndexの間のコンテンツは削除されます。インデックスが提供されていない場合は、選択から取得されます。
パラメータ
- 値
RichTextValue: 修正する値。 - 挿入するフォーマット
RichTextFormat: オブジェクトとして挿入するフォーマット。 - startIndex
[number]: 開始インデックス。 - endIndex
[number]: 終了インデックス。
戻り値
isCollapsed
リッチテキスト値の選択が折りたたまれているかどうかを確認します。折りたたまれているとは、文字が選択されていないが、キャレットが存在することを意味します。選択がない場合は、undefinedが返されます。これはwindow.getSelection().isCollapsed()に似ています。
パラメータ
- props
RichTextValue: 確認するリッチテキスト値。 - props.start
RichTextValue[ 'start' ]: - props.end
RichTextValue[ 'end' ]:
戻り値
isEmpty
リッチテキスト値が空であるかどうかを確認します。これは、テキストやオブジェクト（画像など）が含まれていないことを意味します。
パラメータ
- 値
RichTextValue: 使用する値。
戻り値
join
リッチテキスト値の配列を1つに結合し、オプションでseparatorで区切ります。これはArray.prototype.joinに似ています。
パラメータ
- 値
Array<RichTextValue>: 結合する値の配列。 - separator
[string|RichTextValue]: 区切り文字列または値。
戻り値
registerFormatType
ユニークな名前とその動作を定義するオブジェクトを提供して新しいフォーマットを登録します。
パラメータ
- name
string: フォーマット名。 - settings
WPFormat: フォーマット設定。
戻り値
remove
指定されたstartIndexとendIndexの間のリッチテキスト値からコンテンツを削除します。インデックスが提供されていない場合は、選択から取得されます。
パラメータ
- 値
RichTextValue: 修正する値。 - startIndex
[number]: 開始インデックス。 - endIndex
[number]: 終了インデックス。
戻り値
removeFormat
指定されたstartIndexから指定されたendIndexまでのリッチテキスト値から任意のフォーマットオブジェクトをタイプ別に削除します。インデックスが提供されていない場合は、選択から取得されます。
パラメータ
- 値
RichTextValue: 修正する値。 - formatType
string: 削除するフォーマットタイプ。 - startIndex
[number]: 開始インデックス。 - endIndex
[number]: 終了インデックス。
戻り値
replace
リッチテキスト値を検索し、マッチした部分をreplacementで置き換えます。これはString.prototype.replaceに似ています。
パラメータ
- 値
RichTextValue: 修正する値。 - pattern
RegExp|string: RegExpオブジェクトまたはリテラル。文字列でも構いません。これはそのままの文字列として扱われ、正規表現として解釈されません。最初の出現のみが置き換えられます。 - replacement
Function|string: マッチした部分は指定された値または指定された関数によって返された値で置き換えられます。
戻り値
RichTextData
RichTextDataクラスは、リッチテキスト値のラッパーをインスタンス化するために使用され、データを変換または操作するために使用できるメソッドを提供します。
- 空のインスタンスを作成する：
new RichTextData()。 - HTML文字列から作成する：
RichTextData.fromHTMLString( '<em>hello</em>' )。 - wrapper HTMLElementから作成する：
RichTextData.fromHTMLElement( document.querySelector( 'p' ) )。 - プレーンテキストから作成する：
RichTextData.fromPlainText( '1\n2' )。 - リッチテキスト値から作成する：
new RichTextData( { text: '...', formats: [ ... ] } )。
RichTextValue
フォーマットされた文字列を表すオブジェクト。詳細については、メインの@wordpress/rich-textドキュメントを参照してください。
slice
*パラメータ*- 値 `````RichTextValue`````: 修正する値。- startIndex `````[number]`````: 開始インデックス。- endIndex `````[number]`````: 終了インデックス。*戻り値*- `````RichTextValue`````: 新しく抽出された値。<a name="split"></a>### split指定された`````startIndex`````と`````endIndex`````でリッチテキスト値を2つに分割するか、指定された区切り文字で分割します。これは`````String.prototype.split`````に似ています。インデックスが提供されていない場合は、選択から取得されます。*パラメータ*- 値 `````RichTextValue`````:- 文字列 `````[number|string]`````: 開始インデックス、または分割する文字列。*戻り値*- `````Array<RichTextValue>|undefined`````: 新しい値の配列。<a name="store"></a>### storeリッチテキスト名前空間の定義を保存します。*関連*- [https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore](https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore)*タイプ*- `````Object
toggleFormat
現在の選択でリッチテキスト値にフォーマットオブジェクトをトグルします。
パラメータ
- 値
RichTextValue: 修正する値。 - フォーマット
RichTextFormat: 適用または削除するフォーマット。
戻り値
toHTMLString
リッチテキスト値からHTML文字列を作成します。
パラメータ
- $1
Object: 名前付き引数。 - $1.value
RichTextValue: リッチテキスト値。 - $1.preserveWhiteSpace
[boolean]: trueの場合は改行を保持します。
戻り値
unregisterFormatType
フォーマットを登録解除します。
パラメータ
- name
string: フォーマット名。
戻り値
useAnchor
このフックは、フォーマットタイプのEditコンポーネントで使用され、フォーマットされたアクティブ要素を返すか、フォーマットがアクティブでない場合は選択範囲の仮想要素を返します。返される値は、UIの位置決めに使用されることを意図しており、Popoverコンポーネントにanchorプロップを介して渡すことができます。
パラメータ
- $1
Object: 名前付きパラメータ。 - $1.editableContentElement
HTMLElement|null: 編集可能なコンテンツを含む要素。 - $1.settings
WPFormat=: フォーマットタイプの設定。
戻り値
useAnchorRef
このフックは、フォーマットタイプのEditコンポーネントで使用され、フォーマットされたアクティブ要素を返すか、フォーマットがアクティブでない場合は選択範囲を返します。返される値は、UIの位置決めに使用されることを意図しており、Popoverコンポーネントに渡すことができます。
パラメータ
- $1
Object: 名前付きパラメータ。 - $1.ref
RefObject<HTMLElement>: 編集可能なコンテンツを含む要素のReact ref。 - $1.value
RichTextValue: 選択を確認するための値。 - $1.settings
WPFormat: フォーマットタイプの設定。
戻り値
このパッケージへの貢献
これはGutenbergプロジェクトの一部である個別のパッケージです。このプロジェクトはモノレポとして整理されています。特定の目的を持つ複数の自己完結型ソフトウェアパッケージで構成されています。このモノレポ内のパッケージはnpmに公開され、WordPressや他のソフトウェアプロジェクトで使用されています。
このパッケージやGutenberg全体への貢献について詳しく知りたい場合は、プロジェクトのメイン貢献者ガイドをお読みください。
