ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

ErisPulse-Dashboard

Tip

このドキュメントを読むべきとき:Web画面でボットを視覚的に管理したい場合(モジュールの有効化・無効化、設定編集、ログ閲覧、イベントストリームの監視など)、または自分のモジュール用のDashboard管理ページを登録したい場合にお読みください。必要ない場合はスキップして構いません。

ErisPulse-Dashboard はErisDevが直接メンテナンスするWeb管理パネルモジュールで、ErisPulseに視覚的なランタイム管理インターフェースを提供します:モジュールの有効化・無効化、設定編集、ログ閲覧、イベントストリーム監視など。

Important

DashboardはErisPulseフレームワークの内蔵機能ではありません。別途インストールが必要です:

epsdk install Dashboard

Dashboardは、他のErisPulseモジュールがカスタム管理ページをサイドバーに登録することもサポートしています。登録後、ユーザーはDashboard内で直接そのモジュール専用のビューページに切り替えることができ、独立したフロントエンドを別途開発する必要はありません。

Note

ビュー登録はオプション機能です。

  • Dashboardモジュールが未インストールまたは未ロードの場合、sdk.Dashboard.register_view() を呼び出すと例外がスローされます
  • モジュール自体の他の機能に影響が及ばないよう、登録コードは必ず try/except で囲んでください
  • 登録前にDashboardが利用可能かどうかを確認することをお勧めします:hasattr(sdk, 'Dashboard') and sdk.Dashboard

動作原理

モジュールの on_load()
  → sdk.Dashboard.register_view(...) を呼び出し
  → Dashboardバックエンドがビュー情報を保存
  → WebSocketでフロントエンドに通知
  → フロントエンドがサイドバーナビ項目 + ページコンテナを動的に作成
  → ユーザーがクリックしてモジュールのビューを表示

登録API

sdk.Dashboard.register_view(
    id="MyModule",                    # 必須、一意の識別子
    title="マイモジュール",             # 中国語名
    title_en="My Module",             # 英語名
    icon_svg='<svg>...</svg>',        # サイドバーアイコンSVG
    html_content='<div>...</div>',     # ページのHTMLコンテンツ
    js_content='function xxx() {}',    # ページのJavaScriptロジック
    css_content='.my-style {}',        # 任意のカスタムCSS
    iframe_url='',                     # iframeモードのURL(html_contentとどちらか一方を指定)
    loader="loadMyModuleView",         # このページに切り替えた際に呼び出されるJS関数名
    group="group_extensions",          # サイドバーグループ
    group_title="",                    # カスタムグループの中国語名
    group_title_en="",                 # カスタムグループの英語名
)

パラメータ説明

パラメータ 型 必須 説明
id str はい ビューの一意識別子、モジュール名の使用を推奨
title str いいえ 中国語表示名、デフォルトは id を使用
title_en str いいえ 英語表示名、デフォルトは title を使用
icon_svg str いいえ サイドバーアイコンの完全なSVG文字列
html_content str いいえ* インジェクションモードのページHTMLコンテンツ
js_content str いいえ ページのJavaScriptコード
css_content str いいえ ページのカスタムCSSスタイル
iframe_url str いいえ* iframeモードのURL、設定すると html_content は無視されます
loader str いいえ ページアクティブ時に自動的に呼び出されるJS関数名
group str いいえ サイドバーグループ識別子、デフォルトは group_extensions
group_title str いいえ カスタムグループの中国語タイトル
group_title_en str いいえ カスタムグループの英語タイトル

*html_content と iframe_url のうち少なくとも一方を指定する必要があります。そうでない場合、ページは空白になります。


2つのインジェクションモード

モード1:HTML/JSインジェクション(推奨)

HTML、JS、CSSの文字列を直接提供すると、Dashboardがその内容をページに注入します。このモードはDashboardのスタイルと完全に一致しており、Dashboardが提供するCSSクラス名の使用を推奨します。

sdk.Dashboard.register_view(
    id="HelloPage",
    title="ハローページ", title_en="Hello",
    icon_svg='<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/></svg>',
    html_content='<h1 class="page-title">Hello World</h1><div class="card"><div class="card-body">これはサンプルページです</div></div>',
    group="group_tools",
)

APIルートやJSインタラクションなどを含む完全な天気モジュールの例は、下記の完全なモジュール例を参照してください。

