War3 Wiki

深色模式

自定义 UI 框架（Frame API） ​

Frame API 简介与基础概念 ​

本节将带你认识 Frame API——这是魔兽争霸3中自定义游戏界面（UI）的核心工具。读完本节后，你会理解什么是 Frame、它与传统触发器 UI 的本质区别，以及接下来会用到的几个关键术语。

什么是 Frame API ​

Frame API 是魔兽争霸3提供的一套底层函数（可以理解为一套"命令清单"），用它可以在游戏中创建、控制和排列各种界面元素，比如按钮、血条、背包、对话框等。这些界面元素在 API 中统一叫做 Frame（帧/框架）[^1]。

打个比方：传统触发器 UI 就像用积木拼界面，Frame API 则像是用画笔直接绘制界面——后者更灵活，但也需要更多的知识。

Frame 与传统触发器 UI 的区别 ​

在 Frame API 出现之前，你想做一个自定义按钮，通常需要：

  • 用触发器（Trigger）配合对话框（Dialog）来模拟
  • 依赖暴雪预设的几种 UI 模板，无法自由调整样式

Frame API 的优势在于[^1]：

  • 可以自由创建各种 UI 组件，不再受限于预设模板
  • 可以精确控制每个组件的大小、位置、颜色等属性
  • 可以让 UI 跟随分辨率自动调整，解决4:3和16:9屏幕显示不一致的问题[^1]
  • 支持将 UI 元素互相嵌套，做出复杂的层级结构

💡 新手提示：Frame API 听起来强大，但它的学习曲线比传统触发器 UI 陡峭得多。建议先掌握基本的触发器和变量概念，再来学习 Frame API，会事半功倍。

常用术语解释 ​

在深入学习之前，先认识几个你一定会反复遇到的术语：

术语含义
Frame界面上的一个"零件"，比如一个按钮、一段文字、一张图片
Template（模板）Frame 的"设计图"，定义了这个界面零件长什么样
Point（锚点）Frame 上的一个定位点，用于确定它与其他 Frame 之间的相对位置[^1]
Anchor（锚）定义 Frame 的某个 Point 应该对齐到"父级 Frame"的哪个 Point

⚠️ 常见错误：新手经常把 Template 和 Frame 搞混。Template 只是"设计图"，真正显示在屏幕上的叫 Frame。就像装修图纸（Template）不等于实际房间（Frame）。

小结 ​

本节我们学习了：

  • Frame API 是魔兽争霸3中自定义游戏界面的核心工具
  • Frame API 与传统触发器 UI 的核心区别在于自由度和精度
  • 认识了 Frame、Template、Point、Anchor 四个基础术语

下一节我们将学习如何创建你的第一个 Frame，并把它显示在屏幕上！

创建第一个自定义 Frame ​

本节将手把手教你创建游戏中的第一个自定义界面元素（Frame）。学完本节后，你将能够创建一个可见的按钮或文字框，并理解它们在游戏界面中的层级关系。

操作步骤 ​

  1. 第一步：理解 Frame 是什么 — Frame（框架）是 Warcraft III 界面系统的基本单位，就像拼图的一块。游戏里你看到的血条、技能栏、对话框，都是由一个个 Frame 组成的[^2]。

  2. 第二步：打开触发器编辑器 — 在 World Editor 中按 F4 打开触发器编辑器，我们需要用 JASS 代码来创建 Frame。如果你之前没用过触发器，可以把它理解为"告诉游戏做什么"的指令清单。

  3. 第三步：创建基础 Frame — 在触发器中添加新触发器，命名为 "UI教学"。使用以下代码创建一个最基本的 Frame：

jass
function CreateFirstFrame takes nothing returns nothing
    local framehandle myButton = BlzCreateFrame("ScriptDialogButton", BlzGetOriginFrame(ORIGIN_FRAME_GAME_UI, 0), 0, 0)
    // 这行代码创建了一个按钮类型的 Frame
    // "ScriptDialogButton" 是按钮的模板名称
    // BlzGetOriginFrame(...) 让按钮显示在游戏界面上
endfunction
  1. 第四步：设置 Frame 的位置 — 刚创建的按钮会使用默认位置。我们可以用以下代码把它移动到屏幕中央：
jass
call BlzFrameSetAbsPoint(myButton, FRAMEPOINT_CENTER, 0.4, 0.3)
// FRAMEPOINT_CENTER 表示以中心点定位
// 0.4 是 X 坐标（屏幕宽度比例，从左到右 0~1）
// 0.3 是 Y 坐标（屏幕高度比例，从下到上 0~1）
  1. 第五步：设置 Frame 的大小 — 按钮默认尺寸可能不适合你，用这段代码调整：
