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

来源网址：http://cn.cocos2d-x.org/tutorial/show?id=1624 

在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.     static Label* createWithSystemFont(  
3.         const std::string& text,                          //字符串内容  
4.         const std::string& font,                          //字体（字体名称、或字体文件）  
5.         float fontSize,                                   //字号                             
6.         const Size& dimensions = Size::ZERO,              //label的尺寸大小，默认不设置尺寸  
7.         TextHAlignment hAlignment = TextHAlignment::LEFT, //水平对齐方式，默认左对齐::LEFT  
8.         TextVAlignment vAlignment = TextVAlignment::TOP   //垂直对齐方式，默认顶部  ::TOP  
9.     );  
10. //  

使用举例：

[cpp]  view plain  copy

1. //  
2.     //使用系统的字体名称 "Arial" 来创建  
3.     Label* lb1 = Label::createWithSystemFont("123abc", "Arial", 24);  
4. //  

【createWithTTF】

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

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

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

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

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

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

2.1、TTFConfig配置

[cpp]  view plain  copy

1. //  
2.     typedef struct _ttfConfig   
3.     {  
4.         std::string fontFilePath;  //字体文件路径，如 "fonts/Arial.ttf"  
5.         int fontSize;              //字体大小，默认"12"  
6.         GlyphCollection glyphs;    //使用的字符集，默认"DYNAMIC"  
7.         const char *customGlyphs;  
8.         bool distanceFieldEnabled; //是否让字体紧凑，默认false  
9.         int outlineSize;           //字体轮廓大小，默认"0"  
10.             
11.         //构造函数  
12.         _ttfConfig(  
13.             const char* filePath = "",  
14.             int size = 12,  
15.             const GlyphCollection& glyphCollection = GlyphCollection::DYNAMIC,  
16.             const char *customGlyphCollection = nullptr,  
17.             bool useDistanceField = false,  
18.             int outline = 0  
19.         );  
20.     }TTFConfig;  
21. //  

2.2、使用TTFConfig创建TTF

[cpp]  view plain  copy

1. //  
2.     static Label* createWithTTF(  
3.         const TTFConfig& ttfConfig, //TTFConfig配置  
4.         const std::string& text,    //字符串内容  
5.         TextHAlignment alignment = TextHAlignment::LEFT,  
6.         int maxLineWidth = 0        //最大文本行宽，0表示不设置。可用于自动换行只用  
7.     );  
8. //  

使用举例：

[cpp]  view plain  copy

1. //  
2.     TTFConfig ttfConfig;  
3.     ttfConfig.fontFilePath = "fonts/Marker Felt.ttf"; //必须配置  
4.     ttfConfig.fontSize = 12;  
5.     ttfConfig.distanceFieldEnabled = false;  
6.     ttfConfig.outlineSize = 0;  
7.     ttfConfig.glyphs = GlyphCollection::DYNAMIC;  
8.     ttfConfig.customGlyphs = nullptr;  
9.         
10.     //使用TTFConfig配置，来创建TTF  
11.     Label* lb3 = Label::createWithTTF(ttfConfig, "123abc");  
12. //  

【createWithCharMap】

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

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

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

创建CharMap有三种方式：

• 使用.png图片创建

• 使用纹理Texture2D创建

• 使用.plist创建

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

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

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

[cpp]  view plain  copy

1. //  
2.     //charMapFile  : 字符资源图片png  
3.     //itemWidth    : 每个字符的宽  
4.     //itemHeight   : 每个字符的高  
5.     //startCharMap : 图片第一个是什么字符  
6.     static Label* createWithCharMap(const std::string& charMapFile, int itemWidth, int itemHeight, int startCharMap);  
7.     static Label* createWithCharMap(Texture2D* texture, int itemWidth, int itemHeight, int startCharMap);  
8.     static Label* createWithCharMap(const std::string& plistFile);  
9. //  

0、字符图片资源

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

1、使用.png创建

[cpp]  view plain  copy

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

2、使用Texture2D创建

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

[cpp]  view plain  copy

1. //  
2.     //创建图片纹理Texture2D  
3.     Texture2D* texture = TextureCache::getInstance()->addImage("fonts/digit.png");  
4.         
5.     Label* lb5 = Label::createWithCharMap(texture, 20, 20, '0');  
6.     lb5->setString("123456"); //设置字符串内容  
7. //  

