wow-api-xml-schema

WoW XML Schema

本文档介绍 World of Warcraft 插件开发的 XML Schema。XML 文件以声明方式定义用户界面元素——框体、纹理、字体字符串、字体和动画。虽然大多数 UI 功能也可通过 Lua 中的 Widget API 实现，但 XML 提供了一种结构化方式来定义布局、模板和控件层级。

权威来源： https://warcraft.wiki.gg/wiki/XML_schema XSD 文件： https://raw.githubusercontent.com/Gethe/wow-ui-source/live/Interface/AddOns/Blizzard_SharedXML/UI.xsd 截至版本： Patch 12.0.0（仅限 Retail） 范围： WoW 插件 .xml 文件中使用的所有 XML 元素和属性。

何时使用此技能

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

• 编写或阅读 WoW 插件 .xml UI 定义文件
• 在 XML 中定义框体、纹理、字体字符串或动画
• 设置 XML 虚拟模板（virtual="true"）和继承（inherits=""）
• 了解哪些 XML 属性对应哪些 Lua API 调用
• 在 XML 中配置锚点、层、脚本、键值或调整大小边界
• 使用正确的命名空间声明设置 <Ui> 根元素
• 使用 <Include> 和 <Script> 标签从 XML 加载文件
• 定义 <Font> 或 <FontFamily> 对象以设置文本样式
• 以声明方式创建动画组和动画
• 构建内置框体（intrinsic="true"）
• 了解 XML 元素的继承层级（例如，Button 继承自 Frame，而 Frame 继承自 LayoutFrame）

与其他技能的关系

技能	关系
wow-api-widget	介绍在控件上调用的 Lua 侧 Widget API 方法。本技能介绍 XML 侧的声明式定义。许多 XML 属性都直接对应 Widget API 方法。
wow-addon-structure	介绍 .toc 文件格式和插件加载方式。XML 文件列在 .toc 中，并按顺序加载。
wow-api-framexml	介绍 FrameXML 辅助函数和 mixin。XML 的 mixin 和 secureMixin 属性引用了该文档中介绍的 Lua mixin。
wow-lua-api	介绍 Lua 5.1 环境。<Script> 标签会在该环境中执行 Lua 代码。

控件层级（XML 元素）

<Ui>                          -- Root element; encloses all other tags
├── <Include />               -- Loads another .xml or .lua file
├── <Script />                -- Executes inline or file-based Lua code
├── <Font />                  -- Defines a reusable font object
├── <FontFamily />            -- Defines fonts per alphabet/locale
│
├── <LayoutFrame>             -- Abstract base: name, anchors, size, keyvalues, animations
│   ├── <Texture />           -- Draws an image, solid color, or gradient
│   │   ├── <MaskTexture />   -- Applies a mask to other textures
│   │   └── <Line />          -- Draws a line between two anchors
│   ├── <FontString />        -- Draws text
│   └── <Frame>               -- Handles events, user interaction, contains child widgets
│       ├── <Button>          -- Responds to clicks
│       │   ├── <CheckButton> -- Adds checked/unchecked state
│       │   └── <ItemButton>  -- Intrinsic frame extending Button
│       ├── <ColorSelect>     -- Color wheel + value picker
│       ├── <Cooldown>        -- Rotating edge / swipe overlay
│       ├── <EditBox>         -- Text input field
│       ├── <GameTooltip>     -- Tooltip formatting
│       ├── <MessageFrame>    -- Scrolling message display
│       ├── <Model>           -- 3D model rendering
│       │   ├── <PlayerModel>
│       │   │   ├── <DressUpModel>
│       │   │   └── <TabardModel>
│       │   ├── <CinematicModel>
│       │   └── <UiCamera>
│       ├── <ModelScene>      -- Scene-based 3D rendering
│       ├── <ScrollFrame>     -- Scrollable container
│       ├── <ScrollingMessageFrame> -- Intrinsic scrolling messages
│       ├── <SimpleHTML>      -- Renders HTML content
│       ├── <Slider>          -- Value selector within a range
│       ├── <StatusBar>       -- Fill bar (health, progress, etc.)
│       ├── <MovieFrame>      -- Video playback
│       ├── <ArchaeologyDigSiteFrame>
│       ├── <QuestPOIFrame>
│       └── <ScenarioPOIFrame>
│
└── <AnimationGroup>          -- Contains animations
    └── <Animation>           -- Abstract base for animations
        ├── <Alpha>           -- Fades opacity
        ├── <Scale>           -- Resizes
        │   └── <LineScale>
        ├── <Translation>     -- Moves position
        │   └── <LineTranslation>
        ├── <Path>            -- Moves through control points
        ├── <Rotation>        -- Rotates around an origin
        └── <TextureCoordTranslation> -- Shifts texture coordinates

