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

split

定义

split 用来把一个字符串按照指定的"分隔符"切成多个小段，返回一个数组。你可以把它想象成用菜刀切蛋糕——分隔符就是刀的位置，切完之后得到好几块蛋糕（数组元素）。

比如 "apple,banana,cherry".Split(",") 会返回 ["apple", "banana", "cherry"] 三个元素。

函数签名

C#

// Godot.StringExtensions 方法
public static string[] Split(this string instance, string delimiter, bool allowEmpty = true, int maxSplits = 0)

GDScript

func split(delimiter: String = "", allow_empty: bool = true, max_splits: int = 0) -> PackedStringArray

参数说明

参数	类型	必需	默认值	说明
delimiter	string / String	否	""	分隔符，用来切分字符串的标记。默认按每个字符拆分
allow_empty	bool	否	true	是否允许结果中出现空字符串。设为 false 会自动跳过空段
max_splits	int	否	0	最多切分几次。0 表示不限制，全部切分

返回值

类型： C# 中为 string[]，GDScript 中为 PackedStringArray

返回切分后的字符串数组。原字符串不会被修改。

代码示例

基础用法

C#

using Godot;

public partial class SplitExample : Node
{
    public override void _Ready()
    {
        string csv = "apple,banana,cherry";

        // 用逗号分割
        string[] fruits = csv.Split(",");
        foreach (string fruit in fruits)
        {
            GD.Print(fruit);
        }
        // 运行结果:
        // apple
        // banana
        // cherry
    }
}

GDScript

extends Node

func _ready():
    var csv := "apple,banana,cherry"

    # 用逗号分割
    var fruits := csv.split(",")
    for fruit in fruits:
        print(fruit)
    # 运行结果:
    # apple
    # banana
    # cherry

实际场景：解析配置文件和坐标数据

C#

using Godot;

public partial class ConfigParser : Node
{
    public override void _Ready()
    {
        // 解析坐标字符串 "x,y" 转为 Vector2
        string posStr = "100,200";
        string[] parts = posStr.Split(",");
        if (parts.Length >= 2)
        {
            float x = parts[0].ToFloat();
            float y = parts[1].ToFloat();
            var position = new Vector2(x, y);
            GD.Print($"位置: {position}");
        }
        // 运行结果: 位置: (100, 200)

        // 解析键值对
        string config = "volume=80;muted=false;language=zh";
        string[] pairs = config.Split(";");
        foreach (string pair in pairs)
        {
            string[] kv = pair.Split("=");
            if (kv.Length == 2)
            {
                GD.Print($"键: {kv[0]}, 值: {kv[1]}");
            }
        }
        // 运行结果:
        // 键: volume, 值: 80
        // 键: muted, 值: false
        // 键: language, 值: zh
    }
}

GDScript

extends Node

func _ready():
    # 解析坐标字符串 "x,y" 转为 Vector2
    var pos_str := "100,200"
    var parts := pos_str.split(",")
    if parts.size() >= 2:
        var x := float(parts[0])
        var y := float(parts[1])
        var position := Vector2(x, y)
        print("位置: " + str(position))
    # 运行结果: 位置: (100, 200)

    # 解析键值对
    var config := "volume=80;muted=false;language=zh"
    var pairs := config.split(";")
    for pair in pairs:
        var kv := pair.split("=")
        if kv.size() == 2:
            print("键: " + kv[0] + ", 值: " + kv[1])
    # 运行结果:
    # 键: volume, 值: 80
    # 键: muted, 值: false
    # 键: language, 值: zh

进阶用法：控制 max_splits 和 allow_empty

C#

using Godot;

public partial class SplitAdvanced : Node
{
    public override void _Ready()
    {
        // max_splits：限制分割次数
        string path = "res://assets/textures/player.png";
        string[] pathParts = path.Split("/", true, 2); // 最多切 2 次
        foreach (string p in pathParts)
        {
            GD.Print($"[{p}]");
        }
        // 运行结果:
        // [res:]
        // []
        // [assets/textures/player.png]

        // allow_empty = false：跳过空字符串
        string data = "a,,b,,,c";
        string[] withEmpty = data.Split(",");
        string[] withoutEmpty = data.Split(",", false);
        GD.Print($"含空元素: {withEmpty.Length} 个");
        GD.Print($"不含空元素: {withoutEmpty.Length} 个");
        // 运行结果:
        // 含空元素: 6 个
        // 不含空元素: 3 个

        // 分割多行文本
        string multiline = "第一行\n第二行\n第三行";
        string[] lines = multiline.Split("\n");
        GD.Print($"共 {lines.Length} 行");
        // 运行结果: 共 3 行
    }
}

GDScript

extends Node

func _ready():
    # max_splits：限制分割次数
    var path := "res://assets/textures/player.png"
    var path_parts := path.split("/", true, 2)  # 最多切 2 次
    for p in path_parts:
        print("[" + p + "]")
    # 运行结果:
    # [res:]
    # []
    # [assets/textures/player.png]

    # allow_empty = false：跳过空字符串
    var data := "a,,b,,,c"
    var with_empty := data.split(",")
    var without_empty := data.split(",", false)
    print("含空元素: " + str(with_empty.size()) + " 个")
    print("不含空元素: " + str(without_empty.size()) + " 个")
    # 运行结果:
    # 含空元素: 6 个
    # 不含空元素: 3 个

    # 分割多行文本
    var multiline := "第一行\n第二行\n第三行"
    var lines := multiline.split("\n")
    print("共 " + str(lines.size()) + " 行")
    # 运行结果: 共 3 行

注意事项

1. GDScript 默认按字符分割：如果不传 delimiter（或传空字符串），GDScript 会按每个字符拆分。比如 "abc".split() 返回 ["a", "b", "c"]。C# 的 Split 不支持此行为。
2. 返回类型不同：GDScript 返回 PackedStringArray，C# 返回 string[]。两者在使用上基本一致。
3. 分隔符不会被包含：分割后，分隔符本身不会出现在结果中的任何一个元素里。
4. 连续分隔符产生空字符串：如果两个分隔符紧挨着（如 ",,"），中间会产生空字符串 ""。设置 allow_empty = false 可以过滤掉。
5. C# 替代方案：C# 自带的 string.Split() 也能实现类似功能，但参数风格不同。Godot 的 Split 扩展方法提供了与 GDScript 一致的接口。