Keel v0.5.1 English GitHub

Settings

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

这是上方组件库展示案例的完整源码。examples/components/settings.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/locale"
	"github.com/dyike/keel/ui/markdown"
	"github.com/dyike/keel/ui/theme"
)

func init() {
	registerSection("settings", "shell", func() core.Widget {
		initialLanguage := locale.Current()
		lang := kit.Select("", "中文", "English").OnChange(func(s string) {
			if s == "English" {
				locale.Apply(locale.English())
			} else {
				locale.Apply(locale.Chinese())
			}
		})
		if initialLanguage.Lang == "en" {
			lang.SetValue("English")
		} else {
			lang.SetValue("中文")
		}
		dark := kit.Switch("", theme.Current().Bg == theme.Dark().Bg).OnChange(func(on bool) {
			if on {
				theme.Apply(theme.Dark())
			} else {
				theme.Apply(theme.Light())
			}
		})
		s := kit.Settings().Size(kit.SettingsSizeSmall).GroupNavigation(true).
			Page(kit.SettingPage{Title: demoText("General", "通用"), Icon: kit.IconSettings, Resettable: true, Groups: []kit.SettingGroup{
				{Title: demoText("Language", "语言"), Items: []kit.SettingItem{
					{Label: demoText("Language", "语言"), Description: demoText("Framework text follows the selected language", "框架文字随之切换"), Keywords: []string{"locale", "language"}, Control: lang, Reset: func() {
						if initialLanguage.Lang == "en" {
							lang.SetValue("English")
						} else {
							lang.SetValue("中文")
						}
						locale.Apply(initialLanguage)
					}},
				}},
				{Title: demoText("Appearance", "外观"), Footer: el.ViewFunc(func(*el.Context) el.Element {
					return el.Text(demoText("Reset restores the initial language and light theme.", "重置此页会恢复初始语言和浅色主题。"))
				}), Items: []kit.SettingItem{
					{Label: demoText("Dark mode", "深色模式"), Description: demoText("Takes effect immediately; no restart needed", "立即生效,无需重新启动"), DescriptionContent: markdown.New(demoText("**Takes effect immediately**, without restarting.", "**立即生效**,无需重新启动。")), Keywords: []string{"theme", "dark"}, Control: dark, Reset: func() { dark.SetValue(false); theme.Apply(theme.Light()) }},
				}},
			}}).
			Section(demoText("Notifications", "通知"), kit.IconBell,
				kit.SettingItem{Label: demoText("Email reminders", "邮件提醒"), Description: demoText("Send email for new orders", "新订单时发送邮件"), Control: kit.Switch("", true)},
				kit.SettingItem{Label: demoText("Reminder interval", "提醒间隔"), Control: kit.NumberInput("").Range(1, 60)}).
			Section(demoText("Privacy", "隐私"), kit.IconLock,
				kit.SettingItem{Label: demoText("Usage analytics", "使用统计"), Description: demoText("Send anonymous crash reports", "匿名发送崩溃报告"), Control: kit.Checkbox("", false)})
		return el.Root(s)
	})
}

设置页提供页面导航、页面内多组设置、搜索和整页重置。窗口窄于 600dp 时,导航移到顶部,控件排到说明下方。

name := kit.Input("")
s := kit.Settings().GroupVariant(kit.GroupBoxFill).
    Page(kit.SettingPage{
        Title: "通用", Icon: kit.IconSettings, Resettable: true,
        Groups: []kit.SettingGroup{
            {Title: "账户", Items: []kit.SettingItem{
                {Label: "显示名称", Description: "公开显示的名称",
                 Keywords: []string{"name", "profile"}, Control: name,
                 Reset: func() { name.SetValue("") }},
            }},
            {Title: "外观", Items: []kit.SettingItem{
                {Label: "主题", Description: "立即生效,无需重启",
                 DescriptionContent: markdown.New("**立即生效**,无需重启。"),
                 Control: themeSelect},
            }},
        },
    })

Section(title, icon, items...) 仍适用于只有一组的页面,可与 Page 混用。页面标题须唯一;Value / SetValue 读取和切换页面,首次添加的页面默认打开。TitleSuffix 接收页面标题后的视图。

