@galacean/effects-plugin-rich-text 2.7.4 → 2.8.0-alpha.1

package/dist/index.mjs

@@ -3,11 +3,11 @@
  * Description: Galacean Effects player rich text plugin
  * Author: Ant Group CO., Ltd.
  * Contributors: 云垣
- * Version: v2.7.4
+ * Version: v2.8.0-alpha.1
  */
 
 import * as EFFECTS from '@galacean/effects';
-import { AbstractPlugin, effectsClass, spec, math, assertExist, Texture, glContext, TextStyle, TextLayout, TextComponent, registerPlugin, VFXItem, logger } from '@galacean/effects';
+import { AbstractPlugin, spec, effectsClass, applyMixins, TextComponentBase, TextStyle, math, assertExist, MaskableGraphic, registerPlugin, VFXItem, logger } from '@galacean/effects';
 
 function _set_prototype_of(o, p) {
     _set_prototype_of = Object.setPrototypeOf || function setPrototypeOf(o, p) {
@@ -330,6 +330,123 @@ typeof SuppressedError === "function" ? SuppressedError : function _SuppressedEr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+var RichTextLayout = /*#__PURE__*/ function() {
+    function RichTextLayout(options) {
+        this.width = 0;
+        this.height = 0;
+        var size = options.size, _options_textOverflow = options.textOverflow, textOverflow = _options_textOverflow === void 0 ? spec.TextOverflow.clip : _options_textOverflow, _options_textVerticalAlign = options.textVerticalAlign, textVerticalAlign = _options_textVerticalAlign === void 0 ? spec.TextVerticalAlign.middle : _options_textVerticalAlign, _options_textAlign = options.textAlign, textAlign = _options_textAlign === void 0 ? spec.TextAlignment.left : _options_textAlign, _options_letterSpace = options.letterSpace, letterSpace = _options_letterSpace === void 0 ? 0 : _options_letterSpace, _options_lineHeight = options.lineHeight, lineHeight = _options_lineHeight === void 0 ? 0.571 : _options_lineHeight, _options_wrapEnabled = options.wrapEnabled, wrapEnabled = _options_wrapEnabled === void 0 ? false : _options_wrapEnabled, _options_maxTextWidth = options.maxTextWidth, maxTextWidth = _options_maxTextWidth === void 0 ? 350 : _options_maxTextWidth, _options_maxTextHeight = options.maxTextHeight, maxTextHeight = _options_maxTextHeight === void 0 ? 1000 : _options_maxTextHeight, _options_sizeMode = options.sizeMode, sizeMode = _options_sizeMode === void 0 ? spec.TextSizeMode.autoWidth : _options_sizeMode, _options_useLegacyRichText = options.// @ts-expect-error 兼容旧版
+        useLegacyRichText, useLegacyRichText = _options_useLegacyRichText === void 0 ? false : _options_useLegacyRichText;
+        this.letterSpace = letterSpace;
+        this.lineHeight = lineHeight;
+        this.useLegacyRichText = useLegacyRichText;
+        this.overflow = textOverflow;
+        this.textVerticalAlign = textVerticalAlign;
+        this.textAlign = textAlign;
+        this.width = size ? size[0] : 100;
+        this.height = size ? size[1] : 100;
+        this.wrapEnabled = wrapEnabled;
+        this.maxTextWidth = maxTextWidth;
+        this.maxTextHeight = maxTextHeight;
+        this.sizeMode = sizeMode;
+    }
+    var _proto = RichTextLayout.prototype;
+    _proto.getOffsetY = function getOffsetY(style, lineCount, lineHeight, fontSize, totalLineHeight) {
+        var outlineWidth = style.outlineWidth, fontScale = style.fontScale;
+        // /3 计算Y轴偏移量，以匹配编辑器行为
+        var offsetY = (lineHeight - fontSize) / 3;
+        // 计算基础偏移量
+        var baseOffset = fontSize + outlineWidth * fontScale;
+        // 除去首行之外的总高度，用于 bottom 对齐时将第一行向上偏移
+        var commonCalculation = totalLineHeight !== undefined ? totalLineHeight : lineHeight * (lineCount - 1);
+        var offsetResult = 0;
+        switch(this.textVerticalAlign){
+            case spec.TextVerticalAlign.top:
+                offsetResult = baseOffset + offsetY;
+                break;
+            case spec.TextVerticalAlign.middle:
+                offsetResult = (this.height * fontScale - commonCalculation + baseOffset) / 2;
+                break;
+            case spec.TextVerticalAlign.bottom:
+                offsetResult = this.height * fontScale - commonCalculation - offsetY;
+                break;
+        }
+        return offsetResult;
+    };
+    _proto.getOffsetX = function getOffsetX(style, maxWidth) {
+        var offsetX = 0;
+        switch(this.textAlign){
+            case spec.TextAlignment.left:
+                offsetX = style.outlineWidth * style.fontScale;
+                break;
+            case spec.TextAlignment.middle:
+                offsetX = (this.width * style.fontScale - maxWidth) / 2;
+                break;
+            case spec.TextAlignment.right:
+                offsetX = this.width * style.fontScale - maxWidth;
+                break;
+        }
+        return offsetX;
+    };
+    /**
+   * 富文本垂直对齐计算
+   * @param style - 字体样式
+   * @param lineHeights - 每行高度数组
+   * @param fontSize - 字体大小
+   * @returns 第一行基线的Y坐标
+   */ _proto.getOffsetYRich = function getOffsetYRich(style, lineHeights, fontSize) {
+        if (lineHeights.length === 0) {
+            // 空文本时返回 0，避免计算异常；后续策略可按需要再调整
+            return 0;
+        }
+        var outlineWidth = style.outlineWidth, fontScale = style.fontScale;
+        var total = lineHeights.reduce(function(a, b) {
+            return a + b;
+        }, 0);
+        var offsetY = (lineHeights[0] - fontSize) / 3;
+        var baseOffset = fontSize + outlineWidth * fontScale;
+        var commonCalculation = total - lineHeights[0];
+        var offsetResult = 0;
+        switch(this.textVerticalAlign){
+            case spec.TextVerticalAlign.top:
+                offsetResult = baseOffset + offsetY;
+                break;
+            case spec.TextVerticalAlign.middle:
+                offsetResult = (this.height * fontScale - total) / 2 + baseOffset;
+                break;
+            case spec.TextVerticalAlign.bottom:
+                offsetResult = this.height * fontScale - commonCalculation - offsetY;
+                break;
+        }
+        return offsetResult;
+    };
+    /**
+   * 富文本横向对齐计算
+   * @param style - 字体样式
+   * @param maxWidth - 文本框最大宽度
+   * @param contentW - 文本实际宽度
+   * @returns 水平偏移量
+   */ _proto.getOffsetXRich = function getOffsetXRich(style, maxWidth, contentW) {
+        switch(this.textAlign){
+            case spec.TextAlignment.left:
+                return style.outlineWidth;
+            case spec.TextAlignment.middle:
+                return (maxWidth - contentW) / 2;
+            case spec.TextAlignment.right:
+                return maxWidth - contentW;
+            default:
+                return 0;
+        }
+    };
+    /**
+   * 设置文本框尺寸
+   * - 不包含 fontScale 缩放
+   */ _proto.setSize = function setSize(width, height) {
+        this.width = width;
+        this.height = height;
+    };
+    return RichTextLayout;
+}();
+
 /**
  * 将颜色名称转换为 RGBA
  * @param colorName - 颜色名称
@@ -402,31 +519,620 @@ typeof SuppressedError === "function" ? SuppressedError : function _SuppressedEr
     }
 }
 
+/**
+ * 富文本换行禁用策略
+ * 实现逻辑：仅基于\n换行，无自动换行
+ */ var RichWrapDisabledStrategy = /*#__PURE__*/ function() {
+    function RichWrapDisabledStrategy() {}
+    var _proto = RichWrapDisabledStrategy.prototype;
+    _proto.computeLines = function computeLines(processedOptions, context, style, layout, singleLineHeight, fontScale, letterSpace, scaleFactor) {
+        var _this = this;
+        var lines = [];
+        var baselines = [];
+        var gapPx = (layout.lineHeight || 0) * fontScale;
+        var currentLine = this.createNewLine();
+        var maxLineWidth = 0;
+        var totalHeight = 0;
+        var finishCurrentLine = function() {
+            if (currentLine.chars.length === 0) {
+                return;
+            }
+            // 第1行用真实首行高度，其余行用 gapPx
+            currentLine.lineHeight = lines.length === 0 ? (currentLine.lineAscent || 0) + (currentLine.lineDescent || 0) : gapPx;
+            // 记录本行基线
+            var baseline = lines.length === 0 ? 0 : baselines[baselines.length - 1] + gapPx;
+            baselines.push(baseline);
+            totalHeight += currentLine.lineHeight;
+            lines.push(currentLine);
+            maxLineWidth = Math.max(maxLineWidth, currentLine.width);
+            currentLine = _this.createNewLine();
+        };
+        processedOptions.forEach(function(options) {
+            var text = options.text, isNewLine = options.isNewLine, fontSize = options.fontSize;
+            if (isNewLine) {
+                // 先结束上一行
+                finishCurrentLine();
+            }
+            // 用当前片段字体（权重/家族）设置测量字体
+            var fontStyle = options.fontStyle || style.fontStyle || "normal";
+            context.font = fontStyle + " " + (options.fontWeight || style.textWeight) + " 10px " + (options.fontFamily || style.fontFamily);
+            // 记录段起始 x
+            currentLine.offsetX.push(currentLine.width);
+            // 逐字宽度和高度测量（asc/desc 测量）
+            var segmentInnerX = 0;
+            var charArr = [];
+            var lineAscent = 0;
+            var lineDescent = 0;
+            for(var i = 0; i < text.length; i++){
+                var ch = text[i];
+                var m = context.measureText(ch);
+                var w = m.width;
+                var charWidth = (w <= 0 ? 0 : w) * fontSize * scaleFactor * fontScale;
+                // 测量 asc/desc 并按目标字号缩放
+                var scale = fontSize * fontScale * scaleFactor;
+                var asc = m.actualBoundingBoxAscent * scale;
+                var desc = m.actualBoundingBoxDescent * scale;
+                lineAscent = Math.max(lineAscent, asc);
+                lineDescent = Math.max(lineDescent, desc);
+                if (i > 0) {
+                    segmentInnerX += letterSpace; // 先加"前一个字符与当前字符之间"的间距
+                }
+                charArr.push({
+                    char: ch,
+                    x: segmentInnerX
+                });
+                segmentInnerX += charWidth;
+            }
+            currentLine.chars.push(charArr);
+            currentLine.width += segmentInnerX;
+            currentLine.richOptions.push(options);
+            // 累计行级 asc/desc
+            currentLine.lineAscent = Math.max(currentLine.lineAscent || 0, lineAscent);
+            currentLine.lineDescent = Math.max(currentLine.lineDescent || 0, lineDescent);
+        });
+        // 结束最后一行
+        finishCurrentLine();
+        // 计算 bbox
+        var bboxTop = Infinity;
+        var bboxBottom = -Infinity;
+        if (lines.length === 0) {
+            return {
+                lines: lines,
+                maxLineWidth: maxLineWidth,
+                totalHeight: totalHeight,
+                bboxTop: 0,
+                bboxBottom: 0,
+                bboxHeight: 0
+            };
+        }
+        for(var i = 0; i < lines.length; i++){
+            bboxTop = Math.min(bboxTop, baselines[i] - (lines[i].lineAscent || 0));
+            bboxBottom = Math.max(bboxBottom, baselines[i] + (lines[i].lineDescent || 0));
+        }
+        var bboxHeight = bboxBottom - bboxTop;
+        return {
+            lines: lines,
+            maxLineWidth: maxLineWidth,
+            totalHeight: totalHeight,
+            bboxTop: bboxTop,
+            bboxBottom: bboxBottom,
+            bboxHeight: bboxHeight
+        };
+    };
+    /**
+   * 创建新行
+   */ _proto.createNewLine = function createNewLine() {
+        return {
+            richOptions: [],
+            offsetX: [],
+            width: 0,
+            lineHeight: 0,
+            offsetY: 0,
+            chars: [],
+            lineAscent: 0,
+            lineDescent: 0
+        };
+    };
+    return RichWrapDisabledStrategy;
+}();
+
+/**
+ * 富文本自动换行策略
+ * 实现逻辑：基于\n换行及自动换行
+ */ var RichWrapEnabledStrategy = /*#__PURE__*/ function() {
+    function RichWrapEnabledStrategy() {}
+    var _proto = RichWrapEnabledStrategy.prototype;
+    _proto.computeLines = function computeLines(processedOptions, context, style, layout, singleLineHeight, fontScale, letterSpace, scaleFactor) {
+        var _this = this;
+        var lines = [];
+        var baselines = [];
+        var gapPx = (layout.lineHeight || 0) * fontScale;
+        var currentLine = this.createNewLine();
+        var maxLineWidth = 0;
+        var totalHeight = 0;
+        // 切块缓冲变量
+        var segStartX = null;
+        var segmentInnerX = 0;
+        var chunkChars = [];
+        var chunkOptions = null; // 跟踪当前切块所属options
+        // 结束当前行（含缓冲切块）
+        var finishCurrentLine = function() {
+            flushChunk();
+            if (currentLine.chars.length === 0) {
+                return;
+            }
+            // 第1行用真实首行高度，其余行用 gapPx
+            currentLine.lineHeight = lines.length === 0 ? (currentLine.lineAscent || 0) + (currentLine.lineDescent || 0) : gapPx;
+            // 记录本行基线
+            var baseline = lines.length === 0 ? 0 : baselines[baselines.length - 1] + gapPx;
+            baselines.push(baseline);
+            totalHeight += currentLine.lineHeight;
+            lines.push(currentLine);
+            maxLineWidth = Math.max(maxLineWidth, currentLine.width);
+            currentLine = _this.createNewLine();
+            segStartX = null;
+            segmentInnerX = 0;
+            chunkChars = [];
+            chunkOptions = null;
+        };
+        // 刷新当前切块
+        var flushChunk = function() {
+            if (chunkChars.length === 0) {
+                return;
+            }
+            if (segStartX === null) {
+                segStartX = currentLine.width;
+            }
+            currentLine.offsetX.push(segStartX);
+            currentLine.chars.push(chunkChars);
+            if (chunkOptions) {
+                currentLine.richOptions.push(chunkOptions);
+            }
+            // 重置缓冲
+            segStartX = null;
+            segmentInnerX = 0;
+            chunkChars = [];
+            chunkOptions = null;
+        };
+        processedOptions.forEach(function(options) {
+            var text = options.text, isNewLine = options.isNewLine, fontSize = options.fontSize;
+            // 设置测量字体（包含fontStyle）
+            var fontStyle = options.fontStyle || style.fontStyle || "normal";
+            context.font = fontStyle + " " + (options.fontWeight || style.textWeight) + " 10px " + (options.fontFamily || style.fontFamily);
+            // 显式换行符优先处理
+            if (isNewLine) {
+                flushChunk();
+                finishCurrentLine();
+            }
+            // 逐字符处理
+            for(var i = 0; i < text.length; i++){
+                var ch = text[i];
+                // 获取基础宽度并计算实际宽度（动态缩放）
+                var m = context.measureText(ch);
+                var baseW = m.width;
+                var charWidth = (baseW <= 0 ? 0 : baseW) * fontSize * scaleFactor * fontScale;
+                // 测量 asc/desc 并按目标字号缩放
+                var scale = fontSize * fontScale * scaleFactor;
+                var asc = m.actualBoundingBoxAscent * scale;
+                var desc = m.actualBoundingBoxDescent * scale;
+                // 计算预期宽度（包含字符间距）
+                var spacing = chunkChars.length > 0 ? letterSpace : 0;
+                var willWidth = currentLine.width + spacing + charWidth;
+                // 自动换行判断
+                if (willWidth > (layout.maxTextWidth || Infinity)) {
+                    flushChunk();
+                    finishCurrentLine();
+                }
+                // 初始化切块起点和所属options
+                if (segStartX === null) {
+                    segStartX = currentLine.width;
+                    chunkOptions = options; // 绑定当前切块到options
+                }
+                // 添加字符间距（非首字符）
+                if (chunkChars.length > 0) {
+                    segmentInnerX += letterSpace;
+                    currentLine.width += letterSpace;
+                }
+                // 添加字符到切块（x为切块内相对坐标）
+                chunkChars.push({
+                    char: ch,
+                    x: segmentInnerX
+                });
+                // 累计行级 asc/desc
+                currentLine.lineAscent = Math.max(currentLine.lineAscent || 0, asc);
+                currentLine.lineDescent = Math.max(currentLine.lineDescent || 0, desc);
+                // 更新位置和宽度
+                segmentInnerX += charWidth;
+                currentLine.width += charWidth;
+            }
+            // 文本段结束，落盘当前切块
+            flushChunk();
+        });
+        // 结束最后一行
+        finishCurrentLine();
+        // 计算 bbox
+        var bboxTop = Infinity;
+        var bboxBottom = -Infinity;
+        for(var i = 0; i < lines.length; i++){
+            bboxTop = Math.min(bboxTop, baselines[i] - (lines[i].lineAscent || 0));
+            bboxBottom = Math.max(bboxBottom, baselines[i] + (lines[i].lineDescent || 0));
+        }
+        var bboxHeight = bboxBottom - bboxTop;
+        return {
+            lines: lines,
+            maxLineWidth: maxLineWidth,
+            totalHeight: totalHeight,
+            bboxTop: bboxTop,
+            bboxBottom: bboxBottom,
+            bboxHeight: bboxHeight
+        };
+    };
+    /**
+   * 创建新行
+   */ _proto.createNewLine = function createNewLine() {
+        return {
+            richOptions: [],
+            offsetX: [],
+            width: 0,
+            lineHeight: 0,
+            offsetY: 0,
+            chars: [],
+            lineAscent: 0,
+            lineDescent: 0
+        };
+    };
+    return RichWrapEnabledStrategy;
+}();
+
+/**
+ * 富文本 Display 溢出策略
+ * 在溢出策略中对所有几何量进行一次性缩放
+ */ var RichDisplayOverflowStrategy = /*#__PURE__*/ function() {
+    function RichDisplayOverflowStrategy() {}
+    var _proto = RichDisplayOverflowStrategy.prototype;
+    _proto.apply = function apply(lines, sizeResult, layout, style) {
+        // 安全处理除零情况
+        var safeDiv = function(a, b) {
+            return Math.abs(b) > 1e-5 ? a / b : 1;
+        };
+        var availableW = Math.max(1, layout.maxTextWidth || sizeResult.canvasWidth);
+        var availableH = Math.max(1, layout.maxTextHeight || sizeResult.canvasHeight);
+        var _sizeResult_contentWidth;
+        var contentW = Math.max(1, (_sizeResult_contentWidth = sizeResult.contentWidth) != null ? _sizeResult_contentWidth : sizeResult.canvasWidth);
+        var _sizeResult_bboxHeight;
+        var contentH = Math.max(1, (_sizeResult_bboxHeight = sizeResult.bboxHeight) != null ? _sizeResult_bboxHeight : sizeResult.canvasHeight);
+        // 只缩小不放大
+        var s = Math.min(1, safeDiv(availableW, contentW), safeDiv(availableH, contentH));
+        // 浮点精度处理
+        if (s > 0.9999) {
+            return {
+                globalScale: 1
+            };
+        }
+        // 统一缩放所有几何量
+        for(var _iterator = _create_for_of_iterator_helper_loose(lines), _step; !(_step = _iterator()).done;){
+            var line = _step.value;
+            line.width *= s;
+            line.lineHeight *= s; // 缩小行距（你的 gap-only 模式行高=gapPx）
+            if (line.offsetX) {
+                for(var i = 0; i < line.offsetX.length; i++){
+                    line.offsetX[i] *= s;
+                }
+            }
+            for(var _iterator1 = _create_for_of_iterator_helper_loose(line.chars || []), _step1; !(_step1 = _iterator1()).done;){
+                var seg = _step1.value;
+                for(var _iterator2 = _create_for_of_iterator_helper_loose(seg), _step2; !(_step2 = _iterator2()).done;){
+                    var ch = _step2.value;
+                    ch.x *= s;
+                }
+            }
+            for(var _iterator3 = _create_for_of_iterator_helper_loose(line.richOptions || []), _step3; !(_step3 = _iterator3()).done;){
+                var opt = _step3.value;
+                opt.fontSize *= s; // 缩小字形
+            }
+            // 同步缩放 asc/desc
+            if (line.lineAscent != null) {
+                line.lineAscent *= s;
+            }
+            if (line.lineDescent != null) {
+                line.lineDescent *= s;
+            }
+        }
+        return {
+            globalScale: s
+        };
+    };
+    return RichDisplayOverflowStrategy;
+}();
+
+/**
+ * Clip 溢出策略
+ * 超出画布部分自然裁切
+ */ var RichClippedOverflowStrategy = /*#__PURE__*/ function() {
+    function RichClippedOverflowStrategy() {}
+    var _proto = RichClippedOverflowStrategy.prototype;
+    _proto.apply = function apply(lines, sizeResult, layout, style) {
+        // 不进行任何缩放，直接返回单位缩放系数
+        return {
+            globalScale: 1
+        };
+    };
+    return RichClippedOverflowStrategy;
+}();
+
+/**
+ * Visible 溢出策略
+ * 允许内容超出画布可见
+ */ var RichVisibleOverflowStrategy = /*#__PURE__*/ function() {
+    function RichVisibleOverflowStrategy() {}
+    var _proto = RichVisibleOverflowStrategy.prototype;
+    _proto.apply = function apply(lines, sizeResult, layout, style) {
+        // 不进行任何缩放或裁剪
+        return {
+            globalScale: 1
+        };
+    };
+    return RichVisibleOverflowStrategy;
+}();
+
+/**
+ * 富文本水平对齐策略
+ * 直接使用已缩放的行宽计算偏移量
+ */ var RichHorizontalAlignStrategyImpl = /*#__PURE__*/ function() {
+    function RichHorizontalAlignStrategyImpl() {}
+    var _proto = RichHorizontalAlignStrategyImpl.prototype;
+    _proto.getHorizontalOffsets = function getHorizontalOffsets(lines, sizeResult, overflowResult, layout, style) {
+        var frameW = layout.maxTextWidth;
+        var compX = sizeResult.baselineCompensationX || 0;
+        // 统一用 frame 宽做容器
+        var baseOffsets = lines.map(function(line) {
+            return layout.getOffsetXRich(style, frameW, line.width);
+        });
+        // 仅 visible 叠加水平补偿，clip/display 不加
+        var lineOffsets = layout.overflow === spec.TextOverflow.visible ? baseOffsets.map(function(x) {
+            return x + compX;
+        }) : baseOffsets;
+        return {
+            lineOffsets: lineOffsets
+        };
+    };
+    return RichHorizontalAlignStrategyImpl;
+}();
+
+/**
+ * 富文本垂直对齐策略
+ * 直接使用已缩放的行高
+ */ var RichVerticalAlignStrategyImpl = /*#__PURE__*/ function() {
+    function RichVerticalAlignStrategyImpl() {}
+    var _proto = RichVerticalAlignStrategyImpl.prototype;
+    _proto.getVerticalOffsets = function getVerticalOffsets(lines, sizeResult, overflowResult, layout, style, singleLineHeight) {
+        var lineHeights = lines.map(function(line) {
+            return line.lineHeight;
+        });
+        var compY = sizeResult.baselineCompensationY || 0;
+        var baselineY = 0;
+        if (lines.length === 0) {
+            return {
+                baselineY: 0,
+                lineYOffsets: []
+            };
+        }
+        switch(layout.overflow){
+            case spec.TextOverflow.visible:
+                {
+                    // frame-based 计算
+                    var frameH = layout.maxTextHeight;
+                    var _sizeResult_bboxTop;
+                    var bboxTop = (_sizeResult_bboxTop = sizeResult.bboxTop) != null ? _sizeResult_bboxTop : 0;
+                    var _sizeResult_bboxHeight, _sizeResult_bboxBottom;
+                    var bboxBottom = (_sizeResult_bboxBottom = sizeResult.bboxBottom) != null ? _sizeResult_bboxBottom : bboxTop + ((_sizeResult_bboxHeight = sizeResult.bboxHeight) != null ? _sizeResult_bboxHeight : 0);
+                    var _sizeResult_bboxHeight1;
+                    var bboxHeight = (_sizeResult_bboxHeight1 = sizeResult.bboxHeight) != null ? _sizeResult_bboxHeight1 : bboxBottom - bboxTop;
+                    // 计算 frame 基线
+                    var baselineYFrame = 0;
+                    switch(layout.textVerticalAlign){
+                        case spec.TextVerticalAlign.top:
+                            baselineYFrame = -bboxTop;
+                            break;
+                        case spec.TextVerticalAlign.middle:
+                            baselineYFrame = (frameH - bboxHeight) / 2 - bboxTop;
+                            break;
+                        case spec.TextVerticalAlign.bottom:
+                            baselineYFrame = frameH - bboxHeight - bboxTop;
+                            break;
+                    }
+                    baselineY = baselineYFrame + compY; // 关键：叠加"向下移动 E"
+                    break;
+                }
+            case spec.TextOverflow.clip:
+                {
+                    var firstLine = lines[0];
+                    if (firstLine) {
+                        var _Math;
+                        var richSizes = firstLine.richOptions.map(function(o) {
+                            return o.fontSize;
+                        });
+                        var firstMax = (_Math = Math).max.apply(_Math, [].concat(richSizes.length ? richSizes : [
+                            style.fontSize
+                        ]));
+                        var fontSizeForOffset = firstMax * style.fontScale * singleLineHeight;
+                        baselineY = layout.getOffsetYRich(style, lineHeights, fontSizeForOffset) + compY;
+                    } else {
+                        baselineY = layout.getOffsetYRich(style, lineHeights, style.fontSize * style.fontScale) + compY;
+                    }
+                    break;
+                }
+            case spec.TextOverflow.display:
+                {
+                    // display 垂直对齐改为基于 bbox，而不是 getOffsetYRich
+                    var frameH1 = layout.maxTextHeight;
+                    // 用缩放后的行数据重建 baselines 和 bbox
+                    var baselines = [
+                        0
+                    ];
+                    for(var i = 1; i < lines.length; i++){
+                        baselines[i] = baselines[i - 1] + lines[i].lineHeight;
+                    }
+                    // 计算 bboxTop / bboxBottom（使用行的测量值 lineAscent/lineDescent）
+                    var bboxTop1 = Infinity;
+                    var bboxBottom1 = -Infinity;
+                    for(var i1 = 0; i1 < lines.length; i1++){
+                        var _lines_i_lineAscent;
+                        var asc = (_lines_i_lineAscent = lines[i1].lineAscent) != null ? _lines_i_lineAscent : 0;
+                        var _lines_i_lineDescent;
+                        var desc = (_lines_i_lineDescent = lines[i1].lineDescent) != null ? _lines_i_lineDescent : 0;
+                        bboxTop1 = Math.min(bboxTop1, baselines[i1] - asc);
+                        bboxBottom1 = Math.max(bboxBottom1, baselines[i1] + desc);
+                    }
+                    var bboxHeight1 = bboxBottom1 - bboxTop1;
+                    // 计算 display 模式的基线
+                    var baselineDisplayY = 0;
+                    switch(layout.textVerticalAlign){
+                        case spec.TextVerticalAlign.top:
+                            baselineDisplayY = -bboxTop1;
+                            break;
+                        case spec.TextVerticalAlign.middle:
+                            baselineDisplayY = (frameH1 - bboxHeight1) / 2 - bboxTop1;
+                            break;
+                        case spec.TextVerticalAlign.bottom:
+                            baselineDisplayY = frameH1 - bboxHeight1 - bboxTop1;
+                            break;
+                    }
+                    // 后续 lineYOffsets 保持按行高累计
+                    var lineYOffsets = [];
+                    var currentY = baselineDisplayY;
+                    for(var i2 = 0; i2 < lines.length; i2++){
+                        lineYOffsets.push(currentY);
+                        if (i2 < lines.length - 1) {
+                            currentY += lines[i2 + 1].lineHeight;
+                        }
+                    }
+                    return {
+                        baselineY: baselineDisplayY,
+                        lineYOffsets: lineYOffsets
+                    };
+                }
+        }
+        // 下面行偏移保持不变
+        var lineYOffsets1 = [];
+        var currentY1 = baselineY;
+        lines.forEach(function(line, index) {
+            lineYOffsets1.push(currentY1);
+            if (index < lines.length - 1) {
+                currentY1 += lines[index + 1].lineHeight;
+            }
+        });
+        return {
+            baselineY: baselineY,
+            lineYOffsets: lineYOffsets1
+        };
+    };
+    return RichVerticalAlignStrategyImpl;
+}();
+
+/**
+ * 富文本策略工厂
+ * 负责创建各种策略实例
+ */ var RichTextStrategyFactory = /*#__PURE__*/ function() {
+    function RichTextStrategyFactory() {}
+    /**
+   * 创建换行策略
+   * 根据wrapEnabled参数决定使用哪种策略
+   */ RichTextStrategyFactory.createWrapStrategy = function createWrapStrategy(wrapEnabled) {
+        if (wrapEnabled) {
+            return new RichWrapEnabledStrategy();
+        } else {
+            return new RichWrapDisabledStrategy();
+        }
+    };
+    /**
+   * 创建溢出策略
+   * 支持三种模式：clip（裁切）、display（行级缩放）、visible（不缩放不裁剪）
+   */ RichTextStrategyFactory.createOverflowStrategy = function createOverflowStrategy(mode) {
+        switch(mode){
+            case spec.TextOverflow.clip:
+                return new RichClippedOverflowStrategy();
+            case spec.TextOverflow.display:
+                return new RichDisplayOverflowStrategy();
+            case spec.TextOverflow.visible:
+            default:
+                return new RichVisibleOverflowStrategy();
+        }
+    };
+    /**
+   * 创建水平对齐策略
+   */ RichTextStrategyFactory.createHorizontalAlignStrategy = function createHorizontalAlignStrategy() {
+        return new RichHorizontalAlignStrategyImpl();
+    };
+    /**
+   * 创建垂直对齐策略
+   */ RichTextStrategyFactory.createVerticalAlignStrategy = function createVerticalAlignStrategy() {
+        return new RichVerticalAlignStrategyImpl();
+    };
+    return RichTextStrategyFactory;
+}();
+
 var seed = 0;
-var RichTextComponent = /*#__PURE__*/ function(TextComponent) {
-    _inherits(RichTextComponent, TextComponent);
+var RichTextComponent = /*#__PURE__*/ function(MaskableGraphic) {
+    _inherits(RichTextComponent, MaskableGraphic);
     function RichTextComponent(engine) {
         var _this;
-        _this = TextComponent.call(this, engine) || this;
+        _this = MaskableGraphic.call(this, engine) || this;
+        _this.isDirty = true;
+        _this.text = "";
         _this.processedTextOptions = [];
-        // 字体高度的倍数（字体高度上下多出来的部分就是行间距）
         _this.singleLineHeight = 1.571;
         _this.size = null;
-        /**
-   * 获取第一次渲染的 size
-   */ _this.initialized = false;
-        /**
-   * canvas 大小
-   */ _this.canvasSize = null;
+        _this.initialized = false;
+        _this.canvasSize = null;
+        _this.SCALE_FACTOR = 0.1;
+        _this.ALPHA_FIX_VALUE = 1 / 255;
         _this.name = "MRichText" + seed++;
+        _this.initTextBase(engine);
+        // 延迟初始化策略，等到textLayout被赋值后再初始化
+        _this.richWrapStrategy = RichTextStrategyFactory.createWrapStrategy();
+        _this.richOverflowStrategy = RichTextStrategyFactory.createOverflowStrategy(spec.TextOverflow.display);
+        _this.richHorizontalAlignStrategy = RichTextStrategyFactory.createHorizontalAlignStrategy();
+        _this.richVerticalAlignStrategy = RichTextStrategyFactory.createVerticalAlignStrategy();
         return _this;
     }
     var _proto = RichTextComponent.prototype;
+    _proto.onUpdate = function onUpdate(dt) {
+        MaskableGraphic.prototype.onUpdate.call(this, dt);
+        this.updateTexture();
+    };
+    _proto.onDestroy = function onDestroy() {
+        MaskableGraphic.prototype.onDestroy.call(this);
+        this.disposeTextTexture();
+    };
+    _proto.fromData = function fromData(data) {
+        MaskableGraphic.prototype.fromData.call(this, data);
+        var interaction = data.interaction, options = data.options;
+        this.interaction = interaction;
+        this.textStyle = new TextStyle(options);
+        this.textLayout = new RichTextLayout(options);
+        this.text = options.text ? options.text.toString() : " ";
+        if (this.textLayout.useLegacyRichText) {
+            this.textLayout.textVerticalAlign = spec.TextVerticalAlign.middle;
+        }
+        this.updateStrategies();
+        this.renderText(options);
+        // 设置默认颜色（math.Color）
+        this.material.setColor("_Color", new math.Color(1, 1, 1, 1));
+    };
+    /**
+   * 使用策略结果绘制文本
+   */ _proto.updateStrategies = function updateStrategies() {
+        var layout = this.textLayout;
+        if (layout) {
+            this.richWrapStrategy = RichTextStrategyFactory.createWrapStrategy(layout.wrapEnabled);
+            this.richOverflowStrategy = RichTextStrategyFactory.createOverflowStrategy(layout.overflow);
+        }
+    };
     _proto.generateTextProgram = function generateTextProgram(text) {
         var _this = this;
         this.processedTextOptions = [];
         var program = generateProgram(function(text, context) {
-            //  如果富文本仅包含换行符，则在每个换行符后添加一个空格
             if (/^\n+$/.test(text)) {
                 text = text.replace(/\n/g, "\n ");
             }
@@ -457,48 +1163,69 @@ var RichTextComponent = /*#__PURE__*/ function(TextComponent) {
         });
         program(text);
     };
-    _proto.updateTexture = function updateTexture(flipY) {
+    /**
+   * 根据配置更新文本样式和布局
+   */ _proto.updateWithOptions = function updateWithOptions(options) {
+        this.textStyle = new TextStyle(options);
+        this.textLayout = new RichTextLayout(options);
+        this.text = options.text ? options.text.toString() : " ";
+        // TextLayout 构造函数已经正确处理了 textVerticalAlign，这里不需要再设置
+        if (this.textLayout.useLegacyRichText) {
+            this.textLayout.textVerticalAlign = spec.TextVerticalAlign.middle;
+        }
+        this.updateStrategies();
+        this.isDirty = true;
+    };
+    _proto.renderText = function renderText(options) {
+        var size = options.size;
+        if (size) {
+            this.canvasSize = new math.Vector2(size[0], size[1]);
+        }
+        this.updateTexture();
+    };
+    /**
+   * 更新文本
+   * @returns
+   */ _proto.updateTexture = function updateTexture(flipY) {
         if (flipY === void 0) flipY = true;
-        if (!this.isDirty || !this.context || !this.canvas) {
+        if (!this.isDirty || !this.context || !this.canvas || !this.textStyle || !this.textLayout) {
             return;
         }
-        // 根据 useLegacyRichText 字段来判断使用哪种渲染模式
-        var useLegacy = this.textLayout.useLegacyRichText === true;
+        var layout = this.textLayout;
+        var useLegacy = layout.useLegacyRichText === true;
         this.singleLineHeight = useLegacy ? 1.571 : 1.0;
+        // 根据useLegacyRichText字段来判断使用哪种渲染模式
         if (useLegacy) {
             this.updateTextureLegacy(flipY);
         } else {
-            this.updateTextureModern(flipY);
+            this.updateTextureWithStrategies(flipY);
         }
     };
-    _proto.updateTextureLegacy = function updateTextureLegacy(flipY) {
+    /**
+   * 解析富文本
+   */ _proto.updateTextureLegacy = function updateTextureLegacy(flipY) {
         var _this = this;
-        if (!this.isDirty || !this.context || !this.canvas) {
+        if (!this.isDirty || !this.context || !this.canvas || !this.textStyle) {
             return;
         }
-        // 解析富文本
         this.generateTextProgram(this.text);
-        var _this1 = this, textLayout = _this1.textLayout, textStyle = _this1.textStyle;
-        var overflow = textLayout.overflow, _textLayout_letterSpace = textLayout.letterSpace, letterSpace = _textLayout_letterSpace === void 0 ? 0 : _textLayout_letterSpace;
+        var width = 0, height = 0;
+        var layout = this.textLayout;
+        var textStyle = this.textStyle;
+        var overflow = layout.overflow, _layout_letterSpace = layout.letterSpace, letterSpace = _layout_letterSpace === void 0 ? 0 : _layout_letterSpace;
         var context = this.context;
-        var width = 0;
-        var height = 0;
-        context.save();
         var charsInfo = [];
-        var fontHeight = textStyle.fontSize * this.textStyle.fontScale;
+        var fontHeight = textStyle.fontSize * textStyle.fontScale;
         var charInfo = {
             richOptions: [],
             offsetX: [],
             width: 0,
-            // 包括字体和上下行间距的高度
             lineHeight: fontHeight * this.singleLineHeight,
-            // 字体偏移高度（也就是行间距）
             offsetY: fontHeight * (this.singleLineHeight - 1) / 2
         };
         // 遍历解析后的文本选项
         this.processedTextOptions.forEach(function(options) {
             var text = options.text, isNewLine = options.isNewLine, fontSize = options.fontSize;
-            // 如果是新行，则将之前行的信息存入 charsInfo 并且初始化新行的 charInfo
             if (isNewLine) {
                 charsInfo.push(charInfo);
                 width = Math.max(width, charInfo.width);
@@ -509,12 +1236,9 @@ var RichTextComponent = /*#__PURE__*/ function(TextComponent) {
                     lineHeight: fontHeight * _this.singleLineHeight,
                     offsetY: fontHeight * (_this.singleLineHeight - 1) / 2
                 };
-                // 管理行的总高度调整 canvas 尺寸
                 height += charInfo.lineHeight;
             }
-            // 恢复默认设置
             context.font = (options.fontWeight || textStyle.textWeight) + " 10px " + (options.fontFamily || textStyle.fontFamily);
-            // 计算得到每个字段的宽度 textWidth
             var textMetrics = context.measureText(text);
             var textWidth = textMetrics.width;
             if (textMetrics.actualBoundingBoxLeft !== undefined && textMetrics.actualBoundingBoxRight !== undefined) {
@@ -523,32 +1247,28 @@ var RichTextComponent = /*#__PURE__*/ function(TextComponent) {
                     textWidth = Math.max(textWidth, actualWidth);
                 }
             }
-            var textHeight = fontSize * _this.singleLineHeight * _this.textStyle.fontScale;
+            var textHeight = fontSize * _this.singleLineHeight * textStyle.fontScale;
             if (textHeight > charInfo.lineHeight) {
                 height += textHeight - charInfo.lineHeight;
                 charInfo.lineHeight = textHeight;
-                charInfo.offsetY = fontSize * _this.textStyle.fontScale * (_this.singleLineHeight - 1) / 2;
+                charInfo.offsetY = fontSize * textStyle.fontScale * (_this.singleLineHeight - 1) / 2;
             }
             charInfo.offsetX.push(charInfo.width);
-            // 计算字段宽度*富文本字体大小*缩放因子*整体文本大小+每个字符的间距（每个字符间距存疑，因为实际测量的宽度已经包含了间距）
-            charInfo.width += (textWidth <= 0 ? 0 : textWidth) * fontSize * _this.SCALE_FACTOR * _this.textStyle.fontScale + text.length * letterSpace;
-            // 将富文本数据存入 charInfo
+            charInfo.width += (textWidth <= 0 ? 0 : textWidth) * fontSize * _this.SCALE_FACTOR * textStyle.fontScale + text.length * letterSpace;
             charInfo.richOptions.push(options);
         });
-        // 存储最后一行的字符信息，并且更新最终的宽度和高度用于确定 canvas 尺寸
         charsInfo.push(charInfo);
         width = Math.max(width, charInfo.width);
         height += charInfo.lineHeight;
+        // 存储最后一行的字符信息，并且更新最终的宽度和高度用于确定canvas尺寸
         if (width === 0 || height === 0) {
             this.isDirty = false;
-            context.restore();
             return;
         }
         if (this.size === undefined || this.size === null) {
             this.size = this.item.transform.size.clone();
         }
         var _this_size = this.size, _this_size_x = _this_size.x, x = _this_size_x === void 0 ? 1 : _this_size_x, _this_size_y = _this_size.y, y = _this_size_y === void 0 ? 1 : _this_size_y;
-        // 首次渲染时初始化 canvas 尺寸和组件变换
         if (!this.initialized) {
             this.canvasSize = !this.canvasSize ? new math.Vector2(width, height) : this.canvasSize;
             var _this_canvasSize = this.canvasSize, canvasWidth = _this_canvasSize.x, canvasHeight = _this_canvasSize.y;
@@ -558,318 +1278,333 @@ var RichTextComponent = /*#__PURE__*/ function(TextComponent) {
         }
         assertExist(this.canvasSize);
         var _this_canvasSize1 = this.canvasSize, canvasWidth1 = _this_canvasSize1.x, canvasHeight1 = _this_canvasSize1.y;
-        this.textLayout.width = canvasWidth1 / textStyle.fontScale;
-        this.textLayout.height = canvasHeight1 / textStyle.fontScale;
-        this.canvas.width = canvasWidth1;
-        this.canvas.height = canvasHeight1;
-        context.clearRect(0, 0, canvasWidth1, canvasHeight1);
-        // fix bug 1/255
-        context.fillStyle = "rgba(255, 255, 255, " + this.ALPHA_FIX_VALUE + ")";
-        if (!flipY) {
-            context.translate(0, canvasHeight1);
-            context.scale(1, -1);
-        }
-        if (charsInfo.length === 0) {
-            context.restore();
-            return;
-        }
-        var charsLineHeight = textLayout.getOffsetY(textStyle, charsInfo.length, fontHeight * this.singleLineHeight, textStyle.fontSize);
-        charsInfo.forEach(function(charInfo, index) {
-            var richOptions = charInfo.richOptions, offsetX = charInfo.offsetX, width = charInfo.width;
-            var charWidth = width;
-            var offset = offsetX;
-            if (overflow === spec.TextOverflow.display) {
-                if (width > canvasWidth1) {
-                    var canvasScale = canvasWidth1 / width;
-                    charWidth *= canvasScale;
-                    offset = offsetX.map(function(x) {
-                        return x * canvasScale;
-                    });
-                }
-            }
-            var x = _this.textLayout.getOffsetX(textStyle, charWidth);
-            if (index > 0) {
-                charsLineHeight += charInfo.lineHeight - charInfo.offsetY;
+        layout.width = canvasWidth1 / textStyle.fontScale;
+        layout.height = canvasHeight1 / textStyle.fontScale;
+        this.renderToTexture(canvasWidth1, canvasHeight1, flipY, function(context) {
+            if (charsInfo.length === 0) {
+                return;
             }
-            richOptions.forEach(function(options, index) {
-                var fontScale = textStyle.fontScale, textColor = textStyle.textColor, textFamily = textStyle.fontFamily, textWeight = textStyle.textWeight, richStyle = textStyle.fontStyle;
-                var text = options.text, fontSize = options.fontSize, _options_fontColor = options.fontColor, fontColor = _options_fontColor === void 0 ? textColor : _options_fontColor, _options_fontFamily = options.fontFamily, fontFamily = _options_fontFamily === void 0 ? textFamily : _options_fontFamily, _options_fontWeight = options.fontWeight, fontWeight = _options_fontWeight === void 0 ? textWeight : _options_fontWeight, _options_fontStyle = options.fontStyle, fontStyle = _options_fontStyle === void 0 ? richStyle : _options_fontStyle;
-                var textSize = fontSize;
+            var charsLineHeight = layout.getOffsetY(textStyle, charsInfo.length, fontHeight * _this.singleLineHeight, textStyle.fontSize);
+            charsInfo.forEach(function(charInfo, index) {
+                var richOptions = charInfo.richOptions, offsetX = charInfo.offsetX, width = charInfo.width;
+                var charWidth = width;
+                var offset = offsetX;
                 if (overflow === spec.TextOverflow.display) {
                     if (width > canvasWidth1) {
-                        textSize /= width / canvasWidth1;
+                        var canvasScale = canvasWidth1 / width;
+                        charWidth *= canvasScale;
+                        offset = offsetX.map(function(x) {
+                            return x * canvasScale;
+                        });
                     }
                 }
-                var strOffsetX = offset[index] + x;
-                context.font = fontStyle + " " + fontWeight + " " + textSize * fontScale + "px " + fontFamily;
-                context.fillStyle = "rgba(" + fontColor[0] + ", " + fontColor[1] + ", " + fontColor[2] + ", " + fontColor[3] + ")";
-                context.fillText(text, strOffsetX, charsLineHeight);
+                var x = layout.getOffsetX(textStyle, charWidth);
+                if (index > 0) {
+                    charsLineHeight += charInfo.lineHeight - charInfo.offsetY;
+                }
+                richOptions.forEach(function(options, index) {
+                    var fontScale = textStyle.fontScale, textColor = textStyle.textColor, textFamily = textStyle.fontFamily, textWeight = textStyle.textWeight, richStyle = textStyle.fontStyle;
+                    var text = options.text, fontSize = options.fontSize, _options_fontColor = options.fontColor, fontColor = _options_fontColor === void 0 ? textColor : _options_fontColor, _options_fontFamily = options.fontFamily, fontFamily = _options_fontFamily === void 0 ? textFamily : _options_fontFamily, _options_fontWeight = options.fontWeight, fontWeight = _options_fontWeight === void 0 ? textWeight : _options_fontWeight, _options_fontStyle = options.fontStyle, fontStyle = _options_fontStyle === void 0 ? richStyle : _options_fontStyle;
+                    var textSize = fontSize;
+                    if (overflow === spec.TextOverflow.display) {
+                        if (width > canvasWidth1) {
+                            textSize /= width / canvasWidth1;
+                        }
+                    }
+                    var strOffsetX = offset[index] + x;
+                    // fix bug 1/255
+                    context.font = fontStyle + " " + fontWeight + " " + textSize * fontScale + "px " + fontFamily;
+                    var r = fontColor[0], g = fontColor[1], b = fontColor[2], a = fontColor[3];
+                    context.fillStyle = "rgba(" + r + ", " + g + ", " + b + ", " + a + ")";
+                    context.fillText(text, strOffsetX, charsLineHeight);
+                });
             });
-        });
-        // 与 toDataURL() 两种方式都需要像素读取操作
-        var imageData = context.getImageData(0, 0, this.canvas.width, this.canvas.height);
-        var texture = Texture.createWithData(this.engine, {
-            data: new Uint8Array(imageData.data),
-            width: imageData.width,
-            height: imageData.height
         }, {
-            flipY: flipY,
-            magFilter: glContext.LINEAR,
-            minFilter: glContext.LINEAR,
-            wrapS: glContext.CLAMP_TO_EDGE,
-            wrapT: glContext.CLAMP_TO_EDGE
+            disposeOld: false
         });
-        this.disposeTextTexture();
-        this.renderer.texture = texture;
-        this.material.setTexture("_MainTex", texture);
+        // 与 toDataURL() 两种方式都需要像素读取操作
         this.isDirty = false;
-        context.restore();
     };
-    _proto.updateTextureModern = function updateTextureModern(flipY) {
+    /**
+   * 使用策略管线路径的渲染方法
+   */ _proto.updateTextureWithStrategies = function updateTextureWithStrategies(flipY) {
         var _this = this;
-        var _Math;
-        var _firstLine_richOptions;
+        if (!this.isDirty || !this.context || !this.canvas) {
+            return;
+        }
         // 解析富文本
         this.generateTextProgram(this.text);
-        var _this1 = this, textLayout = _this1.textLayout, textStyle = _this1.textStyle;
-        var overflow = textLayout.overflow, _textLayout_letterSpace = textLayout.letterSpace, letterSpace = _textLayout_letterSpace === void 0 ? 0 : _textLayout_letterSpace;
+        var layout = this.textLayout;
+        var _layout_letterSpace = layout.letterSpace, letterSpace = _layout_letterSpace === void 0 ? 0 : _layout_letterSpace;
         var context = this.context;
-        var width = 0;
-        var height = 0;
         if (!context) {
             return;
         }
-        context.save();
-        var charsInfo = [];
-        var fontHeight = textStyle.fontSize * this.textStyle.fontScale;
-        var charInfo = {
-            richOptions: [],
-            offsetX: [],
-            width: 0,
-            // 包括字体和上下行间距的高度
-            lineHeight: fontHeight * this.singleLineHeight + (this.textLayout.lineGap || 0) * this.textStyle.fontScale,
-            // 字体偏移高度（也就是行间距）
-            offsetY: (this.textLayout.lineGap || 0) * this.textStyle.fontScale / 2,
-            chars: []
-        };
-        // 遍历解析后的文本选项
-        this.processedTextOptions.forEach(function(options) {
-            var text = options.text, isNewLine = options.isNewLine, fontSize = options.fontSize;
-            // 如果是新行，则结束上一行并开始新行
-            if (isNewLine) {
-                // 结束上一行：累加行高并重置charInfo
-                height += charInfo.lineHeight;
-                charsInfo.push(charInfo);
-                width = Math.max(width, charInfo.width);
-                // 初始化新行
-                charInfo = {
-                    richOptions: [],
-                    offsetX: [],
-                    width: 0,
-                    lineHeight: fontHeight * _this.singleLineHeight + (_this.textLayout.lineGap || 0) * _this.textStyle.fontScale,
-                    offsetY: (_this.textLayout.lineGap || 0) * _this.textStyle.fontScale / 2,
-                    chars: []
-                };
-            }
-            // 恢复默认设置
-            context.font = (options.fontWeight || textStyle.textWeight) + " 10px " + (options.fontFamily || textStyle.fontFamily);
-            var textHeight = fontSize * _this.singleLineHeight * _this.textStyle.fontScale + (_this.textLayout.lineGap || 0) * _this.textStyle.fontScale;
-            // 更新当前行的最大行高
-            if (textHeight > charInfo.lineHeight) {
-                charInfo.lineHeight = textHeight;
-                charInfo.offsetY = (_this.textLayout.lineGap || 0) * _this.textStyle.fontScale / 2;
-            }
-            charInfo.offsetX.push(charInfo.width);
-            // 逐字计算宽度以实现字符间距
-            var segmentInnerX = 0;
-            var charArr = [];
-            for(var i = 0; i < text.length; i++){
-                var char = text[i];
-                var tempcharWidth = context.measureText(char).width;
-                var charWidth = (tempcharWidth <= 0 ? 0 : tempcharWidth) * fontSize * _this.SCALE_FACTOR * _this.textStyle.fontScale;
-                charArr.push({
-                    char: char,
-                    x: segmentInnerX,
-                    width: charWidth
-                });
-                segmentInnerX += charWidth + letterSpace;
-            }
-            charInfo.chars.push(charArr);
-            charInfo.width += segmentInnerX;
-            charInfo.richOptions.push(options);
-        });
-        // 结束最后一行
-        height += charInfo.lineHeight;
-        charsInfo.push(charInfo);
-        width = Math.max(width, charInfo.width);
-        if (width === 0 || height === 0) {
+        // 步骤1: 换行策略计算行信息
+        var wrapResult = this.richWrapStrategy.computeLines(this.processedTextOptions, context, this.textStyle, layout, this.singleLineHeight, this.textStyle.fontScale, letterSpace, this.SCALE_FACTOR);
+        if (wrapResult.lines.length === 0 || wrapResult.maxLineWidth === 0 || wrapResult.totalHeight === 0) {
             this.isDirty = false;
-            context.restore();
             return;
         }
+        // 步骤2: 尺寸处理
+        var sizeResult = this.resolveCanvasSize(wrapResult, layout, this.textStyle, this.singleLineHeight);
+        // 首次渲染时初始化 canvas 尺寸和组件变换
+        this.setCanvasSize(sizeResult);
+        // 步骤3: 溢出策略处理
+        var overflowResult = this.richOverflowStrategy.apply(wrapResult.lines, sizeResult, layout, this.textStyle);
+        // 步骤4: 水平对齐策略
+        var horizontalAlignResult = this.richHorizontalAlignStrategy.getHorizontalOffsets(wrapResult.lines, sizeResult, overflowResult, layout, this.textStyle);
+        // 步骤5: 垂直对齐策略
+        var TextVerticalAlignResult = this.richVerticalAlignStrategy.getVerticalOffsets(wrapResult.lines, sizeResult, overflowResult, layout, this.textStyle, this.singleLineHeight);
+        // 使用 this.canvasSize 统一设置画布尺寸
+        assertExist(this.canvasSize);
+        var _this_canvasSize = this.canvasSize, canvasWidth = _this_canvasSize.x, canvasHeight = _this_canvasSize.y;
+        layout.width = canvasWidth / this.textStyle.fontScale;
+        layout.height = canvasHeight / this.textStyle.fontScale;
+        this.renderToTexture(canvasWidth, canvasHeight, flipY, function(context) {
+            // 步骤6: 绘制文本
+            _this.drawTextWithStrategies(context, wrapResult.lines, horizontalAlignResult, TextVerticalAlignResult, overflowResult, _this.textStyle);
+        }, {
+            disposeOld: false
+        });
+        this.isDirty = false;
+    };
+    _proto.setCanvasSize = function setCanvasSize(sizeResult) {
+        var _this = this;
         if (this.size === undefined || this.size === null) {
             this.size = this.item.transform.size.clone();
         }
         var _this_size = this.size, _this_size_x = _this_size.x, x = _this_size_x === void 0 ? 1 : _this_size_x, _this_size_y = _this_size.y, y = _this_size_y === void 0 ? 1 : _this_size_y;
-        // 首次渲染时初始化 canvas 尺寸和组件变换
-        if (!this.initialized) {
-            this.canvasSize = !this.canvasSize ? new math.Vector2(width, height) : this.canvasSize;
-            var _this_canvasSize = this.canvasSize, canvasWidth = _this_canvasSize.x, canvasHeight = _this_canvasSize.y;
-            this.item.transform.size.set(x * canvasWidth * this.SCALE_FACTOR * this.SCALE_FACTOR, y * canvasHeight * this.SCALE_FACTOR * this.SCALE_FACTOR);
-            this.size = this.item.transform.size.clone();
-            this.initialized = true;
-        }
-        assertExist(this.canvasSize);
-        var _this_canvasSize1 = this.canvasSize, canvasWidth1 = _this_canvasSize1.x, canvasHeight1 = _this_canvasSize1.y;
-        this.textLayout.width = canvasWidth1 / textStyle.fontScale;
-        this.textLayout.height = canvasHeight1 / textStyle.fontScale;
-        this.canvas.width = canvasWidth1;
-        this.canvas.height = canvasHeight1;
-        context.clearRect(0, 0, canvasWidth1, canvasHeight1);
-        // fix bug 1/255
-        context.fillStyle = "rgba(255, 255, 255, " + this.ALPHA_FIX_VALUE + ")";
-        if (!flipY) {
-            context.translate(0, canvasHeight1);
-            context.scale(1, -1);
-        }
-        if (charsInfo.length === 0) {
-            context.restore();
-            return;
-        }
-        // 行高数组
-        var lineHeights = charsInfo.map(function(l) {
-            return l.lineHeight;
-        });
-        // 计算第一行基线Y坐标
-        var firstLine = charsInfo[0];
-        var _firstLine_richOptions_map;
-        var firstLineMaxFontSize = (_Math = Math).max.apply(_Math, [].concat((_firstLine_richOptions_map = firstLine == null ? void 0 : (_firstLine_richOptions = firstLine.richOptions) == null ? void 0 : _firstLine_richOptions.map(function(opt) {
-            return opt.fontSize;
-        })) != null ? _firstLine_richOptions_map : [
-            this.textStyle.fontSize
-        ]));
-        var fontSizeForOffset = firstLineMaxFontSize * this.textStyle.fontScale * this.singleLineHeight;
-        var baselineY = textLayout.getOffsetYRich(this.textStyle, lineHeights, fontSizeForOffset);
-        // 逐行绘制
-        charsInfo.forEach(function(charInfo, index) {
-            var richOptions = charInfo.richOptions, offsetX = charInfo.offsetX, width = charInfo.width, chars = charInfo.chars;
-            var charsArr = chars;
-            var charWidth = width;
-            var offset = offsetX;
-            if (overflow === spec.TextOverflow.display) {
-                if (width > canvasWidth1) {
-                    var canvasScale = canvasWidth1 / width;
-                    charWidth *= canvasScale;
-                    offset = offsetX.map(function(x) {
-                        return x * canvasScale;
-                    });
-                    charsArr.forEach(function(charArr) {
-                        charArr.forEach(function(charDetail) {
-                            charDetail.x *= canvasScale;
-                            charDetail.width *= canvasScale;
-                        });
+        var layout = this.textLayout;
+        switch(layout.overflow){
+            case spec.TextOverflow.visible:
+                {
+                    var _Math;
+                    var frameW = layout.maxTextWidth;
+                    var frameH = layout.maxTextHeight;
+                    var _sizeResult_bboxTop;
+                    var bboxTop = (_sizeResult_bboxTop = sizeResult.bboxTop) != null ? _sizeResult_bboxTop : 0;
+                    var _sizeResult_bboxHeight, _sizeResult_bboxBottom;
+                    var bboxBottom = (_sizeResult_bboxBottom = sizeResult.bboxBottom) != null ? _sizeResult_bboxBottom : bboxTop + ((_sizeResult_bboxHeight = sizeResult.bboxHeight) != null ? _sizeResult_bboxHeight : 0);
+                    var _sizeResult_bboxHeight1;
+                    var bboxHeight = (_sizeResult_bboxHeight1 = sizeResult.bboxHeight) != null ? _sizeResult_bboxHeight1 : bboxBottom - bboxTop;
+                    // 计算 frame 基线
+                    var baselineYFrame = 0;
+                    switch(layout.textVerticalAlign){
+                        case spec.TextVerticalAlign.top:
+                            baselineYFrame = -bboxTop;
+                            break;
+                        case spec.TextVerticalAlign.middle:
+                            baselineYFrame = (frameH - bboxHeight) / 2 - bboxTop;
+                            break;
+                        case spec.TextVerticalAlign.bottom:
+                            baselineYFrame = frameH - bboxHeight - bboxTop;
+                            break;
+                    }
+                    // 上下溢出检测
+                    var contentTopInFrame = baselineYFrame + bboxTop;
+                    var contentBottomInFrame = baselineYFrame + bboxBottom;
+                    var overflowTop = Math.max(0, -contentTopInFrame);
+                    var overflowBottom = Math.max(0, contentBottomInFrame - frameH);
+                    // 垂直扩张
+                    var expandTop = overflowTop;
+                    var expandBottom = overflowBottom;
+                    switch(layout.textVerticalAlign){
+                        case spec.TextVerticalAlign.top:
+                            {
+                                var E = overflowBottom;
+                                expandTop = E;
+                                expandBottom = E;
+                                break;
+                            }
+                        case spec.TextVerticalAlign.bottom:
+                            {
+                                var E1 = overflowTop;
+                                expandTop = E1;
+                                expandBottom = E1;
+                                break;
+                            }
+                        case spec.TextVerticalAlign.middle:
+                            {
+                                // 保持非对称：上扩 overflowTop，下扩 overflowBottom
+                                expandTop = overflowTop;
+                                expandBottom = overflowBottom;
+                                break;
+                            }
+                    }
+                    // 位移补偿：始终使用 expandTop
+                    var compY = expandTop;
+                    // 水平扩张
+                    var lines = sizeResult.lines || [];
+                    var xOffsetsFrame = lines.map(function(line) {
+                        return layout.getOffsetXRich(_this.textStyle, frameW, line.width);
                     });
+                    var leftMost = xOffsetsFrame.length > 0 ? (_Math = Math).min.apply(_Math, [].concat(xOffsetsFrame)) : 0;
+                    var ex = Math.max(0, -leftMost);
+                    var expandLeft = ex;
+                    var expandRight = ex;
+                    var finalW = frameW + expandLeft + expandRight;
+                    var finalH = frameH + expandTop + expandBottom;
+                    // 记录补偿，供垂直对齐策略叠加
+                    sizeResult.baselineCompensationX = expandLeft;
+                    sizeResult.baselineCompensationY = compY;
+                    sizeResult.canvasWidth = finalW;
+                    sizeResult.canvasHeight = finalH;
+                    this.canvasSize = new math.Vector2(finalW, finalH);
+                    var _this_size1;
+                    var _ref = (_this_size1 = this.size) != null ? _this_size1 : this.item.transform.size, _ref_x = _ref.x, x1 = _ref_x === void 0 ? 1 : _ref_x, _ref_y = _ref.y, y1 = _ref_y === void 0 ? 1 : _ref_y;
+                    this.item.transform.size.set(x1 * finalW * this.SCALE_FACTOR * this.SCALE_FACTOR, y1 * finalH * this.SCALE_FACTOR * this.SCALE_FACTOR);
+                    this.size = this.item.transform.size.clone();
+                    this.initialized = true;
+                    break;
                 }
-            }
-            var x = _this.textLayout.getOffsetX(textStyle, charWidth);
+            case spec.TextOverflow.clip:
+                {
+                    var frameW1 = layout.maxTextWidth;
+                    var frameH1 = layout.maxTextHeight;
+                    // 直接使用 frame 尺寸作为画布尺寸
+                    sizeResult.canvasWidth = frameW1;
+                    sizeResult.canvasHeight = frameH1;
+                    // clip 模式不需要任何补偿
+                    sizeResult.baselineCompensationX = 0;
+                    sizeResult.baselineCompensationY = 0;
+                    // 设置 canvas 和节点变换
+                    this.canvasSize = new math.Vector2(frameW1, frameH1);
+                    // 把 layout 的尺寸更新为 frame 尺寸
+                    layout.width = frameW1 / this.textStyle.fontScale;
+                    layout.height = frameH1 / this.textStyle.fontScale;
+                    var _this_size2;
+                    var _ref1 = (_this_size2 = this.size) != null ? _this_size2 : this.item.transform.size, _ref_x1 = _ref1.x, x2 = _ref_x1 === void 0 ? 1 : _ref_x1, _ref_y1 = _ref1.y, y2 = _ref_y1 === void 0 ? 1 : _ref_y1;
+                    this.item.transform.size.set(x2 * frameW1 * this.SCALE_FACTOR * this.SCALE_FACTOR, y2 * frameH1 * this.SCALE_FACTOR * this.SCALE_FACTOR);
+                    this.size = this.item.transform.size.clone();
+                    this.initialized = true;
+                    break;
+                }
+            case spec.TextOverflow.display:
+                {
+                    if (!this.initialized) {
+                        this.canvasSize = new math.Vector2(layout.maxTextWidth, layout.maxTextHeight);
+                        this.item.transform.size.set(x * this.canvasSize.x * this.SCALE_FACTOR * this.SCALE_FACTOR, y * this.canvasSize.y * this.SCALE_FACTOR * this.SCALE_FACTOR);
+                        this.size = this.item.transform.size.clone();
+                        this.initialized = true;
+                    }
+                    break;
+                }
+        }
+    };
+    /**
+   * 尺寸处理
+   */ _proto.resolveCanvasSize = function resolveCanvasSize(wrapResult, layout, style, singleLineHeight) {
+        var canvasWidth = Math.max(1, wrapResult.maxLineWidth || 0);
+        var canvasHeight = Math.max(1, wrapResult.totalHeight || 0); // stepTotalHeight
+        layout.width = canvasWidth / style.fontScale;
+        layout.height = canvasHeight / style.fontScale;
+        return {
+            canvasWidth: canvasWidth,
+            canvasHeight: canvasHeight,
+            contentWidth: wrapResult.maxLineWidth,
+            bboxTop: wrapResult.bboxTop,
+            bboxBottom: wrapResult.bboxBottom,
+            bboxHeight: wrapResult.bboxHeight,
+            // 为 visible 模式的画布尺寸计算保留行信息
+            lines: wrapResult.lines
+        };
+    };
+    /**
+   * 使用策略结果绘制文本
+   */ _proto.drawTextWithStrategies = function drawTextWithStrategies(context, lines, horizontalAlignResult, TextVerticalAlignResult, overflowResult, textStyle) {
+        var currentBaselineY = TextVerticalAlignResult.baselineY;
+        var lineOffsets = horizontalAlignResult.lineOffsets;
+        lines.forEach(function(line, index) {
+            var richOptions = line.richOptions, chars = line.chars;
+            var xOffset = lineOffsets[index];
+            var yOffset = currentBaselineY;
             richOptions.forEach(function(options, segIndex) {
                 var fontScale = textStyle.fontScale, textColor = textStyle.textColor, textFamily = textStyle.fontFamily, textWeight = textStyle.textWeight, richStyle = textStyle.fontStyle;
                 var fontSize = options.fontSize, _options_fontColor = options.fontColor, fontColor = _options_fontColor === void 0 ? textColor : _options_fontColor, _options_fontFamily = options.fontFamily, fontFamily = _options_fontFamily === void 0 ? textFamily : _options_fontFamily, _options_fontWeight = options.fontWeight, fontWeight = _options_fontWeight === void 0 ? textWeight : _options_fontWeight, _options_fontStyle = options.fontStyle, fontStyle = _options_fontStyle === void 0 ? richStyle : _options_fontStyle;
+                // 直接使用原始字体大小（已在行数据中预缩放）
                 var textSize = fontSize;
-                if (overflow === spec.TextOverflow.display && width > canvasWidth1) {
-                    textSize /= width / canvasWidth1;
-                }
-                var strOffsetX = offset[segIndex] + x;
                 context.font = fontStyle + " " + fontWeight + " " + textSize * fontScale + "px " + fontFamily;
-                context.fillStyle = "rgba(" + fontColor[0] + ", " + fontColor[1] + ", " + fontColor[2] + ", " + fontColor[3] + ")";
+                var r = fontColor[0], g = fontColor[1], b = fontColor[2], a = fontColor[3];
+                context.fillStyle = "rgba(" + r + ", " + g + ", " + b + ", " + a + ")";
                 // 逐字绘制
-                var charArr = charInfo.chars[segIndex];
+                var segStartX = line.offsetX && line.offsetX[segIndex] ? line.offsetX[segIndex] : 0;
+                var charArr = chars[segIndex];
                 charArr.forEach(function(charDetail) {
-                    context.fillText(charDetail.char, strOffsetX + charDetail.x, baselineY);
+                    // 直接使用缩放后的字符位置
+                    context.fillText(charDetail.char, xOffset + segStartX + charDetail.x, yOffset);
                 });
             });
             // 推进到下一行
-            if (index < charsInfo.length - 1) {
-                baselineY += lineHeights[index + 1];
+            if (index < lines.length - 1) {
+                currentBaselineY += lines[index + 1].lineHeight;
             }
         });
-        var imageData = context.getImageData(0, 0, this.canvas.width, this.canvas.height);
-        var texture = Texture.createWithData(this.engine, {
-            data: new Uint8Array(imageData.data),
-            width: imageData.width,
-            height: imageData.height
-        }, {
-            flipY: flipY,
-            magFilter: glContext.LINEAR,
-            minFilter: glContext.LINEAR,
-            wrapS: glContext.CLAMP_TO_EDGE,
-            wrapT: glContext.CLAMP_TO_EDGE
-        });
-        this.renderer.texture = texture;
-        this.material.setTexture("_MainTex", texture);
-        this.isDirty = false;
-        context.restore();
+    };
+    _proto.unsupported = function unsupported(name) {
+        throw new Error("RichTextComponent does not support " + name + " at runtime.");
     };
     /**
    * 该方法富文本组件不支持
    * @param value - 水平偏移距离
    * @returns
    */ _proto.setShadowOffsetY = function setShadowOffsetY(value) {
-        throw new Error("Method not implemented.");
+        this.unsupported("setShadowOffsetY");
     };
     /**
    * 该方法富文本组件不支持
    * @param value - 模糊程度
    */ _proto.setShadowBlur = function setShadowBlur(value) {
-        throw new Error("Method not implemented.");
+        this.unsupported("setShadowBlur");
     };
     /**
    * 该方法富文本组件不支持
    * @param value - 水平偏移距离
    */ _proto.setShadowOffsetX = function setShadowOffsetX(value) {
-        throw new Error("Method not implemented.");
+        this.unsupported("setShadowOffsetX");
     };
     /**
    * 该方法富文本组件不支持
    * @param value - 阴影颜色
    */ _proto.setShadowColor = function setShadowColor(value) {
-        throw new Error("Method not implemented.");
+        this.unsupported("setShadowColor");
     };
     /**
    * 该方法富文本组件不支持
    * @param value - 外描边宽度
    * @returns
    */ _proto.setOutlineWidth = function setOutlineWidth(value) {
-        throw new Error("Method not implemented.");
+        this.unsupported("setOutlineWidth");
     };
     /**
    * 该方法富文本组件不支持
    * @param value - 是否自动设置宽度
    */ _proto.setAutoWidth = function setAutoWidth(value) {
-        throw new Error("Method not implemented.");
+        this.unsupported("setAutoWidth");
     };
-    _proto.updateWithOptions = function updateWithOptions(options) {
-        this.textStyle = new TextStyle(options);
-        this.textLayout = new TextLayout(options);
-        this.textLayout.textBaseline = options.textBaseline || spec.TextBaseline.middle;
-        this.text = options.text ? options.text.toString() : " ";
+    /**
+   * 该方法富文本组件不支持
+   */ _proto.setFontSize = function setFontSize(value) {
+        this.unsupported("setFontSize");
     };
-    _proto.renderText = function renderText(options) {
-        var size = options.size;
-        if (size) {
-            this.canvasSize = new math.Vector2(size[0], size[1]);
-        }
-        this.updateTexture();
+    /**
+   * @deprecated 2.8.0 本方法已废弃，请使用 setTextVerticalAlign 替代。
+   */ _proto.setTextBaseline = function setTextBaseline(value) {
+        console.warn("setTextBaseline 已废弃，请改用 setTextVerticalAlign。" + "本次调用将转调用 setTextVerticalAlign。");
+        this.setTextVerticalAlign(value);
     };
     return RichTextComponent;
-}(TextComponent);
+}(MaskableGraphic);
 RichTextComponent = __decorate([
     effectsClass(spec.DataType.RichTextComponent)
 ], RichTextComponent);
+applyMixins(RichTextComponent, [
+    TextComponentBase
+]);
 
 /**
  * 插件版本号
- */ var version = "2.7.4";
+ */ var version = "2.8.0-alpha.1";
 registerPlugin("rich-text", RichTextLoader, VFXItem);
 logger.info("Plugin rich text version: " + version + ".");
 if (version !== EFFECTS.version) {