Settings
Example sourceGo · Copyable
This is the complete source for the gallery example above.examples/components/settings.go
Reuse the component construction and Render methods in a scaffolded project. The example’s registerSection and shared helpers are provided by the component gallery.
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)
})
}
The settings page provides page navigation, multiple groups of settings within the page, search, and full page reset. When the window is narrower than 600dp, navigation is moved to the top and controls are arranged below the description.
name := kit.Input("")
s := kit.Settings().GroupVariant(kit.GroupBoxFill).
Page(kit.SettingPage{
Title: "General", Icon: kit.IconSettings, Resettable: true,
Groups: []kit.SettingGroup{
{Title: "Account", Items: []kit.SettingItem{
{Label: "Display name", Description: "Public display name",
Keywords: []string{"name", "profile"}, Control: name,
Reset: func() { name.SetValue("") }},
}},
{Title: "Appearance", Items: []kit.SettingItem{
{Label: "Theme", Description: "Takes effect immediately; no restart needed",
DescriptionContent: markdown.New("**Takes effect immediately**, without restarting."),
Control: themeSelect},
}},
},
})
Section(title, icon, items...) still works for pages with only one set, and can be mixed with Page. The page title must be unique; Value / SetValue reads and switches pages, and the page added for the first time is opened by default. TitleSuffix The view after receiving the page title.
SettingGroup.Footer is outside the group's surface and scrolls and filters with the group; it is not search content and does not become a navigation item. GroupVariant sets a unified appearance. The Variant pointer of the group can overwrite it. It supports Surface, Normal, Fill and Outline of GroupBox. Groups that do not hit any rows are not displayed.
The search is case-insensitive and matches Label, Description, and Keywords alone. Keywords will not be displayed. If there is still a match on the current page, keep it selected, otherwise it will switch to the first matching page; the navigation only displays the matching page. Zero results retain the selection but display an empty state, and a clear search retains the current selection. Query / SetQuery can be searched from the app actions.
DescriptionContent can be connected to the existing markdown.New(...) or any el.View, replacing the display of plain text description; the search content is still provided by Description. Rich text views should be created when building settings to preserve parsing and interaction state. Content replaces the entire line body, and fully customized lines can also be searched by keywords. Vertical forces top-bottom arrangement, Disabled disables interaction within the entire row, including custom content. Standard control column width is 240dp; row labels are supplied for controls without names. RowSpacing adjusts the upper and lower margins of the row, 0 restores the theme default; the control size is configured by the incoming control.
Display the localization reset button after the page declares Resettable: true. Clicking will call Reset for all non-disabled rows on the page, including searching for hidden rows; rows without a callback are skipped. ResetPage(title) provides program entry. Pages that are not reset will not be executed. Default values, application state and persistence are maintained by callbacks and controls are not modified through reflection; for example, when restoring a theme, switches and theme.Apply need to be updated at the same time.
Groups, rows, keywords, and Variant values are copied when adding pages; views and callbacks are still shared by the app. The identity of each row does not change with the position of the search results, and the control state is retained after page cutting and searching.
Usually the window is filled directly with el.Root(settings). Run go run ./examples/components -section settings to see multi-group, keyword, Markdown, and reset examples; add -theme dark to check dark colors. The automatic test covers the original 1×/2× narrow layout, keyboard and status retention, as well as group filtering, page footer, data copy, full page reset, custom rows and disabling; this batch does not undergo real device visual acceptance.
Size and group navigation
Size(SettingsSizeXSmall/Small/Medium/Large) uniformly adjusts row label/caption font size, padding, horizontal spacing, and control column width. The default Medium maintains the original layout. A non-zero value for RowSpacing overrides the size's default inline margins; custom Content and the control's own size are still configured by the application.
GroupNavigation(true) Add the group with title and hit search to the navigation; the narrow window displays the group button of the current page. ShowGroup(page, groupTitle) switches pages and locates groups, and can be used independently of the navigation switch. If the group is missing, has the same name, or is searched and filtered, false will be returned and the query will not be cleared. The target position is calculated by the layout, and off-screen grouping is supported. Value() always returns the page title, SetValue cancels pending group targeting.
Automatic testing covers double-ratio wide and narrow windows, off-screen positioning, group clicks, search filtering, duplicate name rejection and size switching to retain control values; the component library displays Small and group navigation by default. Native vision is not accepted.
SearchInSidebar(true) places search above the desktop navigation. Compact layouts keep search above the content.
PageHeading(false) hides the page heading when the groups already supply headings. Sidebar-search layouts align unfilled group bodies with their headings and keep navigation expanded.
SettingPage.Category groups navigation pages under sidebar headings; empty categories preserve the ungrouped layout.
Use AvailableWidth(dp) when Settings is inside a bounded panel: responsive
layout uses this width instead of the window viewport (zero restores the
viewport). With sidebar search enabled, widths below 800dp switch to a single
horizontally scrollable tab row. Below 600dp, controls stack below their labels.
Resizing preserves the selected page, query and application-owned field values.
With SearchInSidebar(true).PageHeading(false), the top strip stays blank. The first visible group heading is fixed below it, outside the scrolling content; the page name is not repeated.
In the horizontal layout, sidebar search moves beside Settings in the compact header, using a 32dp field. Top spacing shrinks on short and narrow windows.