useColorMode

类别

Browser

导出体积

3.14 kB

上次更改

2 months ago

示例

源码 playground (beta)

← 点击更改颜色模式

基本用法

import { useColorMode
 } from '@vueuse/core'

const mode
 = useColorMode
() // Ref<'dark' | 'light'>

默认情况下，它将使用 usePreferredDark (也称为 auto 模式) 匹配用户浏览器的偏好。在读取 ref 时，默认将返回当前的颜色模式 (dark、light 或你的自定义模式)。可以通过启用 emitAuto 选项将 auto 模式包含在返回的模式中。在写入 ref 时，它将触发 DOM 更新并将颜色模式持久化到本地存储 (或你的自定义存储)。你可以传递 auto 来设置回自动模式。

mode
.value
 // 'dark' | 'light'

mode
.value
 = 'dark' // 切换到暗模式并持久化

mode
.value
 = 'auto' // 切换到自动模式

配置

import { useColorMode
 } from '@vueuse/core'

const mode
 = useColorMode
({
  attribute
: 'theme',
  modes
: {
    // 自定义颜色
    dim
: 'dim',
    cafe
: 'cafe',
  },
}) // Ref<'dark' | 'light' | 'dim' | 'cafe'>

高级用法

你还可以明确访问系统偏好和存储的用户覆盖模式。

import { useColorMode
 } from '@vueuse/core'

const { system
, store
 } = useColorMode
()

system
.value
 // 'dark' | 'light'
store
.value
 // 'dark' | 'light' | 'auto'

const myColorMode
 = computed
(() => store
.value
 === 'auto' ? system
.value
 : store
.value
)

组件用法

vue

<template>
  <UseColorMode v-slot="color
">
    <button
 @click
="color
.mode = color
.mode === 'dark' ? 'light' : 'dark'">
      Mode {{ color
.mode }}
    </button
>
  </UseColorMode>
</template>

类型声明

显示类型声明

export type BasicColorMode
 = "light" | "dark"
export type BasicColorSchema
 = BasicColorMode
 | "auto"
export interface UseColorModeOptions
<T
 extends string = BasicColorMode
>
  extends UseStorageOptions<T
 | BasicColorMode
> {
  /**
   * 应用目标元素的 CSS 选择器
   *
   * @default 'html'
   */
  selector
?: string | MaybeElementRef

  /**
   * 应用于目标元素的 HTML 属性
   *
   * @default 'class'
   */
  attribute
?: string
  /**
   * 初始颜色模式
   *
   * @default 'auto'
   */
  initialValue
?: MaybeRefOrGetter
<T
 | BasicColorSchema
>
  /**
   * 添加到属性时的前缀
   */
  modes
?: Partial
<Record
<T
 | BasicColorSchema
, string>>
  /**
   * 用于处理更新的自定义处理程序。
   * 当指定时，将覆盖默认行为。
   *
   * @default undefined
   */
  onChanged
?: (
    mode
: T
 | BasicColorMode
,
    defaultHandler
: (mode
: T
 | BasicColorMode
) => void,
  ) => void
  /**
   * 自定义存储 ref
   *
   * 如果提供了，将跳过 `useStorage`
   */
  storageRef
?: Ref
<T
 | BasicColorSchema
>
  /**
   * 将数据持久化到 localStorage/sessionStorage 的键。
   *
   * 将 `null` 传递以禁用持久性
   *
   * @default 'vueuse-color-scheme'
   */
  storageKey
?: string | null
  /**
   * 存储对象，可以是 localStorage 或 sessionStorage
   *
   * @default localStorage
   */
  storage
?: StorageLike

  /**
   * 从状态中发出 `auto` 模式
   *
   * 当设置为 `true` 时，首选模式不会被转换为 `light` 或 `dark`。
   * 当需要知道选择了 `auto` 模式时，这很有用。
   *
   * @default undefined
   * @deprecated 当需要知道选择了 `auto` 模式时，使用 `store.value`
   * @see https://vueuse.org/core/useColorMode/#advanced-usage
   */
  emitAuto
?: boolean
  /**
   * 关闭切换时的过渡效果
   *
   * @see https://paco.me/writing/disable-theme-transitions
   * @default true
   */
  disableTransition
?: boolean
}
export type UseColorModeReturn
<T
 extends string = BasicColorMode
> = Ref
<
  T
 | BasicColorSchema

> & {
  store
: Ref
<T
 | BasicColorSchema
>
  system
: ComputedRef
<BasicColorMode
>
  state
: ComputedRef
<T
 | BasicColorMode
>
}
/**
 * Reactive color mode with auto data persistence.
 *
 * @see https://vueuse.org/useColorMode
 * @param options
 */
export declare function useColorMode
<T
 extends string = BasicColorMode
>(
  options
?: UseColorModeOptions
<T
>,
): UseColorModeReturn
<T
>