@aparajita/capacitor-dark-mode

中文文档

6.0.0发布于 2025/10/29MITTypeScriptESM + CJS近 30 天下载 2万

Ionic 网络和本地应用程序的通用暗模式支持

文档目录19 节

QQ 正在产生变化
动机
继续喝
特征
安装
配置
黑暗模式 CSS
插件配置
使用量
API 密码
因数(...)
配置(...)
已忽略
设置 NativeDarkMode 倾听器(...)
添加 Appearance 倾听器(...)
更新(...)
接口
类型异名
数字

电容器暗模式

这个电容 7 插件是Ionic Web,iOS和Android的全暗模式解决方案.

QQ 正在产生变化

为了在导入时符合以暗模式支持构建的Ionic 8 @ionic/vue/css/palettes/dark.class.css,进行了两项修改:

当运行在 Ionic 8+ 上时, 默认的暗模式类是现在 .ion-palette-dark。如果您使用默认值 .dark 类别,替换所有 .dark 在您的 CSS 中设置 .ion-palette-dark。。。 .
暗模式类现在应用到 html 元素替换为 body。。。 .

为了符合Capacitor 6听众界面, addAppearanceListener 现在只返回一个承诺,必须等待.

动机

在网络和iOS上,暗模式与Ionic很容易工作,因为浏览器和WKWebView正确处理 prefers-color-scheme CSS财产. 在Android, 另一方面, prefers-color-scheme 实值好,真的断了我从来没有见过它可靠地工作在Ionic应用, 即使与Capacitor 5和Android DayNight的主题.

使用此插件, 您可以轻松启用并控制应用程序的暗模式全部平台,保证! 这意味着在10前的Android版本(API 29)上,这是第一个支持系统暗模式的版本,你可以允许用户切换暗模式.

继续喝

如果您将暗模式作为用户偏好执行, 您无法仅依赖 CSS prefers-color-scheme 查询; 您必须使用一个类来表示您是否处于暗模式。维持一套相同的 CSS 变量 prefers-color-scheme: dark 和暗类选择器是容易出错的,额外的维护,一般违反DRY原则.

此插件只依靠一个暗类选择器来表示您是否处于暗模式,并根据系统暗模式和/或用户偏好来管理您的暗模式.

安装 | 配置 | 使用量 | API 密码

特征

用于在所有平台启用和控制暗模式的统一 API. QQ
自动暗模式检测(在支持暗模式的系统中). QQ
支持用户暗模式切换. ☀️🌛
支持自定义暗模式偏好存储。 @ @ info
更新状态栏以匹配暗模式, 甚至在Android. QQ
Android 上的自定义状态栏颜色。 @ @ info
系统暗模式变化的注册听众。 @ info
广泛的文件

安装

在你的应用中:

pnpm add @aparajita/capacitor-dark-mode

配置

插件安装后,需要:

如果使用Ionic < 8, 在您的 CSS 中提供暗模式 import '@ionic/vue/css/palettes/dark.class.css' 在离子 8+ 中.
初始化插件 .

黑暗模式 CSS

此插件添加或删除 CSS 类 html 必要时,元素。默认情况下,类是 .dark 离子体 < 8和 .ion-palette-dark 在 Ionic 8+ 上,但您可以任意配置它.

👉🏽 说明: 若您使用 Tailwind 的标签暗模式支持设置 darkMode: 'class' 在您的 Tailwind 配置文件中 .

由您来配置您的 CSS , 以便在该类出现时实际执行暗模式。开始的好地方是标准离子暗模式,它依赖于控制Ionic组件外观的 CSS 变量.

如果您有可用的 CSS 暗主题 prefers-color-scheme,您应该删除所有 @media (prefers-color-scheme: dark) 规则和转而使用 html.dark (或简单 .dark)作为暗模式选择器. 无需在两种模式中重复阴暗模式 a @media (prefers-color-scheme: dark) 块和 a html.dark 块。这就是使用这个插件的好处之一!

/* Remove all prefers-color-scheme selectors! */
@media (prefers-color-scheme: dark) {
  html {
    --ion-color-primary: #428cff;
    /* ... */
  }
}

/* Replace with this */
html.dark {
  --ion-color-primary: #428cff;
  /* ... */
}

插件配置

如果您使用默认的暗模式 CSS 类, 并且不允许用户手动设置光或暗模式, 因此不需要存储偏好, 您全部被设定 ! 插件为您做了所有的工作 .