SettingGroup.Footer 位于组的表面之外,跟随组一起滚动、过滤;它不是搜索内容,也不成为导航项。GroupVariant 设置统一外观,组的 Variant 指针可覆盖它,支持 GroupBox 的 Surface、Normal、Fill、Outline。未命中任何行的组不显示。

搜索不区分大小写,匹配 Label、Description 和独立的 Keywords。关键词不会显示。当前页面仍有匹配时保持选择,否则切到第一个匹配页;导航只显示匹配页。零结果保留选择但显示空状态,清空搜索保留当前选择。Query / SetQuery 可从应用操作搜索。

DescriptionContent 可接现有 markdown.New(...) 或任意 el.View,替代纯文本说明的显示;搜索内容仍由 Description 提供。富文本视图应在构建设置项时创建,以保留解析和交互状态。Content 替换整个行体,完全自定义的行也可用关键词搜索。Vertical 强制上下排列,Disabled 禁用整行,包括自定义内容内的交互。标准控件列宽 240dp;行标签会补给没有名称的控件。RowSpacing 调整行的上下留白,0 恢复主题默认;控件尺寸由传入的控件配置。

页面声明 Resettable: true 后显示本地化重置按钮。点击会调用该页所有未禁用行的 Reset,包括搜索隐藏的行;没有回调的行跳过。ResetPage(title) 提供程序入口,未开启重置的页面不执行。默认值、应用状态和持久化由回调维护,不通过反射修改控件;例如还原主题时,需要同时更新开关和 theme.Apply。

添加页面时会复制组、行、关键词和 Variant 值;视图和回调仍由应用共享。各行身份不随搜索结果的位置变化,控件状态在切页和搜索后保留。

通常直接用 el.Root(settings) 填满窗口。运行 go run ./examples/components -section settings 查看多组、关键词、Markdown 和重置示例;加 -theme dark 检查深色。自动测试覆盖原有 1×/2× 窄布局、键盘和状态保持,以及分组过滤、页尾、数据副本、整页重置、自定义行与禁用;本批未做真机视觉验收。

尺寸与分组导航

Size(SettingsSizeXSmall/Small/Medium/Large) 统一调整行标签/说明字号、内边距、横向间距和控件列宽,默认 Medium 保持原布局。RowSpacing 的非零值覆盖尺寸预设的行内边距;自定义 Content 和控件自身尺寸仍由应用配置。

GroupNavigation(true) 将有标题且命中搜索的分组加入导航;窄窗口显示当前页的分组按钮。ShowGroup(page, groupTitle) 切换页面并定位分组,可独立于导航开关使用。缺失、重名或被搜索过滤的组返回 false,不清空查询。目标位置由布局计算,支持离屏分组。Value() 始终返回页面标题,SetValue 取消待处理的分组定位。

自动测试覆盖双倍率宽窄窗口、离屏定位、分组点击、搜索过滤、重名拒绝与尺寸切换保留控件值;组件库默认展示 Small 和分组导航。原生视觉未验收。

SearchInSidebar(true) 将搜索框放在桌面侧栏顶部;窄布局仍将搜索框放在内容上方。

PageHeading(false) 在分组已有标题时隐藏页标题。侧栏搜索布局让无填充分组的内容与标题左对齐,并保持分类栏展开。

SettingPage.Category 将导航页面组织到侧栏分组标题下;留空保留无分组布局。

Settings 放在有限宽度的面板中时,使用 AvailableWidth(dp) 指定面板宽度, 让响应式布局按面板而非窗口判断;传入 0 恢复使用窗口宽度。启用侧栏搜索时, 小于 800dp 会切换为单行、可横向滚动的标签导航;小于 600dp 时,控件放到标签下方。 调整宽度会保留当前分类、搜索词和应用持有的输入值。

使用 SearchInSidebar(true).PageHeading(false) 时,顶部区域保持留白,不重复显示页面名称;第一个可见分组的标题固定在留白下方,正文在独立区域内滚动。

切换为横向布局后,侧栏搜索移到顶部 Settings 旁,输入框高度为 32dp。较矮或较窄窗口会缩小顶部留白。