总结Cocos2d-x 3.0 中新字体标签Label

Cocos2d-x 2019-05-18

在3.x中，废弃了2.x里的LabelTTF、LabelAtlas、LabelBMFont三个字体类，取而代之的是全新的字体标签Label。

实际上Label是将三个字体类进行了融合，进行统一的管理与渲染，这使得创建字体标签Label的方式更加统一，更加方便。


本节来学习一下3.x中新的标签类Label，如果对2.x中的三个字体类不了解的话，建议先去看看那三个类的用法，再来学习本节内容，能够更好的理解。

（2.x中的旧标签类，请查看这里）

【本节内容】

在3.x中，Label支持四种方式的标签创建。并新增了阴影Shadow、轮廓Outline、发光Glow效果的支持。还支持文字内容的行间距、文字间距、自动换行的设置。

  • 创建系统原生字体API:createWithSystemFont

  • 创建TTF:createWithTTF（原LabelTTF）

  • 创建CharMap:createWithCharMap（原LabelAtlas）

  • 创建BMFont:createWithBMFont（原LabelBMFont）

  • Label的属性与方法

  • 文字效果渲染:Shadow、Outline、Glow

  • 对齐方式:TextHAlignment、TextVAlignment

  • Label的尺寸大小

  • 自动换行

  • 行间距、文字间距

  • 单独设置某个字符

PS：关于图片资源，请在Cocos2dx给出的官方样例cpp-tests中寻找。

【createWithSystemFont】

创建系统原生字体的API。

创建方式如下：

[cpp] view plain copy
  1. //
  2. staticLabel*createWithSystemFont(
  3. conststd::string&text,//字符串内容
  4. conststd::string&font,0); background-color:inherit">//字体（字体名称、或字体文件）
  5. floatfontSize,0); background-color:inherit">//字号
  6. constSize&dimensions=Size::ZERO,0); background-color:inherit">//label的尺寸大小，默认不设置尺寸
  7. TextHAlignmenthAlignment=TextHAlignment::LEFT,//水平对齐方式，默认左对齐::LEFT
  8. TextVAlignmentvAlignment=TextVAlignment::TOP//垂直对齐方式，默认顶部::TOP
  9. );
  10. //
使用举例：
copy
    //使用系统的字体名称"Arial"来创建
  1. Label*lb1=Label::createWithSystemFont("123abc","Arial",24);
  2. //

【createWithTTF】

创建TTF的方式有以下两种：

  • 方式一：与2.x中LabelTTF的创建类似，不过使用的fontFile必须为字体文件。

  • 方式二：通过TTF的配置信息数据结构TTFConfig来创建。

1、方式一：与SystemFont创建类似

注：区别在于fontFile必须为字体文件（如"*.ttf"），即不支持使用系统字体名称来创建。

2、方式二：通过TTFConfig配置来创建

2.1、TTFConfig配置

copy
    typedefstruct_ttfConfig
  1. {
  2. std::stringfontFilePath;//字体文件路径，如"fonts/Arial.ttf"
  3. intfontSize;//字体大小，默认"12"
  4. GlyphCollectionglyphs;//使用的字符集，默认"DYNAMIC"
  5. constchar*customGlyphs;
  6. booldistanceFieldEnabled;//是否让字体紧凑，默认false
  7. intoutlinesize;//字体轮廓大小，默认"0"
  9. //构造函数
  10. _ttfConfig(
  11. char*filePath="",
  12. intsize=12,
  13. constGlyphCollection&glyphCollection=GlyphCollection::DYNAMIC,87); background-color:inherit; font-weight:bold">char*customGlyphCollection=nullptr,87); background-color:inherit; font-weight:bold">boolusedistanceField=false,87); background-color:inherit; font-weight:bold">intoutline=0
  14. }TTFConfig;
  15. 2.2、使用TTFConfig创建TTF
    copy
    staticLabel*createWithTTF(
  1. constTTFConfig&ttfConfig,0); background-color:inherit">//TTFConfig配置
  2. //字符串内容
  3. TextHAlignmentalignment=TextHAlignment::LEFT,
  4. intmaxlinewidth=0//最大文本行宽，0表示不设置。可用于自动换行只用
  5. copy
    TTFConfigttfConfig;
  1. ttfConfig.fontFilePath="fonts/MarkerFelt.ttf";//必须配置
  2. ttfConfig.fontSize=12;
  3. ttfConfig.distanceFieldEnabled=false;
  4. ttfConfig.outlinesize=0;
  5. ttfConfig.glyphs=GlyphCollection::DYNAMIC;
  6. ttfConfig.customGlyphs=nullptr;
  8. //使用TTFConfig配置，来创建TTF
  9. Label*lb3=Label::createWithTTF(ttfConfig,"123abc");
  10. //