jass
call BlzFrameSetSize(myButton, 0.15, 0.05)
// 0.15 是宽度（屏幕宽度的 15%）
// 0.05 是高度（屏幕高度的 5%）
  1. 第六步：添加文字标签 — 给按钮添加文字更容易让玩家理解它的功能：
jass
local framehandle buttonText = BlzGetFrameByName("ScriptDialogButtonText", 0)
call BlzFrameSetText(buttonText, "点击我！")
  1. 第七步：测试你的 Frame — 保存地图后在游戏中测试。按 F9 打开游戏内菜单，或者直接在编辑器中按 Ctrl+F9 进入测试模式。

💡 新手提示：坐标 0.4, 0.3 表示屏幕中心偏左下方的位置。如果你想让按钮精确居中，应该用 0.5, 0.5。数值范围是 0 到 1，代表屏幕的百分比位置。

⚠️ 常见错误：新手常忘记在创建 Frame 前初始化 UI 系统。如果游戏报错"Frame not found"，检查是否调用了 BlzHideOriginFrames(true) 来隐藏默认 UI。另外，Frame 名称必须完全匹配，包括大小写。

小结 ​

完成以上步骤后，你应该在游戏屏幕上看到一个居中显示的按钮，上面写着"点击我！"。这证明你已经掌握了 Frame 的基本创建、定位和设置大小的方法。Frame API 还有更多功能，比如父子层级、动画效果、响应点击事件等，这些会在后续章节中详细介绍。

Frame 样式与视觉属性 ​

本节将学习如何为 Frame（框架/控件）设置背景纹理、文本样式和边框阴影效果。学完本节后，你可以让一个光秃秃的按钮变得美观漂亮，不再是千篇一律的默认白色方块。

操作步骤 ​

  1. 获取 Frame 句柄 — 在触发器中先通过 BlzGetFrameByName("FrameName", 0) 获取要设置的 Frame 对象，保存到变量中[^1]

  2. 设置背景纹理 — 使用 BlzFrameSetTexture(Frame变量, "Assets\\Path\\to\\image.blp", 0, true) 命令，其中第二个参数填写你导入的贴图文件路径[^2]

  3. 设置文本样式 — 先用 BlzFrameSetText(Frame变量, "文字内容") 设置文字，再用 BlzFrameSetTextSize(Frame变量, 0.02) 调整字号大小

  4. 修改文本颜色 — 调用 BlzFrameSetTextColor(Frame变量, 0xFFFF0000) 设置颜色，参数是十六进制RGB值（如 0xFFFF0000 为红色）[^2]

  5. 添加边框效果 — 使用 BlzFrameSetBorderSize(Frame变量, 0.002) 设置边框粗细，再用 BlzFrameSetBorderColor(Frame变量, 0xFF000000) 设置边框颜色

  6. 设置阴影 — 通过 BlzFrameSetLevel(Frame变量, 层级数值) 控制叠放顺序，数值越大越靠前显示

💡 新手提示：所有贴图文件必须先通过 WE 的「资源管理器」导入到地图中，否则路径会找不到。可以右键导入 → 选择 .blp 或 .tga 格式图片。

⚠️ 常见错误：新手经常把 BlzFrameSetTextColor 的十六进制值写错，导致文字变成奇怪的颜色。正确格式是 0xAARRGGBB（AA=透明度，RR=红，GG=绿，BB=蓝），比如纯红是 0xFFFF0000，不是 0xFF0000FF。

小结 ​

完成以上步骤后，你应该成功为 Frame 设置了背景图片、可读的文字说明以及清晰的边框效果。此时你的自定义 UI 已经脱离了"系统默认样式"，开始有了自己的视觉风格。建议打开地图测试模式，边改参数边刷新查看效果，这样学习更直观。

Frame 事件与用户交互 ​

本节你将学习如何让 UI 控件（Frame）响应玩家的操作，比如点击按钮、鼠标悬停等。学完本节后，你就能为你的自定义 UI 添加交互功能，比如点击"开始游戏"按钮后进入游戏。

常用事件类型 ​

Frame 事件就像是 UI 控件的"感知神经"，让它们能够"感知"玩家的操作。常见的 Frame 事件类型包括：

  • 点击事件（MouseClick）：当玩家用鼠标左键点击某个 Frame 时触发
  • 悬停事件（MouseEnter/MouseLeave）：当鼠标进入或离开某个 Frame 区域时触发
  • 拖拽事件（MouseDown/MouseUp）：当玩家按住并拖动鼠标时触发
  • 值改变事件（ValueChange）：当滑动条、数值框等控件的值发生变化时触发[^2]

