cocos2d-x 3.x label 功能详解，包括行列间距等细节问题

尊重知识版权，文章转载于：http://www.taikr.com/group/2/thread/1869

这次主要介绍一下关于cocos2d-x 3.x label自动换行的问题，详细的总结一下Cocos2d-x中新字体标签Label，总结如下：

在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。

创建方式如下：

//
static Label* createWithSystemFont(
const std::string& text,                          //字符串内容
const std::string& font,                          //字体（字体名称、或字体文件）
float fontSize,                                   //字号 
const Size& dimensions = Size::ZERO,              //label的尺寸大小，默认不设置尺寸
TextHAlignment hAlignment = TextHAlignment::LEFT, //水平对齐方式，默认左对齐::LEFT
TextVAlignment vAlignment = TextVAlignment::TOP   //垂直对齐方式，默认顶部  ::TOP
);
//

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

【createWithTTF】

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

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

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

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

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

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

2.1、TTFConfig配置

//

typedef struct _ttfConfig

{

std::string fontFilePath;  //字体文件路径，如 "fonts/Arial.ttf"

int fontSize;              //字体大小，默认"12"

GlyphCollection glyphs;    //使用的字符集，默认"DYNAMIC"

const char *customGlyphs;

bool distanceFieldEnabled; //是否让字体紧凑，默认false

int outlineSize;           //字体轮廓大小，默认"0"

//构造函数

_ttfConfig(

const char* filePath = "",

int size = 12,

const GlyphCollection& glyphCollection = GlyphCollection::DYNAMIC,

const char *customGlyphCollection = nullptr,

bool useDistanceField = false,

int outline = 0

);

}TTFConfig;

//

2.2、使用TTFConfig创建TTF

//

static Label* createWithTTF(

const TTFConfig& ttfConfig, //TTFConfig配置

const std::string& text,    //字符串内容

TextHAlignment alignment = TextHAlignment::LEFT,

int maxLineWidth = 0        //最大文本行宽，0表示不设置。可用于自动换行只用

);

//

使用举例：

//

TTFConfig ttfConfig;

ttfConfig.fontFilePath = "fonts/Marker Felt.ttf"; //必须配置

ttfConfig.fontSize = 12;

ttfConfig.distanceFieldEnabled = false;

ttfConfig.outlineSize = 0;

ttfConfig.glyphs = GlyphCollection::DYNAMIC;

ttfConfig.customGlyphs = nullptr;

//使用TTFConfig配置，来创建TTF

Label* lb3 = Label::createWithTTF(ttfConfig, "123abc");

//

【createWithCharMap】

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

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

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

创建CharMap有三种方式：

• 使用.png图片创建

• 使用纹理Texture2D创建

• 使用.plist创建

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

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

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

//

//charMapFile  : 字符资源图片png

//itemWidth    : 每个字符的宽

//itemHeight   : 每个字符的高

//startCharMap : 图片第一个是什么字符

static Label* createWithCharMap(const std::string& charMapFile, int itemWidth, int itemHeight, int startCharMap);

static Label* createWithCharMap(Texture2D* texture, int itemWidth, int itemHeight, int startCharMap);

static Label* createWithCharMap(const std::string& plistFile);

//

0、字符图片资源

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

1、使用.png创建

1 2 3 4 5

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

2、使用Texture2D创建

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

1 2 3 4 5 6 7

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

3、使用.plist创建

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

如下所示：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

// <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" " http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>version</key>           <!-- plist版本 --> <integer>1</integer> <key>textureFilename</key>   <!-- 字符图片资源: digit.png --> <string>digit.png</string> <key>itemWidth</key>         <!-- 每个字符的宽: 20 --> <integer>20</integer> <key>itemHeight</key>        <!-- 每个字符的高: 20 --> <integer>20</integer> <key>firstChar</key>         <!-- 起始字符    : '0' --> <integer>48</integer> </dict> </plist> //

使用plist创建CharMap的方法：

1 2 3 4 5

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

【createWithBMFont】

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

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

值得注意的是：

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

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

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

1 2 3 4 5 6 7 8 9

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

使用举例：

1 2 3

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

【Label的属性与方法】

Label继承于：

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

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

主要函数如下：

77

 只看楼主回复   倒序查看回复

1回复

