Keel v0.5.1 English GitHub

Form

在线示例:这是真实的 Keel 程序编译成 WebAssembly,可以直接操作。首次加载约 10 MB。全屏打开
示例代码Go · 可复制

这是上方组件库展示案例的完整源码。examples/components/form.go

在脚手架项目中复用组件构造和 Render 写法;示例的 registerSection 与共享辅助函数由组件库提供。

package main

import (
	"github.com/dyike/keel/ui/core"
	"github.com/dyike/keel/ui/el"
	"github.com/dyike/keel/ui/kit"
	"github.com/dyike/keel/ui/theme"
	"time"
)

func init() {
	registerSection("form", "inputs", func() core.Widget {
		name := kit.Input("").Placeholder(demoText("At least 2 characters", "至少 2 个字"))
		email := kit.Input("").Placeholder("name@example.com")
		role := kit.Select("", demoText("Administrator", "管理员"), demoText("Members", "成员"), demoText("Guest", "访客"))
		msg := ""
		f := kit.Form().VerticalLabels(true).
			Field(demoText("Name", "姓名"), name, func() string {
				if len([]rune(name.Value())) < 2 {
					return demoText("Name must contain at least 2 characters", "姓名至少 2 个字")
				}
				return ""
			}).
			Field(demoText("Email", "邮箱"), email, func() string {
				return kit.Required(email.Value(), demoText("Enter an email address", "请填写邮箱"))
			}).
			Field(demoText("Role", "角色"), role, func() string { return kit.Required(role.Value(), demoText("Choose a role", "请选择角色")) })
		f.SetFieldOptions(0, kit.FormFieldOptions{Required: true, Description: demoText("Name shown publicly", "公开显示的姓名")})
		f.SetFieldOptions(1, kit.FormFieldOptions{Required: true, Description: demoText("Used for receiving notifications", "用于接收通知")})
		f.SetFieldOptions(2, kit.FormFieldOptions{Required: true, ColSpan: 2})
		var submit func(cx *el.Context)
		f.Actions(el.ViewFunc(func(cx *el.Context) el.Element {
			return kit.Button(demoText("Submit", "提交"), func() { submit(cx) }).Loading(f.Submitting()).Render(cx)
		}), el.ViewFunc(func(cx *el.Context) el.Element {
			return kit.Button(demoText("Cancel submission", "取消提交"), f.CancelSubmit).Variant(kit.ButtonSecondary).Render(cx)
		}), el.ViewFunc(func(*el.Context) el.Element { return el.Text(msg).TextColor(theme.Muted) }))
		submit = func(cx *el.Context) {
			token := f.BeginSubmit(cx)
			if token == 0 {
				return
			}
			submittedName := name.Value()
			msg = demoText("Validating and submitting…", "正在校验并提交…")
			go func() {
				time.Sleep(600 * time.Millisecond)
				core.Update(func() {
					var errors []string
					if submittedName == "admin" {
						errors = []string{demoText("This name is already taken", "此名称已被占用")}
					}
					if f.FinishSubmit(token, errors) {
						if len(errors) > 0 {
							msg = demoText("Correct the fields", "请修正字段")
						} else {
							msg = demoText("Submitted ", "已提交 ") + submittedName
						}
					}
				})
			}()
		}
		return el.Root(el.ViewFunc(func(cx *el.Context) el.Element {
			width, _ := cx.ViewportSize()
			columns := 1
			if width >= 640 {
				columns = 2
			}
			f.Columns(columns)
			return el.Div().P(24).Items(el.Start).Child(el.Div().W(el.Dp(640)).MaxW(el.Full).Child(f.Render(cx)))
		}))
	})
}

两列表单:左边是标签,右边是控件,提交时统一校验。

name := kit.Input("")
amount := kit.NumberInput("").Range(0, 1e6)
f := kit.Form().
    Field("客户", name, func() string { return kit.Required(name.Value(), "请填写客户") }).
    Field("金额", amount, func() string {
        if amount.Value() <= 0 {
            return "金额必须大于 0"
        }
        return ""
    })
kit.Button("创建", func() {
    if f.Validate(cx) {
        create()
    }
})
  • 校验函数返回错误信息,合法时返回空字符串;可以传 nil 表示不校验这一项。
  • Validate(cx) 运行可见字段的全部校验、在各字段下显示错误、把焦点移到第一个不合法的字段,返回是否全部通过。必须在回调里调用。
  • 自带错误展示的控件按各自编辑规则清除错误;其他控件的错误由 Form 显示,保留到下次校验或异步结果更新。Errors() 返回各字段当前错误的副本。
  • 控件不需要再传标签:Form 会把行标签作为控件的无障碍名称。
  • 自带错误展示的控件实现了 kit.Validatable(SetError、FocusID),包括 Input、TextArea、Select、NumberInput、OtpInput、TimeField、Combobox、DatePicker。
  • kit.Required(s, msg) 在 s 为空或全是空白时返回 msg。LabelWidth(dp) 设置标签列宽,默认 72。
  • Actions(views...) 放在字段下方的按钮行,和控件列左对齐;提交中仍可点击,方便取消。

Agent:容器角色 form,行标签是 text,控件以行标签为名字。

验证:go run ./examples/components -section form,加 -theme dark 检查深色。

所有可见字段的非 nil 校验函数都会执行。Checkbox、Switch、Radio、Slider、Rating 等非文本字段的错误由 Form 放在控件下方;有 FocusID 时聚焦控件,否则聚焦错误字段容器。禁用字段不会成为焦点目标。NumberInput、TimeField 和 Combobox 的可用编辑草稿在校验前提交,避免校验读取旧值。Required 将 Unicode 空白(含全角空格)视为空值。

异步校验与提交共用一次请求:

token := f.BeginSubmit(cx)
if token == 0 { return } // 同步校验失败、禁用或已有请求
payload := customer.Value() // 在 UI 回调里捕获,后台只使用快照
go func() {
    errors := validateAndSave(payload) // []string,按 Field 顺序;nil 表示成功
    core.Update(func() { f.FinishSubmit(token, errors) })
}()

Submitting() 为 true 时字段不可编辑,重复 BeginSubmit 返回 0;外部提交按钮可用 .Loading(f.Submitting()) 显示忙碌状态。FinishSubmit 恢复编辑、展示各字段错误,并在字段恢复可用后聚焦首个错误。错误切片可短于字段数,剩余字段按无错误处理;过长切片、过期或取消的 token 返回 false,不改变状态。

CancelSubmit() 使未完成结果失效并恢复编辑;它不会取消业务 goroutine 的网络请求,应用需要自行取消 I/O。SetDisabled(true)、祖先禁用或再次同步 Validate 也会使请求失效。程序在提交期间替换字段值、或移除表单时,应先调用 CancelSubmit。后台只能通过 core.Update 调用完成接口。

多列与字段配置

Columns(n) 将字段排成 n 个等宽网格列,至少一列;VerticalLabels(true) 把标签放到控件上方。两者独立,默认仍为单字段列、标签在左。响应式断点由应用决定,可在 Render 中按可用宽度调用 Columns。Gap(dp) 设置字段间距,LabelTextSize(sp) 设置标签字号(0 恢复继承)。控件大小由各控件自身配置。

f := kit.Form().Columns(2).VerticalLabels(true).
    FieldWithOptions("姓名", name, validateName, kit.FormFieldOptions{
        Required: true, Description: "公开显示的姓名",
    }).
    FieldWithOptions("邮箱", email, validateEmail, kit.FormFieldOptions{
        Required: true,
    }).
    FieldWithOptions("介绍", bio, nil, kit.FormFieldOptions{ColSpan: 2}).
    Footer(kit.Button("保存", save))

ColSpan 默认 1,限制在当前列数以内;ColStart 从 1 计数,0 表示顺序排列。指定起始列已被当前行占用时从下一行开始;起始列和跨度超过网格边界时收缩到可用列。隐藏字段不占网格位置。Actions 继续按原有方式排列;Footer 独占底部全宽并靠右对齐,可与 Actions 共用,提交中保持可用。

Required 只显示星号,不替代校验器。Description 显示控件下的辅助文字;DescriptionContent 可提供富内容或动态 View,优先于纯文本。Hidden 默认 false;隐藏字段不渲染、不提交草稿、不执行校验,也不会成为错误聚焦目标。其他字段的插入索引和输入状态不受影响。

SetFieldOptions(index, options) 按添加顺序替换配置,非法索引返回 false。改变 Hidden 会取消正在进行的提交并清除此字段错误;其他展示配置变更不会取消提交。异步错误数组仍按完整字段顺序传入,隐藏字段对应的错误被忽略。不要直接修改提交快照中的业务数据。

自动测试覆盖 1×/2× 网格定位、跨列、起始列、隐藏、缩为单列、输入状态、必填提示/说明/页尾,以及隐藏字段校验和异步失效。示例展示响应式两列,尚未完成真机视觉验收。