umbraco-theme

Umbraco 主题

这是什么？

Umbraco 中的主题可以自定义后台的视觉外观。它们可以覆盖 CSS 自定义属性，以更改颜色、字体排版和其他视觉元素。这可以实现暗色模式、高对比度、自定义品牌样式或其他任何视觉主题。用户可以在个人资料设置中选择主题。

文档

实现前务必获取最新文档：

• 基础：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation
• 扩展注册表：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry
• 主题：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types

相关基础技能

• 扩展注册表：注册主题时使用
  • 参考技能：umbraco-extension-registry

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提问 - 想要什么颜色？暗色还是浅色？品牌颜色是什么？
3. 生成文件 - 根据最新文档创建清单和 CSS
4. 说明 - 展示创建了哪些内容以及如何测试

最简示例

清单（manifests.ts）

import type { ManifestTheme } from '@umbraco-cms/backoffice/extension-registry';

export const manifests: Array<ManifestTheme> = [
  {
    type: 'theme',
    alias: 'My.Theme.Dark',
    name: 'My Dark Theme',
    css: () => import('./dark-theme.css?inline'),
  },
];

CSS 主题文件（dark-theme.css）

:root {
  /* Background colors */
  --uui-color-surface: #1e1e1e;
  --uui-color-surface-alt: #252526;
  --uui-color-surface-emphasis: #2d2d30;

  /* Text colors */
  --uui-color-text: #d4d4d4;
  --uui-color-text-alt: #9d9d9d;

  /* Primary/accent colors */
  --uui-color-default: #3c3c3c;
  --uui-color-positive: #4ec9b0;
  --uui-color-warning: #dcdcaa;
  --uui-color-danger: #f14c4c;

  /* Interactive colors */
  --uui-color-interactive: #569cd6;
  --uui-color-interactive-emphasis: #9cdcfe;

  /* Border colors */
  --uui-color-border: #3c3c3c;
  --uui-color-border-standalone: #454545;

  /* Header */
  --uui-color-header-surface: #1e1e1e;
  --uui-color-header-contrast: #d4d4d4;

  /* Selected states */
  --uui-color-selected: #264f78;
  --uui-color-selected-contrast: #ffffff;
}

高对比度主题（high-contrast-theme.css）

:root {
  /* High contrast for accessibility */
  --uui-color-surface: #000000;
  --uui-color-surface-alt: #0a0a0a;

  --uui-color-text: #ffffff;
  --uui-color-text-alt: #e0e0e0;

  --uui-color-border: #ffffff;
  --uui-color-border-standalone: #ffffff;

  --uui-color-interactive: #ffff00;
  --uui-color-interactive-emphasis: #00ffff;

  --uui-color-focus: #ff00ff;
}

品牌主题（brand-theme.css）

:root {
  /* Custom brand colors */
  --uui-color-current: #your-brand-primary;
  --uui-color-current-contrast: #ffffff;
  --uui-color-current-standalone: #your-brand-darker;

  /* Header with brand color */
  --uui-color-header-surface: #your-brand-primary;
  --uui-color-header-contrast: #ffffff;

  /* Interactive elements use brand */
  --uui-color-interactive: #your-brand-primary;
  --uui-color-interactive-emphasis: #your-brand-lighter;
}

接口参考

interface ManifestTheme extends ManifestPlainCss {
  type: 'theme';
}

interface ManifestPlainCss {
  type: string;
  alias: string;
  name: string;
  css: () => Promise<{ default: string } | string>;
}

常用 CSS 自定义属性

表面

• --uui-color-surface - 主背景
• --uui-color-surface-alt - 替代背景
• --uui-color-surface-emphasis - 强调背景

文本

• --uui-color-text - 主要文本
• --uui-color-text-alt - 次要文本

状态颜色

• --uui-color-positive - 成功状态
• --uui-color-warning - 警告状态
• --uui-color-danger - 错误／危险状态

交互

• --uui-color-interactive - 链接、按钮
• --uui-color-interactive-emphasis - 悬停状态
• --uui-color-selected - 已选项目

页眉

• --uui-color-header-surface - 页眉背景
• --uui-color-header-contrast - 页眉文本

最佳实践

• 使用所有 UI 组件测试主题
• 确保对比度足够，满足无障碍要求
• 考虑暗色／浅色模式变体
• 使用 CSS 自定义属性保持一致性

就是这样！务必获取最新文档，保持示例简洁，并生成完整可运行的代码。