• 
  2楼 08她的巷  12-29

  /

  class CC_DLL Label : public SpriteBatchNode, public LabelProtocol

  {

  /**

   * 字体设置

   *     - setSystemFontName : 字体（字体名字、字体文件）

   *     - setSystemFontSize : 字体大小

   *     - setString         : 字符串内容

   *     - setTextColor      : 文字内容颜色

   **/

      //设置System Font类型的字体（字体名字、字体文件）

      //设置System Font类型的字体大小

      //请不要用于其他Label类型！（TTF、CharMap、BMFont）

      virtual void setSystemFontName(const std::string& systemFont);

      virtual void setSystemFontSize(float fontSize);

      virtual const std::string& getSystemFontName() const { return _systemFont;}

      virtual float getSystemFontSize() const { return _systemFontSize;}

    

    

      //改变字符串内容并重新渲染

      //注：如果你没有为Label设置TTF/BMFont/CharMap，会产生很大的开销

      virtual void setString(const std::string& text) override;

      virtual const std::string& getString() const override {  return _originalUTF8String; }

    

    

      //设置文字颜色，仅支持TTF和System Font

      //注：区别 Node节点的颜色

      //      Node ::setColor     : Color3B

      //      Label::setTextColor : Color4B

      virtual void setTextColor(const Color4B &color);

      const Color4B& getTextColor() const { return _textColor; }

    

    

  /**

   * 获取Label的某个字符

   *     - getLetter

   *     - 不支持System Font

   **/

      //不支持System Font

      virtual Sprite* getLetter(int lettetIndex);

    

    

  /**

   * 文字渲染效果

   *     - Shadow  : 阴影

   *     - Outline : 轮廓，仅支持TTF

   *     - Glow    : 发光，仅支持TTF

   **/

      //阴影Shadow（阴影颜色，相对Label的偏移，模糊度）

      //注: 其中blurRadius在3.2中并未实现

      virtual void enableShadow(const Color4B& shadowColor = Color4B::BLACK,const Size &offset = Size(2,-2), int blurRadius = 0);

    

      //轮廓Outline，仅支持TTF（轮廓颜色，轮廓粗细）

      virtual void enableOutline(const Color4B& outlineColor,int outlineSize = -1);

    

      //发光Glow，仅支持TTF

      virtual void enableGlow(const Color4B& glowColor);

    

      //取消阴影/轮廓/发光渲染效果

      virtual void disableEffect();

    

    

  /**

   * 对齐方式

   *    > TextHAlignment : 水平对齐方式

   *        - TextHAlignment:LEFT    : 左对齐

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

   *        - TextHAlignment:RIGHT   : 右对齐

   *    > TextVAlignment : 垂直对齐方式

   *        - TextVAlignment::TOP    : 顶部，默认

   *        - TextVAlignment::CENTER : 中心

   *        - TextVAlignment::BOTTOM : 底部

   **/

      //设置对齐方式

      void setAlignment(TextHAlignment hAlignment) { setAlignment(hAlignment,_vAlignment);}

      void setAlignment(TextHAlignment hAlignment,TextVAlignment vAlignment);

      TextHAlignment getTextAlignment() const { return _hAlignment;}

    

      //设置水平对齐方式

      void setHorizontalAlignment(TextHAlignment hAlignment) { setAlignment(hAlignment,_vAlignment); }

      TextHAlignment getHorizontalAlignment() const { return _hAlignment; }

    

      //设置垂直对齐方式

      void setVerticalAlignment(TextVAlignment vAlignment) { setAlignment(_hAlignment,vAlignment); }

      TextVAlignment getVerticalAlignment() const { return _vAlignment; }

    

    

  /**

   * Label尺寸大小

   *     - setLineBreakWithoutSpace : 开启自动换行功能

   *     - setMaxLineWidth          : 文字内容的最大行宽

   *     - setWidth                 : Label尺寸大小，宽

   *     - setHeight                : Label尺寸大小，高

   *     - setDimensions            : Label尺寸大小

   **/

      //是否开启自动换行功能

      void setLineBreakWithoutSpace(bool breakWithoutSpace);

    

    

      //最大行宽，内容超过MaxLineWidth，就会自动换行

      //前提条件: 仅在width==0时，起作用。

      //  > width == 0;

      //  > setMaxLineWidth(lineWidth);

      //  > setLineBreakWithoutSpace(true);

      //它的效果与下面是类似的.

      //  > setWidth(lineWidth);

      //  > setLineBreakWithoutSpace(true);

      //只是width==0时，就无法设置文本的对齐方式了.

      void setMaxLineWidth(unsigned int maxLineWidth);

      unsigned int getMaxLineWidth() { return _maxLineWidth;}

    

    

      //设置Label的尺寸大小

      //可以理解为Label的文本框大小

      //当setLineBreakWithoutSpace(true)时，内容超过width，会自动换行

      //并且内容支持文本的对齐方式

      //注：设置尺寸大小，使用的是setDimensions，而不是setContentSize ！

      void setWidth(unsigned int width) { setDimensions(width,_labelHeight); }

      void setHeight(unsigned int height){ setDimensions(_labelWidth,height); }

      void setDimensions(unsigned int width,unsigned int height);

      unsigned int getWidth() const { return _labelWidth; }

      unsigned int getHeight() const { return _labelHeight; }  

      const Size& getDimensions() const{ return _labelDimensions; }

    

    

  /**

   * v3.2 新增

   *     - setLineHeight        : 设置行间距

   *     - setAdditionalKerning : 设置文字间距

   *     - getStringLength      : 字符串内容长度

   */

      //设置行间距，不支持system font

      void setLineHeight(float height);

      float getLineHeight() const;

    

      //设置文字间距，不支持system font

      void setAdditionalKerning(float space);

      float getAdditionalKerning() const;

    

      //获取Label的字符串内容长度

      int getStringLength() const;

    

    

  /**

   * 重写Node父类的方法

   *     - setBlendFunc   : 混合模式

   *     - setScale       : 放缩字体大小

   *     - addChild       : 添加子节点

   *     - getDescription : 显示Label的描述

   **/

      //设置颜色混合模式

      virtual void setBlendFunc(const BlendFunc &blendFunc) override;

    

      //放缩字体大小（一般用于CharMap、BMFont）

      virtual void setScale(float scale) override;

      virtual void setScaleX(float scaleX) override;

      virtual void setScaleY(float scaleY) override;

      virtual float getScaleX() const override;

      virtual float getScaleY() const override;

    

      //添加子节点

      virtual void addChild(Node * child, int zOrder=0, int tag=0) override;

      virtual void sortAllChildren() override;

    

      //Label描述

      virtual std::string getDescription() const override;

  };

  //
•