3、使用.plist创建

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

如下所示：

[html]  view plain  copy

1. //  
2.     <?xml version="1.0" encoding="UTF-8"?>  
3.     <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">  
4.     <plist version="1.0">  
5.     <dict>  
6.         <key>version</key>           <!-- plist版本 -->  
7.         <integer>1</integer>  
8.         <key>textureFilename</key>   <!-- 字符图片资源: digit.png -->  
9.         <string>digit.png</string>  
10.         <key>itemWidth</key>         <!-- 每个字符的宽: 20 -->  
11.         <integer>20</integer>  
12.         <key>itemHeight</key>        <!-- 每个字符的高: 20 -->  
13.         <integer>20</integer>  
14.         <key>firstChar</key>         <!-- 起始字符    : '0' -->  
15.         <integer>48</integer>  
16.     </dict>  
17.     </plist>  
18. //  

使用plist创建CharMap的方法：

[cpp]  view plain  copy

1. //  
2.     //plist的配置信息，如上所示  
3.     Label* lb6 = Label::createWithCharMap("fonts/digit.plist");  
4.     lb6->setString("123456");  
5. //  

【createWithBMFont】

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

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

值得注意的是：

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

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

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

[cpp]  view plain  copy

1. //  
2.     static Label* createWithBMFont(  
3.         const std::string& bmfontFilePath, //字体文件.font  
4.         const std::string& text,           //内容  
5.         const TextHAlignment& alignment = TextHAlignment::LEFT,  
6.         int maxLineWidth = 0,   
7.         const Vec2& imageOffset = Vec2::ZERO       //字符图片的起始左上角坐标。一般不要设置这个参数，因为坐标的配置均已在.font里完成  
8.     );  
9. //  

使用举例：

[cpp]  view plain  copy

1. //  
2.     Label* lb7 = Label::createWithBMFont("bitmapFontTest.fnt", "123abc", TextHAlignment::LEFT);  
3. //  

【Label的属性与方法】

Label继承于：

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

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

主要函数如下：

[cpp]  view plain  copy

