Skip to main content

高级主题

基于 CSS 的主题使应用能够通过加载 CSS 文件或更改一些 CSS 属性值来快速自定义颜色。

🌐 CSS-based theming enables apps to customize the colors quickly by loading a CSS file or changing a few CSS property values.

theme-color 元​

🌐 theme-color Meta

theme-color 元标签的值表示浏览器可以用来定制页面或周围界面显示的颜色。这类元标签还可以接受媒体查询，允许开发者为亮色和暗色模式设置主题颜色。

🌐 The theme-color value for a meta tag indicates a color that browsers can use to customize the display of a page or of the surrounding interface. This kind of meta tag can also accept media queries which allow developers to set the theme color for both light and dark modes.

theme-color 元数据的 content 值必须包含有效的 CSS 颜色 ，并且不能包含 CSS 变量。

note

theme-color 元数据控制在 Web 浏览器中运行或作为 PWA 时的界面主题，在使用 Capacitor 或 Cordova 部署应用时不起作用。如果你想自定义状态栏下方的区域，我们建议使用 Capacitor 状态栏插件。

下面的示例演示了如何使用 theme-color 来为 iOS 15 上的浏览器界面设置样式。

🌐 The example below demonstrates how to use theme-color to style the browser interface on iOS 15.

<meta name="theme-color" media="(prefers-color-scheme: light)" content="#0054e9" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#eb445a" />
浅色模式夜间模式
浏览器界面中的浅色模式主题颜色。浏览器界面中的夜间模式主题颜色。

在 macOS Monterey 或更高版本的 Safari 中，theme-color 元信息也可用于自定义工具栏。

🌐 The theme-color meta can also be used to customize the toolbar in Safari on macOS Monterey or newer.

iOS 15 和 macOS 上的 Safari 会自动确定要使用的适当主题颜色，但如果你需要对主题进行更多控制，添加此元标记会很有用。

🌐 Safari on iOS 15 and macOS will automatically determine an appropriate theme color to use, but adding this meta tag is useful if you need more control over the theme.

有一小部分颜色，浏览器不会使用，因为它们会干扰浏览器界面。例如，在 macOS 上的 Safari 中设置 content="red" 不会生效，因为该颜色会干扰工具栏上的红色关闭按钮。如果遇到这种情况，请尝试稍微更改你的颜色选择。

🌐 There is a small subset of colors that browsers will not use as they interfere with the browser interface. For example, setting content="red" will not work in Safari on macOS because that color interferes with the red close button in the toolbar. If you run into this situation, try altering your color selection slightly.

note

如果 manifest.json 中同时存在 theme-color 和 theme，浏览器将更倾向于使用 theme-color 元标签。

欲了解更多信息，请参阅 MDN 主题颜色文档。

全局变量​

🌐 Global Variables

虽然主题部分中的应用变量和分步变量对于更改应用的颜色非常有用，但通常需要在多个组件中使用的变量。以下变量在组件之间共享，用于更改全局填充设置等。

🌐 While the application and stepped variables in the themes section are useful for changing the colors of an application, often times there is a need for variables that are used in multiple components. The following variables are shared across components to change global padding settings and more.

应用变量​

🌐 Application Variables

名称描述
--ion-font-family应用的字体系列
--ion-statusbar-padding应用状态栏顶部内边距
--ion-safe-area-top调整应用的安全区域顶部插入
--ion-safe-area-right调整应用的安全区域右侧插入
--ion-safe-area-bottom调整应用的安全区域底部插入
--ion-safe-area-left调整应用的安全区域左侧插入
--ion-margin调整 Margin 属性 的外边距
--ion-padding调整 Padding 属性 的内边距
--ion-placeholder-opacity调整输入框、文本区域、搜索栏和选择组件中占位符的透明度

网格变量​

🌐 Grid Variables

名称描述
--ion-grid-columns网格中的列数
--ion-grid-padding-xsxs 响应断点下网格的内边距
--ion-grid-padding-smsm 响应断点下网格的内边距
--ion-grid-padding-mdmd 响应断点下网格的内边距
--ion-grid-padding-lglg 响应断点下网格的内边距
--ion-grid-padding-xlxl 响应断点下网格的内边距
--ion-grid-column-padding-xsxs 响应断点下网格列的内边距
--ion-grid-column-padding-smsm 响应断点下网格列的内边距
--ion-grid-column-padding-mdmd 响应断点下网格列的内边距
--ion-grid-column-padding-lglg 响应断点下网格列的内边距
--ion-grid-column-padding-xlxl 响应断点下网格列的内边距

变量的已知限制​

🌐 Known Limitations with Variables

阿尔法问题​

🌐 The Alpha Problem

对于使用十六进制颜色的 alpha 功能，浏览器尚未完全支持。 rgba() 函数只接受 R, G, B, A（红、绿、蓝、透明度）格式的值。以下代码显示了传递给 rgba() 的正确值和错误值示例。

/* These examples use the same color: blueviolet. */
.broken {
  --violet: #8a2be2;

  /* rgba(#8a2be2, .5) */
  color: rgba(var(--violet), 0.5); /* ERROR! Doesn't support hex. */
}

.working {
  --violet-rgb: 138, 43, 226;

  /* rgba(138, 43, 226, .5) */
  color: rgba(var(--violet-rgb), 0.5); /* WORKS! */
}
note

有关如何获取和设置 CSS 变量的更多信息，请参阅 CSS 变量 部分。

Ionic 在多个组件中使用带有透明度（alpha）的颜色。为了使其正常工作，必须以 RGB 格式提供这些属性。更改任何以 -rgb 结尾的属性变体时，重要的是它们也必须以逗号分隔的格式提供且不带括号。以下是更改文本和背景颜色的一些示例。

