@nocobase/client-v2 2.2.0-beta.9 → 3.0.0-alpha.1

package/src/settings-center/AdminSettingsLayout.tsx

@@ -7,29 +7,25 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { ApiOutlined } from '@ant-design/icons';
 import { PageHeader } from '@ant-design/pro-layout';
 import { css } from '@emotion/css';
 import { FlowModelRenderer, useFlowEngine } from '@nocobase/flow-engine';
-import { Layout, Menu, Result, theme } from 'antd';
+import { Layout, Menu, Result, Tabs, theme } from 'antd';
 import React, { useEffect, useMemo, useRef } from 'react';
 import { useTranslation } from 'react-i18next';
-import { Navigate, Outlet, useLocation, useNavigate, useParams } from 'react-router-dom';
-import { useACLRoleContext } from '../acl';
-import { ADMIN_SETTINGS_PATH, type PluginSettingsPageType } from '../PluginSettingsManager';
+import { Navigate, Outlet, useLocation, useNavigate } from 'react-router-dom';
+import type { PluginSettingsPageType } from '../PluginSettingsManager';
 import { useApp } from '../hooks/useApp';
 import { AdminSettingsLayoutModel } from './AdminSettingsLayoutModel';
+import { useSettingsGroups } from './useSettingsGroups';
 import {
   ADMIN_SETTINGS_LAYOUT_MODEL_UID,
   createSettingsPathMap,
-  filterRenderableSettings,
-  filterVisibleSettings,
+  findSettingsByName,
   getDefaultSettingsPath,
-  getMenuItems,
+  getSidebarMenuItems,
+  getSidebarSelectedKey,
   matchSettingsRoute,
-  PLUGIN_MANAGER_SETTING_NAME,
-  replaceRouteParams,
-  sortTopLevelSettings,
 } from './utils';
 
 function SettingsEmpty(props: { type: 'home' | 'route' }) {
@@ -60,57 +56,27 @@ function SettingsEmpty(props: { type: 'home' | 'route' }) {
 /**
  * `client-v2` 的 settings 页面壳实现。
  *
- * 该组件负责左侧菜单、顶部 tabs、默认落点和两类空态，
- * 页面内容本身继续由各个 settings route 的 `<Outlet />` 渲染。
+ * 一级分组铺在顶栏（见 `SettingsGroupNav`），这里负责当前分组下的二三级嵌套菜单、
+ * 默认落点和两类空态，页面内容本身继续由各个 settings route 的 `<Outlet />` 渲染。
  */
 export const InternalAdminSettingsLayout = () => {
   const app = useApp();
   const navigate = useNavigate();
   const location = useLocation();
-  const params = useParams();
   const { token } = theme.useToken();
-  const { t } = useTranslation();
-  const { snippets = [] } = useACLRoleContext();
+  const {
+    activeGroupSettings,
+    allSettings,
+    currentSetting,
+    currentTopLevelSetting,
+    visibleSettings: allVisibleSettings,
+  } = useSettingsGroups();
 
-  const allSettings = useMemo(
-    () => filterRenderableSettings(app.pluginSettingsManager.getList(false) as PluginSettingsPageType[]),
-    [app.pluginSettingsManager],
-  );
-  const visibleSettings = useMemo(
-    () =>
-      filterVisibleSettings(
-        filterRenderableSettings(app.pluginSettingsManager.getList(true) as PluginSettingsPageType[]),
-      ),
-    [app.pluginSettingsManager],
-  );
-  const pluginManagerSetting = useMemo(
-    () => visibleSettings.find((item) => item.name === PLUGIN_MANAGER_SETTING_NAME) || null,
-    [visibleSettings],
-  );
-  const normalSettings = useMemo(
-    () => sortTopLevelSettings(visibleSettings.filter((item) => item.name !== PLUGIN_MANAGER_SETTING_NAME)),
-    [visibleSettings],
-  );
-  const allVisibleSettings = useMemo(
-    () => (pluginManagerSetting ? [pluginManagerSetting, ...normalSettings] : normalSettings),
-    [normalSettings, pluginManagerSetting],
-  );
-  const registeredSettingsMapByPath = useMemo(() => createSettingsPathMap(allSettings), [allSettings]);
   const visibleSettingsMapByPath = useMemo(() => createSettingsPathMap(allVisibleSettings), [allVisibleSettings]);
-  const currentSetting = useMemo(
-    () => matchSettingsRoute(registeredSettingsMapByPath, location.pathname),
-    [location.pathname, registeredSettingsMapByPath],
-  );
   const currentVisibleSetting = useMemo(
     () => matchSettingsRoute(visibleSettingsMapByPath, location.pathname),
     [location.pathname, visibleSettingsMapByPath],
   );
-  const currentTopLevelSetting = useMemo(() => {
-    if (!currentSetting) {
-      return null;
-    }
-    return allSettings.find((item) => item.name === currentSetting.topLevelName) || currentSetting;
-  }, [allSettings, currentSetting]);
   const currentVisibleTopLevelSetting = useMemo(() => {
     if (!currentSetting) {
       return null;
@@ -118,10 +84,42 @@ export const InternalAdminSettingsLayout = () => {
     return allVisibleSettings.find((item) => item.name === currentSetting.topLevelName) || null;
   }, [allVisibleSettings, currentSetting]);
   const defaultSettingsPath = useMemo(() => getDefaultSettingsPath(allVisibleSettings), [allVisibleSettings]);
-  const currentVisibleTabs = useMemo(() => {
-    return (currentVisibleTopLevelSetting?.children || []).filter((item) => !item.hidden) as PluginSettingsPageType[];
-  }, [currentVisibleTopLevelSetting?.children]);
-  const shouldShowTabs = currentVisibleTabs.length > 1 && currentVisibleTopLevelSetting?.showTabs !== false;
+  const settingsRootPath = app.pluginSettingsManager.getRoutePath('');
+  const settingsRootPathWithoutTrailingSlash = settingsRootPath.replace(/\/$/, '');
+
+  const sidebarMenus = useMemo(() => getSidebarMenuItems(activeGroupSettings), [activeGroupSettings]);
+  // 分组里只有一个顶级配置项时不铺左栏：那样整条侧栏只是把顶栏那一项重复一遍。
+  // 它自己的下级（用户和权限的 用户 / 角色和权限 / 同步，AI 员工的几个页面）改用页头下的 Tab。
+  const shouldShowSidebar = activeGroupSettings.length > 1;
+  // 子页面一律走页头下的 Tab：左栏只表达「哪个模块」，模块内部的分页交给 Tab，
+  // 和 v1 设置中心保持一致。
+  const pageTabs = useMemo(() => {
+    const children = (currentVisibleTopLevelSetting?.children || []).filter(
+      (item) => !item.hidden && !item.link && item.path,
+    );
+    return children.length > 1 ? children.map((item) => ({ key: item.path, label: item.label ?? item.title })) : [];
+  }, [currentVisibleTopLevelSetting]);
+  const activeTabKey = useMemo(() => {
+    if (!pageTabs.length) {
+      return undefined;
+    }
+    const matched = pageTabs.find(
+      (tab) => location.pathname === tab.key || location.pathname.startsWith(`${tab.key}/`),
+    );
+    return matched?.key ?? pageTabs[0]?.key;
+  }, [location.pathname, pageTabs]);
+  // 命中的可能是被折叠掉的子项，要换算成左栏里真实存在的那一级，否则整个左栏都不高亮。
+  const selectedMenuKey = useMemo(
+    () =>
+      getSidebarSelectedKey(activeGroupSettings, currentVisibleSetting?.name) ||
+      getSidebarSelectedKey(activeGroupSettings, currentVisibleTopLevelSetting?.name),
+    [activeGroupSettings, currentVisibleSetting?.name, currentVisibleTopLevelSetting?.name],
+  );
+  // 页头只需要补一句「当前在哪个子页」。
+  const pageSubTitle =
+    currentVisibleSetting && currentVisibleSetting.title !== currentTopLevelSetting?.title
+      ? currentVisibleSetting.title
+      : undefined;
 
   useEffect(() => {
     const nextTitle =
@@ -134,33 +132,10 @@ export const InternalAdminSettingsLayout = () => {
     }
   }, [currentTopLevelSetting]);
 
-  const sidebarMenus = useMemo(() => {
-    const items: any[] = [];
-
-    if (pluginManagerSetting && snippets.includes('pm')) {
-      items.push({
-        key: pluginManagerSetting.name,
-        icon: pluginManagerSetting.icon || <ApiOutlined />,
-        label: pluginManagerSetting.label || t('Plugin manager'),
-      });
-    }
-
-    if (items.length && normalSettings.length) {
-      items.push({ type: 'divider' });
-    }
-
-    const normalMenuItems =
-      getMenuItems(normalSettings.map((item) => ({ ...item, children: undefined }) as PluginSettingsPageType)) || [];
-
-    items.push(...normalMenuItems);
-
-    return items;
-  }, [normalSettings, pluginManagerSetting, snippets, t]);
-
   const shouldRedirectToDefault =
-    location.pathname === ADMIN_SETTINGS_PATH ||
-    location.pathname === ADMIN_SETTINGS_PATH.replace(/\/$/, '') ||
-    location.pathname === `${ADMIN_SETTINGS_PATH}index`;
+    location.pathname === settingsRootPath ||
+    location.pathname === settingsRootPathWithoutTrailingSlash ||
+    location.pathname === `${settingsRootPath}index`;
 
   if (shouldRedirectToDefault && defaultSettingsPath) {
     return <Navigate replace to={defaultSettingsPath} />;
@@ -204,41 +179,43 @@ export const InternalAdminSettingsLayout = () => {
         overflow: 'hidden',
       }}
     >
-      <Layout.Sider
-        width={200}
-        style={{
-          background: token.colorBgContainer,
-          borderInlineEnd: `${token.lineWidth}px solid ${token.colorBorderSecondary}`,
-          minHeight: 0,
-          overflowY: 'auto',
-          overflowX: 'hidden',
-        }}
-      >
-        <Menu
-          selectedKeys={currentVisibleTopLevelSetting?.name ? [currentVisibleTopLevelSetting.name] : []}
-          style={{ height: '100%', borderInlineEnd: 'none' }}
-          onClick={({ key }) => {
-            const topLevelSetting = allVisibleSettings.find((item) => item.name === key);
-            if (!topLevelSetting) {
-              return;
-            }
-
-            if (topLevelSetting.link) {
-              window.open(topLevelSetting.link, '_blank', 'noopener,noreferrer');
-              return;
-            }
-
-            const firstPath = topLevelSetting.children?.length
-              ? getDefaultSettingsPath(topLevelSetting.children)
-              : topLevelSetting.path;
-
-            if (firstPath) {
-              navigate(firstPath);
-            }
+      {shouldShowSidebar ? (
+        <Layout.Sider
+          width={200}
+          style={{
+            background: token.colorBgContainer,
+            borderInlineEnd: `${token.lineWidth}px solid ${token.colorBorderSecondary}`,
+            minHeight: 0,
+            overflowY: 'auto',
+            overflowX: 'hidden',
           }}
-          items={sidebarMenus}
-        />
-      </Layout.Sider>
+        >
+          <Menu
+            mode="inline"
+            inlineIndent={16}
+            selectedKeys={selectedMenuKey ? [selectedMenuKey] : []}
+            style={{ height: '100%', borderInlineEnd: 'none' }}
+            onClick={({ key }) => {
+              const setting = findSettingsByName(activeGroupSettings, String(key));
+              if (!setting) {
+                return;
+              }
+
+              if (setting.link) {
+                window.open(setting.link, '_blank', 'noopener,noreferrer');
+                return;
+              }
+
+              const targetPath = setting.children?.length ? getDefaultSettingsPath(setting.children) : setting.path;
+
+              if (targetPath && targetPath !== location.pathname) {
+                navigate(targetPath);
+              }
+            }}
+            items={sidebarMenus}
+          />
+        </Layout.Sider>
+      ) : null}
       <Layout.Content
         style={{
           background: token.colorBgLayout,
@@ -250,41 +227,45 @@ export const InternalAdminSettingsLayout = () => {
           overflow: 'hidden',
         }}
       >
-        <PageHeader
-          ghost={false}
-          title={currentTopLevelSetting?.title}
-          style={{
-            background: token.colorBgContainer,
-            borderBlockEnd: `${token.lineWidth}px solid ${token.colorBorderSecondary}`,
-            paddingBottom: shouldShowTabs ? 0 : token.padding,
-          }}
-          footer={
-            shouldShowTabs ? (
-              <Menu
-                mode="horizontal"
-                selectedKeys={[currentVisibleSetting?.name || currentSetting?.name]}
-                items={getMenuItems(currentVisibleTabs)}
-                onClick={({ key }) => {
-                  const targetPath = replaceRouteParams(app.pluginSettingsManager.getRoutePath(String(key)), params);
-                  if (location.pathname !== targetPath) {
-                    navigate(targetPath);
-                  }
-                }}
-                style={{ marginLeft: -token.marginSM, borderBottom: 'none' }}
-              />
-            ) : null
-          }
-        />
+        {/*
+          页头放在滚动容器**内部**：钉在外面会让页面出现嵌套滚动（窗口一条、内容区一条），
+          插件页面自己再带滚动区时会套成两三层，而且长页面白白少掉一条页头的高度。
+        */}
         <div
           style={{
             flex: 1,
             minHeight: 0,
             boxSizing: 'border-box',
             overflow: 'auto',
-            padding: token.paddingLG,
           }}
         >
-          <Outlet />
+          <PageHeader
+            ghost={false}
+            title={currentTopLevelSetting?.title}
+            subTitle={pageTabs.length ? undefined : pageSubTitle}
+            footer={
+              pageTabs.length ? (
+                <Tabs
+                  activeKey={activeTabKey}
+                  items={pageTabs}
+                  tabBarStyle={{ marginBottom: 0 }}
+                  onChange={(key) => {
+                    if (key !== location.pathname) {
+                      navigate(key);
+                    }
+                  }}
+                />
+              ) : undefined
+            }
+            style={{
+              background: token.colorBgContainer,
+              borderBlockEnd: `${token.lineWidth}px solid ${token.colorBorderSecondary}`,
+              paddingBottom: pageTabs.length ? 0 : token.padding,
+            }}
+          />
+          <div style={{ padding: token.paddingLG }}>
+            <Outlet />
+          </div>
         </div>
       </Layout.Content>
     </Layout>

package/src/settings-center/SystemSettingsPage.tsx

@@ -7,29 +7,14 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { UploadOutlined } from '@ant-design/icons';
-import { Alert, Button, Form, Input, Select, Space, Upload, message, theme } from 'antd';
-import type { RcFile, UploadRequestOption } from 'rc-upload/lib/interface';
-import mime from 'mime';
-import match from 'mime-match';
+import { Alert, App, Button, Form, Input, Select, theme } from 'antd';
 import React, { useEffect, useMemo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
+import { AttachmentUpload } from '../components/AttachmentUpload';
 import languageCodes from '../locale/languageCodes';
 import { useApp } from '../hooks/useApp';
 import { useSystemSettings } from '../flow/system-settings';
 
-type UploadedAttachment = {
-  id?: number;
-  title?: string;
-  filename?: string;
-  url?: string;
-};
-
-type AttachmentStorageRules = {
-  size?: number;
-  mimetype?: string | string[];
-};
-
 /**
  * `System settings` 的最小 v2 表单页面。
  *
@@ -39,14 +24,11 @@ type AttachmentStorageRules = {
 export const SystemSettingsPage = () => {
   const app = useApp();
   const { token } = theme.useToken();
+  const { message } = App.useApp();
   const { t } = useTranslation();
   const { data, loading, error, mutate } = useSystemSettings();
   const [form] = Form.useForm();
   const [submitting, setSubmitting] = useState(false);
-  const [uploading, setUploading] = useState(false);
-  const [storageRules, setStorageRules] = useState<AttachmentStorageRules | null>(null);
-  const logo = Form.useWatch<UploadedAttachment>('logo', form);
-
   useEffect(() => {
     const settings = data?.data;
     if (!settings) {
@@ -60,45 +42,6 @@ export const SystemSettingsPage = () => {
     });
   }, [data?.data, form]);
 
-  useEffect(() => {
-    let mounted = true;
-
-    const loadStorageRules = async () => {
-      try {
-        const attachmentsCollection = app.dataSourceManager?.getCollection?.('main', 'attachments');
-        const storageName = attachmentsCollection?.getOption?.('storage');
-
-        if (!storageName) {
-          if (mounted) {
-            setStorageRules(null);
-          }
-          return;
-        }
-
-        const response = await app.apiClient.request({
-          url: `storages:getBasicInfo/${storageName}`,
-          skipNotify: true,
-        });
-
-        if (!mounted) {
-          return;
-        }
-
-        setStorageRules(response?.data?.data?.rules || null);
-      } catch (error) {
-        if (mounted) {
-          setStorageRules(null);
-        }
-      }
-    };
-
-    void loadStorageRules();
-
-    return () => {
-      mounted = false;
-    };
-  }, [app]);
-
   const languageOptions = useMemo(() => {
     const currentValues = form.getFieldValue('enabledLanguages') || data?.data?.enabledLanguages || [];
     const supported = Array.from(new Set([...Object.keys(languageCodes), ...currentValues]));
@@ -109,78 +52,6 @@ export const SystemSettingsPage = () => {
     }));
   }, [data?.data?.enabledLanguages, form]);
 
-  const accept = useMemo(() => {
-    const value = storageRules?.mimetype;
-    if (!value) {
-      return undefined;
-    }
-    return Array.isArray(value) ? value.join(',') : value;
-  }, [storageRules?.mimetype]);
-
-  const beforeUpload = async (file: RcFile) => {
-    const sizeLimit = storageRules?.size;
-
-    if (typeof sizeLimit === 'number' && sizeLimit > 0 && file.size > sizeLimit) {
-      message.error(t('File size exceeds the limit'));
-      return Upload.LIST_IGNORE;
-    }
-
-    const mimetypeRule = storageRules?.mimetype;
-    const normalizedRule = Array.isArray(mimetypeRule) ? mimetypeRule.join(',').trim() : `${mimetypeRule || ''}`.trim();
-
-    if (!normalizedRule || normalizedRule === '*') {
-      return file;
-    }
-
-    let targetFile = file;
-    if (!targetFile.type) {
-      const extname = targetFile.name?.match(/\.[^.]+$/)?.[0];
-      if (extname) {
-        targetFile = new File([targetFile], targetFile.name, {
-          type: mime.getType(extname) || 'application/octet-stream',
-          lastModified: targetFile.lastModified,
-        }) as RcFile;
-      }
-    }
-
-    const isAllowed = normalizedRule
-      .split(',')
-      .filter(Boolean)
-      .some((rule) => match(targetFile.type)(rule));
-
-    if (!isAllowed) {
-      message.error(t('File type is not allowed'));
-      return Upload.LIST_IGNORE;
-    }
-
-    return targetFile;
-  };
-
-  const handleLogoUpload = async (options: UploadRequestOption) => {
-    const { file, onError, onSuccess } = options;
-    setUploading(true);
-
-    try {
-      const formData = new FormData();
-      formData.append('file', file as RcFile);
-
-      const response = await app.apiClient.request({
-        url: 'attachments:create',
-        method: 'post',
-        data: formData,
-      });
-
-      const nextLogo = response?.data?.data;
-
-      form.setFieldValue('logo', nextLogo);
-      onSuccess?.(response?.data, file as RcFile);
-    } catch (error) {
-      onError?.(error);
-    } finally {
-      setUploading(false);
-    }
-  };
-
   const handleSubmit = async () => {
     const values = await form.validateFields();
     const payload = {
@@ -244,44 +115,7 @@ export const SystemSettingsPage = () => {
           <Input.TextArea autoSize={{ minRows: 2, maxRows: 4 }} />
         </Form.Item>
         <Form.Item name="logo" label={t('Logo')}>
-          <Space direction="vertical" size={token.marginSM}>
-            {logo?.url ? (
-              <img
-                alt="system-logo"
-                src={logo.url}
-                style={{
-                  width: 96,
-                  height: 96,
-                  objectFit: 'contain',
-                  borderRadius: token.borderRadius,
-                  border: `${token.lineWidth}px solid ${token.colorBorder}`,
-                  background: token.colorBgLayout,
-                  padding: token.paddingXS,
-                }}
-              />
-            ) : null}
-            <Space>
-              <Upload
-                showUploadList={false}
-                customRequest={handleLogoUpload}
-                beforeUpload={beforeUpload}
-                accept={accept}
-              >
-                <Button loading={uploading} icon={<UploadOutlined />}>
-                  {t('Upload')}
-                </Button>
-              </Upload>
-              {logo ? (
-                <Button
-                  onClick={() => {
-                    form.setFieldValue('logo', null);
-                  }}
-                >
-                  {t('Delete')}
-                </Button>
-              ) : null}
-            </Space>
-          </Space>
+          <AttachmentUpload preview={{ width: 96, height: 96, fit: 'contain' }} />
         </Form.Item>
         <Form.Item name="enabledLanguages" label={t('Enabled languages')} rules={[{ type: 'array', min: 1 }]}>
           <Select mode="multiple" options={languageOptions} />

package/src/settings-center/groups.ts

@@ -0,0 +1,108 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import type { PluginSettingsPageType } from '../PluginSettingsManager';
+
+/**
+ * Settings 顶层分组。
+ *
+ * 顶栏铺一级（分组），左侧栏铺该分组下的二级 / 三级菜单。
+ * 分组归属优先取配置项自身的 `group` 字段，其次落到内置映射表，最后兜底到 `system`，
+ * 因此第三方插件不改代码也能出现在设置中心里。
+ */
+export type SettingsGroupKey = 'applications' | 'plugins' | 'data' | 'access' | 'automation' | 'ai' | 'system';
+
+export type SettingsGroupDefinition = {
+  key: SettingsGroupKey;
+  /** 未翻译的分组标题，交由调用方过 i18n */
+  title: string;
+  /**
+   * 分组的门面配置项。
+   *
+   * 它会被排到该分组的第一位，并作为点击顶栏分组时的落点；
+   * 不存在（插件没装 / 无权限）时自然退回到分组内的第一项。
+   */
+  primary?: string;
+};
+
+/**
+ * 顶栏铺六个独立入口 + 一个「其他设置」兜底分组。
+ *
+ * 前六个各自只有一个配置项、且都是日常高频，直接当一级入口（标题取配置项自己的名字，
+ * 顺带继承插件的翻译）；其余零散配置全部收进其他设置，靠左栏和悬浮下拉展开。
+ *
+ * 兜底分组不叫「系统设置」：它下面本来就有一个同名的配置项（站点标题、logo 那个），
+ * 分组和子项重名会让人以为点进去是同一个东西。
+ */
+export const SETTINGS_GROUPS: SettingsGroupDefinition[] = [
+  { key: 'applications', title: 'Applications', primary: 'multi-portal' },
+  { key: 'plugins', title: 'Plugin manager', primary: 'plugin-manager' },
+  { key: 'data', title: 'Data sources', primary: 'data-source-manager' },
+  { key: 'access', title: 'Users & Permissions', primary: 'users-permissions' },
+  { key: 'automation', title: 'Workflow', primary: 'workflow' },
+  { key: 'ai', title: 'AI employees', primary: 'ai' },
+  { key: 'system', title: 'Other settings' },
+];
+
+export const DEFAULT_SETTINGS_GROUP: SettingsGroupKey = 'system';
+
+/**
+ * 内置配置项到分组的映射。
+ *
+ * key 为 `pluginSettingsManager.addMenuItem` 时传入的 `key`；
+ * 没列出来的一律落到其他设置，第三方插件不改代码也能出现。
+ */
+const BUILTIN_SETTINGS_GROUP_MAP: Record<string, SettingsGroupKey> = {
+  'multi-portal': 'applications',
+  'plugin-manager': 'plugins',
+  'data-source-manager': 'data',
+  'users-permissions': 'access',
+  workflow: 'automation',
+  ai: 'ai',
+};
+
+/**
+ * 解析某个顶级配置项所属的分组。
+ *
+ * @param {PluginSettingsPageType | null | undefined} setting 顶级配置项
+ * @returns {SettingsGroupKey} 分组 key
+ */
+export function getSettingsGroupKey(setting?: PluginSettingsPageType | null): SettingsGroupKey {
+  if (!setting) {
+    return DEFAULT_SETTINGS_GROUP;
+  }
+
+  const declared = (setting as PluginSettingsPageType & { group?: string }).group;
+  if (declared && SETTINGS_GROUPS.some((group) => group.key === declared)) {
+    return declared as SettingsGroupKey;
+  }
+
+  return BUILTIN_SETTINGS_GROUP_MAP[setting.name] || DEFAULT_SETTINGS_GROUP;
+}
+
+/**
+ * 按分组切分顶级配置项，并丢掉没有任何配置项的空分组。
+ *
+ * @param {PluginSettingsPageType[]} settings 已排序的顶级配置项
+ * @returns 非空分组
+ */
+export function groupTopLevelSettings(settings: readonly PluginSettingsPageType[] = []) {
+  return SETTINGS_GROUPS.map((group) => {
+    const members = settings.filter((setting) => getSettingsGroupKey(setting) === group.key);
+    const primaryIndex = group.primary ? members.findIndex((item) => item.name === group.primary) : -1;
+
+    return {
+      ...group,
+      settings:
+        primaryIndex > 0
+          ? [members[primaryIndex], ...members.slice(0, primaryIndex), ...members.slice(primaryIndex + 1)]
+          : members,
+    };
+  }).filter((group) => group.settings.length > 0);
+}