Integration of outline and shadow to label

cocos/2d/assembler/label/letter-font.ts

@@ -25,7 +25,7 @@
 import { js } from '../../../core';
 import { Label, LabelOutline } from '../../components';
 import { bmfontUtils } from './bmfontUtils';
-import { shareLabelInfo, LetterAtlas, computeHash } from './font-utils';
+import { shareLabelInfo, LetterAtlas, computeHash, LetterRenderTexture } from './font-utils';
 
 const _atlasWidth = 1024;
 const _atlasHeight = 1024;
@@ -39,20 +39,20 @@ export const letterFont = js.mixin(bmfontUtils, {
             _shareAtlas = new LetterAtlas(_atlasWidth, _atlasHeight);
         }
 
-        return _shareAtlas.getTexture();
+        return _shareAtlas.getTexture() as LetterRenderTexture | null;
     },
 
     _updateFontFamily (comp) {
         shareLabelInfo.fontAtlas = _shareAtlas;
         shareLabelInfo.fontFamily = this._getFontFamily(comp);
 
         // outline
-        const outline = comp.getComponent(LabelOutline);
-        if (outline && outline.enabled) {
+        const isOutlined = comp.enableOutline && comp.outlineWidth > 0;
+        if (isOutlined) {
             shareLabelInfo.isOutlined = true;
-            shareLabelInfo.margin = outline.width;
-            shareLabelInfo.out = outline.color.clone();
-            shareLabelInfo.out.a = outline.color.a * comp.color.a / 255.0;
+            shareLabelInfo.margin = comp.outlineWidth;
+            shareLabelInfo.out = comp.outlineColor.clone();
+            shareLabelInfo.out.a = comp.outlineColor.color.a * comp.color.a / 255.0;
         } else {
             shareLabelInfo.isOutlined = false;
             shareLabelInfo.margin = 0;

cocos/2d/assembler/label/ttfUtils.ts

@@ -21,7 +21,7 @@
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  THE SOFTWARE.
 */
-import { Label, LabelOutline, LabelShadow } from '../../components';
+import { Label } from '../../components';
 import { ISharedLabelData } from './font-utils';
 import { UITransform } from '../../framework/ui-transform';
 import { dynamicAtlasManager } from '../../utils/dynamic-atlas/atlas-manager';
@@ -30,13 +30,20 @@ import { TextOutputLayoutData, TextOutputRenderData } from './text-output-data';
 import { TextStyle } from './text-style';
 import { TextLayout } from './text-layout';
 import { view } from '../../../ui/view';
+import { approx } from '../../../core';
 
 const Overflow = Label.Overflow;
 
 export const ttfUtils =  {
 
-    updateProcessingData (style: TextStyle, layout: TextLayout,
-        outputLayoutData: TextOutputLayoutData, outputRenderData: TextOutputRenderData, comp: Label, trans: UITransform): void {
+    updateProcessingData (
+        style: TextStyle,
+        layout: TextLayout,
+        outputLayoutData: TextOutputLayoutData,
+        outputRenderData: TextOutputRenderData,
+        comp: Label,
+        trans: UITransform,
+    ): void {
         // font info // both
         style.isSystemFontUsed = comp.useSystemFont;
         style.fontSize = comp.fontSize;
@@ -62,25 +69,23 @@ export const ttfUtils =  {
         style.underlineHeight = comp.underlineHeight;
 
         // outline// both
-        let outlineComp = LabelOutline && comp.getComponent(LabelOutline);
-        outlineComp = (outlineComp && outlineComp.enabled && outlineComp.width > 0) ? outlineComp : null;
-        if (outlineComp) {
+        const isOutlined = comp.enableOutline && comp.outlineWidth > 0;
+        if (isOutlined) {
             style.isOutlined = true;
-            style.outlineColor.set(outlineComp.color);
-            style.outlineWidth = outlineComp.width;
+            style.outlineColor.set(comp.outlineColor);
+            style.outlineWidth = comp.outlineWidth;
         } else {
             style.isOutlined = false;
         }
 
         // shadow// both
-        let shadowComp = LabelShadow && comp.getComponent(LabelShadow);
-        shadowComp = (shadowComp && shadowComp.enabled) ? shadowComp : null;
-        if (shadowComp) {
+        const isShadow = comp.enableShadow && (comp.shadowBlur > 0 || !approx(comp.shadowOffset.x, 0) || !approx(comp.shadowOffset.y, 0));
+        if (isShadow) {
             style.hasShadow = true;
-            style.shadowColor.set(shadowComp.color);
-            style.shadowBlur = shadowComp.blur;
-            style.shadowOffsetX = shadowComp.offset.x;
-            style.shadowOffsetY = shadowComp.offset.y;
+            style.shadowColor.set(comp.shadowColor);
+            style.shadowBlur = comp.shadowBlur;
+            style.shadowOffsetX = comp.shadowOffset.x;
+            style.shadowOffsetY = comp.shadowOffset.y;
         } else {
             style.hasShadow = false;
         }
@@ -126,8 +131,15 @@ export const ttfUtils =  {
 
             // TextProcessing
             processing.processingString(false, style, layout, outputLayoutData, comp.string);
-            processing.generateRenderInfo(false, style, layout, outputLayoutData, outputRenderData,
-                comp.string, this.generateVertexData);
+            processing.generateRenderInfo(
+                false,
+                style,
+                layout,
+                outputLayoutData,
+                outputRenderData,
+                comp.string,
+                this.generateVertexData,
+            );
 
             const renderData = comp.renderData;
             renderData.textureDirty = true;
@@ -173,9 +185,11 @@ export const ttfUtils =  {
     },
 
     updateVertexData (comp: Label): void {
+        // no needs to update vertex data
     },
 
     updateUVs (comp: Label): void {
+        // no needs to update uv data
     },
 
     _updateFontFamily (comp: Label): string {

cocos/2d/components/deprecated.ts

@@ -31,7 +31,8 @@ import { UIMeshRenderer } from './ui-mesh-renderer';
 import { Graphics } from './graphics';
 import { UIStaticBatch } from './ui-static-batch';
 import { UIOpacity } from './ui-opacity';
-import { js, cclegacy, replaceProperty } from '../../core';
+import { js, cclegacy, replaceProperty, markAsWarning } from '../../core';
+import { LabelShadow } from './label-shadow';
 
 /**
  * Alias of [[Mask]]
@@ -125,3 +126,29 @@ replaceProperty(MaskType, 'MaskType', [
         targetName: 'MaskType',
     },
 ]);
+
+markAsWarning(LabelOutline.prototype, 'LabelOutline.prototype', [
+    {
+        name: 'width',
+        suggest: 'Please use Label.prototype.outlineWidth instead.',
+    },
+    {
+        name: 'color',
+        suggest: 'Please use Label.prototype.outlineColor instead.',
+    },
+]);
+
+markAsWarning(LabelShadow.prototype, 'LabelShadow.prototype', [
+    {
+        name: 'color',
+        suggest: 'Please use Label.prototype.shadowColor instead.',
+    },
+    {
+        name: 'offset',
+        suggest: 'Please use Label.prototype.shadowOffset instead.',
+    },
+    {
+        name: 'blur',
+        suggest: 'Please use Label.prototype.shadowBlur instead.',
+    },
+]);

cocos/2d/components/label-outline.ts

@@ -25,7 +25,7 @@
 
 import { ccclass, help, executionOrder, menu, tooltip, requireComponent, executeInEditMode, serializable } from 'cc.decorator';
 import { Component } from '../../scene-graph/component';
-import { Color, cclegacy } from '../../core';
+import { Color, assertIsTrue, cclegacy } from '../../core';
 import { Label } from './label';
 
 /**
@@ -35,15 +35,7 @@ import { Label } from './label';
  * @zh
  * 描边效果组件,用于字体描边,只能用于系统字体。
  *
- * @example
- * ```ts
- * import { Node, Label, LabelOutline } from 'cc';
- * // Create a new node and add label components.
- * const node = new Node("New Label");
- * const label = node.addComponent(Label);
- * const outline = node.addComponent(LabelOutline);
- * node.parent = this.node;
- * ```
+ * @deprecated since v3.8.2, please use [[Label.enableOutline]] instead.
  */
 @ccclass('cc.LabelOutline')
 @help('i18n:cc.LabelOutline')
@@ -64,25 +56,19 @@ export class LabelOutline extends Component {
      * @zh
      * 改变描边的颜色。
      *
-     * @example
-     * ```ts
-     * import { Color } from 'cc';
-     * outline.color = new Color(0.5, 0.3, 0.7, 1.0);
-     * ```
+     * @deprecated since v3.8.2, please use [[Label.outlineColor]] instead.
      */
     @tooltip('i18n:labelOutline.color')
-    // @constget
     get color (): Readonly<Color> {
-        return this._color;
+        const label = this.node.getComponent(Label);
+        assertIsTrue(label, 'Required Label component to work, please add Label component.');
+        return label.outlineColor;
     }
 
     set color (value) {
-        if (this._color === value) {
-            return;
-        }
-
-        this._color.set(value);
-        this._updateRenderData();
+        const label = this.node.getComponent(Label);
+        assertIsTrue(label, 'Required Label component to work, please add Label component.');
+        label.outlineColor = value;
     }
 
     /**
@@ -92,38 +78,37 @@ export class LabelOutline extends Component {
      * @zh
      * 改变描边的宽度。
      *
-     * @example
-     * ```ts
-     * outline.width = 3;
-     * ```
+     * @deprecated since v3.8.2, please use [[Label.outlineWidth]] instead.
      */
     @tooltip('i18n:labelOutline.width')
     get width (): number {
-        return this._width;
+        const label = this.node.getComponent(Label);
+        assertIsTrue(label, 'Required Label component to work, please add Label component.');
+        return label.outlineWidth;
     }
 
     set width (value) {
-        if (this._width === value) {
-            return;
-        }
-
-        this._width = value;
-        this._updateRenderData();
+        const label = this.node.getComponent(Label);
+        assertIsTrue(label, 'Required Label component to work, please add Label component.');
+        label.outlineWidth = value;
     }
 
+    /**
+     * @deprecated since v3.8.2, please use [[Label.enableOutline]] instead.
+     */
     public onEnable (): void {
-        this._updateRenderData();
+        const label = this.node.getComponent(Label);
+        assertIsTrue(label, 'Required Label component to work, please add Label component.');
+        label.enableOutline = true;
     }
 
+    /**
+     * @deprecated since v3.8.2, please use [[Label.enableOutline]] instead.
+     */
     public onDisable (): void {
-        this._updateRenderData();
-    }
-
-    protected _updateRenderData (): void {
         const label = this.node.getComponent(Label);
-        if (label) {
-            label.updateRenderData(true);
-        }
+        assertIsTrue(label, 'Required Label component to work, please add Label component.');
+        label.enableOutline = false;
     }
 }