# カスタムプロパティ

カスタムプロパティを使うと、エンドユーザーが Fluxlay アプリの設定 UI からスライダー・カラーピッカー・トグル・ドロップダウン等で壁紙をパーソナライズできるようになります。

## 1. マニフェストでプロパティを定義

`fluxlay.yaml` に `properties` セクションを追加します:

```yaml title="fluxlay.yaml"
schemaVersion: 1
name: My Wallpaper
slug: my-wallpaper
version: 0.1.0
kind: web

properties:
  speed:
    type: number
    label: アニメーション速度
    default: 1.0
    min: 0.1
    max: 5.0
    step: 0.1
  volume:
    type: range
    label: 音量
    default: 50
    min: 0
    max: 100
    step: 1
  accentColor:
    type: color
    label: アクセントカラー
    default: "#3b82f6"
  darkMode:
    type: boolean
    label: ダークモード
    default: true
  title:
    type: text
    label: タイトル
    default: ""
    maxLength: 40
  layout:
    type: select
    label: レイアウト
    default: grid
    options:
      - value: grid
        label: グリッド
      - value: list
        label: リスト
      - value: masonry
        label: メイソンリー
  tags:
    type: multi-select
    label: 表示タグ
    default: [time]
    min: 1
    max: 3
    options:
      - value: time
        label: 時刻
      - value: date
        label: 日付
      - value: weather
        label: 天気
  background:
    type: image
    label: 背景画像
    accept: ["image/*"]
    maxBytes: 5242880
  font:
    type: font
    label: フォント
    default: Inter
    sources: [system, google]
    category: sans-serif
```

## 2. 壁紙でプロパティを読み取る

`useProperties()` フックで現在の値にアクセスします:

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

interface Props {
  speed: number;
  accentColor: string;
  darkMode: boolean;
  layout: string;
}

function Wallpaper() {
  const { speed, accentColor, darkMode, layout } = useProperties<Props>();

  return (
    <div
      style={{
        backgroundColor: darkMode ? "#1a1a2e" : "#ffffff",
        color: accentColor
      }}
    >
      <p>速度: {speed}x</p>
      <p>レイアウト: {layout}</p>
    </div>
  );
}
```

このフックは自動的に:

- 初期値を取得（デフォルト値にユーザーのカスタマイズをマージ）
- ユーザーが値を変更したときにリアルタイムで更新をサブスクライブ

## 3. アプリでテスト

1. `fluxlay dev` で開発サーバーを起動します。
2. Fluxlay デスクトップアプリの設定を開きます。
3. 壁紙の設定カードにプロパティが表示されます。
4. 値を調整すると、壁紙がリアルタイムで更新されます。

## バリデーション

マニフェストはビルド時にバリデーションされます。主なルール:

- **schemaVersion**: `1` を必須で宣言する必要があります。
- **number** / **range**: `default` は `min` と `max` の範囲内である必要があります。`range` は UI でスライダーとして表示され、`min` / `max` は必須です。
- **color**: `default` は有効な hex カラー（`#rgb`、`#rrggbb`、`#rrggbbaa`）である必要があります。
- **text**: `maxLength` を指定した場合、`default` の文字数はそれ以下である必要があります。
- **select**: `default` は `options` のいずれかの `value` と一致する必要があります。
- **multi-select**: `default` の各要素が `options` に含まれ、`min` / `max` を指定した場合は選択数の制約も満たす必要があります。
- **image** / **file**: `accept` は MIME 形式（例: `image/*`、`application/pdf`）。値は SDK ではホスト OS の絶対パス（未設定時は `null`）として届きます。
- **font**: `sources` は `system` および/または `google`。`google` を含む場合はマニフェストの `network` で Google Fonts へのアクセスを宣言する必要があります。

## 注意事項

- ユーザーのカスタマイズは壁紙の slug ごとに保存され、アプリ再起動後も保持されます。
- ユーザーがカスタマイズしていないプロパティはマニフェストのデフォルト値を使用します。

詳細は [useProperties リファレンス](/ja/studio/developer/reference/sdk/use-properties.md)を参照してください。