ユーザー管理

ユーザー管理機能は、SpreadJS ベースのアプリケーションでユーザー情報を管理するための集中化された拡張可能なメカニズムを提供します。

この機能は、スレッド式コメントなどのコンポーネント間での、名前、ID、アバターなどのユーザーデータの作成、取得、更新方法を定義します。

基本概念

User

User は IUser インターフェイスを実装するプレーンな JavaScript オブジェクトです。

これは個々のユーザーを表し、次の主要な識別プロパティを保持します：

id – ユーザーの一意識別子
name – ユーザーの表示名
email (任意) – 連絡先または参照情報
avatar (任意) – さまざまな画像ソース形式で定義できるビジュアル表現
color (任意) – ラベル付けや視覚的識別に使用するカスタム色

サンプルのユーザーオブジェクトは次のとおりです：

{
  id: "user1",
  name: "Alice",
  email: "alice@example.com",
  color: "#5B8FF9"
}

UserManager

GC.Spread.Common 名前空間にある UserManager オブジェクトは、スプレッドシート環境でユーザー情報へアクセスし管理するためのグローバル関数を提供します。

グローバルシングルトン であり、インスタンス化は不要です。
アプリケーション全体でユーザーデータの保存、取得、更新方法を制御します。
すべてのユーザーとそのメタデータを管理します。
ユーザー検索やイベントバインディングの設定をサポートします。
実行時に現在のユーザーコンテキストを設定／取得できます。
get はユーザー情報を取得するための非同期関数です。

UserManager は SpreadJS プラットフォーム全体でユーザー関連操作を行うための共有サービスとして機能します。

セットアップと構成

ユーザー管理を有効にするには、アプリケーションのユーザーデータを定義し、UserManager がユーザー情報を取得する方法を構成します。

構成では SpreadJS に次を指示します：

ID によってユーザーの詳細を取得する方法
ユーザー検索を実行する方法
必要に応じて一貫したビジュアル表現のためのカラースキームを指定する方法

ユーザーの定義

user は IUser インターフェイスに従う JavaScript オブジェクトです。

各ユーザーは少なくとも id と name が必要で、email、avatar、color を任意で追加できます。

var users = [
  { id: "user1", name: "Alice", email: "alice@example.com" },
  { id: "user2", name: "Bob",   email: "bob@example.com" }
];

注記：
avatar プロパティは URL、data URL、Blob、ローカルファイルなど複数の画像形式をサポートします。

UserManager の構成

UserManager は通常はアプリケーション初期化時などに configure() メソッドで一度だけ構成する必要があります。

このメソッドには、ユーザーデータの取得や検索方法を定義する設定オブジェクトを渡します。

get(userId) – 指定されたIDのユーザーオブジェクトを返す Promise<IUser> を返します。
get は IUserManagerOptions に設定された get を実行します。
search(query) –（任意）ユーザー選択UI を実装する場合に、条件に一致するユーザーを返します。
colorScheme –（任意）アバターまたは表示色を自動生成する際のカスタム色を定義します。

const options = {
  get: async (userId) => {
        if (userId === undefined) {
            return;
        }
        return new Promise((resolve) => {
            const user = users.find(u => u.id === userId);
            resolve(user);
        });
    },
  search: async (query) => {
        return new Promise((resolve) => {
            resolve(users.filter(u =>
                u.name.toLowerCase().includes(query.toLowerCase()) ||
                u.email.toLowerCase().includes(query.toLowerCase())
            ));
        });
    }
}

GC.Spread.Common.UserManager.configure(options);

構成後、UserManager は グローバルシングルトン として動作し、スレッド式コメントなどの SpreadJSの機能が ID を使用してユーザーデータへ自動的にアクセスします。

UserManager の使用

構成後、UserManager を使用してアプリケーション内の現在ユーザーコンテキストを管理できます。

これには現在ユーザーの設定・取得、ユーザーイベントの処理が含まれます。

現在のユーザー設定

current() メソッドは現在のユーザー ID の取得／設定に使用します。

例：

// 現在のユーザーを設定する
GC.Spread.Common.UserManager.current("user1");

// 現在のユーザーを取得する
var currentUserId = GC.Spread.Common.UserManager.current();

注記：
現在ユーザーが設定されていない場合、UserManager は既定のグローバルユーザーとして “ゲスト” を自動生成します。

ゲストユーザーは自動生成時に次を持ちます：

ランダム UUID の id
カルチャに応じた表示名（例: 英語カルチャでは “Guest”）

ユーザーイベントの処理

UserManager は次のメソッドによるイベント購読と管理をサポートします:

bind(event, handler) – イベントに関数を登録し、発生時に呼び出します。
unbind(event, handler?) – 登録を解除します。handler を省略した場合、そのイベントのすべてのハンドラーが解除されます。

サポートされるイベント：

CurrentUserChanged — 現在のユーザーが正常に変更されると、非同期でトリガーされるイベントです。

このイベントに登録すると、アプリケーションロジックでユーザー変更に応じた UI 更新やデータ再取得を行えます。

例：

function onUserChanged(event, args) {
  console.log(`User changed: ${args.oldCurrentUser?.id} → ${args.newCurrentUser?.id}`);
}

// イベントを購読
GC.Spread.Common.UserManager.bind(GC.Spread.Common.Events.CurrentUserChanged, onUserChanged);

// イベントの購読を解除
GC.Spread.Common.UserManager.unbind(GC.Spread.Common.Events.CurrentUserChanged, onUserChanged);

アバター処理ルール

アバター画像が指定されていない場合：

user.name の先頭文字（大文字）をアバターテキストとして使用します。
背景色は user.color が指定されていればそれを使用します。
user.color がない場合、ユーザー ID に基づいてあらかじめ定義されたカラースキームから決定的な色を選択します。

既定のカラースキーム

SpreadJS は colorScheme が指定されていない場合、次の 20 色パレットを使用します:

#3B82F6  #10B981  #8B5CF6  #F59E0B  #EF4444
#06B6D4  #EC4899  #84CC16  #6366F1  #14B8A6
#F97316  #A855F7  #22C55E  #EAB308  #F43F5E
#0EA5E9  #D946EF  #65A30D  #DC2626  #7C3AED

開発者は UserManager の構成時に colorScheme 配列を指定することで既定スキームを上書きできます。

注記：
色数は柔軟であり、アルゴリズムは ID を利用可能な色に自動的にマッピングします。

GC.Spread.Common.UserManager.configure({
  get: async (userId) => {
        if (userId === undefined) {
            return;
        }
        return new Promise((resolve) => {
            const user = users.find(u => u.id === userId);
            resolve(user);
        });
    },
  search: async (query) => {
        return new Promise((resolve) => {
            resolve(users.filter(u =>
                u.name.toLowerCase().includes(query.toLowerCase()) ||
                u.email.toLowerCase().includes(query.toLowerCase())
            ));
        });
    },
  colorScheme: ["#5B8FF9", "#61DDAA", "#F6BD16"] // カスタムカラー
});