企业官网建设流程全解析

• 文档
• 教程
• 游戏开发

导读

CodeEdit 是 Godot 引擎（本仓库 godot-docs 为 Godot Engine 官方文档）提供的一个专门用于编辑纯文本代码的多行文本编辑控件。它继承了 TextEdit 的全部文本编辑能力，并额外内置了行号、行折叠、代码补全、缩进管理、字符串/注释定界符、书签/断点/执行行标记等一系列代码编辑器特性，是构建脚本编辑器、自定义 IDE 或任何面向代码输入界面的核心基础控件。阅读本文后，你将掌握 CodeEdit 的完整属性、方法、信号与主题定制接口，并能直接基于这些 API 搭建一个具备代码补全、符号跳转与断点标记能力的自定义代码编辑器。

CodeEdit 是什么：继承体系与定位

根据 classes/class_codeedit.rst 的类声明，CodeEdit 的完整继承链为：

CodeEdit < TextEdit < Control < CanvasItem < Node < Object

它本质上是 TextEdit 的专用化子类。TextEdit 的定位是"多行文本编辑器"，"它也有有限度的代码编辑设施，例如语法高亮支持；如需更高级的代码编辑功能，请参见 CodeEdit"（见 TextEdit 类描述）。而 CodeEdit 则进一步提供了代码编辑器中常见的大量特性：行号、行折叠、代码补全、缩进管理，以及字符串/注释管理。

有两个需要特别注意的基础约定：

• 文字方向：无论系统 locale 如何，CodeEdit 默认始终使用从左到右（LTR）的文本方向来正确展示源代码。
• 零基索引：作为 TextEdit 的子类，行号和列号均以零为基准，与数组索引一致。例如第一行文本通过get_line(0)获取，第二行通过get_line(1)获取。

在 Godot 引擎自身架构中，CodeEdit 也是脚本编辑器的底层载体。这一点可以从仓库内的 ScriptEditorBase 类文档 得到印证：其get_base_editor()方法返回"用于编辑脚本的底层 Control，对于文本脚本而言，就是一个 CodeEdit"。同时 GDScriptSyntaxHighlighter 类文档 也明确指出，该语法高亮器"可用于 TextEdit 和 CodeEdit 节点"——这意味着你可以为 CodeEdit 挂载语法高亮，实现完整的源码着色体验。

基础编辑能力：行号与缩进管理

行号显示

CodeEdit 可以通过一组gutters_*属性控制行号栏（gutter）的显示：

对应的 setter/getter 为set_draw_line_numbers()/is_draw_line_numbers_enabled()、set_line_numbers_min_digits()/get_line_numbers_min_digits()、set_line_numbers_zero_padded()/is_line_numbers_zero_padded()。

缩进配置

缩进相关的操作方法与输入动作直接挂钩：

• do_indent()：无选区时在光标处插入缩进，有选区时按indent_lines()方式缩进选中行，等价于ProjectSettings.input/ui_text_indent动作，所用缩进字符取决于indent_use_spaces与indent_size；
• indent_lines()：缩进所有被选中或光标所在的行；
• unindent_lines()：反向操作，等价于ProjectSettings.input/ui_text_dedent动作；
• convert_indent(from_line = -1, to_line = -1)：将from_line到to_line之间的缩进统一转换为indent_use_spaces指定的形式（制表符或空格），参数传-1表示转换全文。

配合自动缩进与括号补全（见下文），CodeEdit 可以复刻现代 IDE 中"回车后自动缩进、花括号自动换行"的输入体验。

自动括号补全与匹配高亮

CodeEdit 内置了自动括号补全系统，由以下属性驱动：

auto_brace_completion_pairs的默认值覆盖了常见的引号与括号场景：双引号、单引号、圆括号、方括号、花括号。由于字典中的"括号"实际上是符号字符串，你可以按语言需求定制任意配对，例如为模板语法注册<与>的配对（add_auto_brace_completion_pair("<!--", "-->")等）。

配套的方法包括：

• add_auto_brace_completion_pair(start_key, end_key)：新增一对括号；起始键和结束键都必须是符号，且只有起始键要求唯一；
• get_auto_brace_completion_close_key(open_key)：获取指定起始键的闭合键；
• has_auto_brace_completion_open_key(open_key)/has_auto_brace_completion_close_key(close_key)：分别判断起始键 / 闭合键是否存在。

行折叠与代码区域

行折叠开关

line_folding属性（bool，默认false）控制是否允许折叠行。若为false，fold_line()等折叠方法将不起作用，且can_fold_line()恒返回false。

