最后更新日期：2026-04-16

最后同步日期：2026-04-15 | Godot 官方原文 — @icon

@icon

定义

@icon 是 GDScript 中的一个注解（annotation），用来给当前脚本指定一个自定义图标。这个图标会显示在编辑器的节点树、检查器面板和"添加节点"对话框中，帮助你快速识别这个自定义节点是什么。

简单说，就像给每个脚本贴了个"标签贴纸"。Godot 内置的节点有各自的图标（比如 Camera3D 是个小相机，Light3D 是个小灯泡），你自己的脚本默认显示的是一个通用脚本图标。用 @icon 可以换成你自己设计的图标，一眼就能认出"哦，这是个敌人脚本"。

在 C# 中，对应的写法是在类上方添加 [Icon("res://path/to/icon.svg")] 特性。

语法

C#

// 给脚本指定自定义图标
[Icon("res://icons/enemy.svg")]
public partial class Enemy : CharacterBody3D
{
    [Export] public int ExHealth = 100;
}

GDScript

# 给脚本指定自定义图标
@icon("res://icons/enemy.svg")
class_name Enemy
extends CharacterBody3D

@export var ex_health: int = 100

参数说明

参数	类型	必需	说明
icon_path	String	是	图标文件的路径，必须是 res:// 开头的项目内部路径。推荐使用 SVG 格式（矢量图标，缩放不失真），也支持 PNG 等位图格式

返回值

@icon 是一个注解，没有返回值。它的作用是改变脚本在编辑器中显示的图标。

代码示例

C#

using Godot;

// ===== 基础用法：指定自定义图标 =====
[Icon("res://icons/sword.svg")]
[GlobalClass]
public partial class Weapon : Node3D
{
    [Export] public int ExDamage = 10;

    public override void _Ready()
    {
        GD.Print($"武器已就绪，攻击力: {ExDamage}");
    }
}
// 运行结果: 武器已就绪，攻击力: 10


// ===== 实际场景：为不同角色类型设置图标 =====
[Icon("res://icons/player.svg")]
[GlobalClass]
public partial class Player : CharacterBody3D
{
    [Export] public float ExMoveSpeed = 200f;

    public override void _Ready()
    {
        GD.Print($"玩家初始化，速度: {ExMoveSpeed}");
    }
}
// 运行结果: 玩家初始化，速度: 200

[Icon("res://icons/boss.svg")]
[GlobalClass]
public partial class Boss : CharacterBody3D
{
    [Export] public int ExPhaseCount = 3;

    public override void _Ready()
    {
        GD.Print($"Boss 初始化，阶段数: {ExPhaseCount}");
    }
}
// 运行结果: Boss 初始化，阶段数: 3


// ===== 进阶用法：组织图标资源 =====
// 建议把图标放在统一的目录中
// res://icons/
//   ├── components/
//   │   ├── health.svg
//   │   ├── inventory.svg
//   │   └── movement.svg
//   ├── characters/
//   │   ├── player.svg
//   │   ├── enemy.svg
//   │   └── npc.svg
//   └── items/
//       ├── weapon.svg
//       ├── armor.svg
//       └── potion.svg

[Icon("res://icons/components/health.svg")]
[GlobalClass]
public partial class HealthComponent : Node
{
    [Export] public int ExMaxHealth = 100;
    private int _currentHealth;

    public void TakeDamage(int amount)
    {
        _currentHealth = Mathf.Max(_currentHealth - amount, 0);
        GD.Print($"生命值: {_currentHealth}/{ExMaxHealth}");
    }
}
// 运行结果: 生命值: 80/100

GDScript

# ===== 基础用法：指定自定义图标 =====
@icon("res://icons/sword.svg")
class_name Weapon
extends Node3D

@export var ex_damage: int = 10

func _ready():
    print("武器已就绪，攻击力: %d" % ex_damage)
# 运行结果: 武器已就绪，攻击力: 10


# ===== 实际场景：为不同角色类型设置图标 =====
@icon("res://icons/player.svg")
class_name Player
extends CharacterBody3D

@export var ex_move_speed: float = 200.0

func _ready():
    print("玩家初始化，速度: %.0f" % ex_move_speed)
# 运行结果: 玩家初始化，速度: 200

@icon("res://icons/boss.svg")
class_name Boss
extends CharacterBody3D

@export var ex_phase_count: int = 3

func _ready():
    print("Boss 初始化，阶段数: %d" % ex_phase_count)
# 运行结果: Boss 初始化，阶段数: 3


# ===== 进阶用法：组件系统图标 =====
@icon("res://icons/components/health.svg")
class_name HealthComponent
extends Node

@export var ex_max_health: int = 100
var _current_health: int

func take_damage(amount: int):
    _current_health = maxi(_current_health - amount, 0)
    print("生命值: %d/%d" % [_current_health, ex_max_health])
# 运行结果: 生命值: 80/100

注意事项

• @icon 的路径必须是项目内部路径（res:// 开头），不能使用外部路径。
• 推荐使用 SVG 格式：矢量图标在任何缩放比例下都清晰，而且文件体积小。Godot 编辑器自身的图标也是 SVG 格式。
• 图标尺寸建议为 16x16 或 32x32 像素（SVG 无所谓，位图建议这些尺寸）。
• @icon 只在编辑器中生效，不影响游戏运行时的任何行为。
• 如果图标文件不存在或路径错误，编辑器会回退到默认的脚本图标，不会报错。
• C# 中使用 [Icon("res://path/to/icon.svg")] 特性。
• 建议将图标文件统一放在项目的 icons/ 目录下，方便管理。
• @icon 通常和 class_name（或 [GlobalClass]）搭配使用，这样自定义类在编辑器中既有名字又有图标。