wow-api-escape-sequences

WoW UI 转义序列

本技能介绍《魔兽世界》插件开发中可用的 UI 转义序列。许多可在屏幕上显示文本的 UI 元素都支持以 |（竖线）字符开头的特殊序列。这些序列可在普通 Lua 字符串中实现内嵌着色、纹理／图集渲染、语法变形、换行提示等功能。

权威来源： https://warcraft.wiki.gg/wiki/UI_escape_sequences 截至版本： 补丁 12.0.0（仅正式服） 范围： WoW UI 文本渲染器可识别的所有 | 转义序列。

何时使用本技能

在以下情况下使用本技能：

• 在聊天消息、工具提示或 FontString 中嵌入颜色代码
• 使用命名全局颜色（|cn）或物品品质颜色（|cnIQ）
• 在文本中插入内嵌纹理或图集图标
• 应用本地化语法规则（韩语、法语、俄语、复数、冠词）
• 了解换行提示（|W）或 Kstring 混淆（|K）
• 使用 WrapTextInColorCode()、CreateTextureMarkup()、CreateSimpleTextureMarkup() 或 CreateAtlasMarkup() 等辅助函数

与其他技能的关系

技能	关系
wow-api-framexml	介绍从 Lua 生成转义序列标记的实用函数（WrapTextInColorCode、CreateTextureMarkup、CreateSimpleTextureMarkup、CreateAtlasMarkup）。
wow-api-widget	FontString、EditBox、SimpleHTML、GameTooltip 及其他显示文本的小部件会渲染这些序列。
wow-lua-api	Lua 的 string.format、print() 和聊天函数会输出可能包含这些序列的字符串。

---

重要：竖线字符

在 Lua 源代码中可以直接使用 |：

print("|cFFFF0000Red text|r normal")

在聊天窗口或游戏内文本编辑器中，必须对字面量 | 进行转义。请改用 \124（竖线的 ASCII 码）：

/run print("\124cFFFF0000Red text\124r normal")

---

着色

ARGB 十六进制颜色

|cAARRGGBBtext|r

• AA — Alpha（当前会被忽略；始终使用 FF）。
• RR GG BB — 红、绿、蓝通道，每个通道各用两位十六进制数字表示。
• |r — 弹出最近添加的颜色，恢复到前一个颜色（自补丁 9.0.1 起）。此前，它会完全重置为默认颜色。

嵌套示例：

print("white |cFFFF0000red |cFF00FF00green|r back to red|r back to white")

全局命名颜色（|cn）

|cnCOLOR_NAME:text|r

使用命名的 GlobalColor 为 text 着色。颜色名称来自 GlobalColor 数据库表。

print("|cnPURE_GREEN_COLOR:Green text|r normal")

物品品质颜色（|cnIQ）

|cnIQn:text|r

使用物品品质 n 对应的颜色渲染 text，其中 n 是数值型 Enum.ItemQuality 值（0 = 粗糙／灰色，1 = 普通／白色，2 = 优秀／绿色，3 = 精良／蓝色，4 = 史诗／紫色，5 = 传说／橙色，……）。颜色会根据用户的颜色覆盖设置更新。

print("|cnIQ4:Epic quality text|r")

命名颜色（|cn）于补丁 10.0.0 添加；|cnIQ 于补丁 11.1.5 添加。

---

纹理

内嵌纹理

|Tpath:height[:width[:offsetX:offsetY[:textureWidth:textureHeight:leftTexel:rightTexel:topTexel:bottomTexel[:rVertexColor:gVertexColor:bVertexColor]]]]|t

在 FontString 中插入图像。path 可以是文件路径（使用 / 或 \\ 分隔），也可以是数字 FileDataID。

尺寸规则

height	width	结果
0	省略	文本行高的正方形图标（TextHeight × TextHeight）
> 0	省略	正方形图标（height × height）
0	0	边长为 TextHeight 的正方形
> 0	0	宽为 TextHeight，高为 height
0	> 0	将 width 视为纵横比：Width = width × TextHeight，Height = TextHeight
> 0	> 0	明确指定 width × height

可选参数

参数	用途
offsetX、offsetY	相对于自然位置的像素偏移
textureWidth、textureHeight	源图像的像素尺寸
leftTexel、rightTexel、topTexel、bottomTexel	以像素为单位的裁剪坐标（未归一化的 x1 x2 y1 y2；参见 Texture:SetTexCoord）
rVertexColor、gVertexColor、bVertexColor	RGB 着色值，每项为 0–255

常见模式

-- Square icon at text size (most common for spell/item icons)
"|T133784:0|t"
"|TInterface/Icons/INV_Misc_Coin_01:0|t"

-- Explicit 16×16 icon
"|TInterface/Icons/INV_Misc_Coin_01:16|t"

-- Rectangular image with aspect ratio
"|TInterface/Glues/LoadingBar/Loading-BarFill:0:2|t"

-- Cropped texture (4px border removed from a 64×64 source)
"|TInterface/Icons/INV_Misc_Coin_01:16:16:0:0:64:64:4:60:4:60|t"

-- Tinted texture (green tint: 73,177,73)
"|TInterface/ChatFrame/UI-ChatIcon-ArmoryChat:14:14:0:0:16:16:0:16:0:16:73:177:73|t"

纹理图集

|A:atlas:height:width[:offsetX:offsetY[:rVertexColor:gVertexColor:bVertexColor]]|a