モード2:iframe埋め込み

モジュールが独自のHTMLページURLを提供し(ルートの登録は自身で行う必要があります)、Dashboardがiframeとして埋め込みます。完全に独立したUIや複雑なインタラクションが必要なシナリオに適しています。

sdk.Dashboard.register_view(
    id="MyVisualizer",
    title="データ可視化", title_en="Data Visualizer",
    iframe_url="/MyVisualizer/view",
    group="group_tools",
)

iframeモードでは、認証用の token パラメータがURLに自動的に追加されます。


サイドバーグループ

モジュールはビューが属するサイドバーグループを指定できます。Dashboardには以下の組み込みグループがあります:

グループ識別子 中国語名 位置
group_overview 概要 第1グループ
group_events イベント 第2グループ
group_extensions 拡張 第3グループ(デフォルト)
group_system システム 第4グループ
group_tools ツール 第5グループ

組み込みグループ名を指定すると、モジュールのビューはそのグループの末尾に追加されます:

group="group_tools"  # "ツール"グループに追加

カスタムグループ名(group_ で始まらない名前)を使用することもでき、Dashboardが自動的に新しいグループを作成します:

group="my_group",
group_title="マイグループ",
group_title_en="My Group",

よく使うCSSクラス名

モジュールのビューでHTMLインジェクションモードを使用する場合、視覚的一貫性を保つためにDashboardの既存のCSSクラス名を直接使用できます:

クラス名 用途
page-title ページタイトル、例:<h1 class="page-title">タイトル</h1>
card カードコンテナ
card-header カードのタイトルバー
card-body カードのコンテンツ領域
grid-2 2カラムグリッドレイアウト
grid-3 3カラムグリッドレイアウト
btn 基本ボタン
btn-primary メインボタン(青)
btn-secondary サブボタン
btn-icon アイコンボタン
btn-danger 危険な操作用ボタン

DashboardはCSS変数でテーマカラーを制御しており、モジュールのビュー内で直接参照できます:

CSS変数 用途
var(--bg-p) メイン背景色
var(--bg-s) サブ背景色
var(--bg-t) 第3背景色(カードなど)
var(--tx-p) メインテキスト色
var(--tx-s) サブテキスト色
var(--tx-t) 補助テキスト色
var(--bd) ボーダー色
var(--accent) アクセントカラー
var(--ok-c) 成功色
var(--er-c) エラー色

これらの変数はDashboardのライト/ダークテーマに応じて自動的に切り替わるため、モジュール側で追加の処理は不要です。


認証とAPI呼び出し

モジュールのビューのJSからモジュール独自のAPIを呼び出す際は、認証のためにDashboardのトークンを付ける必要があります:

var token = localStorage.getItem('__ep_tk__');
var resp = await fetch('/YourModule/api/data', {
    headers: { 'Authorization': 'Bearer ' + token }
});
var data = await resp.json();

モジュールのAPIエンドポイントがトークンを検証するかどうかは自由に決定できます。検証が必要な場合は、リクエストヘッダーから抽出できます:

async def _api_data(self, request):
    token = request.headers.get("Authorization", "").replace("Bearer ", "")
    if not token:
        return {"error": "Unauthorized"}, 401
    return {"data": "hello"}

完全なモジュール例

以下は完全な天気モジュールの例で、ビューの登録方法、APIデータの提供方法、アンロード時のリソースクリーンアップ方法を示しています:

from ErisPulse import sdk
from ErisPulse.Core.Bases import BaseModule
from ErisPulse.Core.Event import command