每种事件类型都有其特定的用途，比如按钮通常只需要监听点击事件，而滑动条则需要监听值改变事件。

事件回调函数编写 ​

事件回调函数是当事件触发时自动执行的代码。以下是编写回调函数的基本步骤：

  1. 打开触发器编辑器 — 在 WE 顶部菜单栏点击"触发器"（Trigger）按钮，打开触发器窗口[^3]
  2. 创建新的回调函数 — 右键点击"新建触发器"，选择"新建回调"或使用 BlzTriggerRegisterFrameEvent 函数在 JASS 中注册事件[^2]
  3. 编写响应逻辑 — 在回调函数中写入当事件发生时要执行的代码，例如：
    • 隐藏当前界面
    • 显示新界面
    • 修改某个变量值

💡 新手提示：回调函数的名称建议起得有意义，比如 BtnStart_Click 比 Callback1 更容易后期维护。

将事件连接到触发器 ​

将 Frame 事件连接到 WE 的触发系统，这样你就可以用触发器来控制游戏逻辑：

  1. 获取目标 Frame — 使用 BlzGetFrameByName("FrameName", 0) 获取你要操作的 UI 控件[^2]
  2. 创建触发器 — 新建一个空白触发器，作为处理这个 UI 事件的"指挥官"
  3. 注册事件 — 在触发器的"初始化"动作中，使用函数将 Frame 的点击事件与你的触发器关联
  4. 添加条件与动作 — 在触发器内部设置：当这个事件触发时，执行哪些具体的游戏操作

⚠️ 常见错误：新手经常忘记先"注册事件"就直接写动作代码，导致事件触发时没有任何反应。一定要确保事件注册语句在触发器的初始化部分执行。

小结 ​

完成以上步骤后，你应该已经掌握了 Frame 事件的基本概念、常用事件类型，以及如何通过回调函数和触发器来实现 UI 交互。现在你可以尝试为你的自定义 UI 添加一个简单的按钮交互功能了！

Frame 模板系统 ​

本节你将学习如何使用 Frame 模板系统来创建可复用的 UI 组件。学完后，你能够制作自己的按钮、进度条等组件，并在地图中多次使用，而不用每次都重新设计。

什么是 Template ​

Template（模板） 就像是一个"模具"。想象一下，如果你要做100个相同的按钮，一个一个设计会非常麻烦。Template 允许你先设计好一个按钮的样式，然后让其他按钮"继承"这个样式[^1]。

在 Frame API 中，Template 是一组预先定义好的属性（比如尺寸、颜色、贴图位置等），你可以反复使用它来创建新的 Frame。

创建可复用的 Frame 模板 ​

  1. 打开触发编辑器 — 在 World Editor 中，按 F4 打开触发编辑器[^2]

  2. 新建一个"配置 Frame"的触发器 — 右键点击左侧面板，选择"新建" → "触发器"，命名为"UI_模板配置"

  3. 使用 FrameCreateTemplate 函数 — 在触发器中添加动作：

    lua
    FrameCreateTemplate("MyButtonTemplate", "BACKDROP", "ScriptDialogButton")
    • "MyButtonTemplate" 是你给模板起的名字
    • "BACKDROP" 是模板类型
    • "ScriptDialogButton" 是基于哪个现有 Frame 作为基础[^2]

  4. 为模板设置属性 — 添加 FrameSetTemplateProperty 来设置模板的尺寸、颜色等属性

  5. 保存模板 — 使用 FrameRegisterTemplate 将模板注册到系统中，使其可以被其他 Frame 调用

💡 新手提示：Template 名字建议使用有意义的命名，比如 HP条模板、技能按钮模板，这样以后查看代码时更容易理解。

模板继承与覆盖 ​

  1. 创建继承自模板的新 Frame — 使用 FrameCreateFromTemplate 函数：

    lua
    FrameCreateFromTemplate("Player1_HPBar", "MyButtonTemplate")

    这时会创建一个完全复制了模板属性的新 Frame[^1]

  2. 单独修改某个 Frame 的属性 — 即使新 Frame 来自模板，你仍然可以单独修改它的属性：

    lua
    FrameSetSize("Player1_HPBar", 0.3, 0.02)
FrameSetPoint("Player1_HPBar", "LEFT", "UI_Container", "LEFT", 0.01, 0.0)

    这只影响 "Player1_HPBar"，不会改变模板本身[^2]

  3. 使用继承创建多个实例 — 你可以基于同一个模板创建任意数量的 Frame：

    lua
    FrameCreateFromTemplate("Player2_HPBar", "MyButtonTemplate")
FrameCreateFromTemplate("Player3_HPBar", "MyButtonTemplate")

