CocosCreator3.8 研究ノート (20) CocosCreator UI コンポーネント (4)

リッチテキストコンポーネント

RichText コンポーネントはリッチ テキスト コントロールです。実際には複数の Label ノードから組み立てられます。さまざまなスタイル効果を持つテキストを表示するために使用されます。テキストのスタイルは BBCode タグを通じて設定されます。

現在サポートされているスタイルは、色 (color)、フォント サイズ (size)、フォント ストローク (アウトライン)、太字 (b)、斜体 (i)、下線 (u)、改行 (br)、イメージ (img)、およびクリック イベントです。 （の上）。


1. リッチテキスト属性

属性	機能の説明
弦	リッチ テキスト コンテンツ文字列。BBCode を使用して特定のテキストのスタイルを指定できます。
水平揃え	水平方向の配置
垂直方向の整列	垂直方向の配置
フォントサイズ	フォント サイズ、単位はポイント (注: このフィールドは BBCode で設定されたフォント サイズには影響しません)
フォント	リッチ テキストのカスタム フォント。すべてのラベル フラグメントはこのカスタマイズされた TTF フォントを使用します。
フォントファミリー	リッチテキストのカスタムシステムフォント
システムフォントを使用する	システムフォントを使用するかどうか
最大幅	リッチ テキストの最大幅。0 を渡すと、行を手動で折り返す必要があります。
行の高さ	フォント行の高さ、単位はポイントです
画像アトラス	img タグ内の src 属性名は、imageAtlas 内で有効な spriteFrame を見つける必要があります。そうでない場合、img タグは無効と判断されます。
ハンドルタッチイベント	このオプションがチェックされている場合、リッチテキストはノードの境界ボックス内のすべての入力イベント (マウスとタッチ) をブロックし、入力イベントが基礎となるノードに浸透するのを防ぎます。

2. BBCodeタグのフォーマット

(1)、基本フォーマット

現在サポートされているタグの種類は、size、color、b、i、u、img などで、それぞれフォント サイズ、フォントの色、太字、斜体、下線、ピクチャ、クリック イベントをカスタマイズするために使用されます。

各タグには開始タグと終了タグがあり、開始タグの名前と属性の形式は要件を満たしており、すべて小文字である必要があります。

終了タグの名前はまったくチェックされません。終了タグの定義を満たす必要があるだけです。

注: すべてのタグ名は小文字である必要があり、属性値は次のように=記号を使用して割り当てられます。

<color=green>test</color>，<size=50>test1</>

(2) BBCodeがサポートするタグ