🌐 Ionic uses colors with an opacity (alpha) in several components. In order for this to work, those properties must be provided in RGB format. When changing any of the properties that have a variation ending in -rgb, it is important they are also provided in a comma separated format without parentheses. Below are some examples for changing text and background color.

:root {
  /* These examples use the same color: sienna. */
  --ion-text-color: #a0522d;
  --ion-text-color-rgb: 160, 82, 45;

  /* These examples use the same color: lightsteelblue. */
  --ion-background-color: #b0c4de;
  --ion-background-color-rgb: 176, 196, 222;
}

请注意，RGB 格式的颜色与十六进制属性的颜色完全相同，但现在可以与 rgba() 一起使用。例如，--ion-text-color-rgb 现在可以如下使用

🌐 Note that the RGB formatted colors are the exact same color as the hex properties, but can now be used with rgba(). For example, --ion-text-color-rgb can now be used in the following way

body {
  color: rgba(var(--ion-text-color-rgb), 0.25);
}

媒体查询中的变量​

🌐 Variables in Media Queries

目前媒体查询中不支持 CSS 变量，但已有公开草案提出添加自定义媒体查询和自定义环境变量，可以解决这个问题！然而，按照当前的支持情况，以下内容将无法工作：

🌐 CSS variables in media queries are not currently supported, but there are open drafts to add custom media queries and custom environment variables that would solve this problem! However, with the current state of support, the following will not work:

:root {
  --breakpoint: 600px;
}

@media (min-width: var(--breakpoint)) {
  /* Doesn't work :( */
}

修改 CSS 颜色变量​

🌐 Modifying CSS Color Variables

虽然可以使用 Sass 的内置函数轻松更改颜色，但目前修改 CSS 变量中设置的颜色并不那么容易。在 CSS 中可以通过分离 RGB 或 HSL 通道并修改每个值来实现，但这很复杂且功能不完整。

🌐 While it is possible to easily alter a color in Sass using its built-in functions, it is currently not as easy to modify colors set in CSS Variables. This can be accomplished in CSS by splitting the RGB or HSL channels and modifying each value, but it is complex and has missing functionality.

这究竟意味着什么？基本上，使用 CSS 预处理器，例如 Sass，让我们可以使用函数来操作单一颜色。例如，我们可以在 Sass 中创建以下颜色：

🌐 What exactly does this mean? Basically, using a CSS preprocessor, such as Sass, allows us to use functions to manipulate a single color. For example, we can create the following colors in Sass:

// Background color, shade, and tint
$background: #0054e9;
$background-shade: mix(#000, $background, 12%);
$background-tint: mix(#fff, $background, 10%);

// Text color, darker and lighter
$text: #444;
$text-darker: darken($text, 15);
$text-lighter: lighten($text, 15);

通过 Sass 编译器运行后，颜色将具有以下值：

🌐 After running through the Sass compiler, the colors will have the following values:

变量值
$background#0054e9
$background-shade#004acd
$background-tint#1a65eb
$text#444444
$text-darker#1e1e1e
$text-lighter#6a6a6a

但是，由于 CSS 变量可以在运行时设置并且更加动态，因此目前无法使用简单的函数来操作它们。

🌐 However, because CSS variables can be set at runtime and are more dynamic, it is not currently possible to manipulate them using a simple function.

这通常不是问题，但当一个应用需要动态主题时，就会出现问题。在 Ionic 中，这就是为什么每种颜色都有多种变化的原因，也正是为什么分级颜色 对于主题化是必要的原因。

🌐 This is normally not a problem, but when an application needs to have dynamic theming it presents issues. In Ionic, this is the reason that there are variations to each color, and it is also why stepped colors are necessary for theming.

有一些草稿和议题正在讨论颜色修改提案，这些提案将使这成为可能。

🌐 There are drafts and issues discussing color modification proposals that would make this possible.

安全区域填充​

🌐 Safe Area Padding

显示屏的安全区域是指不被设备的刘海、状态栏或其他属于设备界面而非应用的元素覆盖的部分。安全区域的尺寸因设备和方向（纵向或横向）而异。

🌐 The safe area of a display is the section that is not covered by the device's notch, status bar, or other elements that are part of the device's UI and not the app's. The dimensions of the safe area are different across devices and orientations (portrait or landscape).

例如，下面是 iPhone 14 Pro Max 的截图。红色部分是安全区，白色部分是应用内容可能被覆盖的地方。

🌐 For example, below are screenshots of an iPhone 14 Pro Max. The red section is the safe area, and the white sections are places where the app's content would be covered up.

肖像风景

为了适应这一点，Ionic 会自动为某些组件添加内边距。例如，放置在 ion-modal 中的第一个 ion-toolbar 组件将根据设备安全区的顶部边缘接收内边距。这可以避免设备的刘海遮挡头部文本。

🌐 To accommodate this, Ionic automatically adds padding to certain components. For example, the first ion-toolbar component placed in an ion-modal will receive padding according to the top edge of the device's safe area. This avoids the device's notch covering up the header text.

这个填充可以通过 CSS 使用 Application Variables 中描述的 --ion-safe-area-(dir) 变量手动调整。值可以为整个应用设置，也可以按组件设置。例如：

🌐 This padding can be manually adjusted through CSS using the --ion-safe-area-(dir) variables described in Application Variables. Values can be set for the whole application, or on a per component basis. For example:

html {
  --ion-safe-area-left: 25px;
}

ion-modal {
  --ion-safe-area-top: 0;
}

目录