折叠判定规则由can_fold_line(line)定义：当某一行满足以下任一条件时即为"可折叠"：

• 它是合法代码区域（见下文代码区域）的起始行；
• 它是注释块或字符串块的起始行；
• 它的下一个非空行拥有更大的缩进（依据 TextEdit 的get_indent_level()）。

折叠操作 API 一览：

代码区域（Code Region）

代码区域是 CodeEdit 特有的代码组织方式：它是一段代码，折叠时会被高亮标记，用于辅助组织长脚本。其核心机制是用注释定界符 + 起始/结束标签圈定区域，默认标签为region/endregion，配合行注释定界符后形如#region与#endregion。

#region 初始化逻辑 var health := 100 var max_health := 100 #endregion

相关方法：

• create_code_region()：用当前选区创建代码区域。前提是至少定义一个单行注释定界符（见下文add_comment_delimiter()）；
• set_code_region_tags(start = "region", end = "endregion")：自定义区域起始/结束标签（不含注释定界符）；
• get_code_region_start_tag()/get_code_region_end_tag()：获取当前起始/结束标签；
• is_line_code_region_start(line)/is_line_code_region_end(line)：判断指定行是否为区域起点/终点。

折叠栏（fold gutter）负责呈现区域折叠状态：gutters_draw_fold_gutter属性（bool，默认false）开启后，每个可折叠行绘制can_fold_code_region图标，每个已折叠行绘制folded_code_region图标，点击图标即可切换折叠（toggle_foldable_line()）。注意：line_folding必须为true图标才会显示。

字符串与注释定界符管理

CodeEdit 能够"识别"哪些文本处于字符串或注释区域中，这依赖**定界符（delimiter）**机制。两个数组属性管理全局配置：

注意默认的字符串定界符写法"' '"与"\" \""是"起始键 + 空格 + 结束键"的编码形式，表示从'到'、从"到"。

在运行时可通过以下方法动态管理定界符：

• add_string_delimiter(start_key, end_key, line_only = false)：定义从start_key到end_key的字符串定界符。两个键都应为符号，start_key不能与其他定界符共享。若line_only为true或end_key为空字符串，则该区域不会延续到下一行；
• add_comment_delimiter(start_key, end_key, line_only = false)：同上，用于注释定界符；
• remove_string_delimiter(start_key)/remove_comment_delimiter(start_key)：移除指定定界符；
• clear_string_delimiters()/clear_comment_delimiters()：清空全部定界符；
• has_string_delimiter(start_key)/has_comment_delimiter(start_key)：判断是否存在某定界符；
• get_delimiter_start_key(index)/get_delimiter_end_key(index)：按索引获取区域起始/结束键。

查询接口是定界符机制的实战核心：

• is_in_string(line, column = -1)：若line的column处于字符串中，返回该字符串区域的定界符索引；不传column时，若整行都是字符串则返回索引；否则返回-1；
• is_in_comment(line, column = -1)：同上，用于注释区域判定；
• get_delimiter_start_position(line, column)/get_delimiter_end_position(line, column)：若给定行列位于字符串或注释内，返回该区域的起始/结束位置（Vector2，x 为行、y 为列）；若不在或找不到对应端点，两个值均为-1。

这一组 API 让你能够精确判断"光标是否在字符串里"，从而在实现自动补全、括号匹配或语法着色时避免误判。

代码补全系统：从候选队列到弹出菜单

代码补全是 CodeEdit 最强大的特性。它由属性、虚拟方法、信号与方法构成一个完整的闭环。

开关与触发

当用户触发补全请求时，引擎会调用可覆写的虚拟方法_request_code_completion(force)（若被覆写，则不会发送code_completion_requested信号），否则发送code_completion_requested信号供外部处理。

候选选项与弹出

补全候选由以下方法驱动：

