Vugu v2 `vg-for` 循环指令实战指南:从基础 for 循环到 Go 1.23 迭代器

原创2026-10-14 13:44:001,730 阅读
文章标签:前端Web框架

Vugu v2 vg-for 循环指令实战指南:从基础 for 循环到 Go 1.23 迭代器

vg-for 是 Vugu(Go + WebAssembly 前端框架,v2 版本)中用于在模板里渲染列表的核心指令。本文以官方示例 v2/examples/vg-for 为骨架,完整讲解该示例的构建、运行与修改方法,并结合 root.vugu 的源码逐一剖析五种 vg-for 写法(for i 循环、key/value 循环、快捷写法、排序循环、迭代器循环),最后深入 vugugen 代码生成器源码,解释 vg-for 在底层是如何被翻译成真实 Go 循环的。读完本文,你将能在自己的 Vugu 项目中熟练使用 vg-for 渲染任何列表数据,并理解其与 vg-if、vg-content 的组合用法。

示例概览:一个页面展示五种循环写法

vg-for 是一个 HTML 元素上的属性(attribute),作用与 JavaScript 框架中的 v-for、v-for 类似:让被标记的元素(及其子树)按照 Go 表达式的返回结果反复生成。本示例的页面标题是 "vg-for Loop Examples",通过 5 个按钮分别控制 5 个循环示例区块的显示与隐藏,分别演示:

区块 vg-for 写法 迭代目标
for i 循环 i:=0;i<c.DaysInWeek();i++ 数组 [7]string(一周七天)
key/value 循环 k, v := range c.DaysInWeekIth() map[string]string
快捷写法 c.DaysInWeekIth() 由生成器自动展开为 key, value := range ...
排序循环 index, value := range c.DaysInWeekIthSorted() 按 key 排序后的 slice
迭代器循环 index := range c.DaysInWeekIterator() Go 1.23 的 iter.Seq2[int, string]

按钮与各区块之间通过组件方法 ToggleForILoop()、ToggleKVLoop()、ToggleShortCutLoop()、ToggleSortedLoop()、ToggleIteratorLoop() 切换布尔字段,配合 vg-if='c.ShowXxxLoop()' 控制对应 <div> 是否渲染。这是 Vugu 中"事件驱动重新渲染"的典型模式:点击按钮 → 方法翻转布尔值 → 触发重渲染 → vg-if 决定区块显隐。

构建示例

前置条件

构建本示例需要预先安装两个工具:

  • docker:示例最终通过本地 nginx 容器来托管 main.wasm 与 index.html;
  • mage:Vugu 项目首选的构建工具,magefile.go 中定义了所有构建任务。

如果只想用自己习惯的构建工具而不使用 mage,可以参照 v2/examples/Readme.md 中"不使用 mage 构建"一节的手工步骤(下文也会给出)。需要说明的是,这些示例模块不能被 go get 直接获取,必须克隆整个仓库后进入 v2 目录操作。

克隆仓库并进入 v2 目录

git clone https://github.com/vugu/vugu
cd vugu/v2

注意:示例位于 v2/examples 下,是一个独立的 Go module,其 go.mod 通过 replace github.com/vugu/vugu/v2 => ../.. 指向仓库内的 v2 源码,因此必须在本仓库克隆目录中构建。

用 mage 构建单个示例

mage SingleExample github.com/vugu/vugu/v2/examples/vg-for

SingleExample 任务(定义于 v2/magefiles/magefile.go)会先构建 vugu 包与 vugugen 工具(保证示例始终使用最新版工具链),然后拉取 nginx 镜像、启动本地容器,最后把指定模块编译成 WebAssembly 二进制。构建成功后,shell 中会输出如下提示:

Local nginx container started.
Connect to http://localhost:8889/<example-test-directory-name>
e,g. http://localhost:8889/fetch-and-display
To stop the local nginx container please run:
	mage StopLocalNginxForExamples

这里的 8889 端口来自 StartLocalNginxForExamples 任务对 nginx 容器的端口映射,整个 examples 目录会被只读挂载进容器(详见 v2/examples/Readme.md 中的 docker run --mount type=bind,source=./examples,target=/usr/share/nginx/html,readonly -p 8889:80)。因此只要一个示例被构建过,访问任意 <目录名> 路径即可打开对应页面。

不使用 mage 的手工构建方式

如果必须使用其他构建工具,可以手工复刻 mage 的步骤(以本示例为例):