名前	説明する	例	予防
色	フォントのレンダリング色を指定します。色の値には、白、黒などの組み込みの色を指定することも、赤などの 16 進数の色の値を使用することもできます#ff0000。	<color=#ff0000>Red Text</color>
サイズ	フォントのレンダリング サイズを指定します。サイズ値は整数である必要があります	<size=30>enlarge me</size>	サイズ値は等号を使用して割り当てる必要があります
概要	テキストのストロークの色とストロークの幅を設定します	<outline color=red width=4>A label with outline</outline>	ストロークの色または幅を指定しない場合、デフォルトの色は白 (#ffffff)、デフォルトの幅は 1 です。
b	レンダリングに太字フォントを使用するように指定します	<b>This text will be rendered as bold</b>	名前は小文字にする必要があり、太字で書くことはできません
私	レンダリングに斜体を使用するように指定します	<i>This text will be rendered as italic</i>	名前は小文字にする必要があり、斜体で書くことはできません
あなた	テキストに下線を引く	<u>This text will have a underline</u>	名前は小文字にする必要があり、下線を付けることはできません
の上	クリックイベントハンドラ関数を指定します。タグのテキストコンテンツがクリックされたときに、イベント応答関数が呼び出されます。	<on click="handler"> click me! </on>	on タグに追加できる click 属性に加えて、次のような color タグや size タグも追加できます。<size=10 click="handler2">click me</size>
パラメータ	クリック イベントがトリガーされると、コールバック関数の 2 番目のパラメーターの値を取得できます。	<on click="handler" param="test"> click me! </on>	クリックイベントに依存
br	空白行を挿入する	<br/>	注:<br></br>と は<br>サポートされていません。
画像	リッチ テキストに画像とテキストの混合機能を追加するには、img の src 属性が ImageAtlas アトラス内の有効なスプライトフレーム名である必要があります。	<img src='emoji1' click='handler' />	注：<img src='foo' click='bar' />この書き方のみが有効です。大きな画像を指定した場合、画像によって作成されたスプライトは比例的に拡大縮小され、拡大縮小値はリッチ テキストの行の高さをスプライトの高さで割った値に等しくなります。

(3) imgタグのオプション属性

img タグ タイプにはオプションの属性が用意されており、widthとheightを使用して SpriteFrame のサイズを指定し、画像を行の高さより大きくしたり小さくしたりできます (ただし、この設定によって行の高さは変更されません)。

SpriteFrame の高さまたは幅を変更した後、align行内の画像の配置を調整するために を使用する必要がある場合があります。

属性	説明する	例	予防
身長	SpriteFrame のレンダリングの高さを指定します。サイズ値は整数である必要があります。	<img src='foo' height=50 />	高さ属性のみを使用する場合、SpriteFrame は画像の比率を維持するために幅を自動的に計算します。
幅	SpriteFrame のレンダリング幅を指定します。サイズ値は整数である必要があります。	<img src='foo' width=50 />	高さと幅の両方の属性を同時に使用できます<img src='foo' width=20 height=30 />
整列する	行内の SpriteFrame の配置を指定します。値はbottom、topまたはcenter	<img src='foo' align=center />	デフォルトの配置は下です

カスタマイズされた画像レイアウトをサポートするために、offsetRichText 内の SpriteFrame の位置を微調整するためのプロパティも提供されます。

設定する場合、offset属性値は整数である必要があることに注意してください。

オフセットプロパティ	例	説明する	予防
Y	<img src='foo' offset=5 />	SpriteFrame の y 軸に 5 を加えた値を指定します	offset で 1 つの値のみを設定する場合、それは y 軸のオフセットを表します。
Y	<img src='foo' offset=-5 />	SpriteFrame の y 軸が 5 だけ削減されることを指定します	負の整数を設定すると、y 軸を縮小できます。
X、Y	<img src='foo' offset=6,-5 />	SpriteFrame の x 軸が 6 に追加され、y 軸が 5 に減らされるように指定します。	offset 属性の値には0-9、-および の,文字のみを含めることができます。

(4) ラベルのネスティング

标签与标签是支持嵌套的，且嵌套规则跟 HTML 是一样的。比如下面的嵌套标签设置一个文本的渲染大小为 30，且颜色为绿色。

<size=30><color=green>I'm green</color></size>

也可以实现为:

<color=green><size=30>I'm green</size></color>

（5）、文本缓存

对于复杂的富文本，底层可能有十几个 label 节点，drawcall 数量会比较高，引擎为富文本组件提供了 Label 组件的文本缓存类型设置，来适当减少 drawcall 的增加。

一般情况下，不应该在游戏的主循环里面频繁地修改富文本的文本内容，这可能会导致性能比较低。

如果能不使用富文本组件，就尽量使用普通的文本组件，推荐使用 BMFont，因为 BMFont的效率是最高的。

类型	功能说明
NONE	默认值，对富文本所拆分创建的每个 Label 节点，设置其 CacheMode 为 NONE 类型，即将每个 Label 的整段文本生成一张位图并单独进行渲染。
BITMAP	选择后，对富文本所拆分创建的每个 Label 节点，设置其 CacheMode 为 BITMAP 类型，即将每个 Label 的整段文本生成一张位图，并将该位图添加到动态图集中，再依据动态图集进行合并渲染。
CHAR	选择后，对富文本所拆分创建的每个 Label 节点，设置其 CacheMode 为 CHAR 类型，即将每个 Label 的文本以“字”为单位缓存到全局共享的位图中，相同字体样式和字号的每个字符将在全局共享一份缓存。

二、RichText 组件的使用

这里以添加事件为例，进行演示：

1、新建任意一个带有 RichText 组件的节点。并创建一个自定义脚本，挂载在 RichText 组件上

这里新建了一个自定义脚本TestRichText.ts。

2、将如下的代码复制到 RichText 的 String 属性内

<on click="onClicked" param="你好，这是点击事件">Click</on>

3、复制下面的代码到TestRichText.ts中：

import { _decorator, Component, EventTouch } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('TestRictText')
export class TestRictText extends Component {
    start() {

    }

    update(deltaTime: number) {
        
    }

    onClicked(eventTouch:EventTouch, param:string){
        console.log("onClicked", param);
    }

}

4、编译运行

使用鼠标点击Click文本，可以查看到控制台的输出：