【createWithCharMap】

CharMap的用法与2.x中的LabelAtlas是一样的，一般用来显示数字。不过它也可以用来显示其他字符，如英文字符。

字体文件资源一般来自一张.png图片，或.plist文件。

注：图片中每个字符的大小必须是固定的，若要改变字体大小，只能通过setScale放缩来实现。

创建CharMap有三种方式：

从图片中从左到右，一块一块截取。从字符startCharMap开始一一对应。

第一块小图片对应字符startCharMap；第二块小图片对应字符startCharMap+1；第三块对应startCharMap+2……以此类推。

注：startCharMap为ASCII码，即：数字'0'为48。

copy
    //charMapFile:字符资源图片png
  1. //itemWidth:每个字符的宽
  2. //itemHeight:每个字符的高
  3. //startCharMap:图片第一个是什么字符
  4. staticLabel*createWithCharMap(conststd::string&charMapFile,intitemWidth,87); background-color:inherit; font-weight:bold">intitemHeight,87); background-color:inherit; font-weight:bold">intstartCharMap);
  5. staticLabel*createWithCharMap(Texture2D*texture,87); background-color:inherit; font-weight:bold">intstartCharMap);
  6. conststd::string&plistFile);
  7. 0、字符图片资源

    digit.png：200*20（每个数字20*20）。



    1、使用.png创建

    copy
      //create字符图片.png，每个字符宽，高，起始字符
    1. Label*lb4=Label::createWithCharMap("fonts/digit.png",20,'0');
    2. lb4->setString("123456");//设置字符串内容
    3. //

    2、使用Texture2D创建

    使用方法实际上与.png是类似的。

    copy
      //创建图片纹理Texture2D
    1. Texture2D*texture=TextureCache::getInstance()->addImage("fonts/digit.png");
    2. Label*lb5=Label::createWithCharMap(texture,'0');
    3. lb5->setString("123456"); 3、使用.plist创建

      在digit.plist里需要配置：用到的字符图片资源.png，每个字符的宽、高，起始字符。

      如下所示：

      [html] copy
        //
      1. <?xmlversion="1.0"encoding="UTF-8"?>
      2. <!DOCTYPEplistPUBLIC"-//Apple//DTdplIST1.0//EN""http://www.apple.com/DTDs/PropertyList-1.0.dtd">
      3. <plistversion="1.0">
      4. dictkey>version</><!--plist版本-->
      5. integer>1>textureFilename<!--字符图片资源:digit.png-->
      6. string>digit.png>itemWidth<!--每个字符的宽:20-->
      7. >20>itemHeight<!--每个字符的高:20-->
      8. >firstChar<!--起始字符:'0'-->
      9. >48plist //
      使用plist创建CharMap的方法：
      copy
        //plist的配置信息，如上所示
      1. Label*lb6=Label::createWithCharMap("fonts/digit.plist");
      2. lb6->setString("123456");
      3. 【createWithBMFont】

        BMFont的用法与2.x中的LabelBMFont是一样的。

        这个类使用之前，需要添加好字体文件，包括一个图片文件（*.png）和一个字体坐标文件（*.fnt），这两个文件名称必须一样。可以下载一个fnt编辑工具来自定义字体。

        值得注意的是：

        • 在2.x中，可以使用getChildByTag(i)来获取第i个字符，对其单独设置属性、动作等。

        • 在3.x中，则是使用getLetter(i)，而不再是getChildByTag(i)。

        这个类也没办法指定字体的字号大小，需要用setScale来缩放调整大小。

        copy
          staticLabel*createWithBMFont(
        1. conststd::string&bmfontFilePath,0); background-color:inherit">//字体文件.font
        2. //内容
        3. constTextHAlignment&alignment=TextHAlignment::LEFT,87); background-color:inherit; font-weight:bold">intmaxlinewidth=0,153); background-color:inherit; font-weight:bold">constVec2&imageOffset=Vec2::ZERO//字符图片的起始左上角坐标。一般不要设置这个参数，因为坐标的配置均已在.font里完成
        4. );
        5. copy
            Label*lb7=Label::createWithBMFont("bitmapFontTest.fnt","123abc",TextHAlignment::LEFT);
          1. 【Label的属性与方法】

            Label继承于：

            • SpriteBatchNode:用于加快字体的渲染速度。

            • LabelProtocol:用于设置Label的字符串内容。

            主要函数如下：

            copy
              classCC_DLLLabel:publicSpriteBatchNode,publicLabelProtocol
            1. /**
            2. *字体设置
            3. *-setSystemFontName:字体（字体名字、字体文件）
            4. *-setSystemFontSize:字体大小
            5. *-setString:字符串内容
            6. *-setTextColor:文字内容颜色
            7. **/
            8. //设置SystemFont类型的字体（字体名字、字体文件）
            9. //设置SystemFont类型的字体大小
            10. //请不要用于其他Label类型！（TTF、CharMap、BMFont）
            11. virtualvoidsetSystemFontName(conststd::string&systemFont);
            12. voidsetSystemFontSize(floatfontSize);
            13. conststd::string&getSystemFontName()const{return_systemFont;}
            14. virtualfloatgetSystemFontSize()return_systemFontSize;}
            15. //改变字符串内容并重新渲染
            16. //注：如果你没有为Label设置TTF/BMFont/CharMap，会产生很大的开销
            17. voidsetString(conststd::string&text)override;
            18. conststd::string&getString()constoverride{return_originalUTF8String;}
            19. //设置文字颜色，仅支持TTF和SystemFont
            20. //注：区别Node节点的颜色
            21. //Node::setColor:Color3B
            22. //Label::setTextColor:Color4B
            23. voidsetTextColor(constColor4B&color);
            24. constColor4B&getTextColor()return_textColor;}
            25. *获取Label的某个字符
            26. *-getLetter
            27. *-不支持SystemFont
            28. //不支持SystemFont
            29. virtualSprite*getLetter(intlettetIndex);
            30. /**
            31. *文字渲染效果
            32. *-Shadow:阴影
            33. *-Outline:轮廓，仅支持TTF
            34. *-Glow:发光，仅支持TTF
            35. //阴影Shadow（阴影颜色，相对Label的偏移，模糊度）
            36. //注:其中blurRadius在3.2中并未实现
            37. voidenableShadow(constColor4B&shadowColor=Color4B::BLACK,153); background-color:inherit; font-weight:bold">constSize&offset=Size(2,-2),87); background-color:inherit; font-weight:bold">intblurRadius=0);
            38. //轮廓Outline，仅支持TTF（轮廓颜色，轮廓粗细）
            39. voidenableOutline(constColor4B&outlineColor,87); background-color:inherit; font-weight:bold">intoutlinesize=-1);
            40. //发光Glow，仅支持TTF
            41. voidenableGlow(constColor4B&glowColor);
            42. //取消阴影/轮廓/发光渲染效果
            43. voiddisableEffect();
            44. *对齐方式
            45. *>TextHAlignment:水平对齐方式
            46. *-TextHAlignment:LEFT:左对齐
            47. *-TextHAlignment:CENTER:居中对齐，默认
            48. *-TextHAlignment:RIGHT:右对齐
            49. *>TextVAlignment:垂直对齐方式
            50. *-TextVAlignment::TOP:顶部，默认
            51. *-TextVAlignment::CENTER:中心
            52. *-TextVAlignment::BottOM:底部
            53. **/
            54. //设置对齐方式
            55. voidsetAlignment(TextHAlignmenthAlignment){setAlignment(hAlignment,_vAlignment);}
            56. voidsetAlignment(TextHAlignmenthAlignment,TextVAlignmentvAlignment);
            57. TextHAlignmentgetTextAlignment()return_hAlignment;}
            58. //设置水平对齐方式
            59. voidsetHorizontalAlignment(TextHAlignmenthAlignment){setAlignment(hAlignment,_vAlignment);}
            60. TextHAlignmentgetHorizontalAlignment()//设置垂直对齐方式
            61. voidsetVerticalAlignment(TextVAlignmentvAlignment){setAlignment(_hAlignment,vAlignment);}
            62. TextVAlignmentgetVerticalAlignment()return_vAlignment;}
            63. *Label尺寸大小
            64. *-setLineBreakWithoutSpace:开启自动换行功能
            65. *-setMaxlinewidth:文字内容的最大行宽
            66. *-setWidth:Label尺寸大小，宽
            67. *-setHeight:Label尺寸大小，高
            68. *-setDimensions:Label尺寸大小
            69. //是否开启自动换行功能
            70. voidsetLineBreakWithoutSpace(boolbreakWithoutSpace);
            71. //最大行宽，内容超过Maxlinewidth，就会自动换行
            72. //前提条件:仅在width==0时，起作用。
            73. //>width==0;
            74. //>setMaxlinewidth(linewidth);
            75. //>setLineBreakWithoutSpace(true);
            76. //它的效果与下面是类似的.
            77. //>setWidth(linewidth);
            78. //>setLineBreakWithoutSpace(true);
            79. //只是width==0时，就无法设置文本的对齐方式了.
            80. voidsetMaxlinewidth(unsignedintmaxlinewidth);
            81. unsignedintgetMaxlinewidth(){return_maxlinewidth;}
            82. //设置Label的尺寸大小
            83. //可以理解为Label的文本框大小
            84. //当setLineBreakWithoutSpace(true)时，内容超过width，会自动换行
            85. //并且内容支持文本的对齐方式
            86. //注：设置尺寸大小，使用的是setDimensions，而不是setContentSize！
            87. voidsetWidth(unsignedintwidth){setDimensions(width,_labelHeight);}
            88. voidsetHeight(unsignedintheight){setDimensions(_labelWidth,height);}
            89. voidsetDimensions(unsignedintwidth,unsignedintheight);
            90. unsignedintgetWidth()return_labelWidth;}
            91. intgetHeight()return_labelHeight;}
            92. constSize&getDimensions()return_labelDimensions;}
            93. *v3.2新增
            94. *-setLineHeight:设置行间距
            95. *-setAdditionalKerning:设置文字间距
            96. *-getStringLength:字符串内容长度
            97. */
            98. //设置行间距，不支持systemfont
            99. voidsetLineHeight(floatheight);
            100. floatgetLineHeight()const;
            101. //设置文字间距，不支持systemfont
            102. voidsetAdditionalKerning(floatspace);
            103. floatgetAdditionalKerning()//获取Label的字符串内容长度
            104. intgetStringLength()const;
            105. *重写Node父类的方法
            106. *-setBlendFunc:混合模式
            107. *-setScale:放缩字体大小
            108. *-addChild:添加子节点
            109. *-getDescription:显示Label的描述
            110. //设置颜色混合模式
            111. voidsetBlendFunc(constBlendFunc&blendFunc)override;
            112. //放缩字体大小（一般用于CharMap、BMFont）
            113. voidsetScale(floatscale)override;
            114. voidsetScaleX(floatscaleX)override;
            115. voidsetScaleY(floatscaleY)override;
            116. floatgetScaleX()constoverride;
            117. floatgetScaleY()constoverride;
            118. //添加子节点
            119. voidaddChild(Node*child,87); background-color:inherit; font-weight:bold">intzOrder=0,87); background-color:inherit; font-weight:bold">inttag=0)override;
            120. voidsortAllChildren()override;
            121. //Label描述
            122. virtualstd::stringgetDescription() };
            123. 【文字渲染效果】

              支持三种渲染效果：

              • Shadow:阴影

              • Outline:轮廓，仅支持TTF

              • Glow:发光，仅支持TTF

              注：其中Outline与Glow两个效果，只会作用一个。即无法一起使用。

              使用举例：

              copy
                Label*lb=Label::createWithTTF("123abc","fonts/MarkerFelt.ttf",50);
              1. lb->setPosition(visibleSize/2);
              2. this->addChild(lb);
              3. lb->enableShadow(Color4B::GREEN,Size(10,10));//阴影
              4. lb->enableOutline(Color4B::RED,3);//轮廓
              5. //lb->enableGlow(Color4B::GREEN);//发光
              6. //取消阴影、轮廓、发光效果
              7. //lb->disableEffect();
              8. //

              如图所示：





              【对齐方式】

              • TextHAlignment:水平对齐方式

              * TextHAlignment:LEFT:左对齐

              * TextHAlignment:CENTER:居中对齐，默认

              * TextHAlignment:RIGHT:右对齐

              • TextVAlignment:垂直对齐方式

              * TextVAlignment::TOP:顶部，默认

              * TextVAlignment::CENTER:中心

              * TextVAlignment::BottOM:底部

              仅在设置了Label的尺寸大小setDimensions(width,height)，大于显示的字符串内容的尺寸大小，才会起作用。

              对齐方式举例，如下几张图片所示：

              对齐方式为：

              • TextHAlignment:LEFT

              • TextVAlignment::TOP


              【自动换行】

              在3.x中，自动换行有两种方式。（当然你也可以使用C++里的转移字符'\n'进行手动换行）

              1、利用setMaxlinewidth

              设置每行显示文字的最大宽度。

              注：这种方法仅在Labelwidth==0的情况下，才会有效。

              使用方法：

              copy
                lb->setLineBreakWithoutSpace(true);
              1. lb->setMaxlinewidth(120);//最大宽度120
              2. 如图：

                2、利用setDimensions

                copy

                  lb->setWidth(80);//设置Label尺寸宽80
                1. lb->setMaxlinewidth(120);//设置了Labelwidth，这个就无效了
                2. 【文字间距】

                  间距的调整，是在v3.2之后才出现的。可以设置文本内容的行间距与文字间距。

                  注：不支持SystemFont。

                  • setLineHeight:设置行间距

                  • setAdditionalKerning:设置额外文字间距

                  copy

                    lb->setLineHeight(80);
                  1. lb->setAdditionalKerning(10);
                  2. 图解：

                    【单独设置某个字符】

                    学过2.x中的LabelBMFont的同学，应该知道这个是怎么回事吧？

                    在3.x中，使用TTF、CharMap、BMFont创建的文字标签，其字符串内容的每个字符都是一个Sprite精灵图片，可以对其进行单独的设置。如精灵放缩、执行动作等。

                  3. lb->getStringLength():获取字符串内容的总长度

                  4. lb->getLetter(i):获取第i个位置上的字符

                    5. 使用举例：

                    copy
                      //获取字符串总长度，length=6
                    1. cclOG("%d",lb->getStringLength());
                    2. //获取第1个字符
                    3. Sprite*letter1=lb->getLetter(1);
                    4. letter1->setColor(Color3B::GREEN);//设置颜色
                    5. letter1->setScale(2.0f);//放缩
                    6. //获取第4个字符
                    7. Sprite*letter4=lb->getLetter(4);
                    8. letter4->setColor(Color3B::RED);//设置颜色
                    9. letter4->runAction(RepeatForever::create(RotateBy::create(1.0f,90)));//执行旋转动作
                    10. 如图：

                      相关文章

                      如何使用CCRenderTexture创建动态纹理 Cocos2d-x 2 1 4
                          本文实践自 RayWenderlich、Ali Hafizji 的文章《...
                      Cocos-code-ide使用入门学习
                      Cocos-code-ide使用入门学习地点：杭州滨江邮箱：appdevzw@1...
                      Cocos2D-x-3.0 编译(Win7)
                      第一次開始用手游引擎挺激动！！！进入正题。下载资源1：从C...
                      Cocos2d-x 2 0 在Windows平台下的使用
                          Cocos2d-x是一款强大的基于OpenGLES的跨平台游戏开发...
                      quick-cocos2d-x实例之挑战记忆极限设计文档
                      1.  来源 QuickV3sample项目中的2048样例游戏，以及最近《...
                      Cocos2d-x 3 X CMake MinGW版本编译运行
                         Cocos2d-x3.x已经支持使用CMake来进行构建了，这里尝试...