# 安装 vugu 包与 vugugen 工具
go install github.com/vugu/vugu/v2
go install github.com/vugu/vugu/v2/cmd/vugugen

# 进入示例目录,由 *.vugu 生成 *_gen_js_wasm.go 等 Go 源码
cd v2/examples/vg-for
vugugen

# 交叉编译出 WebAssembly 二进制(注意传模块名而非文件列表)
GOOS=js GOARCH=wasm go build -o ./main.wasm github.com/vugu/vugu/v2/examples/vg-for

生成的 main.wasm 需要由 Web 服务器托管,配合 index.html 一起提供。index.html 中通过 WebAssembly.instantiateStreaming(fetch("/vg-for/main.wasm"), ...) 加载 wasm,并把内容渲染进 id="vugu_mount_point" 的 <div> 中——这个挂载点 id 与 main_wasm.go 中的 mountPoint := "#vugu_mount_point" 必须严格一致。

运行示例

构建完成后,直接在浏览器打开:

http://localhost:8889/vg-for/

页面加载后会看到 5 个切换按钮。点击 "Toggle "for i" loop" 会渲染出一周七天的列表;点击其他按钮会渲染对应风格的循环结果。观察点包括:

  • key/value 与快捷写法都迭代同一个 Go map,而 Go 语言规范规定 map 的遍历顺序是随机的,因此每次点击重渲染,列表顺序都可能不同;
  • 排序循环用 maps.Keys + slices.Sorted 把 map 的 key("1st"、"2nd"…)按字母序排序后输出;
  • 迭代器循环会由组件内的迭代器函数逐条 yield 数据,同时在浏览器控制台打印每一条 i: 0, v:Monday 之类的日志。

修改示例并即时生效

修改示例同样简单。核心原则是:改 root.go(组件逻辑)或 root.vugu(模板),然后重新运行 mage SingleExample ...,最后刷新浏览器,让浏览器加载新的 wasm 二进制。

原文档给出的示范是给 Root.ListLength() 方法增加一行日志(该方法为旧版示例中返回列表长度的方法,当前仓库版本的 Root 结构已改为 daysInWeek 数组与 daysInWeekIth 映射字段,见 root.go,但修改思路完全一致)。你可以把下面这段演示代码中的方法名替换成当前组件里任意方法,例如 DaysInWeek():

// Return the current list length
func (c *Root) ListLength() int {
    fmt.Printf("Current list length: %d\n", len(c.list))
    return len(c.list)
}

修改后重新构建:

mage SingleExample github.com/vugu/vugu/v2/examples/vg-for

再次浏览 http://localhost:8889/vg-for/ 并刷新浏览器,就可以在浏览器 JavaScript 控制台中看到 fmt.Printf 输出的日志——这是调试 Vugu 组件最直接的手段。注意 root.go 已经导入了 fmt 包,无需额外添加 import。

如果修改了 *.vugu 模板,则重新运行 vugugen(或 mage SingleExample,它会自动触发代码生成)即可。仓库中的 root_gen_js_wasm.go 就是由 root.vugu 生成的、带 //go:build js && wasm 构建标签的代码文件。

源码级剖析:五种 vg-for 写法

以下代码均摘自 root.vugu,可对照 root_gen_js_wasm.go 中生成的 Go 代码查看一一对应关系。

1. for i 循环:遍历数组下标

<li vg-for='i:=0;i<c.DaysInWeek();i++'>
    <div vg-content='fmt.Sprintf("%s is day number %d", c.DayOfWeek(i),i+1)'></div>
</li>

这是标准 Go 的三段式 for 写法(初始化;条件;步进)。c.DaysInWeek() 返回常量 numberOfDaysInWeek = 7,c.DayOfWeek(i) 按下标返回 daysInWeek 数组中的星期名。生成的代码为 for i := 0; i < c.DaysInWeek(); i++ { ... },循环体内部每次创建新的 li 节点。

2. key/value 循环:遍历 Go map

<li vg-for='k, v := range c.DaysInWeekIth()'>
    <div vg-content='fmt.Sprintf("The %s day of the week is %s", k, v)'></div>
</li>

c.DaysInWeekIth() 返回 map[string]string(如 "1st" -> "Monday")。模板里直接在循环体内引用 k、v 两个变量。注意 map 遍历顺序随机,因此每次渲染顺序都不同——这正是示例刻意展示的行为。

3. 快捷写法:自动展开为 key/value

<li vg-for='c.DaysInWeekIth()'>
    <div vg-content='fmt.Sprintf("The %s day of the week is %s", key, value)'></div>
