From 5996ecf5f36a21f7b26b779be40dda189f575258 Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Sat, 21 Mar 2026 14:43:55 +0800
Subject: [PATCH] =?UTF-8?q?docs(core):=20=E6=B7=BB=E5=8A=A0=E5=86=85?=
 =?UTF-8?q?=E7=BD=AE=E6=95=B0=E5=80=BC=E6=98=BE=E7=A4=BA=E5=B7=A5=E5=85=B7?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增内置数值显示工具使用说明
- 提供 FormatCompact 和 ToCompactString 示例代码
- 展示 NumericFormatOptions 配置选项用法
- 介绍本地化文本中的数值格式化功能
- 更新相关链接列表移除多余逗号
---
 docs/zh-CN/core/utility.md | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/docs/zh-CN/core/utility.md b/docs/zh-CN/core/utility.md
index 60a9f1d..37f199e 100644
--- a/docs/zh-CN/core/utility.md
+++ b/docs/zh-CN/core/utility.md
@@ -365,6 +365,42 @@ public class EncryptionUtility : IUtility
 }
 ```
 
+### 内置数值显示工具
+
+对于 UI 中常见的数值缩写显示，优先使用 `GFramework.Core` 提供的数值显示工具，而不是在业务层重复拼接字符串。
+
+```csharp
+using System.Globalization;
+using GFramework.Core.Abstractions.Utility.Numeric;
+using GFramework.Core.Extensions;
+using GFramework.Core.Utility.Numeric;
+
+var gold = NumericDisplay.FormatCompact(1250);             // "1.3K"
+var damage = 15320.ToCompactString();                      // "15.3K"
+
+var exact = NumericDisplay.Format(1234.56m, new NumericFormatOptions
+{
+    MaxDecimalPlaces = 2,
+    FormatProvider = CultureInfo.InvariantCulture
+}); // "1.23K"
+
+var grouped = NumericDisplay.Format(12345, new NumericFormatOptions
+{
+    CompactThreshold = 1000000m,
+    UseGroupingBelowThreshold = true,
+    FormatProvider = CultureInfo.InvariantCulture
+}); // "12,345"
+```
+
+如果你在本地化文本中展示数值，也可以直接使用内置 formatter：
+
+```json
+{
+  "status.gold": "Gold: {gold:compact}",
+  "status.damage": "Damage: {damage:compact:maxDecimals=2}"
+}
+```
+
 ### 5. 对象池工具
 
 ```csharp
@@ -610,4 +646,4 @@ public class CollectionUtility : IUtility
 - [`command`](./command.md) - Command 中可以使用 Utility
 - [`architecture`](./architecture.md) - 在架构中注册 Utility
 - [`ioc`](./ioc.md) - Utility 通过 IoC 容器管理
-- [`extensions`](./extensions.md) - 提供 GetUtility 扩展方法
\ No newline at end of file
+- [`extensions`](./extensions.md) - 提供 GetUtility 扩展方法