docs(coroutine): 更新协程相关文档

- 添加了 AsCoroutineInstruction()、ToCoroutineEnumerator() 和 StartTaskAsCoroutine()
  的使用场景说明
- 优化了等待异步方法的文档描述,明确不同 API 的适用场景
- 详细说明了 CancelWith 方法的节点有效性判断机制和停止条件
- 补充了 Godot 协程中 Task 转协程的具体使用建议
This commit is contained in:
GeWuYou 2026-03-12 12:49:29 +08:00
parent 1c30149ebd
commit 4362989056
2 changed files with 19 additions and 3 deletions

View File

@ -175,6 +175,11 @@ var handle1 = scheduler.Run(coroutine);
var handle2 = scheduler.StartTaskAsCoroutine(LoadDataAsync());
```
- `AsCoroutineInstruction()` 适合已经处在某个协程内部,只需要在当前位置等待 `Task` 完成的场景。
- `ToCoroutineEnumerator()` 适合需要把 `Task` 先转换成 `IEnumerator<IYieldInstruction>`,再传给 `scheduler.Run(...)`
`Sequence(...)` 或其他只接受协程枚举器的 API。
- `StartTaskAsCoroutine()` 适合已经持有 `CoroutineScheduler`,并希望把 `Task` 直接作为一个顶层协程启动的场景。
### 等待事件
```csharp
@ -408,8 +413,8 @@ scheduler.OnCoroutineException += (handle, exception) =>
### 如何等待异步方法?
可以直接 `yield return task.AsCoroutineInstruction()`,也可以使用 `scheduler.StartTaskAsCoroutine(task)` 启动一个以 Task
为主体的协程
在现有协程里等待 `Task` 时,优先使用 `yield return task.AsCoroutineInstruction()`;如果要把 `Task` 单独交给调度器启动,使用
`scheduler.StartTaskAsCoroutine(task)`;如果中间还需要传给只接受协程枚举器的 API则先调用 `task.ToCoroutineEnumerator()`
## 相关文档

View File

@ -103,7 +103,14 @@ public partial class MyNode : Node
- `CancelWith(Node node1, Node node2)`
- `CancelWith(params Node[] nodes)`
只要任一被监视的节点失效,包装后的协程就会停止继续枚举。
`CancelWith(...)` 内部通过 `Timing.IsNodeAlive(...)` 判断节点是否仍然有效。只要任一被监视的节点出现以下任一情况,包装后的协程就会停止继续枚举:
- 节点引用为 `null`
- Godot 实例已经失效或已被释放
- 节点已进入 `queue_free` / `IsQueuedForDeletion()`
- 节点已退出场景树,`IsInsideTree()` 返回 `false`
这意味着协程不只会在节点真正释放时停止;节点一旦退出场景树,下一次推进时也会停止。
## Segment 分段
@ -195,6 +202,10 @@ LoadSomethingAsync()
.RunCoroutine();
```
- 已经在一个协程内部时,优先使用 `yield return task.AsCoroutineInstruction()`,这样可以直接把 `Task` 嵌入当前协程流程。
- 如果要把一个现成的 `Task` 当作独立协程入口交给 Godot 协程系统运行,再使用
`task.ToCoroutineEnumerator().RunCoroutine()`
### 等待事件总线事件
可以通过事件总线等待业务事件: