Keel v0.5.1 English GitHub

Questionnaire

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

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

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

package main

import (
	"fmt"
	"strings"

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

func init() {
	registerSection("questionnaire", "inputs", func() core.Widget {
		result := ""
		q := kit.Questionnaire(
			kit.Question{ID: "role", Title: demoText("What is your role in the team?", "你在团队里的角色?"), Kind: kit.QuestionSingle, Options: []string{demoText("Development", "开发"), demoText("Design", "设计"), demoText("Product", "产品")}, FreeformLabel: demoText("Other role", "其他角色"), Required: true},
			kit.Question{ID: "tools", Title: demoText("Which tools do you use?", "平时用哪些工具?"), Description: demoText("Select multiple options. Figma is disabled; number shortcuts follow selectable option order.", "可以多选;Figma 暂不可选,数字快捷键按可选项编号"), Kind: kit.QuestionMultiple, Options: []string{"Go", "Figma", "Git", "Keel"}, FreeformLabel: demoText("Other tools", "其他工具")},
			kit.Question{ID: "score", Title: demoText("Overall satisfaction", "整体满意度"), Kind: kit.QuestionRating, Required: true},
			kit.Question{ID: "name", Title: demoText("What is your name?", "怎么称呼你?"), Kind: kit.QuestionText},
			kit.Question{ID: "note", Title: demoText("Any other suggestions?", "还有什么建议?"), Kind: kit.QuestionLongText},
		)
		q.Shortcuts(kit.QuestionnaireShortcutsNumbers)
		q.SetChoiceDisabled("tools", "Figma", true)
		q.OnSubmit(func(a map[string]kit.Answer) {
			result = fmt.Sprintf(demoText("Submitted: %s · %s · %d stars", "已提交:%s · %s · %d 星"), a["role"].Text, strings.Join(a["tools"].Choices, "/"), a["score"].Rating)
		})
		density := kit.QuestionnaireSizeMedium
		disabled := false
		custom := true
		q.Layout(func(cx *el.Context, state kit.QuestionnaireContext, parts kit.QuestionnaireParts) el.Element {
			if !custom {
				return nil
			}
			return el.Div().Gap(12).Items(el.Stretch).Child(
				parts.Progress,
				el.Div().Border(1, theme.Outline).Rounded(theme.RadiusLg).P(16).Gap(12).Items(el.Stretch).Child(parts.Title, parts.Description, parts.Answer, parts.Freeform, parts.Error),
				el.Div().Row().Gap(8).Child(parts.Previous, el.Div().Grow(), parts.Skip, parts.Forward),
			)
		})
		return el.Embed(el.ViewFunc(func(cx *el.Context) el.Element {
			return el.Div().P(24).Gap(16).W(el.Dp(480)).MaxW(el.Full).Child(kit.Button(demoText("Enable / disable questionnaire", "启用 / 禁用问卷"), func() { disabled = !disabled; q.SetDisabled(disabled) }).Variant(kit.ButtonSecondary).Render(cx), kit.Button(demoText("Toggle default / custom layout", "切换默认 / 自定义布局"), func() { custom = !custom }).Render(cx), kit.Button(demoText("Change questionnaire size", "切换问卷尺寸"), func() { density = (density + 1) % 4; q.Size(density) }).Render(cx), q.Render(cx), el.Text(result).TextColor(theme.Muted))
		}))
	})
}

一页一题的问卷。

q := kit.Questionnaire(
    kit.Question{ID: "role", Title: "你的角色?", Kind: kit.QuestionSingle, Options: roles, Required: true},
    kit.Question{ID: "tools", Title: "常用工具", Kind: kit.QuestionMultiple, Options: tools},
    kit.Question{ID: "score", Title: "满意度", Kind: kit.QuestionRating, Scale: 5, Required: true},
    kit.Question{ID: "note", Title: "建议", Kind: kit.QuestionLongText},
).OnSubmit(func(a map[string]kit.Answer) { save(a) })
  • 题型:QuestionSingle(单选)、QuestionMultiple(多选)、QuestionText(单行文本)、QuestionLongText(多行文本)、QuestionRating(星级评分,默认 5 星)。
  • 顶部是进度条,显示"第 3 / 10 题"。点"下一题"时,必填题没有作答会显示错误,不能翻页;作答后错误自动消失。
  • 最后一页的"提交"会校验全部启用题;未作答、未主动跳过或有校验错误时跳到首个错误题,通过后调用 OnSubmit。
  • 答案用 Answer 表示,按题目类型填写 Text、Choices(按选项顺序)、Rating,可另带 Freeform 或 Skipped;Answer.Empty() 判断是否作答。
  • Value() 返回目前所有的答案;SetValue 回填答案,比如恢复草稿;Page() / SetPage(i) 读取或切换当前页。
  • "上一题""下一题""提交"、进度文字、必填提示都来自 locale。

Agent:容器角色 form,名字是进度文字;当前题目是以题目标题命名的 group,控件以题目标题为名字。

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

SetDisabled(true) 禁用当前答案控件、前后翻页和提交,不触发校验或 OnSubmit;程序仍可调用 SetPage、SetValue。重新启用后保留当前页及答案。

构造时复制题目及选项,之后修改原始切片不会改变问卷。题目 ID 必须非空且唯一;不支持的题型会在构造时 panic。Value 与 OnSubmit 提供独立的答案快照,修改返回 map 或多选答案切片不会影响内部状态。

条件题、跳过与完成状态

Question.Disabled 设置初始禁用条件,SetQuestionDisabled(id, on) 动态更新,未知 ID 返回 false。禁用题退出导航、进度、校验和提交,但保留草稿,Value 仍可读到。禁用当前题时先找后面的可用题,再找前面的题;全部禁用时 Page 为 -1,组件隐藏。应用可在 OnAnswerChange(func(id string, answer kit.Answer)) 中根据前题答案更新条件。

可选题现在需要作答或显式跳过,不能把“还没答”隐式当作完成。Skip() / “跳过”按钮清空当前可选题答案,保存 Answer.Skipped=true 并前进;最后一题跳过后尝试提交。必填题不能跳过。回到跳过的题重新作答会清除跳过状态。SetValue 支持恢复可选题的 Skipped 状态。

Progress() 返回当前启用题集合的快照:Current 从 1 开始,Total、Answered、Skipped、Unanswered 分别是总题数及三种作答状态的数量,Completed 表示已经完成一次有效提交。OnComplete 只在进入完成状态时执行,首次有效提交中先于 OnSubmit;每次有效提交仍调用 OnSubmit。修改答案、条件或外部错误会使完成状态失效。提交快照只包含启用题;Value 仍包含所有题。

自由输入和校验

单选、多选题可设置 FreeformLabel,显示有名称的自由输入框。Answer.Freeform 保存有效自由文本;空白文本不算作答。单选题在选项和自由输入之间切换,选择固定选项时保留自由输入草稿,但不将其作为有效答案提交;重新输入时自由输入生效。多选题允许 Choices 与 Freeform 同时作答。

Question.Validate func(Answer, map[string]Answer) string 做同步自定义校验,收到当前题答案和启用题的独立答案快照,返回空串表示通过。下一题校验当前题,提交校验所有启用题并定位第一道错误题;必填/未作答检查在自定义校验之前,主动跳过不运行自定义校验。回调应只检查快照,不修改问卷。

SetExternalError(id, message) 保存服务器或应用错误,空串清除;ExternalError(id) 查询。外部错误优先显示并阻止通过,输入和 Reset 都不会自动清除。应用负责在接受新答案后清除它,不自动发起网络校验。

Question.DefaultAnswer 定义构造时的默认答案,Choices 会复制。Reset() 恢复这份默认答案、清除内部错误和完成状态,回到第一道启用题;保留外部错误与当前禁用条件。后续 SetValue 只改变当前答案,不移动 Reset 基线。

选项快捷键

Shortcuts(kit.QuestionnaireShortcutsLetters) 开启 A–Z,QuestionnaireShortcutsNumbers 开启 1–9,默认 Off。快捷键按当前题未禁用选项的顺序映射,单选选中,多选切换;只在问卷获得焦点且焦点不在文本输入中时处理,不处理带修饰键的按键。按住按键不重复切换,释放后可再次触发。默认键盘导航支持左右键前后翻题、上下键在多选控件/自由输入之间移动焦点、Enter 确认已作答或已跳过的当前题,以及 Cmd/Ctrl+Enter 从文本输入确认。文本输入保留普通方向键和 Enter;单选组、评分控件保留自身方向键行为;操作按钮保留 Enter 激活。空答案不会因 Enter 隐式提交。KeyboardNavigation(false) 关闭这些导航绑定,独立于选项快捷键配置。选项文字应由应用提示对应快捷键。

自动测试覆盖条件导航、禁用题排除、跳过、重新提交、完成事件、外部错误/Reset、自定义校验、自由输入保留及选项快捷键;尚未完成真机视觉/输入法验收。

SetChoiceDisabled(questionID, option, on) 动态禁用固定选项,未知题/选项返回 false。禁用项保留内部选择草稿,但退出有效答案、校验快照和快捷键编号;重新启用恢复有效答案,条件变化会清除完成状态。全题必填规则仍生效:若禁用了全部选项且没有可用自由输入,应用应同时禁用该题以避免无法作答。程序 SetValue 可以恢复禁用项的草稿,但 Value/提交只包含可用项。

新增自动测试覆盖默认答案所有权/Reset、禁用项有效答案与快捷键重编号、文本 Cmd/Ctrl+Enter、普通箭头保护、多选焦点移动和关闭导航;未做真机输入法及视觉验收。

自定义组合布局

Layout(func(cx, state, parts) el.Element) 可重新排列当前题目的组成部分。QuestionnaireParts 提供 Progress、Title、Description、Answer、Freeform、Error、Previous、Skip、Forward;不适用的部分为 nil。返回 nil 或 Layout(nil) 恢复默认排列。

这些元素使用同一份答案控件与原有校验/跳过/提交命令。外层 form 始终保留禁用继承、键盘导航和焦点管理。每个元素只能放入本帧树中一次,不能跨帧保存;通常应保留 Answer 和导航按钮。省略部件只隐藏对应界面,不会关闭快捷键命令。自定义布局改变控件的树路径时,输入焦点和选区可能重置。

QuestionnaireContext 提供当前 Question、Answer、Progress、从零开始的 Page、错误文字及问卷自身 Disabled;题目选项、默认答案与当前答案的切片均为副本。不要在布局回调中修改问卷状态,修改应放在事件回调中。组件库提供默认布局与自定义卡片的切换。自动测试覆盖组合后的必填校验、输入、禁用提交、上下文副本及默认布局恢复;原生输入法未验收。

统一尺寸

Size(QuestionnaireSizeXSmall/Small/Medium/Large) 调整标题、说明、错误字号、选项标记和文字、评分星形、输入框、部件间距与导航按钮。默认 Medium 沿用原布局;大小切换保留答案和控件实例。自定义 Layout 可从 QuestionnaireContext.Size 读取档位,提供的内置部件已应用尺寸,应用新增的容器与控件自行配置。组件库提供循环切换按钮;自动测试覆盖双倍率五种题型、四档导航按钮、答案保留、省略部件及恢复输入。原生视觉未验收。