插入纹理图集区域。atlas 可以是名称字符串，也可以是数字图集 ID。注意 |A 后面的 :。

-- Atlas by name
"|A:groupfinder-icon-role-large-tank:19:19|a Tank"

-- Atlas by numeric ID
"|A:4259:19:19|a Tank"

另请参阅：AtlasID

---

Kstrings

|Kq1|k

Kstrings 是不透明的字符串占位符，可防止插件解析机密或受保护的文本。客户端会将其渲染为实际显示字符串，但插件无法将其作为纯文本读取。

前缀	用法
q	Battle.net 账号名称（C_BattleNet.GetFriendAccountInfo）
r	组队查找器列表名称／评论（C_LFGList.GetSearchResultInfo、C_LFGList.GetActiveEntryInfo）
u	社区消息内容（C_Club.GetMessageInfo、C_Club.GetMessagesInRange）
v	社区频道聊天（CHAT_MSG_COMMUNITIES_CHANNEL 事件）

在 Patch 4.0.1 中新增。

---

语法／本地化序列

这些序列用于处理特定语言的词形变化，使单个本地化字符串能够生成语法正确的输出。

|1 — 韩语助词

text|1A;B;

选择助词 A（后接辅音）或 B（后接元音）。

print("라면|1을;를;")  -- 라면을 (ramyeoneul)
print("나무|1을;를;")  -- 나무를 (namureul)

|2 — 法语介词

|2 text

辅音前输出 de text，元音前输出 d'text。|2 后面的尾随空格会被忽略。

print("|2 fraise") -- de fraise
print("|2 avion")  -- d'avion

|3 — 俄语名词变格

|3-id(text)

将俄语名词变为 5 种格之一（id = 1–5）。

print("|3-1(Кролик)") -- Кролика   (Genitive)
print("|3-2(Кролик)") -- Кролику   (Dative)
print("|3-3(Кролик)") -- Кролика   (Accusative)
print("|3-4(Кролик)") -- Кроликом  (Instrumental)
print("|3-5(Кролик)") -- Кролике   (Prepositional)

另请参阅：DeclineName() API。

|4 — 复数形式

number |4singular:plural;
number |4singular:plural1:plural2;   -- ruRU has three forms

根据前面的数字选择单数或复数。

print("1 |4car:cars;")      -- 1 car
print("2 |4car:cars;")      -- 2 cars
print("3 blue |4car:cars;") -- 3 blue cars

|7 — 复数（大数字／非英语语言）

行为与 |4 相同，但专用于某些非英语区域设置中的大数字。

print("1 |7Million:Millionen;") -- 1 Million
print("2 |7Million:Millionen;") -- 2 Millionen

|5 — 不定冠词（a／an）

|5 text
|5^ text   -- uppercase article

辅音发音前插入 a，元音发音前插入 an。

print("|5 banana")  -- a banana
print("|5 apple")   -- an apple
print("|5^ apple")  -- An apple

|6 — 转为小写

|6 TEXT
|6(TEXT MORE)

将下一个单词（或括号括起的内容）转为小写。

print("|6 HELLO WORLD")  -- hello WORLD
print("|6(HELLO WORLD)") -- hello world

---

自动换行

|Wtext|w

提示括起的 text 不应被拆分到多行。如果文本需要换行，客户端会优先在 |W 起始标记之前换行，而不是在其中间拆分。如果文本仍然过宽，则可能会忽略此提示。

在 Patch 5.4.1 中新增。

---

其他序列

序列	效果
|n	换行（如果控件支持）。等同于 \n 或 \r。
||	字面管道字符 |。
任何无效的 |X	原样显示（行为未定义）。

---

实用函数（FrameXML）

这些 FrameXML 辅助函数会生成转义序列标记：

函数	输出
WrapTextInColorCode(text, colorHexString)	|cFFRRGGBBtext|r
CreateTextureMarkup(file, fileW, fileH, width, height, left, right, top, bottom)	|T...|t，包含纹理坐标
CreateSimpleTextureMarkup(file, width, height)	|Tfile:height:width|t
CreateAtlasMarkup(atlasName, height, width, offsetX, offsetY)	|A:atlas:height:width:...|a

-- Color a string red
WrapTextInColorCode("Critical!", "FFFF0000")
-- "|cFFFF0000Critical!|r"

-- Inline 16×16 coin icon
CreateSimpleTextureMarkup("Interface/Icons/INV_Misc_Coin_01", 16, 16)
-- "|TInterface/Icons/INV_Misc_Coin_01:16:16|t"

-- Atlas tank icon
CreateAtlasMarkup("groupfinder-icon-role-large-tank", 16, 16)
-- "|A:groupfinder-icon-role-large-tank:16:16|a"

---

补丁历史

补丁	变更
11.1.5	新增 |cnIQ 物品品质颜色序列。
10.0.0	新增 |cn 命名颜色序列。
9.0.1	|r 现在会按顺序弹出嵌套颜色，而不是重置为默认颜色。
5.4.1	新增 |W 自动换行提示。
4.0.1	新增 |K Kstrings。

---

另请参阅

• 超链接 — 相关的管道符分隔链接序列（|H...|h...|h）。
• wow-api-framexml 技能 — 详细介绍 WrapTextInColorCode、CreateTextureMarkup、CreateSimpleTextureMarkup、CreateAtlasMarkup。
• wow-api-widget 技能 — 介绍会渲染这些序列的 FontString、GameTooltip 和其他控件。