@k8ordo/color-scheme

API

@k8ordo/color-schemeがexportするコンポーネントとフック、値、型の一覧です。

このページの内容

ColorSchemeScript

import元 @k8ordo/color-scheme

最初の描画の前に<html>へdarkクラスを付けるインラインスクリプトです。themeColorを渡すと、theme-colorのmetaも書きます。ルートレイアウトの<head>に置きます。

ts
ColorSchemeScript(props: ColorSchemeScriptProps): ReactNode

引数

defaultPreferenceColorSchemePreference = 'system'
何も選んでいない訪問者に、最初の描画で適用する値です。プロバイダのdefaultPreferenceと同じ値を渡します。
themeColor{ light: string; dark: string } | undefined
アドレスバーなど、ブラウザのUIに使うライトとダークの色です。渡すと、スクリプトが画面の配色に合ったtheme-colorのmetaを書きます。ページではtheme-colorのmetaを書きません。
noncestring | undefined
スクリプトに付けるnonceです。@k8ordo/frameworkのserverモードではnonce()を渡します。ハッシュで許可するときは省略します。

注意

  • 'use client'のモジュールからexportしているので、Server Componentのルートレイアウトからそのまま描画できます。スクリプトの中身はHTMLにだけ書かれ、ペイロードには載りません。
  • どのスタイルシートよりも前に置きます。@k8ordo/frameworkは、<head>に書いたインラインスクリプトをスタイルシートより前へ移します。
layout.tsx
export default function RootLayout({
  children,
}: {
  children: ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ColorSchemeScript />
      </head>
      <body>
        <ColorSchemeProvider>{children}</ColorSchemeProvider>
      </body>
    </html>
  );
}

ColorSchemeProvider

import元 @k8ordo/color-scheme

ページ全体を包むプロバイダです。ルートレイアウトの<body>の中に置きます。ハイドレーションのあと、保存した選択やOSの設定が変わるたびに<html>のdarkクラスを更新します。スクリプトが書いたtheme-colorのmetaも合わせて書き換えます。

ts
ColorSchemeProvider(props: ColorSchemeProviderProps): ReactNode

引数

defaultPreferenceColorSchemePreference = 'system'
何も選んでいない訪問者に適用する値です。'system'ならOSの設定に従います。'light'か'dark'なら、訪問者が選ぶまでその配色になります。ColorSchemeScriptにも同じ値を渡します。
childrenReactNode
ページ全体です。

注意

  • 'use client'のモジュールからexportしているので、Server Componentのルートレイアウトからそのまま描画できます。
  • <html>にはsuppressHydrationWarningを付けます。スクリプトが付けたclassはサーバーのHTMLに無く、開発時のReactが食い違いとして報告します。
  • アプリに1つだけ置きます。2つあると、それぞれがクラスを付けるので、結果が食い違うことがあります。
layout.tsx
export default function RootLayout({
  children,
}: {
  children: ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ColorSchemeScript />
      </head>
      <body>
        <ColorSchemeProvider>{children}</ColorSchemeProvider>
      </body>
    </html>
  );
}

useColorScheme

import元 @k8ordo/color-scheme

画面に出ている配色と訪問者の選択、選択を変える関数を返します。Client Componentで使います。

ts
useColorScheme(): UseColorScheme

戻り値

UseColorScheme — schemeとpreference、setPreferenceをまとめたオブジェクトです。

フィールド

scheme'light' | 'dark'
画面に出ている配色です。訪問者の選択、プロバイダの既定値、OSの設定の順で決まります。
preference'light' | 'dark' | 'system'
訪問者の選択です。何も選んでいないときは'system'です。
setPreference(preference: ColorSchemePreference) => void
選択を保存します。'system'を渡すと保存した選択を消し、プロバイダの既定値に戻ります。

注意

  • プロバイダの外で呼ぶと、useColorScheme needs <ColorSchemeProvider> above itで始まるエラーになります。既定値は返しません。
  • プロバイダが決めた値を読むだけです。<html>のクラスもlocalStorageも書き換えません。
  • サーバーの描画とハイドレーションの描画では、既定値から決めた値を返します。既定値が'system'なら'light'です。保存した選択とOSの設定は、その次の描画から反映されます。
scheme-toggle.tsx
const { scheme, setPreference } = useColorScheme();

<button
  onClick={() => {
    setPreference(scheme === 'dark' ? 'light' : 'dark');
  }}
  type="button"
>
  Toggle
</button>

トグルと3択の作り方は切り替えボタンを見てください。

colorSchemeState

import元 @k8ordo/color-scheme

設定の保存先を表す、@k8ordo/stateのdefineLocalStateの定義です。localStorageのk8ordo-state:color-schemeに、preferenceだけを持つオブジェクトとして保存します。

