一个文本渲染解决方案 ![showCase1.gif](https://download.cocos.com/CocosStore/markdown/e0f8554a466049f9ab55e6a783d2afbd/e0f8554a466049f9ab55e6a783d2afbd.gif) ## 特性 - 基于SDF进行文本渲染，无损放大 - 支持最多8张纹理的BMFont - 导出参数合理，以及项目多语言种类不多的情况下，可以将项目中所有文本全部导出在一个字体文件中 - 一般来说，WebGL至少支持8个纹理单元，OpenGL至少支持16个纹理单元 - 支持颜色渐变 - 支持斜体 - 支持下划线、删除线 - 支持描边、镂空、阴影、辉光等特效，且这些特效会作用在下划线与删除线上 - 提供顶点数据接口，可以自由实现顶点动画 - 提供新的排版模式ELLIPSIS——当文本超出节点大小时，自动以"..."结尾 - 支持富文本 ## 版本支持目前经过测试的版本与系统如下，未列出的版本与系统仅表示暂未测试。 | Cocos Creator | [v2.4.9](https://github.com/LeeYip/cocos-text-mesh-pro/tree/v2.4.9) | [v3.6.0](https://github.com/LeeYip/cocos-text-mesh-pro/tree/v3.6.0) | | :-: | :-: | :-: | | Android | ✓ | ✓ | | Web | ✓ | ✓ | - **v2.4.9分支** - 此分支应该都可用于2.4.x系列版本，只不过2.4.5及以下版本中引擎源码材质hash值计算有bug，会导致某些情况下无法合批，请自行测试 - **v3.6.0分支** - 目前不支持低于3.6的版本，在3.6中引擎渲染实现有较大改动，故无法兼容 - 此分支对native的支持需要用cpp目录下的文件替换引擎源码中对应的c++文件 - Cocos Creator3.x的合批判断过于严格，只要不是同一个材质的引用，就不会合批。在JS层我做了一些hack的写法，修改了合批判断，使得相同uniform参数的材质实例得以合批。而native上的合批判断实现在c++层，暂未进行修改，所以目前如果希望将相同uniform参数的进行合批，请自行屏蔽掉组件内使用材质实例动态修改材质宏和uniform参数的代码，并尽可能的使用共享材质 ## 如何使用 #### 插件 ![plugin1.png](https://download.cocos.com/CocosStore/markdown/b8e7a95327ea4efd946ff37359c38968/b8e7a95327ea4efd946ff37359c38968.png) 插件中有两个选项，Font Tool为SDF字体生成工具。Import Assets为将TextMeshPro组件与材质等导入到assets目录下，若无法自动导入，请到插件目录下手动复制。 ![image.png](https://download.cocos.com/CocosStore/markdown/f93cbc1ec94d41e6af6d16d44da4e731/f93cbc1ec94d41e6af6d16d44da4e731.png) Font Tool界面如上图所示 - Hiero路径：字体导出依赖工具，点击下载按钮会进入下载地址，需要确保已安装Java环境才能运行此工具 - 源字体：需要导出的ttf字体文件 - 导出目录：SDF字体导出目录 - 导出名称：导出的SDF字体文件名 - 导出文本：可选择导出输入框内的文本或者导出txt文件内的文本 - 字体参数：Font Size为字体导出大小，Padding为字体间距，这两个参数大一些会对渲染效果好一点，但过大可能会导致导出的纹理数量过多，注意不可超出纹理上限 - 纹理参数：导出的纹理大小 - SDF Scale：此参数越大对最终渲染效果越好，但过大会导致字体导出过于缓慢。原理是导出字体前先对所有字体进行此值的放大，然后再生成SDF纹理，再将字体缩小为导出的Font Size进行导出。 - Save：保存插件配置 - Export：导出字体，生成运行时所需的json和png。期间会用命令行自动打开Hiero工具，导出过程根据设置的参数可能会非常缓慢，请耐心等待Hiero自行关闭。 #### 组件 ![compnent1.png](https://download.cocos.com/CocosStore/markdown/cc17e7c477d04f7e988c28211ad7727b/cc17e7c477d04f7e988c28211ad7727b.png)
组件参数如上图所示 - Font：使用Font Tool导出的字体json文件 - Overflow：除了Cocos Creator Label组件的排版方式之外，还提供了新的排版模式ELLIPSIS。会自动计算文本大小，若超出节点大小，则以"..."结尾（**字体导出文本中必须包含字符"."**） ![compnent2.gif](https://download.cocos.com/CocosStore/markdown/f89c86f9450a41798d35d4f9e969cb24/f89c86f9450a41798d35d4f9e969cb24.gif) - EnableItalic：斜体 - EnableUnderline：下划线，可调节高度（**字体导出文本中必须包含字符"_"**） - EnableStrikethrough：删除线，可调节高度（**字体导出文本中必须包含字符"_"**） - ColorGradient：颜色渐变开关，提供四个顶点的颜色设置，会和顶点颜色混合为最终的顶点颜色 ![compnent3.png](https://download.cocos.com/CocosStore/markdown/e45cfac2bb154080994b0756320d1ca2/e45cfac2bb154080994b0756320d1ca2.png) - TmpUniform：控制shader部分的参数，不同参数会影响TextMeshPro的合批 - FaceColor：文本主体的颜色 - FaceDilate：文本主体的粗细，范围0-1，0.5为标准值 - FaceSoftness：文本主体的柔和度，越小字体显示越硬，越大则会让字体显示越虚 ![compnent5.png](https://download.cocos.com/CocosStore/markdown/ab401e8d9ccd4d93b5f7df1b5059e499/ab401e8d9ccd4d93b5f7df1b5059e499.png) - EnableOutline：描边开关，配合FaceColor透明度可以实现文本镂空效果 ![compnent4.png](https://download.cocos.com/CocosStore/markdown/cdc8622dc1b64b07b32e5ed1bdb8e161/cdc8622dc1b64b07b32e5ed1bdb8e161.png) - OutlineColor：描边颜色 - OutlineThickness：描边厚度 - EnableUnderlay：阴影开关 ![compnent6.png](https://download.cocos.com/CocosStore/markdown/b22d5be3031e473e984f59b163df86a9/b22d5be3031e473e984f59b163df86a9.png) - UnderlayColor：阴影颜色 - UnderlayOffset：阴影偏移，如x方向偏移一个像素则需填入的值为1/纹理宽度，y方向同理 - UnderlayDilate：阴影厚度 - UnderlaySoftness：阴影柔和度 - EnableGlow：辉光开关，可以理解为在其他文本效果之上叠加一层描边，所以底下的颜色越暗效果越明显 ![compnent7.png](https://download.cocos.com/CocosStore/markdown/4b62b534cfe243fbab66a491f8ba695a/4b62b534cfe243fbab66a491f8ba695a.png) - GlowColor：辉光颜色 - GlowOffset：辉光偏移，范围0-1，0.5为标准值 - GlowInner：辉光向内的厚度 - GlowOuter：辉光向外的厚度 - GlowPower：辉光强度，范围0-1，1为最强 - Textures：字体依赖的纹理 #### API - **`forceUpdateRenderData(): void`** 立即更新渲染数据 - **`setFont(font: cc.JsonAsset, textures: cc.Texture2D[]): void`** 动态设置字体 - **`isVisible(index: number): boolean`** 根据字符下标判断此字符是否可见 - **`setVisible(index: number, visible: boolean): void`** 根据字符下标设置字符是否可见 - **`getColorExtraVertices(index: number): [cc.Color, cc.Color, cc.Color, cc.Color] | null`** 根据字符下标获取颜色顶点数据，顺序为[左下, 右下, 左上, 右上] - **`setColorExtraVertices(index: number, data: [cc.Color, cc.Color, cc.Color, cc.Color]): void`** 根据字符下标设置颜色顶点数据，会和节点颜色混合为最终的顶点颜色，顺序为[左下, 右下, 左上, 右上] - **`getPosVertices(index: number): [cc.Vec2, cc.Vec2, cc.Vec2, cc.Vec2] | null`** 根据字符下标获取坐标顶点数据，顺序为[左下, 右下, 左上, 右上] - **`setPosVertices(index: number, data: [cc.Vec2, cc.Vec2, cc.Vec2, cc.Vec2]): void`** 根据字符下标设置坐标顶点数据，顺序为[左下, 右下, 左上, 右上] ## 富文本 ![richtext.png](https://download.cocos.com/CocosStore/markdown/9edcec2512e04988a432146d72c1b463/9edcec2512e04988a432146d72c1b463.png) 如需使用富文本请使用**TmpRichText**组件，除粗体标签外支持全部Cocos的RichText组件的标签，且拓展支持了所有TextMeshPro具备的效果。 - 复杂文本情况下draw call会少于Cocos的RichText组件 - 内部对图片节点与文本节点做了分层处理，进一步减少了draw call **支持标签** | 名称 | 描述 | 示例 | 注意事项 | | :-: | :-: | :-: | :-: | | size | 字体渲染大小，大小值必须是一个整数 | \enlarge me\ | Size值必须使用等号赋值 | | color | 字体顶点颜色，颜色值可以是内置颜色，比如 white、black 等，也可以使用 16 进制颜色值，比如 #ff0000 表示红色 | \Red Text\ | | | cg | 启用字体颜色渐变，指定四个顶点的额外颜色，会与顶点色混合 | \color gradient\ | 默认值参考TextMeshPro组件 | | face | 文本主体颜色、厚度、柔和度 | \face\ | 默认值和取值范围请参考TextMeshPro组件face相关属性 | | i | 斜体 | \This text will be rendered as italic\ | | | u | 启用下划线，可指定下划线的偏移 | \This text will have a underline\ | 等号后面的值即下划线偏移值，默认值参考TextMeshPro组件underline相关属性 | | s | 启用删除线，可指定删除线的偏移 | \~~This text will have a strikethrough\~~ | 等号后面的值即删除线偏移值，默认值参考TextMeshPro组件strikethrough相关属性 | | outline | 字体的描边颜色和描边宽度 | \A label with outline\ | 默认值和取值范围请参考TextMeshPro组件outline相关属性 | | underlay | 字体的阴影颜色、偏移、厚度、柔和度 | \underlay\ | 默认值和取值范围请参考TextMeshPro组件underlay相关属性 | | glow | 字体辉光效果颜色、偏移、厚度 | \\glow\\ | 默认值和取值范围请参考TextMeshPro组件glow相关属性 | | on | 指定一个点击事件处理函数，当点击该 Tag 所在文本内容时，会调用该事件响应函数 | \ click me! \ | 除了 on 标签可以添加 click 属性，color 和 size 标签也可以添加，比如 \click me\ | | param | 当点击事件触发时，可以在回调函数的第二个参数获取该数值 | \ click me! \ | 依赖 click 事件 | | br | 插入一个空行 | \
| 注意：\
\
和 \
都是不支持的。 | | img | 给富文本添加图文混排功能，img 的 src 属性必须是 ImageAtlas 图集里面的一个有效的 spriteframe 名称 | \

| 规则与Cocos的RichText组件一致 | ## 注意事项 - 由于Cocos Creator不同版本引擎渲染实现差异过大，故针对不同版本需单独实现，后续若有新增支持的版本请在[GitHub](https://github.com/LeeYip/cocos-text-mesh-pro)仓库对应分支中查看。 - 切勿将字体纹理打入图集中 - 暂不提供控制下划线与删除线的顶点数据 - 个人时间精力有限，难免会出现疏漏，使用前请自行充分测试 ## 如何联系 - [GitHub](https://github.com/LeeYip/cocos-text-mesh-pro) - [官方论坛](https://forum.cocos.org/t/topic/138765)