@nocobase/client-v2 2.3.0-alpha.1 → 3.0.0-alpha.2

package/src/settings-app/SettingsShell.tsx

@@ -0,0 +1,167 @@
+/**
+ * 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 { FlowModelRenderer } from '@nocobase/flow-engine';
+import { ConfigProvider, Layout, theme as antdTheme, type ThemeConfig } from 'antd';
+import React, { useMemo, type FC } from 'react';
+import { useLocation } from 'react-router-dom';
+import { HelpLite } from '../flow/admin-shell/admin-layout/HelpLite';
+import {
+  USER_CENTER_ACTION_ID,
+  type UserCenterTopbarActionModel,
+} from '../flow/models/topbar/UserCenterTopbarActionModel';
+import { useApp } from '../hooks/useApp';
+import { useCurrentUserAuthStatus } from '../nocobase-buildin-plugin/currentUserAuthStatus';
+import { SettingsBrand } from './SettingsBrand';
+import { SettingsGroupNav } from './SettingsGroupNav';
+import { SettingsSearch } from './SettingsSearch';
+import {
+  buildSettingsGlobalCss,
+  buildSettingsNeutralTheme,
+  getSettingsHeaderColors,
+  withSettingsHeaderTheme,
+} from './settingsTheme';
+import { useSettingsThemeConfig } from './useSettingsThemeConfig';
+
+const rootStyle: React.CSSProperties = {
+  height: '100vh',
+  minWidth: 0,
+  overflow: 'hidden',
+};
+
+const headerContentStyle: React.CSSProperties = {
+  alignItems: 'center',
+  display: 'flex',
+  gap: 24,
+  height: '100%',
+  justifyContent: 'space-between',
+};
+
+const actionsStyle: React.CSSProperties = {
+  alignItems: 'center',
+  display: 'flex',
+  flexShrink: 0,
+  gap: 8,
+  height: '100%',
+};
+
+const workspaceStyle: React.CSSProperties = {
+  display: 'flex',
+  flex: 1,
+  minWidth: 0,
+  minHeight: 0,
+  overflow: 'hidden',
+};
+
+const contentStyle: React.CSSProperties = {
+  flex: 1,
+  minWidth: 0,
+  minHeight: 0,
+  overflow: 'hidden',
+};
+
+const embedContainerStyle: React.CSSProperties = {
+  flexShrink: 0,
+  height: '100%',
+  position: 'relative',
+  width: 'fit-content',
+};
+
+export const SettingsShell: FC = ({ children }) => {
+  const app = useApp();
+  const location = useLocation();
+  const { token } = antdTheme.useToken();
+  // 设置中心的外观由主题编辑器里那条「简约」主题记录约束；读不到才用代码里的中性配色兜底。
+  const storedThemeConfig = useSettingsThemeConfig();
+  // 顶栏和补丁样式要按**设置中心自己这套主题**算色，不能直接用上面那个 `token`——
+  // 这个组件在自己的 ConfigProvider 外面，`token` 是业务端主题的。用它的话，业务端一切暗黑，
+  // 顶栏就跟着变黑，而内容区还是简约的白，一半黑一半白。
+  const settingsToken = useMemo(
+    () => (storedThemeConfig ? antdTheme.getDesignToken(storedThemeConfig) : token),
+    [storedThemeConfig, token],
+  );
+  const settingsShellTheme = useMemo<ThemeConfig>(
+    () =>
+      storedThemeConfig ? withSettingsHeaderTheme(storedThemeConfig, settingsToken) : buildSettingsNeutralTheme(token),
+    [settingsToken, storedThemeConfig, token],
+  );
+  const headerColors = useMemo(() => getSettingsHeaderColors(settingsToken), [settingsToken]);
+  const settingsGlobalCss = useMemo(() => buildSettingsGlobalCss(settingsToken), [settingsToken]);
+  const authStatus = useCurrentUserAuthStatus(app);
+  const isAuthenticationRoute = (app.router.matchRoutes(location.pathname) || []).some((match) => {
+    const routeId = match.route.id;
+    return routeId === 'auth' || routeId?.startsWith('auth.') || routeId === '2fa' || routeId?.startsWith('2fa.');
+  });
+
+  if (isAuthenticationRoute) {
+    // 登录 / 二次验证页也要套设置中心自己的主题，否则它跟的是业务端主题：
+    // 业务端切暗黑之后登录页是暗的，登进去又变成浅色，中间闪一下。
+    // 外面这层用 `display: contents`，只为了让作用在 `.nb-settings-shell` 上的补丁样式
+    // 也能命中登录页，不改变任何布局。
+    return (
+      <ConfigProvider theme={settingsShellTheme}>
+        <style>{settingsGlobalCss}</style>
+        <div className="nb-settings-shell" style={{ display: 'contents' }}>
+          {children}
+        </div>
+      </ConfigProvider>
+    );
+  }
+
+  const shouldShowHeader = authStatus === 'authenticated';
+  const hasUserCenterModel = Boolean(app.flowEngine.getModelClass('UserCenterTopbarActionModel'));
+  const userCenter = hasUserCenterModel
+    ? app.flowEngine.getModel<UserCenterTopbarActionModel>(`topbar-action-${USER_CENTER_ACTION_ID}`) ||
+      app.flowEngine.createModel<UserCenterTopbarActionModel>({
+        use: 'UserCenterTopbarActionModel',
+        uid: `topbar-action-${USER_CENTER_ACTION_ID}`,
+      })
+    : null;
+
+  return (
+    <ConfigProvider theme={settingsShellTheme}>
+      <style>{settingsGlobalCss}</style>
+      <Layout className="nb-settings-shell" style={rootStyle}>
+        <Layout.Header
+          style={
+            {
+              // 深色顶栏自带层次，只有浅色顶栏才需要一条分割线把它和内容区分开。
+              borderBottom: headerColors.dark
+                ? 'none'
+                : `${settingsToken.lineWidth}px solid ${settingsToken.colorBorderSecondary}`,
+              display: shouldShowHeader ? undefined : 'none',
+              height: 46,
+              lineHeight: '46px',
+              paddingInline: settingsToken.paddingLG,
+              // 顶栏子组件（动作条、pinned 插件列表）有一部分直接读 CSS 变量而不是 antd token，
+              // 而且兜底值是按深色顶栏写死的浅色，这里一并覆盖，免得白底上出现白图标。
+              '--nb-topbar-action-hover-bg': headerColors.bgHover,
+              '--colorTextHeaderMenu': headerColors.text,
+              '--nb-topbar-action-color': headerColors.text,
+            } as React.CSSProperties
+          }
+        >
+          <div style={headerContentStyle}>
+            <SettingsBrand />
+            <SettingsGroupNav />
+            <div style={actionsStyle}>
+              <SettingsSearch />
+              <HelpLite />
+              {userCenter ? <FlowModelRenderer model={userCenter} /> : null}
+            </div>
+          </div>
+        </Layout.Header>
+        <div style={workspaceStyle}>
+          <Layout.Content style={contentStyle}>{children}</Layout.Content>
+          <div id="nocobase-embed-container" style={embedContainerStyle} />
+        </div>
+      </Layout>
+    </ConfigProvider>
+  );
+};

package/src/settings-app/isSettingsApp.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 `SettingsApplication`
+ * 本身——那会让插件反向依赖壳的实现。
+ *
+ * @param {any} app 应用实例
+ * @returns {boolean} 是设置中心返回 true
+ */
+export function isSettingsApp(app?: any): boolean {
+  return Boolean(app?.isSettingsApp);
+}

