settings: Added a way to add additional search keywords

crates/story/src/stories/settings_story.rs

@@ -314,6 +314,18 @@ impl SettingsStory {
                             .default_value(false),
                         )
                         .description("Lock the other settings."),
+                        SettingItem::new(
+                            "Foo",
+                            SettingField::switch(
+                                |cx: &App| AppSettings::global(cx).disabled,
+                                |checked: bool, cx: &mut App| {
+                                    AppSettings::global_mut(cx).disabled = checked
+                                },
+                            )
+                            .default_value(false),
+                        )
+                        .description("Find me by searching for my sibling")
+                        .keywords(["Bar"]),
                         SettingItem::render(|options, _, _| {
                             h_flex()
                                 .w_full()

crates/ui/src/setting/item.rs

@@ -22,13 +22,15 @@ pub enum SettingItem {
     Item {
         title: SharedString,
         description: Option<Text>,
+        keywords: Vec<SharedString>,
         layout: Axis,
         disabled: bool,
         field: Rc<dyn AnySettingField>,
     },
     /// A full custom element to render.
     Element {
         disabled: bool,
+        keywords: Vec<SharedString>,
         render: Rc<dyn Fn(&RenderOptions, &mut Window, &mut App) -> AnyElement + 'static>,
     },
 }
@@ -44,6 +46,7 @@ impl SettingItem {
             description: None,
             layout: Axis::Horizontal,
             disabled: false,
+            keywords: Vec::new(),
             field: Rc::new(field),
         }
     }
@@ -56,12 +59,31 @@ impl SettingItem {
     {
         SettingItem::Element {
             disabled: false,
+            keywords: Vec::new(),
             render: Rc::new(move |options, window, cx| {
                 render(options, window, cx).into_any_element()
             }),
         }
     }
 
+    /// Set additional keywords used only for search matching (not rendered).
+    ///
+    /// For example, an item titled "Enable Two-factor auth" can be made
+    /// searchable via "MFA". This is also useful for custom elements that
+    /// have no title/description but should still show up in search results.
+    pub fn keywords<I, S>(mut self, keywords: I) -> Self
+    where
+        I: IntoIterator<Item = S>,
+        S: Into<SharedString>,
+    {
+        let keywords: Vec<SharedString> = keywords.into_iter().map(Into::into).collect();
+        match &mut self {
+            SettingItem::Item { keywords: k, .. } => *k = keywords,
+            SettingItem::Element { keywords: k, .. } => *k = keywords,
+        }
+        self
+    }
+
     /// Set whether the setting item is disabled, default is false.
     ///
     /// A disabled item is rendered with reduced opacity. For
@@ -106,17 +128,23 @@ impl SettingItem {
     pub(crate) fn is_match(&self, query: &str, cx: &App) -> bool {
         match self {
             SettingItem::Item {
-                title, description, ..
+                title,
+                description,
+                keywords,
+                ..
             } => {
-                title.to_lowercase().contains(&query.to_lowercase())
-                    || description.as_ref().map_or(false, |d| {
-                        d.get_text(cx)
-                            .to_lowercase()
-                            .contains(&query.to_lowercase())
-                    })
+                let q = &query.to_lowercase();
+                title.to_lowercase().contains(q)
+                    || description
+                        .as_ref()
+                        .map_or(false, |d| d.get_text(cx).to_lowercase().contains(q))
+                    || keywords.iter().any(|s| s.to_lowercase().contains(q))
             }
             // We need to show all custom elements when not searching.
-            SettingItem::Element { .. } => query.is_empty(),
+            SettingItem::Element { keywords, .. } => {
+                let q = &query.to_lowercase();
+                query.is_empty() || keywords.iter().any(|s| s.to_lowercase().contains(q))
+            }
         }
     }
 
@@ -191,6 +219,7 @@ impl SettingItem {
                     layout,
                     disabled,
                     field,
+                    ..
                 } => div()
                     .w_full()
                     .overflow_hidden()
@@ -235,7 +264,9 @@ impl SettingItem {
                         cx,
                     )))
                     .into_any_element(),
-                SettingItem::Element { disabled, render } => div()
+                SettingItem::Element {
+                    disabled, render, ..
+                } => div()
                     .w_full()
                     .when(disabled, |this| this.opacity(0.5))
                     .child((render)(

docs/docs/components/settings.md

@@ -8,7 +8,7 @@ description: A settings UI with grouped setting items and pages.
 > Since: v0.5.0
 
 The Settings component provides a UI for managing application settings. It includes grouped setting items and pages.
-We can search by title and description to filter the settings to display only relevant settings (Like this macOS, iOS Settings).
+We can search by title, description, and custom keywords to filter the settings to display only relevant settings (Like this macOS, iOS Settings).
 
 ## Import
 
@@ -260,6 +260,30 @@ SettingItem::render(|options, _, _| {
 .disabled(true)
 ```
 
+### Search Keywords
+
+Use `keywords` to attach additional search terms to an item. They are only used
+for search matching and are never rendered. For example, an item titled "Enable
+Two-factor auth" can be made searchable via "MFA":
+
+```rust
+SettingItem::new(
+    "Enable Two-factor auth",
+    SettingField::switch(...)
+)
+.keywords(["MFA", "2FA"])
+```
+
+This is also useful for [SettingItem::render] custom items that have no title or
+description but should still appear in search results:
+
+```rust
+SettingItem::render(|options, _, _| {
+    h_flex().child("Custom content").into_any_element()
+})
+.keywords(["Advanced", "Network"])
+```
+
 ## Setting Fields
 
 The [SettingField] enum provides different field types for various input needs.

docs/zh-CN/docs/components/settings.md

@@ -7,7 +7,7 @@ description: 用于构建设置页、设置分组和设置项的界面组件。
 
 > Since: v0.5.0
 
-Settings 组件用于构建应用设置界面，支持页面分组、搜索过滤以及多种字段类型，适合实现类似 macOS 或 iOS 设置页的结构。
+Settings 组件用于构建应用设置界面，支持页面分组、按标题/描述/自定义关键词搜索过滤以及多种字段类型，适合实现类似 macOS 或 iOS 设置页的结构。
 
 ## 导入
 
@@ -253,6 +253,30 @@ SettingItem::render(|options, _, _| {
 .disabled(true)
 ```
 
+### 搜索关键词
+
+通过 `keywords` 可以为设置项附加额外的搜索关键词。这些关键词仅用于搜索匹配，
+不会被渲染出来。例如，标题为 "Enable Two-factor auth" 的设置项可以通过 "MFA"
+搜索到：
+
+```rust
+SettingItem::new(
+    "Enable Two-factor auth",
+    SettingField::switch(...)
+)
+.keywords(["MFA", "2FA"])
+```
+
+这对于没有标题和描述、但仍希望能被搜索到的 [SettingItem::render] 自定义项同样
+有用：
+
+```rust
+SettingItem::render(|options, _, _| {
+    h_flex().child("Custom content").into_any_element()
+})
+.keywords(["Advanced", "Network"])
+```
+
 ## Setting Fields
 
 [SettingField] 枚举提供了多种常见字段类型。