@blocklet/ui-react/docs/getting-started.ja.md

Some useful front-end web components that can be used in Blocklets.

# はじめに

このガイドでは、`@blocklet/ui-react` ライブラリをインストールし、最初のコンポーネントをレンダリングするための手順をステップバイステップで説明します。目標は、最小限の時間でアプリケーション内に機能する `Header` と `Footer` を実装することです。

## 前提条件

先に進む前に、開発環境に以下がインストールされていることを確認してください：
*   動作する React プロジェクト。
*   Node.js とパッケージマネージャー（npm または yarn）。

## インストール

まず、お使いのパッケージマネージャーを使用して、`@blocklet/ui-react` パッケージをプロジェクトに追加します。

npm を使用する場合:
```bash npm
npm install @blocklet/ui-react
```

yarn を使用する場合:
```bash yarn
yarn add @blocklet/ui-react
```

## 基本的な使用法: Header と Footer

`Header` と `Footer` コンポーネントはシンプルに設計されており、初期設定なしでレンダリングできます。これらのコンポーネントは、blocklet のメタデータから自動的にデータを取得します。

1.  `Header` と `Footer` コンポーネントをメインのアプリケーションファイル（例：`App.js`）にインポートします。
2.  それぞれをアプリケーションのレイアウトの最上部と最下部に配置します。

```jsx App.js icon=logos:react
import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';
import Footer from '@blocklet/ui-react/lib/Footer';

function App() {
  return (
    <div>
      <Header />
      <main style={{ padding: '20px', minHeight: 'calc(100vh - 128px)' }}>
        {/* アプリケーションのコンテンツはここに記述します */}
        <h1>Welcome to My Blocklet</h1>
      </main>
      <Footer />
    </div>
  );
}

export default App;
```

コンポーネントは、アプリケーション名、ロゴ、ナビゲーションリンクなどの設定詳細を、Blocklet Server 環境によって注入される `window.blocklet` メタデータオブジェクトから自動的に取得します。

さらに、`Header` コンポーネントは、状況に応じて追加のコントロールをインテリジェントにレンダリングします：
*   `SessionContext` が利用可能な場合、**ユーザーセッションマネージャー**が表示されます。
*   `LocaleContext` が利用可能な場合、**言語セレクター**が表示されます。

## 手動設定

開発、テスト、またはデフォルトのメタデータを上書きする必要がある場合、`blockletMeta` プロパティを使用して設定オブジェクトをコンポーネントに直接渡すことができます。

```jsx App.js icon=logos:react
import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';

const customBlockletMeta = {
  appName: 'My Custom App',
  appLogo: 'https://path.to/your/logo.png',
  navigation: [
    {
      title: 'Home',
      link: '/',
    },
    {
      title: 'Documentation',
      link: '/docs',
    },
  ],
};

function App() {
  return (
    <div>
      <Header blockletMeta={customBlockletMeta} />
      {/* ... rest of your app */}
    </div>
  );
}
```

このアプローチにより、グローバルな `window.blocklet` オブジェクトによって提供されるデータを上書きし、コンポーネントの外観と動作を正確に制御できます。

## Header のカスタマイズ

`Header` コンポーネントには右側に `addons` エリアがあり、アクションボタンやカスタムリンクなど、独自のコンポーネントを含めるようにカスタマイズできます。

`addons` プロパティは、デフォルトのアドオンコンポーネントを引数として受け取る関数を受け入れます。これにより、既存のコンポーネントの前に追加したり、後ろに追加したり、完全に置き換えたりすることができます。

```jsx CustomHeader.js icon=logos:react
import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';
import Button from '@mui/material/Button'; // Material-UI を使用した例

function CustomHeader() {
  return (
    <Header
      addons={existingAddons => {
        return [
          <Button
            key="custom-action"
            variant="contained"
            color="primary"
            size="small"
            style={{ marginRight: 8 }}>
            Custom Action
          </Button>,
          ...existingAddons, // 重要: デフォルトのセッション/ロケールアドオンを保持します
        ];
      }}
    />
  );
}
```

この例では、カスタムボタンが既存のアドオンの前に追加されています。`...existingAddons` を含めることで、デフォルトのセッションおよびロケールコントロールが表示されたままになるようにします。

## まとめ

これで、`@blocklet/ui-react` ライブラリのインストール、デフォルトの `Header` および `Footer` コンポーネントのレンダリング、そしてカスタム設定やアドオンの提供方法を学びました。

これらの基本を理解したことで、ライブラリで利用可能なすべてのコンポーネントを探索する準備が整いました。レイアウト、ユーザー管理、ユーティリティコンポーネントに関する詳細なドキュメントについては、[コンポーネント](./components.md) セクションに進んでください。