1. //  
2. class CC_DLL Label : public SpriteBatchNode, public LabelProtocol  
3. {  
4. /** 
5.  * 字体设置 
6.  *     - setSystemFontName : 字体（字体名字、字体文件） 
7.  *     - setSystemFontSize : 字体大小 
8.  *     - setString         : 字符串内容 
9.  *     - setTextColor      : 文字内容颜色 
10.  **/  
11.     //设置System Font类型的字体（字体名字、字体文件）  
12.     //设置System Font类型的字体大小  
13.     //请不要用于其他Label类型！（TTF、CharMap、BMFont）  
14.     virtual void setSystemFontName(const std::string& systemFont);  
15.     virtual void setSystemFontSize(float fontSize);  
16.     virtual const std::string& getSystemFontName() const { return _systemFont;}  
17.     virtual float getSystemFontSize() const { return _systemFontSize;}  
18.     
19.     
20.     //改变字符串内容并重新渲染  
21.     //注：如果你没有为Label设置TTF/BMFont/CharMap，会产生很大的开销  
22.     virtual void setString(const std::string& text) override;  
23.     virtual const std::string& getString() const override {  return _originalUTF8String; }  
24.     
25.     
26.     //设置文字颜色，仅支持TTF和System Font  
27.     //注：区别 Node节点的颜色  
28.     //      Node ::setColor     : Color3B  
29.     //      Label::setTextColor : Color4B  
30.     virtual void setTextColor(const Color4B &color);  
31.     const Color4B& getTextColor() const { return _textColor; }  
32.     
33.     
34. /** 
35.  * 获取Label的某个字符 
36.  *     - getLetter 
37.  *     - 不支持System Font 
38.  **/  
39.     //不支持System Font  
40.     virtual Sprite* getLetter(int lettetIndex);  
41.     
42.     
43. /** 
44.  * 文字渲染效果 
45.  *     - Shadow  : 阴影 
46.  *     - Outline : 轮廓，仅支持TTF 
47.  *     - Glow    : 发光，仅支持TTF 
48.  **/  
49.     //阴影Shadow（阴影颜色，相对Label的偏移，模糊度）  
50.     //注: 其中blurRadius在3.2中并未实现  
51.     virtual void enableShadow(const Color4B& shadowColor = Color4B::BLACK,const Size &offset = Size(2,-2), int blurRadius = 0);  
52.     
53.     //轮廓Outline，仅支持TTF（轮廓颜色，轮廓粗细）  
54.     virtual void enableOutline(const Color4B& outlineColor,int outlineSize = -1);  
55.     
56.     //发光Glow，仅支持TTF  
57.     virtual void enableGlow(const Color4B& glowColor);  
58.     
59.     //取消阴影/轮廓/发光渲染效果  
60.     virtual void disableEffect();  
61.     
62.     
63. /** 
64.  * 对齐方式 
65.  *    > TextHAlignment : 水平对齐方式 
66.  *        - TextHAlignment:LEFT    : 左对齐 
67.  *        - TextHAlignment:CENTER  : 居中对齐，默认 
68.  *        - TextHAlignment:RIGHT   : 右对齐 
69.  *    > TextVAlignment : 垂直对齐方式 
70.  *        - TextVAlignment::TOP    : 顶部，默认 
71.  *        - TextVAlignment::CENTER : 中心 
72.  *        - TextVAlignment::BOTTOM : 底部 
73.  **/  
74.     //设置对齐方式  
75.     void setAlignment(TextHAlignment hAlignment) { setAlignment(hAlignment,_vAlignment);}  
76.     void setAlignment(TextHAlignment hAlignment,TextVAlignment vAlignment);  
77.     TextHAlignment getTextAlignment() const { return _hAlignment;}  
78.     
79.     //设置水平对齐方式  
80.     void setHorizontalAlignment(TextHAlignment hAlignment) { setAlignment(hAlignment,_vAlignment); }  
81.     TextHAlignment getHorizontalAlignment() const { return _hAlignment; }  
82.     
83.     //设置垂直对齐方式  
84.     void setVerticalAlignment(TextVAlignment vAlignment) { setAlignment(_hAlignment,vAlignment); }  
85.     TextVAlignment getVerticalAlignment() const { return _vAlignment; }  
86.     
87.     
88. /** 
89.  * Label尺寸大小 
90.  *     - setLineBreakWithoutSpace : 开启自动换行功能 
91.  *     - setMaxLineWidth          : 文字内容的最大行宽 
92.  *     - setWidth                 : Label尺寸大小，宽 
93.  *     - setHeight                : Label尺寸大小，高 
94.  *     - setDimensions            : Label尺寸大小 
95.  **/  
96.     //是否开启自动换行功能  
97.     void setLineBreakWithoutSpace(bool breakWithoutSpace);  
98.     
99.     
100.     //最大行宽，内容超过MaxLineWidth，就会自动换行  
101.     //前提条件: 仅在width==0时，起作用。  
102.     //  > width == 0;  
103.     //  > setMaxLineWidth(lineWidth);  
104.     //  > setLineBreakWithoutSpace(true);  
105.     //它的效果与下面是类似的.  
106.     //  > setWidth(lineWidth);  
107.     //  > setLineBreakWithoutSpace(true);  
108.     //只是width==0时，就无法设置文本的对齐方式了.  
109.     void setMaxLineWidth(unsigned int maxLineWidth);  
110.     unsigned int getMaxLineWidth() { return _maxLineWidth;}  
111.     
112.     
113.     //设置Label的尺寸大小  
114.     //可以理解为Label的文本框大小  
115.     //当setLineBreakWithoutSpace(true)时，内容超过width，会自动换行  
116.     //并且内容支持文本的对齐方式  
117.     //注：设置尺寸大小，使用的是setDimensions，而不是setContentSize ！  
118.     void setWidth(unsigned int width) { setDimensions(width,_labelHeight); }  
119.     void setHeight(unsigned int height){ setDimensions(_labelWidth,height); }  
120.     void setDimensions(unsigned int width,unsigned int height);  
121.     unsigned int getWidth() const { return _labelWidth; }  
122.     unsigned int getHeight() const { return _labelHeight; }    
123.     const Size& getDimensions() const{ return _labelDimensions; }  
124.     
125.     
126. /** 
127.  * v3.2 新增 
128.  *     - setLineHeight        : 设置行间距 
129.  *     - setAdditionalKerning : 设置文字间距 
130.  *     - getStringLength      : 字符串内容长度 
131.  */  
132.     //设置行间距，不支持system font  
133.     void setLineHeight(float height);  
134.     float getLineHeight() const;  
135.     
136.     //设置文字间距，不支持system font  
137.     void setAdditionalKerning(float space);  
138.     float getAdditionalKerning() const;  
139.     
140.     //获取Label的字符串内容长度  
141.     int getStringLength() const;  
142.     
143.     
144. /** 
145.  * 重写Node父类的方法 
146.  *     - setBlendFunc   : 混合模式 
147.  *     - setScale       : 放缩字体大小 
148.  *     - addChild       : 添加子节点 
149.  *     - getDescription : 显示Label的描述 
150.  **/  
151.     //设置颜色混合模式  
152.     virtual void setBlendFunc(const BlendFunc &blendFunc) override;  
153.     
154.     //放缩字体大小（一般用于CharMap、BMFont）  
155.     virtual void setScale(float scale) override;  
156.     virtual void setScaleX(float scaleX) override;  
157.     virtual void setScaleY(float scaleY) override;  
158.     virtual float getScaleX() const override;  
159.     virtual float getScaleY() const override;  
160.     
161.     //添加子节点  
162.     virtual void addChild(Node * child, int zOrder=0, int tag=0) override;  
163.     virtual void sortAllChildren() override;  
164.     
165.     //Label描述  
166.     virtual std::string getDescription() const override;  
167. };  
168. //  

