useColorMode

具有自动数据持久化的响应式颜色模式（深色/浅色/自定义）。

Reactive color mode (dark / light / customs) with auto data persistence.

基本使用

import { useColorMode } from '@vueuse/core'

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

import { useColorMode } from '@vueuse/core'

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

默认情况下，它将使用 usePreferredDark （auto模式）与用户的浏览器偏好相匹配。读取 ref 时，默认情况下它将返回当前颜色模式（深色，浅色或你的自定义模式）。通过启用emitAuto，可以将 auto 模式包括在返回的模式中。当写入 ref 时，它会触发 DOM 更新并将颜色模式保存到本地存储（或您的自定义存储）。您可以通过 auto 设置回自动模式。

By default, it will match with users' browser preference using usePreferredDark (a.k.a auto mode). When reading the ref, it will by default return the current color mode (dark, light or your custom modes). The auto mode can be included in the returned modes by enabling the emitAuto option. When writing to the ref, it will trigger DOM updates and persist the color mode to local storage (or your custom storage). You can pass auto to set back to auto mode.

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

mode.value = 'dark' // change to dark mode and persist

mode.value = 'auto' // change to auto mode

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

mode.value = 'dark' // change to dark mode and persist

mode.value = 'auto' // change to auto mode

例子

源

← 点击以更改颜色

Config

import { useColorMode } from '@vueuse/core'

const mode = useColorMode({
  attribute: 'theme',
  modes: {
    // custom colors
    dim: 'dim',
    cafe: 'cafe',
  },
}) // Ref<'dark' | 'light' | 'dim' | 'cafe'>

import { useColorMode } from '@vueuse/core'

const mode = useColorMode({
  attribute: 'theme',
  modes: {
    // custom colors
    dim: 'dim',
    cafe: 'cafe',
  },
}) // Ref<'dark' | 'light' | 'dim' | 'cafe'>

Component Usage

该函数还通过@vueuse/components提供了一个无渲染的组件版本。了解更多.

This function also provides a renderless component version via the @vueuse/components package. Learn more about the usage.

html

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

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

类型声明(Type Declarations)

显示类型声明

typescript

export type BasicColorSchema = "light" | "dark" | "auto"
export interface UseColorModeOptions<T extends string = BasicColorSchema>
  extends UseStorageOptions<T | BasicColorSchema> {
  /**
   * CSS Selector for the target element applying to
   *
   * @default 'html'
   */
  selector?: string
  /**
   * HTML attribute applying the target element
   *
   * @default 'class'
   */
  attribute?: string
  /**
   * The initial color mode
   *
   * @default 'auto'
   */
  initialValue?: T | BasicColorSchema
  /**
   * Prefix when adding value to the attribute
   */
  modes?: Partial<Record<T | BasicColorSchema, string>>
  /**
   * A custom handler for handle the updates.
   * When specified, the default behavior will be overridden.
   *
   * @default undefined
   */
  onChanged?: (
    mode: T | BasicColorSchema,
    defaultHandler: (mode: T | BasicColorSchema) => void
  ) => void
  /**
   * Custom storage ref
   *
   * When provided, `useStorage` will be skipped
   */
  storageRef?: Ref<T | BasicColorSchema>
  /**
   * Key to persist the data into localStorage/sessionStorage.
   *
   * Pass `null` to disable persistence
   *
   * @default 'vueuse-color-scheme'
   */
  storageKey?: string | null
  /**
   * Storage object, can be localStorage or sessionStorage
   *
   * @default localStorage
   */
  storage?: StorageLike
  /**
   * Emit `auto` mode from state
   *
   * When set to `true`, preferred mode won't be translated into `light` or `dark`.
   * This is useful when the fact that `auto` mode was selected needs to be known.
   *
   * @default undefined
   */
  emitAuto?: boolean
  /**
   * Disable transition on switch
   *
   * @see https://paco.me/writing/disable-theme-transitions
   * @default false
   */
  disableTransition?: boolean
}
/**
 * Reactive color mode with auto data persistence.
 *
 * @see https://vueuse.org/useColorMode
 * @param options
 */
export declare function useColorMode<T extends string = BasicColorSchema>(
  options?: UseColorModeOptions<T>
): WritableComputedRef<BasicColorSchema | T>

export type BasicColorSchema = "light" | "dark" | "auto"
export interface UseColorModeOptions<T extends string = BasicColorSchema>
  extends UseStorageOptions<T | BasicColorSchema> {
  /**
   * CSS Selector for the target element applying to
   *
   * @default 'html'
   */
  selector?: string
  /**
   * HTML attribute applying the target element
   *
   * @default 'class'
   */
  attribute?: string
  /**
   * The initial color mode
   *
   * @default 'auto'
   */
  initialValue?: T | BasicColorSchema
  /**
   * Prefix when adding value to the attribute
   */
  modes?: Partial<Record<T | BasicColorSchema, string>>
  /**
   * A custom handler for handle the updates.
   * When specified, the default behavior will be overridden.
   *
   * @default undefined
   */
  onChanged?: (
    mode: T | BasicColorSchema,
    defaultHandler: (mode: T | BasicColorSchema) => void
  ) => void
  /**
   * Custom storage ref
   *
   * When provided, `useStorage` will be skipped
   */
  storageRef?: Ref<T | BasicColorSchema>
  /**
   * Key to persist the data into localStorage/sessionStorage.
   *
   * Pass `null` to disable persistence
   *
   * @default 'vueuse-color-scheme'
   */
  storageKey?: string | null
  /**
   * Storage object, can be localStorage or sessionStorage
   *
   * @default localStorage
   */
  storage?: StorageLike
  /**
   * Emit `auto` mode from state
   *
   * When set to `true`, preferred mode won't be translated into `light` or `dark`.
   * This is useful when the fact that `auto` mode was selected needs to be known.
   *
   * @default undefined
   */
  emitAuto?: boolean
  /**
   * Disable transition on switch
   *
   * @see https://paco.me/writing/disable-theme-transitions
   * @default false
   */
  disableTransition?: boolean
}
/**
 * Reactive color mode with auto data persistence.
 *
 * @see https://vueuse.org/useColorMode
 * @param options
 */
export declare function useColorMode<T extends string = BasicColorSchema>(
  options?: UseColorModeOptions<T>
): WritableComputedRef<BasicColorSchema | T>

Source

贡献者(Contributors)

日志(Changelog)

Pending for release...

320ab - feat(useDark, useColorMode): introduce disableTransition option

useColorMode #

基本使用 #

例子 #

Config #

Component Usage #

类型声明(Type Declarations) #

Source #

贡献者(Contributors) #

日志(Changelog) #