</li>

这是 vg-for 的一个特殊快捷语法:如果 vg-for 的属性值中不含空白字符(即不是一个完整的 Go 循环语句),生成器会自动把它展开为:

for key, value := range expr

其中 expr 应当返回两个值(可以是一个方法调用,就像这里的 c.DaysInWeekIth())。展开后模板中即可隐式引用 key 与 value 两个变量。这一展开逻辑实现在 v2/gen/parser-go.go 的 emitForExpr 函数中:

if !strings.Contains(forx, ":=") {
    // make it so `w` is a shorthand for `key, value := range w`
    forx = "key, value := range " + forx
    shortcutCase = true
}

由于生成器无法预知 key/value 是否真的在标签内被使用,它会额外补两行 _ = key、_ = value,避免 Go 编译器报"变量声明未使用"错误(这也解释了生成的 root_gen_js_wasm.go 中 for key, value := range c.DaysInWeekIth() { _ = key; _ = value; ... } 的来历)。

4. 排序循环:maps + slices 组合

<li vg-for='index, value := range c.DaysInWeekIthSorted()'>
    <div vg-content='fmt.Sprintf("The %s day of the week is  %s", value, c.DayOfWeek(index))'></div>
</li>

c.DaysInWeekIthSorted() 在 root.go 中的实现为:

func (c *Root) DaysInWeekIthSorted() []string {
    return slices.Sorted(maps.Keys(c.daysInWeekIth))
}

它使用 Go 新标准库 maps.Keys 取出 map 的所有 key,再交给 slices.Sorted 排序,返回一个按 key 字母序排列的 []string。于是 index 是排序后的位置,value 是 "1st"、"2nd" 之类的 key,再通过 c.DayOfWeek(index) 反查星期名。

5. 迭代器循环:Go 1.23 range-over-func

<li vg-for='index := range c.DaysInWeekIterator()'>
    <div vg-content='fmt.Sprintf("The day of the week at index %d is %s", index, c.DayOfWeek(index))'></div>
</li>

c.DaysInWeekIterator() 返回 iter.Seq2[int, string](Go 1.23 引入的迭代器类型),实现为一个闭包式的 yield 函数:

func (c *Root) DaysInWeekIterator() iter.Seq2[int, string] {
    return func(yield func(int, string) bool) {
        for i, v := range c.daysInWeek {
            fmt.Printf("i: %d, v:%s\n", i, v)
            if !yield(i, v) {
                return
            }
        }
    }
}

模板中的 index := range c.DaysInWeekIterator() 正是 Go 1.23 的 range-over-function 语法,逐条从迭代器取下标。得益于 vg-for 的表达式直接透传为 Go 循环语句,任何 Go 语法层面的迭代能力(包括标准库迭代器、自定义 iter.Seq 等)都能在模板中直接使用。

vg-for 属性如何被识别

vg-for 的解析入口在 v2/gen/parser-util.go 的 vgForExpr 函数:它遍历元素的属性,寻找以 vg-for 开头的属性名(支持形如 vg-for.xxx 的选项点分形式),取出属性值并去掉首尾空白后返回;staticVGAttr 则会把所有 vg- 前缀、.、:、@ 开头的属性从静态属性中剔除,交由代码生成器特殊处理。组件元素(如 <MyComp vg-for=...>)的循环处理则位于 v2/gen/parser-component.go,普通 HTML 元素走 v2/gen/parser-go.go 的 emitForExpr。总体而言,vg-for、vg-if、vg-content 在编译期就被翻译成了普通的 Go for / if / SetInnerHTML 语句,运行期没有任何模板解释开销。

运行环境要求

本示例(尤其是迭代器与排序写法)依赖 Go 1.23+ 的 iter、maps、slices 包。示例的 go.mod 声明 go 1.25.0,并依赖 github.com/vugu/vjson 与 github.com/vugu/vugu/v2(后者通过 replace 指向仓库根目录)。浏览器侧则需要支持 WebAssembly;如果浏览器不支持,index.html 会显示 "This application requires WebAssembly support. Please upgrade your browser."。构建产物是 GOOS=js GOARCH=wasm 交叉编译出的 main.wasm,必须通过 HTTP 服务(如 mage 启动的本地 nginx 容器)访问,直接 file:// 打开无法加载。

停止示例所用的 nginx 容器时,执行:

mage StopLocalNginxForExamples

该任务(同样定义于 v2/magefiles/magefile.go)会停止并清理本地 nginx 容器。

登录后查看全文
vugu