class Main(BaseModule):
    def __init__(self):
        self.sdk = sdk
        self.logger = sdk.logger.get_child("Weather")
        self.config = self._load_config()

    @staticmethod
    def get_load_strategy():
        from ErisPulse.loaders import ModuleLoadStrategy
        return ModuleLoadStrategy(lazy_load=False, priority=50)

    async def on_load(self, event):
        self._register_routes()
        self._register_dashboard_view()
        self.logger.info("天気モジュールがロードされました")

    async def on_unload(self, event):
        self._unregister_routes()
        if hasattr(self.sdk, 'Dashboard') and self.sdk.Dashboard:
            self.sdk.Dashboard.unregister_view("Weather")
        self.logger.info("天気モジュールがアンロードされました")

    def _load_config(self):
        config = self.sdk.config.getConfig("Weather")
        if not config:
            default = {"city": "北京", "api_key": ""}
            self.sdk.config.setConfig("Weather", default)
            return default
        return config

    def _register_routes(self):
        r = self.sdk.router
        r.register_http_route("Weather", "/api/current",
                              handler=self._api_current, methods=["GET"])

    def _unregister_routes(self):
        r = self.sdk.router
        try:
            r.unregister_http_route("Weather", "/api/current")
        except Exception:
            pass

    async def _api_current(self, request):
        return {
            "city": self.config.get("city", "北京"),
            "temp": 25,
            "humidity": 60,
        }

    def _register_dashboard_view(self):
        try:
            dashboard = self.sdk.Dashboard
            dashboard.register_view(
                id="Weather",
                title="天気", title_en="Weather",
                icon_svg='<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg>',
                html_content='''
                    <h1 class="page-title">天気検索</h1>
                    <p style="color:var(--tx-s);margin-bottom:16px">現在の天気情報を表示</p>
                    <div class="grid-2">
                        <div class="card">
                            <div class="card-header">現在の天気</div>
                            <div class="card-body">
                                <div id="weather-info" style="font-size:14px;color:var(--tx-s)">「更新」をクリックして読み込み</div>
                            </div>
                        </div>
                        <div class="card">
                            <div class="card-header">操作</div>
                            <div class="card-body">
                                <button class="btn btn-primary" onclick="refreshWeather()">更新</button>
                            </div>
                        </div>
                    </div>
                ''',
                js_content='''
                    async function loadWeatherView() { await refreshWeather(); }
                    async function refreshWeather() {
                        var el = document.getElementById('weather-info');
                        if (!el) return;
                        el.textContent = '読み込み中...';
                        try {
                            var resp = await fetch('/Weather/api/current', {
                                headers: { 'Authorization': 'Bearer ' + localStorage.getItem('__ep_tk__') }
                            });
                            var data = await resp.json();
                            el.innerHTML = '<p>都市: ' + (data.city || '--') + '</p>' +
                                           '<p>温度: ' + (data.temp || '--') + '°C</p>' +
                                           '<p>湿度: ' + (data.humidity || '--') + '%</p>';
                        } catch (e) {
                            el.textContent = '読み込み失敗: ' + e.message;
                        }
                    }
                ''',
                loader="loadWeatherView",
                group="group_tools",
            )
        except Exception as e:
            self.logger.warning(f"Dashboardビューの登録に失敗しました: {e}")

ビューの登録解除

モジュールのアンロード時には unregister_view() を呼び出して、登録済みのビューをクリーンアップする必要があります:

async def on_unload(self, event):
    if hasattr(self.sdk, 'Dashboard') and self.sdk.Dashboard:
        self.sdk.Dashboard.unregister_view("Weather")

登録解除後、DashboardのフロントエンドはWebSocketを通じてサイドバーナビ項目とページコンテンツをリアルタイムで削除するため、ユーザーがページを再読み込みする必要はありません。


注意事項

  1. ロード順序 — Dashboardのロード優先度は 99999(高優先度)です。あなたのモジュールの優先度はこれより低い値(例:50)にし、Dashboardが先にロードを完了するようにしてください
  2. 防御的プログラミング — Dashboardモジュールが未インストールまたは未ロードの可能性があるため、ビュー登録時は try/except で囲んでください
  3. リソースクリーンアップ — on_unload 内で unregister_view() を呼び出し、登録済みのビューを削除してください
  4. IDの一意性 — id パラメータはDashboard全体で一意である必要があります。モジュール名をそのまま使用することを推奨します
  5. SVGアイコン — icon_svg は完全な <svg> タグである必要があります。サイズは viewBox="0 0 24 24" を使用し、stroke="currentColor" でDashboardのテーマカラーを継承することを推奨します
  6. JS関数の命名 — js_content 内の関数名は一意なもの(例:loadWeatherView)にし、他のモジュールとの衝突を避けてください
  7. 動的更新 — モジュールがビューを登録/登録解除すると、DashboardのフロントエンドはWebSocketを通じてサイドバーをリアルタイムで更新します。ページの再読み込みは不要です

次のステップ