如果您使用默认以外的暗模式 CSS 类, 您需要配置插件。在应用程序安装之前, 您将会想要这样做以避免任何视觉缺陷。例如,如果您的应用程序使用一个暗模式 CSS 类: .dark-mode,您可以在基于Vue的Ionic app中配置这样的插件:

主关

const app = createApp(App).use(IonicVue, config).use(router)

router
  .isReady()
  .then(() => {
    // configure() is a synonym for init()
    DarkMode.init({ cssClass: 'dark-mode' })
      .then(() => {
        app.mount('#app')
      })
      .catch(console.error)
  })
  .catch(console.error)

在反应或Angular-based Ionic app中使用等效.

👉🏽 说明: 如果导入, 使用自定义的暗模式类不会对 Ionic 8+ 工作 @ionic/vue/css/palettes/dark.class.css 您必须使用默认值( E).ion-palette-dark在这样的情况下.

自定义首选项存储

如果您想要将用户的暗模式偏好存储于自定义位置( 例如 ) localStorage),您必须创建返回偏好和存储偏好设置的获取函数,并将这些函数传递给 init 或者说 configure 方法.

预选赛

import type { DarkModeGetterResult } from '@aparajita/capacitor-dark-mode'
import { DarkModeAppearance } from '@aparajita/capacitor-dark-mode'

const kDarkModePref = 'dark-mode'

export function getAppearancePref(): DarkModeGetterResult {
  return localStorage.getItem(kDarkModePref)
}

export function setAppearancePref(appearance: DarkModeAppearance) {
  localStorage.setItem(kDarkModePref, appearance)
}

主关

import { getAppearancePref, setAppearancePref } from './prefs'

router
  .isReady()
  .then(() => {
    DarkMode.init({
      cssClass: 'dark-mode',
      getter: getAppearancePref,
      setter: setAppearancePref,
    })
      .then(() => {
        app.mount('#app')
      })
      .catch(console.error)
  })
  .catch(console.error)

以上示例使用同步函数,但您也可以使用返回一个承诺的自动同步获取器,所以对您如何或在何处存储首选没有限制.

Android 状态栏定制

在Android上,还有几个附加选项你可以传递给 init()/configure() 当黑模式被切换时, 状态栏会发生什么.

同步状态栏
若为 syncStatusBar 实值 true,状态栏将更新以匹配暗模式。这是默认行为.

状态Bar 背景变量
何时 syncStatusBar 实值 true,默认情况下,状态栏背景将设定为 --background CSS 变量 ion-content 元素,由 ion-content 作为:

ion-content {
  /*
    The stock Ionic theme sets --ion-background-color
    in dork mode.
   */
  --background: var(--ion-background-color, #fff);
}

如果您想要为状态栏使用不同的颜色, 您可以设置 statusBarBackgroundVariable 改为不同的 CSS 变量的名称。然后可以在您的 CSS 中相应设置变量 .

如果变量的值不是有效的 3 或 6 位“ #” 前缀的十六进制颜色,则不更改 .

状态 Bar 定型器
何时 syncStatusBar 实值 true 并设置一个有效的背景颜色,默认情况下,状态栏样式将根据背景颜色的亮度设置:

// Default threshold is 0.5
const statusBarStyle = isDarkColor(color) ? Style.Dark : Style.Light

如果您想要使用不同的样式, 可以设定 statusBarStyleGetter 以返回要使用的样式的函数。此函数将随当前 Style (基于外观设置,而非背景颜色)和状态栏背景颜色,并应当返回 Style 应设置状态栏.

例如,你可以使用 isDarkColor() (由插件导出) 具有不同阈值 :

import { Style } from '@capacitor/status-bar'

const statusBarStyleGetter = (style?: Style, color?: string) => {
  if (color) {
    const isDark = isDarkColor(color, 0.4)
    return isDark ? Style.Dark : Style.Light
  }

  return style
}

👉🏽 说明: 获取器也被称为当 syncStatusBar 实值 'textOnly'。。。 .

使用量

我可以花很多时间解释详细的用法,但也许最好的解释是用整个插件API的完整例子,并显示如何处理用户暗模式偏好变化. 检查演示程序这里。你会特别想看看 prefs.ts 财务报告和审定财务报表 dark-mode-demo.vue。。。 .

因数(...)

init(options?: DarkModeOptions) => Promise<void>

初始化插件,并可选地配置用于检索当前暗模式状态的暗模式类和获取器. 在应用被挂起之前应当这样做, 但是在 ATER 定义了 dom( 例如在 <body> 结尾) 以避免错误模式的闪出 .

参数	类型
选项	暗模式选项

配置(...)

configure(options?: DarkModeOptions) => Promise<void>

一个同义词 init。。。 .

参数	类型
选项	暗模式选项

已忽略

isDarkMode() => Promise<IsDarkModeResult>

网络: 返回结果 prefers-color-scheme: dark 媒体查询.

原生:返回系统目前是否处于暗模式.

回返情况: 承诺 <暗黑模式结果> 翻译:

设置 NativeDarkMode 倾听器(...)

setNativeDarkModeListener(options: Record<string, unknown>, callback: DarkModeListener) => Promise<string>

参数	类型
选项	记录< 字符串, 未知 >
回调	黑暗模式倾听器

回返情况: 承诺<字符串>

添加 Appearance 倾听器(...)

addAppearanceListener(listener: DarkModeListener) => Promise<DarkModeListenerHandle>

添加一个在系统外观变化时被调用的收听器,无论系统外观是否与当前外观相匹配。收听者称为AFTER 暗模式类,状态栏由插件更新. 收听者将被叫来 DarkModeListenerData 表示当前系统外观是否为黑暗.

返回的手柄包含一个 remove 函数,当不需要收听器时,例如当一个组件被卸载时(HMR经常发生这种情况),应当确定该函数。否则会出现内存出漏和多个听众执行同一种功能.

参数	类型
监听器	黑暗模式倾听器

回返情况: 承诺 <暗道听牌游戏> 翻译:

更新(...)

update(data?: DarkModeListenerData) => Promise<DarkModeAppearance>

根据暗模式状态,在html元素上添加或删除暗模式类. 当系统外观发生变化时,您不需要使用此名称 .

如果您正在手动设置外观, 并且您已经指定了获取器函数, 您应该将这种方法称为 AFTER , 即配置的获取器更改返回的值 .

返回当前外观.

参数	类型
数据	黑暗模式倾听者数据

回返情况: 承诺 <黑暗模式> 翻译:

接口

暗模式选项

转至 configure。。。 .

Prop	类型	说明
css 分类	字符串	CSS 类名用于切换暗模式 .
获取器	黑暗模式编辑器	如果设定, 此函数将被调用以获取当前暗模式状态, 而不是 `isDarkMode`。例如,您可能想要让用户手动设置暗/灯模式,并存储该偏好。如果函数要表示无法取出值, 它应该返回无效或未定义, 在这种情况下 `isDarkMode` 将被使用. 如果您没有提供黑模式状态的存储, 请不要在选项中通过 .
设置	黑暗模式编辑器	如果设定了, 此函数将被调用以设置当前暗模式状态, 当 `update` 名为. 例如,您可能想要让用户手动设置暗/光模式并存储该偏好,例如本地Storage .
禁用转换	布尔	如果选中的话, 插件会在切换出暗模式时自动禁用所有转换。这样做是为了防止不同元素以不同的速度在光和暗模式之间切换. 例如,"离子-项目"在其所有属性上默认具有过渡性. 如果您想要自己处理转换, 请设置为错误 .
同步状态栏	暗模式同步状态栏	只有机器人若为 `statusBarStyleGetter` 设置,此选项未被使用. 如果为真, 在Android上, 状态栏的背景和内容将被同步到当前 `DarkModeAppearance`。。。 . 如果“ text Only ” , 在 Android 上, 只将状态栏内容与当前同步 `DarkModeAppearance`:外观为暗色而反之为淡色. 在iOS上,此选项未被使用,状态栏背景由系统与暗模式同步.
状态Bar 背景变量	字符串	只有机器人如果设定了, 此 CSS 变量将被使用, 而不是“ -- 背景” 来设置状态栏背景颜色 .
状态 Bar 定型器	状态栏StyleGetter	只有机器人如果设定,和 `syncStatusBar` ,此函数将调用以获取当前状态栏样式,而不是基于暗模式。如果函数想要表示无法取出值,它应该返回一个假值,在这种情况下,当前外观将用来决定样式.

暗黑模式结果

返回结果 isDarkMode。。。 .

Prop	类型
阴暗	布尔

黑暗模式倾听者数据

您的外观监听器调用将接收此数据, 显示系统是否处于暗模式 .

Prop	类型
阴暗	布尔

暗道听牌游戏

当你打电话 addAppearanceListener,你得到一个可以用来移除收听器的把手。见添加辅助收听器更多细节.

方法	签署
删除	() 无效

类型异名

黑暗模式编辑器

你的外观功能类型 .

(): DarkModeGetterResult | Promise<DarkModeGetterResult>

黑暗模式Getter 结果

您的外观更清晰的功能应返回(直接或作为承诺) :

- 一个黑暗模式表示这是你想要的外表

- 应使用无效或未定义表示系统外观的系统

DarkModeAppearance | null |

黑暗模式编辑器

您的外观设置功能类型 .

(appearance: DarkModeAppearance): void | Promise<void>

暗模式同步状态栏

同步状态栏选项的可能值 .

boolean | 'textOnly'

状态栏StyleGetter

您状态条样式获取器函数的类型 .

(style?: Style, backgroundColor?: string): StatusBarStyleGetterResult | Promise<StatusBarStyleGetterResult>

状态栏StyleGetter Result

您的风格获取器函数应当返回( 直接或作为承诺) :

- 一个样式表示这是你想要的样式

- 应使用无效或未定义来表示默认行为

Style | null |

记录

构造 T 类型 K 的一组属性类型

{ [P in K]: T; }

黑暗模式倾听器

您的外表听者调用类型 .

(data: DarkModeListenerData): void

数字

黑暗模式

成员	数值
阴暗	"黑暗"
光线	光线
系统	系统

样式

成员	数值	说明
阴暗	达克	暗背景的轻文本 .
光线	"灯"	浅色背景的黑暗文本 .
默认	"保卫"	风格取自设备外观. 如果设备使用"暗黑"模式,则状态栏文本会很轻. 如果设备使用"光"模式,则状态栏文本会变暗. 在Android上,默认是应用软件推出的那个.

版本与发布记录

@aparajita/capacitor-dark-mode 共发布 25 个版本，首次发布于 2022/07/24；过去 12 个月发布了 0 个版本。

版本	发布日期	距今
`6.0.0`latest	2025/10/29	1 年前
`5.0.2`	2024/07/17	2 年前
`5.0.1`	2024/04/22	2 年前
`5.0.0`	2024/04/21	2 年前
`4.0.1`	2023/10/24	3 年前
`4.0.0`	2023/06/16	3 年前

关于 @aparajita/capacitor-dark-mode 的常见问题

@aparajita/capacitor-dark-mode 是什么？

Ionic 网络和本地应用程序的通用暗模式支持

如何安装 @aparajita/capacitor-dark-mode？

在项目目录运行 npm install @aparajita/capacitor-dark-mode，或使用 pnpm add / yarn add / bun add。

@aparajita/capacitor-dark-mode 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@aparajita/capacitor-dark-mode 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require() 都可以使用，打包工具会自动选择合适的版本。

@aparajita/capacitor-dark-mode 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >=20.0.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@aparajita/capacitor-dark-mode 可以商用吗？

@aparajita/capacitor-dark-mode 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@aparajita/capacitor-dark-mode 的下载量有多少？

根据 npm 官方下载统计，@aparajita/capacitor-dark-mode 在 2026/10/06 – 2026/11/04 这 30 天内被下载 20,293 次，日均约 676 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@aparajita/capacitor-dark-mode 还在维护吗？

最新版本 6.0.0 发布于 2025/10/29（1 年前）；至今共发布 25 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/07/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @aparajita/capacitor-dark-mode

pnpmpnpm add @aparajita/capacitor-dark-mode
yarnyarn add @aparajita/capacitor-dark-mode
bunbun add @aparajita/capacitor-dark-mode

在你的项目目录中运行此命令。

近 30 天下载

20,293

约 2万次日均 676 次

统计周期 2026/10/06 – 2026/11/04
数据来自 npm 官方下载统计，1 天前更新

最新版本6.0.0发布于 1 年前

开源许可MIT宽松许可

包体积93.2 kB30 个文件 · 解压后

运行依赖5 个

模块格式ESM + CJS

TypeScript自带类型

Node.js>=20.0.0

发布版本25 个近 12 个月 0 个

首次发布2022/07/244 年前

元数据更新2025/10/29

每一个软件包背后，
都有分享与创造的人。