参考文件

参考文件	内容
XML-FOUNDATION.md	术语、XML 命名空间设置、<Ui>、<Include>、<Script>、<LayoutFrame> 基础元素、<Anchors>、<Size>、<KeyValues>、<Animations>
XML-FRAME-TYPES.md	<Frame> 及其所有子类型：Button、CheckButton、ItemButton、ColorSelect、Cooldown、EditBox、GameTooltip、MessageFrame、Model（及其子类型）、ScrollFrame、ScrollingMessageFrame、SimpleHTML、Slider、StatusBar、POI 框体
XML-REGIONS.md	<Texture>、<MaskTexture>、<Line>、<FontString>，以及通用子元素：<Color>、<Gradient>、<TexCoords>、<Shadow>、<Inset>、<Dimension>
XML-FONTS.md	<Font>、<FontFamily>、<FontHeight>、<Member>
XML-ANIMATIONS.md	<AnimationGroup>、基础 <Animation>、<Alpha>、<Scale>、<LineScale>、<Translation>、<LineTranslation>、<Path>、<Rotation>、<TextureCoordTranslation>

快速示例

一个最简 XML 文件，用于在屏幕中央显示纹理：

<Ui xmlns="http://www.blizzard.com/wow/ui/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.blizzard.com/wow/ui/
                        https://raw.githubusercontent.com/Gethe/wow-ui-source/live/Interface/AddOns/Blizzard_SharedXML/UI.xsd">
    <Frame parent="UIParent">
        <Size x="64" y="64"/>
        <Anchors>
            <Anchor point="CENTER"/>
        </Anchors>
        <Layers>
            <Layer level="ARTWORK">
                <Texture file="interface/icons/inv_mushroom_11" setAllPoints="true"/>
            </Layer>
        </Layers>
    </Frame>
</Ui>

常见 XML 属性类型

XSD 类型	Lua 等效类型	示例
xs:string	string	"MyFrame"、"interface/icons/spell_nature_heal"
xs:boolean	boolean	"true"、"false"
xs:int	number（整数）	"0"、"42"
xs:float	number（浮点数）	"1.0"、"0.5"
xs:unsignedInt	number（非负整数）	"0"、"255"
ui:FRAMEPOINT	string	"CENTER"、"TOPLEFT"、"BOTTOMRIGHT"
ui:FRAMESTRATA	string	"BACKGROUND"、"LOW"、"MEDIUM"、"HIGH"、"DIALOG"、"FULLSCREEN"、"FULLSCREEN_DIALOG"、"TOOLTIP"
ui:DRAWLAYER	string	"BACKGROUND"、"BORDER"、"ARTWORK"、"OVERLAY"、"HIGHLIGHT"
ui:ORIENTATION	string	"HORIZONTAL"、"VERTICAL"
ui:OUTLINETYPE	string	"NONE"、"NORMAL"、"THICK"
ui:ALPHAMODE	string	"DISABLE"、"BLEND"、"ALPHAKEY"、"ADD"、"MOD"
ui:INSERTMODE	string	"TOP"、"BOTTOM"
ui:JUSTIFYHTYPE	string	"LEFT"、"CENTER"、"RIGHT"
ui:JUSTIFYVTYPE	string	"TOP"、"MIDDLE"、"BOTTOM"
ui:ANIMLOOPTYPE	string	"NONE"、"REPEAT"、"BOUNCE"
ui:ANIMSMOOTHTYPE	string	"NONE"、"IN"、"OUT"、"IN_OUT"、"OUT_IN"
ui:ANIMCURVETYPE	string	"NONE"、"SMOOTH"
ui:KEYVALUETYPE	string	"nil"、"boolean"、"number"、"string"、"global"
ui:WRAPMODE	string	"CLAMP"、"REPEAT"、"CLAMPTOBLACK"、"CLAMPTOBLACKADDITIVE"、"CLAMPTOWHITE"、"MIRROR"

编辑器设置

使用 VS Code 和 Red Hat XML 扩展，在 WoW XML 文件中进行架构验证、自动补全和错误检查。