【文字渲染效果】

支持三种渲染效果：

• Shadow:阴影
  

• Outline:轮廓，仅支持TTF
  

• Glow:发光，仅支持TTF

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

使用举例：

[cpp]  view plain  copy

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

如图所示：

【对齐方式】

• 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'进行手动换行）

• 利用lb->setLineBreakWithoutSpace(true)，来支持自动换行功能。

• 利用setMaxLineWidth(maxLineWidth)，来控制自动换行。

• 利用setDimensions(width,height)，来控制自动换行。

1、利用setMaxLineWidth

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

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

使用方法：

[cpp]  view plain  copy

1. //  
2.     lb->setLineBreakWithoutSpace(true);  
3.     lb->setMaxLineWidth(120); //最大宽度120  
4. //  

如图：

2、利用setDimensions

使用方法：

[cpp]  view plain  copy

1. //  
2.     lb->setLineBreakWithoutSpace(true);  
3.     lb->setWidth(80);         //设置Label尺寸宽80  
4.     lb->setMaxLineWidth(120); //设置了Label width，这个就无效了  
5. //  

如图：

【文字间距】

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

注：不支持SystemFont。

• setLineHeight:设置行间距

• setAdditionalKerning:设置额外文字间距

使用举例：

[cpp]  view plain  copy

1. //  
2.     lb->setLineHeight(80);  
3.     lb->setAdditionalKerning(10);  
4. //  

图解：

【单独设置某个字符】

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

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

注：不支持SystemFont。

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

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

使用举例：

[cpp]  view plain  copy

1. //  
2.     Label* lb = Label::createWithTTF("123abc", "fonts/Marker Felt.ttf", 50);  
3.     lb->setPosition(visibleSize / 2);  
4.     this->addChild(lb);  
5.     
6.     //获取字符串总长度，length = 6  
7.     CCLOG("%d", lb->getStringLength());  
8.     
9.     //获取第1个字符  
10.     Sprite* letter1 = lb->getLetter(1);  
11.     letter1->setColor(Color3B::GREEN); //设置颜色  
12.     letter1->setScale(2.0f);           //放缩  
13.     
14.     //获取第4个字符  
15.     Sprite* letter4 = lb->getLetter(4);  
16.     letter4->setColor(Color3B::RED);  //设置颜色  
17.     letter4->runAction(RepeatForever::create(RotateBy::create(1.0f, 90))); //执行旋转动作  

1. //  如图：
   
   

   参考阅读：

   http://cn.cocos2d-x.org/tutorial/show?id=1446

   http://www.cocoachina.com/bbs/read.php?tid=197179

   
   

   来源网址：http://blog.csdn.net/u010105970/article/details/39754123