package/src/settings-app/runtimePaths.ts

@@ -0,0 +1,104 @@
+/**
+ * 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 { stripModernClientPrefix } from '../authRedirect';
+import type { BaseApplication } from '../BaseApplication';
+import {
+  resolveSettingsAppScope,
+  resolveSettingsAppScopeWithinPublicPath,
+  resolveSettingsDocumentPath,
+} from './settingsDocumentPath';
+
+type SettingsRuntimeApp = Pick<BaseApplication<any>, 'name'> & {
+  getPublicPath?: () => string;
+  router?: {
+    basename?: string;
+    getBasename?: () => string | undefined;
+  };
+};
+
+const LEGACY_EMAIL_OAUTH_PATH = '/admin/settings/mail/oauth2';
+
+const ROUTE_MAPPINGS = [
+  { from: '/admin/ai/knowledge-base/detail', to: '/settings/ai/knowledge-base/detail' },
+  { from: '/admin/workflow/executions', to: '/settings/workflow/executions' },
+  { from: '/admin/workflow/workflows', to: '/settings/workflow/workflows' },
+  { from: '/admin/settings', to: '/settings' },
+  { from: '/settings', to: '/settings' },
+] as const;
+
+function normalizePathname(pathname?: string) {
+  const normalized = `/${String(pathname || '/').trim()}`.replace(/\/{2,}/g, '/');
+  return normalized === '/' ? normalized : normalized.replace(/\/+$/, '');
+}
+
+function splitPathSuffix(pathLike: string) {
+  const match = String(pathLike || '').match(/^([^?#]*)(.*)$/);
+  return {
+    pathname: normalizePathname(match?.[1]),
+    suffix: match?.[2] || '',
+  };
+}
+
+function getRuntimeAppScope(app: SettingsRuntimeApp, pathname: string) {
+  const basename = app.router?.getBasename?.() || app.router?.basename;
+  const publicPath = app.getPublicPath?.() || '/';
+  return (
+    resolveSettingsAppScopeWithinPublicPath(publicPath, pathname) ||
+    resolveSettingsAppScopeWithinPublicPath(publicPath, basename) ||
+    (app.name && app.name !== 'main' ? resolveSettingsAppScope(`/apps/${app.name}`) : '')
+  );
+}
+
+function getRootPublicPath(app: SettingsRuntimeApp, appScope: string) {
+  const basename = app.router?.getBasename?.() || app.router?.basename || '';
+  const publicPath = app.getPublicPath?.();
+  if (publicPath) {
+    return normalizePathname(stripModernClientPrefix(publicPath));
+  }
+
+  const normalizedBasename = normalizePathname(basename);
+  const basenameWithoutAppScope =
+    appScope && normalizedBasename.endsWith(appScope)
+      ? normalizedBasename.slice(0, -appScope.length)
+      : normalizedBasename;
+  return normalizePathname(stripModernClientPrefix(basenameWithoutAppScope));
+}
+
+function findMappedRoute(pathname: string) {
+  for (const mapping of ROUTE_MAPPINGS) {
+    const index = pathname.indexOf(mapping.from);
+    if (index < 0) {
+      continue;
+    }
+    const tail = pathname.slice(index + mapping.from.length);
+    if (tail && !tail.startsWith('/')) {
+      continue;
+    }
+    return `${mapping.to}${tail}`;
+  }
+  return '/settings';
+}
+
+export function resolveStandaloneSettingsPath(app: SettingsRuntimeApp, pathLike: string, contextPathname?: string) {
+  const { pathname, suffix } = splitPathSuffix(pathLike);
+  const appScope = getRuntimeAppScope(app, contextPathname || pathname);
+  const rootPublicPath = getRootPublicPath(app, appScope).replace(/\/+$/, '');
+  const documentBasePath = `${rootPublicPath}${appScope}`;
+  const oauthIndex = pathname.indexOf(LEGACY_EMAIL_OAUTH_PATH);
+
+  if (oauthIndex >= 0) {
+    const oauthTail = pathname.slice(oauthIndex + LEGACY_EMAIL_OAUTH_PATH.length);
+    if (!oauthTail || oauthTail.startsWith('/')) {
+      return `${documentBasePath}${LEGACY_EMAIL_OAUTH_PATH}${oauthTail}${suffix}`;
+    }
+  }
+
+  return `${resolveSettingsDocumentPath(rootPublicPath, appScope, findMappedRoute(pathname))}${suffix}`;
+}

package/src/settings-app/settingsDocumentPath.ts

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+
+export type SettingsAppScope = '' | `/${'apps' | '_app'}/${string}`;
+
+function ensureLeadingSlash(value: string) {
+  return value.startsWith('/') ? value : `/${value}`;
+}
+
+export function normalizeSettingsRootPublicPath(value?: string) {
+  const normalized = ensureLeadingSlash(String(value || '/').trim() || '/').replace(/\/{2,}/g, '/');
+  return normalized.endsWith('/') ? normalized : `${normalized}/`;
+}
+
+export function resolveSettingsAppScope(pathname?: string): SettingsAppScope {
+  const match = /\/(apps|_app)\/([^/?#]+)(?=\/|[?#]|$)/.exec(ensureLeadingSlash(String(pathname || '/')));
+  return match ? (`/${match[1]}/${match[2]}` as SettingsAppScope) : '';
+}
+
+export function resolveSettingsAppScopeWithinPublicPath(publicPath: string, pathname?: string): SettingsAppScope {
+  const root = normalizeSettingsRootPublicPath(publicPath).replace(/\/+$/, '');
+  const path = ensureLeadingSlash(String(pathname || '/').split(/[?#]/)[0]).replace(/\/{2,}/g, '/');
+  const relativePath = root && (path === root || path.startsWith(`${root}/`)) ? path.slice(root.length) || '/' : path;
+  const match = /^\/(?:settings\/)?(apps|_app)\/([^/]+)(?=\/|$)/.exec(relativePath);
+  return match ? (`/${match[1]}/${match[2]}` as SettingsAppScope) : '';
+}
+
+function normalizeSettingsRoutePath(value: string) {
+  const normalized = ensureLeadingSlash(String(value || '/settings')).replace(/\/{2,}/g, '/');
+  return normalized === '/' ? '/settings' : normalized.replace(/\/+$/, '');
+}
+
+function removeSettingsRouteRoot(settingsRoute: string) {
+  if (settingsRoute === '/settings') {
+    return '';
+  }
+  return settingsRoute.replace(/^\/settings(?=\/|$)/, '');
+}
+
+export function resolveSettingsDocumentPath(
+  rootPublicPath: string,
+  appScope: SettingsAppScope,
+  settingsRoutePath: string,
+) {
+  const root = normalizeSettingsRootPublicPath(rootPublicPath);
+  const rootPrefix = root === '/' ? '' : root.replace(/\/+$/, '');
+  const settingsRoute = normalizeSettingsRoutePath(settingsRoutePath);
+  if (!appScope) {
+    return `${rootPrefix}${settingsRoute}`;
+  }
+  return `${rootPrefix}/settings${appScope}${removeSettingsRouteRoot(settingsRoute)}`;
+}
+
+export function resolveSettingsDocumentBasename(rootPublicPath: string, appScope: SettingsAppScope) {
+  const root = normalizeSettingsRootPublicPath(rootPublicPath);
+  if (!appScope) {
+    return root;
+  }
+  return normalizeSettingsRootPublicPath(`${root}settings${appScope}`);
+}

package/src/settings-app/settingsTheme.ts

@@ -0,0 +1,301 @@
+/**
+ * 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 { GlobalToken, ThemeConfig } from 'antd';
+
+/**
+ * 粗略判断一个颜色是不是深色背景。
+ *
+ * 只支持 `#rgb` / `#rrggbb`，解析不出来时按浅色处理。
+ *
+ * @param {string | undefined} color 背景色
+ * @returns {boolean} 是否为深色
+ */
+export function isDarkColor(color?: string) {
+  if (typeof color !== 'string') {
+    return false;
+  }
+
+  const hex = color.trim().replace('#', '');
+  const normalized =
+    hex.length === 3
+      ? hex
+          .split('')
+          .map((char) => char + char)
+          .join('')
+      : hex;
+
+  if (normalized.length !== 6 || /[^0-9a-f]/i.test(normalized)) {
+    return false;
+  }
+
+  const r = parseInt(normalized.slice(0, 2), 16);
+  const g = parseInt(normalized.slice(2, 4), 16);
+  const b = parseInt(normalized.slice(4, 6), 16);
+
+  // Rec. 601 亮度
+  return (r * 299 + g * 587 + b * 114) / 1000 < 128;
+}
+
+/**
+ * 取顶栏配色。
+ *
+ * 设置中心的顶栏刻意**不跟随**主题编辑器里的 `colorBgHeader`：那套深色顶栏是给业务端的，
+ * 设置中心用容器底色（浅色主题下就是白色）+ 一条细分割线，和业务端在视觉上分开。
+ * 文字和图标一律走正文色，深色主题下由 `colorBgContainer` 自动翻成浅色。
+ *
+ * @param {GlobalToken} token 外层主题 token
+ * @returns 顶栏底色、文字色、hover / active 色，以及顶栏是否为深色
+ */
+export function getSettingsHeaderColors(token: GlobalToken) {
+  const bg = token.colorBgContainer;
+
+  return {
+    bg,
+    dark: isDarkColor(bg),
+    text: token.colorText,
+    textHover: token.colorText,
+    textActive: token.colorText,
+    bgHover: token.colorFillQuaternary,
+    bgActive: token.colorFillQuaternary,
+  };
+}
+
+/**
+ * 顶栏一级导航专用主题。
+ *
+ * 顶栏自己是透明底（底色由 Layout.Header 给），下拉浮层跟着顶栏用容器色；
+ * 选中 / hover 的颜色一律交给外层主题，也就是默认蓝。
+ *
+ * @param {GlobalToken} token 外层主题 token
+ * @returns {ThemeConfig} 顶栏菜单主题
+ */
+export function buildSettingsHeaderMenuTheme(token: GlobalToken): ThemeConfig {
+  const colors = getSettingsHeaderColors(token);
+
+  return {
+    components: {
+      Menu: {
+        itemBg: 'transparent',
+        popupBg: colors.bg,
+        subMenuItemBg: 'transparent',
+        // 顶栏表达的是「在哪个模块」，属于背景信息：选中态用一条下划线 + 加粗就够，
+        // 实心色块太重，会跟左栏那个「当前页面」的强指示打架。
+        // 未选中项也用正文色——次要灰在白底顶栏上偏淡，看不清；选中态靠下划线 + 加粗区分。
+        itemColor: token.colorText,
+        itemHoverColor: token.colorText,
+        horizontalItemSelectedColor: token.colorText,
+        horizontalItemSelectedBg: 'transparent',
+        horizontalItemHoverColor: token.colorText,
+        horizontalItemBorderRadius: 0,
+      },
+    },
+  };
+}
+
+/**
+ * 构造设置中心的外壳主题。
+ *
+ * 只做**顶栏**这一层：白（或深色主题下的容器色）底 + 细分割线，文字与图标走正文色，
+ * 和业务端那条深色顶栏区分开。
+ *
+ * 选中态一律用浅灰底 + 正文色，只有开关这类「开/关」控件才用纯黑填充。
+ * 各插件页面里 `controlItemBgActive` 常被当成纯背景用、文字色不跟着走，所以那个 token
+ * 也保持浅色，不然列表行会变成深底深字。
+ *
+ * @param {GlobalToken} token 外层主题 token
+ * @returns {ThemeConfig} 设置中心外壳主题
+ */
+export function buildSettingsNeutralTheme(token: GlobalToken): ThemeConfig {
+  const headerColors = getSettingsHeaderColors(token);
+  const dark = headerColors.dark;
+  /** 选中态底色：浅色主题下是黑，深色主题下翻成白 */
+  const activeBg = dark ? '#ffffff' : '#000000';
+  const activeText = dark ? '#000000' : '#ffffff';
+
+  return {
+    token: {
+      // 顶栏图标（帮助、用户中心、pinned 插件）默认按深色顶栏取浅色；
+      // 这里的顶栏是灰白的，必须翻成正文色，否则整排图标白底白字看不见。
+      colorTextHeaderMenu: headerColors.text,
+      colorTextHeaderMenuHover: headerColors.textHover,
+      colorTextHeaderMenuActive: headerColors.textActive,
+      colorBgHeaderMenuHover: headerColors.bgHover,
+      colorBgHeaderMenuActive: headerColors.bgActive,
+      // 主色收成黑白。antd 会拿它派生一整套色板，而近黑色派生出来的「浅色背景」是 #5e5e5e
+      // 这种中灰，列表行、Select 选项选中后就成了深底深字，所以派生的那几个必须显式钉住。
+      colorPrimary: activeBg,
+      colorInfo: activeBg,
+      colorPrimaryHover: dark ? '#ffffff' : '#333333',
+      colorPrimaryActive: dark ? '#d4d4d4' : '#000000',
+      colorPrimaryBg: token.colorFillQuaternary,
+      colorPrimaryBgHover: token.colorFillTertiary,
+      colorPrimaryBorder: token.colorBorder,
+      colorPrimaryBorderHover: token.colorTextTertiary,
+      // 提示类（Alert / Tag 的 info 态）同理：主色一黑，派生的底色就成了脏灰配黑字。
+      colorInfoBg: token.colorFillQuaternary,
+      colorInfoBgHover: token.colorFillTertiary,
+      colorInfoBorder: token.colorBorderSecondary,
+      colorInfoBorderHover: token.colorBorder,
+      colorInfoText: token.colorText,
+      controlItemBgActive: token.colorFillQuaternary,
+      controlItemBgActiveHover: token.colorFillTertiary,
+      // 压在主色上的文字：浅色主题下主色是黑，文字白；深色主题反过来。
+      colorTextLightSolid: activeText,
+      // 链接：灰色 + 下划线（下划线在 settingsGlobalCss 里补，token 层没有这一项）
+      colorLink: token.colorTextSecondary,
+      colorLinkHover: token.colorText,
+      colorLinkActive: token.colorText,
+      // 自绘选中态（列表行、树节点）读这一对，见 CustomToken 里的说明。
+      // 这里用浅底：整行纯黑太重，行内的图标、标签都得跟着反色，得不偿失。
+      // 文字色留空表示「不覆盖」，各页面保持正文色即可。
+      colorBgItemActive: token.colorFillSecondary,
+      colorTextItemActive: '',
+    } as ThemeConfig['token'],
+    components: {
+      Layout: {
+        headerBg: headerColors.bg,
+        headerColor: headerColors.text,
+        bodyBg: token.colorBgLayout,
+      },
+      Menu: {
+        // 左栏选中态：浅底 + 加粗，不再画左侧竖线。
+        itemSelectedBg: token.colorFillSecondary,
+        itemSelectedColor: token.colorText,
+        // 子菜单容器保留一层很淡的底色标记「这是一组」，但要比选中项浅一档，
+        // 否则两层灰叠在一起就分不出哪个是选中的。
+        subMenuItemBg: token.colorFillQuaternary,
+        subMenuItemSelectedColor: token.colorText,
+        horizontalItemSelectedColor: token.colorText,
+        horizontalItemSelectedBg: 'transparent',
+        activeBarBorderWidth: 0,
+      },
+      Spin: {
+        // 加载态跟着中性配色走，别在一片黑白灰里闪一个蓝点。
+        colorPrimary: token.colorTextTertiary,
+      },
+      Select: {
+        // 下拉选中项用浅灰底 + 正文色，别在下拉里压一条纯黑。
+        optionSelectedBg: token.colorFillSecondary,
+        optionSelectedColor: token.colorText,
+      },
+      Switch: {
+        colorPrimary: activeBg,
+        colorPrimaryHover: activeBg,
+      },
+      Tabs: {
+        // 页签选中态跟着黑白走，不然一页里既有黑色选中项又有蓝色页签。
+        itemSelectedColor: token.colorText,
+        itemHoverColor: token.colorText,
+        itemActiveColor: token.colorText,
+        inkBarColor: token.colorText,
+      },
+    },
+  };
+}
+
+/**
+ * 给外部主题补上设置中心的顶栏配色。
+ *
+ * 顶栏那几个 token（`colorBgHeader`、`colorTextHeaderMenu` 系列、`Layout.headerBg`）
+ * 刻意不放进「简约」主题记录里：那条记录是通用的，业务端顶栏是深色的、logo 和图标都按
+ * 深底做的，一旦被改成白底就得连 logo 一起反色。设置中心的顶栏是白的，所以在这一层补。
+ *
+ * @param {ThemeConfig} theme 主题记录里读到的配置
+ * @param {GlobalToken} token 外层主题 token
+ * @returns {ThemeConfig} 补齐顶栏配色后的主题
+ */
+export function withSettingsHeaderTheme(theme: ThemeConfig, token: GlobalToken): ThemeConfig {
+  const colors = getSettingsHeaderColors(token);
+
+  return {
+    ...theme,
+    token: {
+      ...theme.token,
+      colorTextHeaderMenu: colors.text,
+      colorTextHeaderMenuHover: colors.textHover,
+      colorTextHeaderMenuActive: colors.textActive,
+      colorBgHeaderMenuHover: colors.bgHover,
+      colorBgHeaderMenuActive: colors.bgActive,
+    } as ThemeConfig['token'],
+    components: {
+      ...theme.components,
+      Layout: {
+        ...theme.components?.Layout,
+        headerBg: colors.bg,
+        headerColor: colors.text,
+        bodyBg: token.colorBgLayout,
+      },
+    },
+  };
+}
+
+/**
+ * 设置中心的全局补丁样式。
+ *
+ * 这几件事 antd 没给 token，只能落到 CSS：
+ * - 裸 `<a>` 的颜色。它吃的是**最外层** ConfigProvider 生成的全局 reset 样式，
+ *   我们这层嵌套 ConfigProvider 的 `colorLink` 够不着，只能在 CSS 里压一次。
+ * - 链接下划线（`colorLink` 只管颜色）
+ * - Switch 禁用态压得更淡，跟「未启用但可点」区分开
+ * - 顶栏选中项的下划线、左栏选中项的加粗
+ *
+ * @param {GlobalToken} token 外层主题 token
+ * @returns {string} 可直接塞进 `<style>` 的 CSS
+ */
+export function buildSettingsGlobalCss(token: GlobalToken): string {
+  return `
+/* 最外层 body 的底色来自业务端主题（暗黑下是 #141414）。内容区一般把它整块盖住，
+   但内容不满屏、或者滚动橡皮筋回弹时会漏出来，所以这里一并接管。
+   设置中心是独立入口的单页应用，这条全局规则不会影响业务端。 */
+body {
+  background: ${token.colorBgLayout};
+}
+.nb-settings-shell a:not(.ant-btn):not(.ant-menu-item):not(.ant-tabs-tab-btn):not([class*="ant-"]) {
+  color: ${token.colorTextSecondary};
+}
+.nb-settings-shell a:not(.ant-btn):not(.ant-menu-item):not(.ant-tabs-tab-btn):not([class*="ant-"]):hover {
+  color: ${token.colorText};
+}
+.nb-settings-shell a:not(.ant-btn):not(.ant-menu-item):not(.ant-tabs-tab-btn),
+.nb-settings-shell .ant-btn-link:not(:disabled) {
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+.nb-settings-shell .ant-layout-header .ant-menu-horizontal > .ant-menu-item::after,
+.nb-settings-shell .ant-layout-header .ant-menu-horizontal > .ant-menu-submenu::after {
+  border-bottom: none !important;
+}
+.nb-settings-shell .ant-layout-header .ant-menu-horizontal > .ant-menu-item-selected,
+.nb-settings-shell .ant-layout-header .ant-menu-horizontal > .ant-menu-submenu-selected {
+  font-weight: 600;
+  box-shadow: inset 0 -2px 0 0 ${token.colorText};
+}
+.nb-settings-shell .ant-layout-sider .ant-menu-item-selected {
+  font-weight: 600;
+}
+.nb-settings-shell .ant-layout-sider .ant-menu-item::after,
+.nb-settings-shell .ant-layout-sider .ant-menu-submenu-title::after {
+  display: none !important;
+}
+/* 未启用态保持 antd 默认的实心灰滑轨：之前做成白底描边太淡，和「禁用」几乎看不出差别。
+   禁用态不用整体压暗（插件管理器里一整屏都是不可操作的内置插件，压狠了像坏了），
+   而是把滑轨调到跟「未启用」同一档灰、滑块的小白圆点也压成浅灰——
+   整体退成一片同色系的浅灰，跟纯黑的「开着且能关」拉开距离。 */
+.nb-settings-shell .ant-switch-disabled {
+  opacity: 1;
+}
+.nb-settings-shell .ant-switch-disabled.ant-switch-checked {
+  background: ${token.colorTextQuaternary};
+}
+.nb-settings-shell .ant-switch-disabled .ant-switch-handle::before {
+  background: ${token.colorBorderSecondary};
+}
+`;
+}