ts
const colorSchemeState = defineLocalState(
  'color-scheme',
  z.object({ preference: z.optional(z.enum(['light', 'dark'])) }),
);

フィールド

kind'local'
状態の置き場所の種類です。localStorageなので'local'です。
key'color-scheme'
@k8ordo/stateの中での名前です。ストアはこの名前ごとに1つです。
schemaZodMiniObject
定義に渡したスキーマです。
storageKey'k8ordo-state:color-scheme'
localStorageのキーです。k8ordo-state:にkeyをつなげた値です。
inlineRead() => string
インラインスクリプトに書くJavaScriptの式を返します。式を評価すると保存したオブジェクトになり、値を読めないときはnullになります。

注意

  • useAppState(colorSchemeState)で、保存したpreferenceをフックを通さずに読めます。値は'light' | 'dark' | undefinedで、解決したschemeではありません。
  • 選択はsetPreferenceで変えます。同じタブでlocalStorage.setItemを直接呼んだ値は、再読み込みまで画面に反映されません。
  • defineLocalState('color-scheme', …)をもう1つ定義しないでください。ストアは名前で共有されるので、2つの定義が同じ保存した値を読み書きします。
stored-preference.tsx
const [{ preference }] = useAppState(colorSchemeState);
// 'light' | 'dark' | undefined

colorSchemeScriptHash

import元 @k8ordo/color-scheme

ColorSchemeScriptが描画するインラインスクリプトのSHA-256を、CSPのソースの形('sha256-…')で返します。nonceを使わずにスクリプトを許可するポリシーに入れます。

ts
colorSchemeScriptHash(
  options?: ColorSchemeScriptOptions,
): Promise<string>

引数

options.defaultPreferenceColorSchemePreference = 'system'
ColorSchemeScriptに渡しているdefaultPreferenceです。既定値はスクリプトの文字列に入るので、この値でハッシュが変わります。
options.themeColor{ light: string; dark: string } | undefined
ColorSchemeScriptに渡しているthemeColorです。色もスクリプトの文字列に入るので、この値でハッシュが変わります。キーを書く順はハッシュに影響しません。

戻り値

Promise<string> — 'sha256-…'のように、前後の引用符を含んだCSPのソースです。

注意

  • ハッシュの値をポリシーに書き写さず、ポリシーを書く場所で毎回呼びます。スクリプトの文字列はインストールしたバージョンのもので、更新で変わることがあります。
  • 応答ごとにnonceを付けられるなら、ハッシュは要りません。
vite.config.ts
framework({
  mode: 'static',
  csp: {
    'script-src': ["'self'", await colorSchemeScriptHash()],
  },
});

ポリシーの組み立て方はCSPを見てください。

ColorScheme

import元 @k8ordo/color-scheme

画面に出せる配色です。schemeの型です。

ts
type ColorScheme = 'light' | 'dark';

ColorSchemePreference

import元 @k8ordo/color-scheme

配色か'system'です。訪問者の選択としての'system'は「何も選んでいない」を表し、プロバイダの既定値に従います。既定値としての'system'はOSの設定に従います。

ts
type ColorSchemePreference = ColorScheme | 'system';

ColorSchemeProviderProps

import元 @k8ordo/color-scheme

ColorSchemeProviderのpropsの型です。プロバイダを包むコンポーネントを自分で作るときに使います。

ts
type ColorSchemeProviderProps = {
  readonly defaultPreference?: ColorSchemePreference;
  readonly children: ReactNode;
};

ColorSchemeScriptOptions

import元 @k8ordo/color-scheme

ColorSchemeScriptのpropsのうち、スクリプトの文字列に入るものの型です。colorSchemeScriptHash()の引数の型です。

ts
type ColorSchemeScriptOptions = {
  readonly defaultPreference?: ColorSchemePreference;
  readonly themeColor?: {
    readonly light: string;
    readonly dark: string;
  };
};

ColorSchemeScriptProps

import元 @k8ordo/color-scheme

ColorSchemeScriptのpropsの型です。スクリプトを包むコンポーネントを自分で作るときに使います。

ts
type ColorSchemeScriptProps = ColorSchemeScriptOptions & {
  readonly nonce?: string;
};

UseColorScheme

import元 @k8ordo/color-scheme

useColorScheme()の戻り値の型です。フックの値をpropsで受け取るコンポーネントに使います。

ts
type UseColorScheme = {
  readonly scheme: ColorScheme;
  readonly preference: ColorSchemePreference;
  readonly setPreference: (preference: ColorSchemePreference) => void;
};
k8ordo

Baselineに入った機能を、制限なく使うReactのライブラリ群。