wow-api-widget

WoW Widget API（精选）

本技能介绍 World of Warcraft Retail 的 Widget API，内容经过精选，重点介绍最常用的核心类型、方法和模式。如需完整列表，请查看源链接。

事实来源：https://warcraft.wiki.gg/wiki/Widget_API 脚本处理器：https://warcraft.wiki.gg/wiki/Widget_script_handlers XML 架构：https://warcraft.wiki.gg/wiki/XML_schema 截至版本：Patch 12.0.0（Retail）

何时使用此技能

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

• 创建或操作 UI 框架（CreateFrame、Frame:SetPoint、Frame:Show）
• 使用纹理和视觉区域（Texture:SetTexture、TextureBase:SetAtlas）
• 处理字体字符串和文本显示（FontString:SetText、FontInstance:SetFont）
• 构建动画（AnimationGroup:Play、Animation:SetDuration）
• 管理工具提示（GameTooltip:SetOwner、GameTooltip:AddLine）
• 处理按钮和交互控件（Button:SetText、EditBox:SetText、Slider:SetValue）
• 使用状态栏和冷却计时器（StatusBar:SetValue、Cooldown:SetCooldown）
• 使用模型框架进行 3D 显示（Model:SetModel、ModelScene:CreateActor）
• 锚定、调整大小、显示或隐藏 UI 元素，并设置父级
• 为框架注册事件（Frame:RegisterEvent、Frame:RegisterUnitEvent）
• 设置脚本处理器（ScriptObject:SetScript、ScriptObject:HookScript）

Widget 层级（简表）

FrameScriptObject
  Object
    ScriptObject
      ScriptRegion (+ ScriptRegionResizing + AnimatableObject)
        Region
          TextureBase -> Texture, MaskTexture, Line
          FontString (+ FontInstance)
        Frame (+ FontInstance)
          Button -> CheckButton
          EditBox, MessageFrame, ScrollFrame, Slider, StatusBar, Cooldown
          GameTooltip, SimpleHTML, ColorSelect, MovieFrame
          Model -> PlayerModel -> CinematicModel, DressUpModel -> TabardModel
          ModelScene -> ModelSceneActor

AnimationGroup -> Animation -> Alpha, Rotation, Scale, Translation, Path, FlipBook
Font (FrameScriptObject + FontInstance)

如何使用此技能

1. 确定你要使用的 Widget 类型（例如：Frame、Texture、Button）。
2. 查看上方层级，找出它继承的基类型。
3. 打开相关参考文件，查看核心方法和示例。
4. 如需完整方法列表，请查看源链接。

参考文件

参考资料	内容
BASE-WIDGETS.md	基类型、锚定、输入、脚本、可见性
TEXTURE-WIDGETS.md	TextureBase、Texture、MaskTexture、Line
FONT-WIDGETS.md	FontInstance、Font、FontString
ANIMATION-WIDGETS.md	AnimationGroup、Animation、Alpha、Rotation、Scale、Translation、Path
FRAME-WIDGETS.md	Frame 的核心行为、事件、层级、移动
FRAME-CONTROLS.md	Button、CheckButton、EditBox、ScrollFrame、Slider、StatusBar、Cooldown、MessageFrame、SimpleHTML
ADVANCED-WIDGETS.md	GameTooltip、Model/PlayerModel、ModelScene、ColorSelect、MovieFrame

核心模式

创建和锚定

local frame = CreateFrame("Frame", "MyFrame", UIParent, "BackdropTemplate")
frame:SetSize(240, 120)
frame:SetPoint("CENTER")

local title = frame:CreateFontString(nil, "OVERLAY", "GameFontNormal")
title:SetPoint("TOP", 0, -12)
title:SetText("Hello")

事件和脚本

local f = CreateFrame("Frame")
f:RegisterEvent("PLAYER_LOGIN")
f:SetScript("OnEvent", function(self, event)
    print("Ready", event)
end)

按钮

local btn = CreateFrame("Button", nil, UIParent, "UIPanelButtonTemplate")
btn:SetSize(120, 32)
btn:SetPoint("CENTER")
btn:SetText("Click")
btn:RegisterForClicks("AnyUp")
btn:SetScript("OnClick", function(self, button)
    print("Clicked", button)
end)

动画

local ag = frame:CreateAnimationGroup()
local fade = ag:CreateAnimation("Alpha")
fade:SetFromAlpha(0)
fade:SetToAlpha(1)
fade:SetDuration(0.25)
ag:Play()

XML 架构快速入门

<Ui>
  <Frame name="MyXmlFrame" parent="UIParent" hidden="true">
    <Size x="240" y="120"/>
    <Anchors>
      <Anchor point="CENTER"/>
    </Anchors>
    <Scripts>
      <OnLoad>
        self:RegisterEvent("PLAYER_LOGIN")
      </OnLoad>
      <OnEvent>
        print(event)
      </OnEvent>
    </Scripts>
  </Frame>
</Ui>

脚本处理器速查

• ScriptRegion：OnShow、OnHide、OnEnter、OnLeave、OnMouseDown、OnMouseUp、OnMouseWheel
• Frame：OnEvent、OnUpdate、OnSizeChanged、OnDragStart、OnDragStop、OnKeyDown、OnKeyUp
• Button：OnClick、OnDoubleClick、PreClick、PostClick
• EditBox：OnTextChanged、OnEnterPressed、OnEscapePressed、OnTabPressed
• Slider/StatusBar：OnValueChanged、OnMinMaxChanged
• AnimationGroup/Animation：OnPlay、OnStop、OnFinished、OnUpdate

如需按 Widget 类型划分的完整处理器列表，请参阅 https://warcraft.wiki.gg/wiki/Widget_script_handlers。

专用 Widget（摘要）

有关高级 Widget（GameTooltip、Model、ModelScene、ColorSelect、MovieFrame），请参阅 ADVANCED-WIDGETS.md。 如需完整方法列表和专用 Widget 详情，请查看 Widget API 页面。

安全注解

API 参考中标注的方法有使用限制：

• #protected - 仅限 Blizzard 安全代码使用。
• #secureframe - 战斗期间无法在受保护的框架上调用。
• #nocombat - 战斗锁定期间无法调用。
• #restrictedframe - 战斗期间，不安全代码访问受保护的框架时返回 nil。
• #anchorfamily - 适用锚点族限制。

来源

• https://warcraft.wiki.gg/wiki/Widget_API
• https://warcraft.wiki.gg/wiki/Widget_script_handlers
• https://warcraft.wiki.gg/wiki/XML_schema