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

snapped

定义

snapped() 用来将一个数值"吸附"到最近的步长倍数上——简单说，就是"按刻度对齐"。

想象一段楼梯，每级台阶高 0.5 米。你现在站在 3.7 米高的位置，但楼梯只有 3.5 米和 4.0 米两个位置有台阶。snapped(3.7, 0.5) 会帮你"跳"到离你最近的台阶——3.5 米（因为 3.7 离 3.5 更近）。再比如 snapped(3.8, 0.5) 则会跳到 4.0 米（因为 3.8 离 4.0 更近）。

这就像你在一把只有整厘米刻度的尺子上量东西——不管你量出来是 3.72 厘米还是 3.78 厘米，最后都要"对齐"到最近的刻度线：3.7 或 3.8。

snapped() 是 snappedf()（浮点数版）和 snappedi()（整数版）的"通用版"，会根据你传入的参数类型自动判断该用哪个。

函数签名

C#

// 浮点数版本
public static float Snapped(float s, float step)

GDScript

# 自动适配 int 和 float
func snapped(x: float, step: float) -> float

参数说明

参数	类型	必需	说明
s / x	float	是	要对齐的原始值
step	float	是	步长（吸附的间隔大小）

返回值

float —— 离 x 最近的 step 的整数倍。例如 snapped(3.7, 1.0) 返回 4.0，snapped(3.2, 1.0) 返回 3.0。

代码示例

C#

// ===== 基础用法 =====
float a = Mathf.Snapped(3.7f, 1.0f);
// 运行结果: a = 4.0（离 3.7 最近的整数倍是 4）

float b = Mathf.Snapped(3.2f, 1.0f);
// 运行结果: b = 3.0（离 3.2 最近的整数倍是 3）

float c = Mathf.Snapped(5.0f, 0.5f);
// 运行结果: c = 5.0（5.0 已经是 0.5 的整数倍，不变）

float d = Mathf.Snapped(3.7f, 0.5f);
// 运行结果: d = 3.5（3.5 和 4.0 之间选更近的 3.5）


// ===== 实际场景：让角色对齐到网格（每格 32 像素） =====
using Godot;

public partial class GridMover : Node2D
{
    [Export] public float ExGridSize = 32.0f;  // 网格大小

    public float SnapToGrid(float position)
    {
        return Mathf.Snapped(position, ExGridSize);
    }

    public override void _Ready()
    {
        float playerX = 45.3f;
        float snappedX = SnapToGrid(playerX);
        GD.Print($"原始位置: {playerX} → 对齐后: {snappedX}");
        // 运行结果: 原始位置: 45.3 → 对齐后: 32

        float playerY = 78.9f;
        float snappedY = SnapToGrid(playerY);
        GD.Print($"原始位置: {playerY} → 对齐后: {snappedY}");
        // 运行结果: 原始位置: 78.9 → 对齐后: 64
    }
}


// ===== 进阶用法：让滑块值按固定步进变化 =====
// UI 滑块只能选择 0.1 的倍数值
[Export] public float ExSliderStep = 0.1f;

private float _sliderValue = 0.0f;

public void OnSliderDragged(float rawValue)
{
    _sliderValue = Mathf.Snapped(rawValue, ExSliderStep);
    GD.Print($"滑块值: {_sliderValue:F1}");
}

// 模拟：
// OnSliderDragged(0.37f)  → 运行结果: 滑块值: 0.4
// OnSliderDragged(0.82f)  → 运行结果: 滑块值: 0.8
// OnSliderDragged(0.05f)  → 运行结果: 滑块值: 0.1

GDScript

# ===== 基础用法 =====
var a = snapped(3.7, 1.0)
# 运行结果: a = 4.0（离 3.7 最近的整数倍是 4）

var b = snapped(3.2, 1.0)
# 运行结果: b = 3.0（离 3.2 最近的整数倍是 3）

var c = snapped(5.0, 0.5)
# 运行结果: c = 5.0（5.0 已经是 0.5 的整数倍，不变）

var d = snapped(3.7, 0.5)
# 运行结果: d = 3.5（3.5 和 4.0 之间选更近的 3.5）


# ===== 实际场景：让角色对齐到网格（每格 32 像素） =====
extends Node2D

@export var ex_grid_size: float = 32.0  # 网格大小

func snap_to_grid(position: float) -> float:
	return snapped(position, ex_grid_size)

func _ready():
	var player_x = 45.3
	var snapped_x = snap_to_grid(player_x)
	print("原始位置: %.1f → 对齐后: %.1f" % [player_x, snapped_x])
	# 运行结果: 原始位置: 45.3 → 对齐后: 32.0

	var player_y = 78.9
	var snapped_y = snap_to_grid(player_y)
	print("原始位置: %.1f → 对齐后: %.1f" % [player_y, snapped_y])
	# 运行结果: 原始位置: 78.9 → 对齐后: 64.0


# ===== 进阶用法：让滑块值按固定步进变化 =====
# UI 滑块只能选择 0.1 的倍数值
@export var ex_slider_step: float = 0.1

var _slider_value: float = 0.0

func on_slider_dragged(raw_value: float) -> void:
	_slider_value = snapped(raw_value, ex_slider_step)
	print("滑块值: %.1f" % _slider_value)

# 模拟：
# on_slider_dragged(0.37)  → 运行结果: 滑块值: 0.4
# on_slider_dragged(0.82)  → 运行结果: 滑块值: 0.8
# on_slider_dragged(0.05)  → 运行结果: 滑块值: 0.1

注意事项

• 如果 step 为 0，函数返回 0（不会报错，但也没有实际意义）。
• 当 x 恰好处于两个步长倍数的正中间时（如 snapped(2.5, 1.0)），函数会向上取整，返回 3.0。
• 步长 step 为负数时，其绝对值会被当作步长使用。
• 如果需要明确使用浮点数或整数版本，请使用 snappedf()（浮点数）或 snappedi()（整数）。