• add_code_completion_option(type, display_text, insert_text, text_color = Color(1,1,1,1), icon = null, value = null, location = 1024)：向候选队列提交一个条目。type为CodeCompletionKind枚举（见下文）；display_text是菜单上显示的文字；insert_text是选中后插入的文本；location表示该选项相对补全查询位置的来源层级，参考CodeCompletionLocation枚举。注意：该列表会替换所有现有候选；
• update_code_completion_options(force)：提交所有通过add_code_completion_option()添加的候选，若force为true则强制弹出补全菜单。同样会替换所有现有候选；
• request_code_completion(force = false)：触发code_completion_requested信号；force为true时绕过所有检查，否则要求光标位于单词中或前缀之后；若当前所有选项都是文件路径、节点路径或信号类型，则会忽略本次请求；
• confirm_code_completion(replace = false)：将选中条目插入文本，replace为true时替换而非合并现有文本；
• cancel_code_completion()：取消补全菜单；
• set_code_completion_selected_index(index)/get_code_completion_selected_index()：设置/获取当前选中选项的索引；
• get_code_completion_options()/get_code_completion_option(index)：获取全部选项或指定选项。每个选项是包含以下键值对的 Dictionary：kind（CodeCompletionKind）、display_text（菜单显示文本）、insert_text（选中后插入的文本）、font_color（菜单文字颜色）、icon（菜单图标）、default_value（符号的值）；
• set_code_hint(code_hint)/set_code_hint_draw_below(draw_below)：设置光标处的代码提示文本（传空字符串清除），并控制提示绘制在主光标下方还是上方；
• get_text_for_code_completion()：返回在光标处插入字符0xFFFF的完整文本，供补全实现分析上下文。

# 典型的补全提供流程：在 code_completion_requested 信号中填充候选 func _on_code_completion_requested() -> void: clear_code_completion_options() # 可选：清空旧候选 add_code_completion_option( CodeEdit.CodeCompletionKind.KIND_FUNCTION, "my_function()", "my_function()", Color(0.6, 0.9, 1.0) ) update_code_completion_options(false)

（注：示例方法clear_code_completion_options对应引擎实际实现中的清空接口，具体以引擎 API 为准。）

两个可覆写的虚拟方法

• _filter_code_completion_candidates(candidates)：覆写后决定candidates中哪些条目应被展示。入参与返回值均为Dictionary数组，内容参见get_code_completion_option()；
• _confirm_code_completion(replace)：覆写后自定义选中条目的插入逻辑；replace为true时替换既有文本。

CodeCompletionKind 枚举（补全类型）

CodeCompletionLocation 枚举（选项来源）

location参数并非始终存在。仓库内的 Godot 4.1 升级指南 记录了该 API 的演进：CodeEdit的add_code_completion_option方法在 4.1 版本新增了可选的location参数（对应引擎 PR GH-75746），GDScript 完全兼容，C# 二进制兼容性需借助兼容层。这意味着基于旧版本编写的补全代码仍可编译运行，但新代码建议显式传入location以获得更准确的候选排序。

符号查找与悬停提示

CodeEdit 提供了一套"符号（symbol）"级别的交互机制，用于实现"按住点击跳转定义""悬停显示文档"等 IDE 功能。它依赖以下属性与信号：

典型交互链路如下：

1. 用户悬停某个符号，引擎发出symbol_validate(symbol)信号（前提：symbol_lookup_on_click为true）；
2. 外部代码校验该符号是否可查找，并调用set_symbol_lookup_word_as_valid(valid)回执结果；
3. 若校验有效且用户点击该词，引擎发出symbol_lookup(symbol, line, column)；
4. 若开启了symbol_tooltip_on_hover，悬停延迟达到ProjectSettings.gui/timers/tooltip_delay_sec秒后发出symbol_hovered(symbol, line, column)（与Control.mouse_entered不同，它不会立即触发）。

func _on_symbol_validate(symbol: String) -> void: # 自定义校验逻辑：例如判断 symbol 是否存在于符号表中 set_symbol_lookup_word_as_valid(_symbol_table.has(symbol)) func _on_symbol_lookup(symbol: String, line: int, column: int) -> void: # 跳转到符号定义位置 pass

配套的文本取用方法：

• get_text_for_symbol_lookup()：返回在光标处插入字符0xFFFF的完整文本；
• get_text_with_cursor_char(line, column)：返回在指定行列处插入字符0xFFFF的完整文本；
• set_symbol_lookup_word_as_valid(valid)：设置symbol_validate信号所发出的符号是否为有效查找目标。

书签、断点与执行行标记

CodeEdit 为调试器与代码导航场景提供了三种行级标记，全部由 gutter 呈现：

对应的状态读写方法：

• 书签：set_line_as_bookmarked(line, bookmarked)、is_line_bookmarked(line)、get_bookmarked_lines()、clear_bookmarked_lines()；
• 断点：set_line_as_breakpoint(line, breakpointed)、is_line_breakpointed(line)、get_breakpointed_lines()、clear_breakpointed_lines()；
• 执行行：set_line_as_executing(line, executing)、is_line_executing(line)、get_executing_lines()、clear_executing_lines()。

