API
@k8ordo/color-schemeがexportするコンポーネントとフック、値、型の一覧です。
このページの内容
ColorSchemeScript
import元 @k8ordo/color-scheme
最初の描画の前に<html>へdarkクラスを付けるインラインスクリプトです。themeColorを渡すと、theme-colorのmetaも書きます。ルートレイアウトの<head>に置きます。
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.tsxexport 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も合わせて書き換えます。
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.tsxexport 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で使います。
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.tsxconst { 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だけを持つオブジェクトとして保存します。
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.tsxconst [{ preference }] = useAppState(colorSchemeState);
// 'light' | 'dark' | undefinedcolorSchemeScriptHash
import元 @k8ordo/color-scheme
ColorSchemeScriptが描画するインラインスクリプトのSHA-256を、CSPのソースの形('sha256-…')で返します。nonceを使わずにスクリプトを許可するポリシーに入れます。
colorSchemeScriptHash(
options?: ColorSchemeScriptOptions,
): Promise<string>引数
options.defaultPreferenceColorSchemePreference = 'system'ColorSchemeScriptに渡しているdefaultPreferenceです。既定値はスクリプトの文字列に入るので、この値でハッシュが変わります。options.themeColor{ light: string; dark: string } | undefinedColorSchemeScriptに渡しているthemeColorです。色もスクリプトの文字列に入るので、この値でハッシュが変わります。キーを書く順はハッシュに影響しません。
戻り値
Promise<string> — 'sha256-…'のように、前後の引用符を含んだCSPのソースです。
注意
- ハッシュの値をポリシーに書き写さず、ポリシーを書く場所で毎回呼びます。スクリプトの文字列はインストールしたバージョンのもので、更新で変わることがあります。
- 応答ごとにnonceを付けられるなら、ハッシュは要りません。
vite.config.tsframework({
mode: 'static',
csp: {
'script-src': ["'self'", await colorSchemeScriptHash()],
},
});ポリシーの組み立て方はCSPを見てください。
ColorScheme
import元 @k8ordo/color-scheme
画面に出せる配色です。schemeの型です。
type ColorScheme = 'light' | 'dark';ColorSchemePreference
import元 @k8ordo/color-scheme
配色か'system'です。訪問者の選択としての'system'は「何も選んでいない」を表し、プロバイダの既定値に従います。既定値としての'system'はOSの設定に従います。
type ColorSchemePreference = ColorScheme | 'system';ColorSchemeProviderProps
import元 @k8ordo/color-scheme
ColorSchemeProviderのpropsの型です。プロバイダを包むコンポーネントを自分で作るときに使います。
type ColorSchemeProviderProps = {
readonly defaultPreference?: ColorSchemePreference;
readonly children: ReactNode;
};ColorSchemeScriptOptions
import元 @k8ordo/color-scheme
ColorSchemeScriptのpropsのうち、スクリプトの文字列に入るものの型です。colorSchemeScriptHash()の引数の型です。
type ColorSchemeScriptOptions = {
readonly defaultPreference?: ColorSchemePreference;
readonly themeColor?: {
readonly light: string;
readonly dark: string;
};
};ColorSchemeScriptProps
import元 @k8ordo/color-scheme
ColorSchemeScriptのpropsの型です。スクリプトを包むコンポーネントを自分で作るときに使います。
type ColorSchemeScriptProps = ColorSchemeScriptOptions & {
readonly nonce?: string;
};UseColorScheme
import元 @k8ordo/color-scheme
useColorScheme()の戻り値の型です。フックの値をpropsで受け取るコンポーネントに使います。
type UseColorScheme = {
readonly scheme: ColorScheme;
readonly preference: ColorSchemePreference;
readonly setPreference: (preference: ColorSchemePreference) => void;
};