unity-textmeshpro
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseUnity TextMeshPro - Professional Text Rendering
Unity TextMeshPro - 专业文本渲染
Overview
概述
TextMeshPro (TMPro) is Unity's advanced text rendering solution using Signed Distance Field (SDF) technology for resolution-independent, high-quality text with minimal performance overhead.
Foundation Required: (TryGetComponent, FindAnyObjectByType), (UI systems, Canvas, UGUI)
unity-csharp-fundamentalsunity-uiCore Topics:
- SDF font asset creation and configuration
- Dynamic vs static font assets
- Rich text formatting and styling
- Material presets and text effects
- Performance optimization patterns
- Localization and dynamic text handling
TextMeshPro（TMPro）是Unity的高级文本渲染解决方案，采用Signed Distance Field（SDF）技术，可生成与分辨率无关的高质量文本，且性能开销极低。
基础要求：（TryGetComponent、FindAnyObjectByType），（UI系统、Canvas、UGUI）
unity-csharp-fundamentalsunity-ui核心主题：
- SDF字体资源创建与配置
- 动态与静态字体资源
- 富文本格式与样式
- 材质预设与文本效果
- 性能优化模式
- 本地化与动态文本处理
Quick Start
快速开始
Basic Text Setup
基础文本设置
csharp
using TMPro;
using UnityEngine;
public class TextController : MonoBehaviour
{
[SerializeField] private TMP_Text mDisplayText;
void Start()
{
mDisplayText.text = "Hello, World!";
mDisplayText.fontSize = 36;
mDisplayText.color = Color.white;
}
}csharp
using TMPro;
using UnityEngine;
public class TextController : MonoBehaviour
{
[SerializeField] private TMP_Text mDisplayText;
void Start()
{
mDisplayText.text = "Hello, World!";
mDisplayText.fontSize = 36;
mDisplayText.color = Color.white;
}
}TMP_Text vs TextMeshProUGUI vs TextMeshPro
TMP_Text、TextMeshProUGUI与TextMeshPro的区别
csharp
// TMP_Text - Base class, use for serialization (works with both)
[SerializeField] private TMP_Text mText;
// TextMeshProUGUI - Canvas UI text (most common)
[SerializeField] private TextMeshProUGUI mUiText;
// TextMeshPro - 3D world space text (MeshRenderer)
[SerializeField] private TextMeshPro mWorldText;csharp
// TMP_Text - 基类，用于序列化（兼容两种类型）
[SerializeField] private TMP_Text mText;
// TextMeshProUGUI - 画布UI文本（最常用）
[SerializeField] private TextMeshProUGUI mUiText;
// TextMeshPro - 3D世界空间文本（MeshRenderer）
[SerializeField] private TextMeshPro mWorldText;Rich Text Formatting
富文本格式
csharp
// Basic formatting
text.text = "<b>Bold</b> and <i>Italic</i>";
text.text = "<size=48>Large</size> and <size=24>Small</size>";
text.text = "<color=#FF0000>Red</color> text";
// Advanced formatting
text.text = "<mark=#FFFF00AA>Highlighted</mark>";
text.text = "H<sub>2</sub>O and E=mc<sup>2</sup>";
text.text = "<s>Strikethrough</s> and <u>Underline</u>";
// Sprite embedding
text.text = "Score: 100 <sprite=0>";csharp
// 基础格式
text.text = "<b>加粗</b> 和 <i>斜体</i>";
text.text = "<size=48>大号</size> 和 <size=24>小号</size>";
text.text = "<color=#FF0000>红色</color> 文本";
// 高级格式
text.text = "<mark=#FFFF00AA>高亮</mark>";
text.text = "H<sub>2</sub>O 和 E=mc<sup>2</sup>";
text.text = "<s>删除线</s> 和 <u>下划线</u>";
// 嵌入精灵
text.text = "得分: 100 <sprite=0>";Component Selection Guide
组件选择指南
| Scenario | Component | Reason |
|---|---|---|
| UI Canvas text | TextMeshProUGUI | Canvas integration, auto-batching |
| 3D world labels | TextMeshPro | MeshRenderer, world-space |
| Serialized reference | TMP_Text | Works with both types |
| Input field | TMP_InputField | Built-in input handling |
| Dropdown | TMP_Dropdown | Built-in dropdown UI |
| 场景 | 组件 | 原因 |
|---|---|---|
| UI画布文本 | TextMeshProUGUI | 画布集成、自动批处理 |
| 3D世界标签 | TextMeshPro | 网格渲染器、世界空间 |
| 序列化引用 | TMP_Text | 兼容两种类型 |
| 输入框 | TMP_InputField | 内置输入处理 |
| 下拉菜单 | TMP_Dropdown | 内置下拉菜单UI |
Font Asset Best Practices
字体资源最佳实践
Font Asset Types
字体资源类型
Static Font Asset:
- Pre-generated character set
- Best performance (no runtime generation)
- Use for: Known character sets, optimized builds
Dynamic Font Asset:
- Runtime character generation
- Flexible but slower initial render
- Use for: Localization, user input, unknown characters静态字体资源：
- 预生成字符集
- 性能最佳（无运行时生成）
- 适用场景：已知字符集、优化构建
动态字体资源：
- 运行时生成字符
- 灵活但初始渲染速度较慢
- 适用场景：本地化、用户输入、未知字符Creating Optimal Font Assets
创建最优字体资源
-
Font Asset Creator (Window > TextMeshPro > Font Asset Creator)
- Set appropriate Atlas Resolution (1024x1024 for basic, 2048x2048 for CJK)
- Use "Custom Character List" for known character sets
- Enable Multi Atlas Textures for large character sets
-
Sampling Point Size: Use highest size that fits atlas (better quality)
-
Padding: 5-9 for normal use, higher for effects (outline, glow)
-
字体资源创建工具（Window > TextMeshPro > Font Asset Creator）
- 设置合适的图集分辨率（基础场景用1024x1024，中日韩等大字符集用2048x2048）
- 针对已知字符集使用「自定义字符列表」
- 大字符集启用「多图集纹理」
-
采样点大小：使用能容纳在图集中的最大尺寸（质量更好）
-
内边距：常规使用5-9，效果（轮廓、发光）需要更大值
Performance Guidelines
性能指南
Text Update Optimization
文本更新优化
csharp
// BAD: Frequent text changes trigger mesh rebuild
void Update()
{
scoreText.text = $"Score: {score}"; // Rebuilds every frame
}
// GOOD: Update only when value changes
private int mLastScore = -1;
void Update()
{
if (score != mLastScore)
{
mLastScore = score;
scoreText.text = $"Score: {score}";
}
}
// BETTER: Use SetText for formatted updates (less allocation)
void UpdateScore(int score)
{
scoreText.SetText("Score: {0}", score);
}csharp
// 不良写法：频繁修改文本会触发网格重建
void Update()
{
scoreText.text = $"Score: {score}"; // 每帧都会重建
}
// 良好写法：仅在值变化时更新
private int mLastScore = -1;
void Update()
{
if (score != mLastScore)
{
mLastScore = score;
scoreText.text = $"Score: {score}";
}
}
// 更优写法：使用SetText进行格式化更新（更少内存分配）
void UpdateScore(int score)
{
scoreText.SetText("Score: {0}", score);
}Memory-Efficient Patterns
内存高效模式
csharp
// Use StringBuilder for complex text construction
private readonly StringBuilder mSb = new StringBuilder(256);
void BuildComplexText()
{
mSb.Clear();
mSb.Append("Player: ");
mSb.Append(playerName);
mSb.Append(" | Score: ");
mSb.Append(score);
displayText.SetText(mSb);
}
// Prefer SetText with parameters over string interpolation
text.SetText("{0}/{1}", currentHP, maxHP); // Less GC
// Instead of
text.text = $"{currentHP}/{maxHP}"; // More GCcsharp
// 使用StringBuilder构建复杂文本
private readonly StringBuilder mSb = new StringBuilder(256);
void BuildComplexText()
{
mSb.Clear();
mSb.Append("玩家: ");
mSb.Append(playerName);
mSb.Append(" | 得分: ");
mSb.Append(score);
displayText.SetText(mSb);
}
// 优先使用带参数的SetText而非字符串插值
text.SetText("{0}/{1}", currentHP, maxHP); // 更少GC
// 而不是
text.text = $"{currentHP}/{maxHP}"; // 更多GCMaterial Presets
材质预设
csharp
// Apply material preset at runtime
[SerializeField] private Material mHighlightMaterial;
[SerializeField] private Material mNormalMaterial;
void Highlight(bool active)
{
mText.fontMaterial = active ? mHighlightMaterial : mNormalMaterial;
}
// Modify material properties
mText.fontMaterial.SetFloat(ShaderUtilities.ID_OutlineWidth, 0.2f);
mText.fontMaterial.SetColor(ShaderUtilities.ID_OutlineColor, Color.black);csharp
// 运行时应用材质预设
[SerializeField] private Material mHighlightMaterial;
[SerializeField] private Material mNormalMaterial;
void Highlight(bool active)
{
mText.fontMaterial = active ? mHighlightMaterial : mNormalMaterial;
}
// 修改材质属性
mText.fontMaterial.SetFloat(ShaderUtilities.ID_OutlineWidth, 0.2f);
mText.fontMaterial.SetColor(ShaderUtilities.ID_OutlineColor, Color.black);Reference Documentation
参考文档
Fundamentals
基础概念
Core TextMeshPro concepts:
- SDF technology explanation
- Font asset creation workflow
- Character sets and fallback fonts
- Sprite assets integration
- Style sheets usage
核心TextMeshPro概念：
- SDF技术详解
- 字体资源创建流程
- 字符集与回退字体
- 精灵资源集成
- 样式表使用
Performance Optimization
性能优化
Optimization techniques:
- Mesh geometry optimization
- Dynamic batching strategies
- Font atlas memory management
- Text update minimization patterns
- Profiling text rendering
优化技巧：
- 网格几何优化
- 动态批处理策略
- 字体图集内存管理
- 文本更新最小化模式
- 文本渲染性能分析
Advanced Patterns
高级模式
Advanced usage patterns:
- Custom shaders and effects
- Text animation techniques
- Localization integration
- Typewriter effects
- Link and event handling
高级使用模式：
- 自定义着色器与效果
- 文本动画技术
- 本地化集成
- 打字机效果
- 链接与事件处理
Key Principles
核心原则
- Use TMP_Text for References: Base class works with both UI and 3D text
- Prefer SetText() over .text: Reduces GC allocations for dynamic values
- Update Only When Changed: Avoid unnecessary mesh rebuilds
- Choose Appropriate Font Assets: Static for performance, Dynamic for flexibility
- Batch Similar Text: Group text with same material for draw call reduction
- 使用TMP_Text作为引用：基类兼容UI和3D文本
- 优先使用SetText()而非.text：减少动态值的GC分配
- 仅在变化时更新：避免不必要的网格重建
- 选择合适的字体资源：静态资源追求性能，动态资源追求灵活性
- 批量相似文本：将使用相同材质的文本分组以减少绘制调用
Common Anti-Patterns
常见反模式
csharp
// AVOID: Creating new materials per text instance
text.fontMaterial = new Material(text.fontMaterial); // Memory leak risk
// AVOID: Updating text in Update() without change check
void Update() { text.text = score.ToString(); } // Constant rebuild
// AVOID: Excessive rich text nesting
text.text = "<b><i><color=#FF0000><size=48>...</size></color></i></b>";
// AVOID: Dynamic fonts for static content
// Use pre-generated static font assets insteadcsharp
// 避免：为每个文本实例创建新材质
text.fontMaterial = new Material(text.fontMaterial); // 存在内存泄漏风险
// 避免：在Update()中无检查地更新文本
void Update() { text.text = score.ToString(); } // 持续重建
// 避免：过度嵌套富文本
text.text = "<b><i><color=#FF0000><size=48>...</size></color></i></b>";
// 避免：静态内容使用动态字体
// 改用预生成的静态字体资源Platform Considerations
平台注意事项
- Mobile: Use static font assets, minimize atlas size, avoid complex effects
- WebGL: Pre-load font assets, avoid dynamic font generation
- VR/AR: Consider text readability, use larger fonts, avoid thin outlines
- 移动端：使用静态字体资源，最小化图集尺寸，避免复杂效果
- WebGL：预加载字体资源，避免动态字体生成
- VR/AR：考虑文本可读性，使用更大字体，避免细轮廓
Integration with Other Skills
与其他技能的集成
- unity-ui: TextMeshPro integrates with Canvas and UI Toolkit
- unity-performance: Text rendering impacts draw calls and memory
- unity-mobile: Font asset optimization critical for mobile
- unity-async: Async font loading with Addressables
- unity-ui：TextMeshPro与Canvas和UI Toolkit集成
- unity-performance：文本渲染影响绘制调用和内存
- unity-mobile：字体资源优化对移动端至关重要
- unity-async：使用Addressables进行异步字体加载