set_line_as_breakpoint()等 setter 在标记置真且对应 gutter 开启时，会在栏位中绘制对应主题图标（bookmark、breakpoint、executing_line）。这些 API 正是调试器在脚本编辑器中断点可视化与当前执行行高亮的实现基础。

此外，行删除会影响标记：breakpoint_toggled(line)信号在断点被添加或移除时发出；若某行通过退格键被删除，会在旧行号上发出该信号。

行级快捷操作：删除、复制、合并与移动

CodeEdit 内置了大量针对行的编辑操作，便于复刻现代编辑器的快捷键行为：

信号一览

外观定制：主题属性

CodeEdit 提供丰富的主题项，可完全自定义编辑器观感。

颜色（Color）

常量（int）

图标与样式

• 图标（Texture2D）：bookmark、breakpoint、can_fold（可折叠行图标）、can_fold_code_region（可折叠代码区域图标）、completion_color_bg（补全中颜色预览框的背景面板，用于半透明颜色显示）、executing_line、folded（已折叠且可展开图标）、folded_code_region（已折叠代码区域图标）、folded_eol_icon（折叠行行尾图标）；
• 样式盒（StyleBox）：completion，用于代码补全弹窗的边框与背景绘制。

行长指导线

line_length_guidelines属性（Array[int]，默认[]）在指定列绘制垂直参考线，用于代码规范约束（如 80/100 列限制）。第一个条目被视为主要硬指导线，绘制得更醒目，次级指导线使用 50% 透明度的line_length_guideline_color。

实战组合：搭建一个最小化的代码编辑界面

综合以上 API，可以在 Godot 中通过场景树或脚本快速搭建一个具备核心编辑器能力的 CodeEdit。以下示例展示了属性组合与信号接线：

extends Control @onready var code_edit: CodeEdit = $CodeEdit func _ready() -> void: # 基础编辑体验 code_edit.gutters_draw_line_numbers = true code_edit.gutters_line_numbers_min_digits = 4 code_edit.indent_size = 4 code_edit.indent_use_spaces = true code_edit.indent_automatic = true code_edit.line_folding = true code_edit.gutters_draw_fold_gutter = true # 代码补全 code_edit.code_completion_enabled = true code_edit.code_completion_prefixes = ["."] code_edit.code_completion_requested.connect(_on_code_completion_requested) # 括号补全与匹配高亮 code_edit.auto_brace_completion_enabled = true code_edit.auto_brace_completion_highlight_matching = true # 注释 / 字符串定界符（以 GDScript 为例） code_edit.add_comment_delimiter("#", "", true) # 单行注释 code_edit.add_string_delimiter("\"", "\"", false) code_edit.add_string_delimiter("'", "'", false) # 断点栏（供调试集成） code_edit.gutters_draw_breakpoints_gutter = true code_edit.breakpoint_toggled.connect(_on_breakpoint_toggled) func _on_code_completion_requested() -> void: add_code_completion_option( CodeEdit.CodeCompletionKind.KIND_KEYWORD, "extends", "extends " ) update_code_completion_options(false) func _on_breakpoint_toggled(line: int) -> void: print("断点切换于行：", line)

运行这段脚本即可获得：带行号的编辑区、自动缩进、括号自动补全与匹配高亮、#注释识别、可点击切换的断点栏，以及按需弹出的代码补全菜单。如需语法着色，可将 GDScriptSyntaxHighlighter 或自定义的SyntaxHighlighter资源挂载到 CodeEdit 上，从而把文本编辑器升级为真正的源码编辑器。

小结

CodeEdit 把现代代码编辑器的高频能力浓缩为一个开箱即用的 Godot 控件：行号与缩进管理、自动括号补全与匹配高亮、行折叠与代码区域、字符串/注释定界符识别、完整的代码补全闭环（候选队列 → 过滤 → 确认插入）、符号查找与悬停提示，以及面向调试的书签/断点/执行行标记。其 API 设计以"可覆写的虚拟方法 + 信号"双通道开放，既能通过code_completion_requested、symbol_validate等信号与外部逻辑解耦，也可直接继承 CodeEdit 覆写_request_code_completion()等钩子深度定制。无论是为游戏内嵌一个脚本输入框、制作教学工具，还是构建自定义编辑器，CodeEdit 都是最直接的技术底座。如需继续深挖，可对照阅读基类 TextEdit 文档（掌握全部底层文本编辑能力）、ScriptEditorBase 文档（了解引擎脚本编辑器如何复用 CodeEdit），以及 Godot 4.1 升级指南（了解补全 API 的版本演进）。

• 文档
• 教程
• 游戏开发