⚠️ 常见错误：新手容易混淆"模板"和"实例"。模板是模具本身，而实例是用模具做出来的产品。修改模板会影响之后创建的所有新实例，但不会影响已经创建好的实例。

小结 ​

完成以上步骤后，你应该：

  • 理解 Template 的概念及其作用
  • 能够创建一个可复用的 Frame 模板
  • 掌握如何使用模板创建多个 Frame 实例
  • 学会单独修改某个实例而不影响模板

这样，你就可以开始构建自己的一套 UI 组件库，让地图的界面开发变得更加高效！

实战案例与常见问题 ​

本节将通过两个实战案例教你制作基础 UI 组件，并分享调试与优化的实用技巧。学完本节后，你将能够独立创建简单的自定义按钮，并学会排查常见的 Frame 错误。

简单按钮与对话框制作 ​

  1. 创建全屏基准框 — 首先在触发器中创建一个自定义的"全屏 Frame"，将其尺寸设为与游戏窗口一致。这是后续所有 UI 元素定位的参照基准[^1]。
  2. 定义按钮模板 — 使用 BlzCreateFrameByType 函数创建一个 BUTTON 类型的框实例，设置其纹理、大小和位置参数[^2]。
  3. 绑定点击事件 — 通过 BlzTriggerRegisterFrameEvent 将按钮与触发器关联，设置 FRAMEEVENT_CONTROL_CLICK 事件类型。
  4. 添加到对话框 — 将按钮通过父框架关系挂载到对话框或全屏基准框上，设置 FrameSetPoint 确定其相对于父框架的位置。
  5. 显示与隐藏控制 — 使用 BlzFrameSetVisible 控制按钮的显示状态，通常配合游戏初始化触发器使用。

💡 新手提示：创建 Frame 时务必先确保父框架已存在，否则游戏会崩溃。可以先在初始化函数中创建基础框架，再在其上添加子元素。

⚠️ 常见错误：很多新手忘记给 Frame 设置绝对坐标，只设置相对于父框架的位置，导致 UI 元素出现在屏幕外。解决方法是在 FrameSetPoint 中同时指定水平和垂直坐标。

性能优化技巧 ​

  1. 减少实时刷新 — 避免在每帧触发器中更新 Frame 状态，将刷新频率控制在 0.5-1 秒一次即可满足大多数需求[^1]。
  2. 合并同类元素 — 如果需要显示大量相似按钮（如道具列表），使用 BlzCreateFrameByType 的实例复制功能，而非重新定义每个按钮。
  3. 延迟加载非必要 UI — 将不常用的对话框（如帮助界面、高级设置）在玩家需要时才创建，避免开局时一次性加载所有 UI 资源。
  4. 谨慎使用高分辨率纹理 — 高清纹理会占用大量内存，尽量对远处或小型 UI 元素使用低分辨率贴图。

💡 新手提示：可以在地图初始化时创建一个"UI 管理器"变量，统一控制所有自定义框架的创建和销毁逻辑，便于后续维护。

调试与错误排查方法 ​

  1. 检查帧名称拼写 — Frame API 对大小写敏感，"QuestButton" 和 "questbutton" 是完全不同的框架，务必与模板定义保持一致[^2]。
  2. 使用打印输出定位 — 在触发器关键位置添加 BJDebugMsg 语句，输出变量值以确认执行流程是否正确。
  3. 逐步注释法 — 当 UI 不显示时，逐一注释掉 BlzCreateFrame 调用，直到找出具体是哪个框架创建失败。
  4. 验证游戏日志 — 打开游戏目录下的 war3vis.log 文件，查找包含 "Frame" 或 "UI" 的错误信息，通常会指出问题框架名称。
  5. 测试不同分辨率 — 在 4:3 和 16:9 显示器上分别测试，确保相对定位的 Frame 在各分辨率下位置正确[^1]。

⚠️ 常见错误：新手经常混淆 FrameSetPoint 的参数顺序，导致按钮位置与预期相反。记住格式是：FrameSetPoint(目标框, 锚点方向, 父框, 父框锚点, X偏移, Y偏移)。

💡 新手提示：遇到无法解决的白屏或闪退问题时，尝试在 WE 中将地图另存为新文件名后重新打开，有时文件缓存会导致奇怪的 UI 故障。

参考来源 ​

[^1]: The Big UI-Frame Tutorial - HIVE — accessed 2026-05-31 [^2]: GitHub - lep/jassdoc: Document the WarCraft 3 API — accessed 2026-05-31 [^3]: ［精品］魔兽编辑器详细教程 - 易码工作室 — accessed 2026-05-31

内容由多智能体 AI 系统自动生成，仅供学习参考

Copyright © 2026 War3 Wiki