FLUXLAY

useProperties

壁紙マニフェスト（fluxlay.yaml）で定義され、エンドユーザーが Fluxlay アプリの設定 UI でカスタマイズしたプロパティ値をサブスクライブします。

インポート

import { useProperties } from "@fluxlay/react";

シグネチャ

function useProperties<T extends PropertyValues = PropertyValues>(): T;

型パラメータ

パラメータデフォルト説明
TPropertyValuesプロパティ値オブジェクトの型。Record<string, number | string | boolean | string[] | null> を拡張します。

戻り値

現在のプロパティ値を含むオブジェクトを返します。各キーは fluxlay.yaml で定義したプロパティ ID に対応します。値はマニフェストのデフォルト値に、ユーザーのカスタマイズが上書きされた結果を反映しています。

初期値の取得が完了するまで {} を返します。

マニフェスト定義

プロパティは fluxlay.yaml で定義します:

fluxlay.yaml
schemaVersion: 1
properties:
  particleCount:
    type: number
    label: パーティクル数
    default: 100
    min: 10
    max: 500
    step: 10
  themeColor:
    type: color
    label: テーマカラー
    default: "#ff6b35"
  showClock:
    type: boolean
    label: 時計を表示
    default: true
  animationStyle:
    type: select
    label: アニメーションスタイル
    default: wave
    options:
      - value: wave
        label: Wave
      - value: spiral
        label: Spiral

properties の完全なスキーマはマニフェストリファレンスを参照してください。

プロパティ型

型TypeScript 型UI コントロール説明
numbernumberステッパー / 入力min/max/step を任意で指定可能な数値。
rangenumberスライダースライダー UI を強制する数値。min / max 必須。
colorstringカラーピッカーhex カラー文字列（例: "#ff6b35"）。
booleanbooleanトグルスイッチtrue または false。
textstringテキスト入力自由入力テキスト。maxLength / placeholder を任意指定。
selectstringドロップダウン定義済みオプションからの単一選択。
multi-selectstring[]チェックリスト / マルチセレクト定義済みオプションからの複数選択。min / max で個数制約。
imagestring | nullファイルピッカー（画像）エンドユーザーが選んだローカル画像の絶対パス。未設定時は null。
filestring | nullファイルピッカー任意のローカルファイルの絶対パス。未設定時は null。
fontstringフォントセレクタフォントファミリ名。sources: [system, google] で取得元を指定。

使用例

interface WallpaperProperties {
  particleCount: number;
  themeColor: string;
  showClock: boolean;
  animationStyle: string;
}
 
function Wallpaper() {
  const { particleCount, themeColor, showClock, animationStyle } = useProperties<WallpaperProperties>();
 
  return (
    <div style={{ backgroundColor: themeColor }}>
      <p>パーティクル数: {particleCount}</p>
      <p>アニメーション: {animationStyle}</p>
      {showClock && <Clock />}
    </div>
  );
}

備考

  • プロパティ値はマウント時に取得され、その後リアルタイムでストリーミングされます。ユーザーが設定 UI で値を変更すると、フックは更新された値で即座に再レンダリングされます。
  • ユーザーのカスタマイズは壁紙の slug ごとに永続化されます。同じ壁紙を再インストールまたは再割り当てしても、以前のカスタマイズが復元されます。
  • このフックは Fluxlay デスクトップアプリ内でのみ動作します。通常のブラウザでは {} を返します。
  • image / file の値はホスト OS 上のファイルパスです。ファイルが移動・削除されると読み込みに失敗するため、壁紙側でフォールバック処理を実装してください。
  • マニフェストには schemaVersion: 1 の宣言が必須です。旧形式の type: string は廃止され、select（options 必須）または text（自由入力）に分割されています。