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を通じてサイドバーナビ項目とページコンテンツをリアルタイムで削除するため、ユーザーがページを再読み込みする必要はありません。
注意事項
- ロード順序 — Dashboardのロード優先度は
99999(高優先度)です。あなたのモジュールの優先度はこれより低い値(例:50)にし、Dashboardが先にロードを完了するようにしてください - 防御的プログラミング — Dashboardモジュールが未インストールまたは未ロードの可能性があるため、ビュー登録時は
try/exceptで囲んでください - リソースクリーンアップ —
on_unload内でunregister_view()を呼び出し、登録済みのビューを削除してください - IDの一意性 —
idパラメータはDashboard全体で一意である必要があります。モジュール名をそのまま使用することを推奨します - SVGアイコン —
icon_svgは完全な<svg>タグである必要があります。サイズはviewBox="0 0 24 24"を使用し、stroke="currentColor"でDashboardのテーマカラーを継承することを推奨します - JS関数の命名 —
js_content内の関数名は一意なもの(例:loadWeatherView)にし、他のモジュールとの衝突を避けてください - 動的更新 — モジュールがビューを登録/登録解除すると、DashboardのフロントエンドはWebSocketを通じてサイドバーをリアルタイムで更新します。ページの再読み込みは不要です
次のステップ
- PCを開かずにスマホでボットを管理したい:ErisPulse-App(公式マルチプラットフォームクライアント。Dashboardと同じAPIセットを共有しており、モジュールのビューも同様に利用可能)
- ビューにバックエンドデータAPIを提供したい:ルートマネージャーでHTTPルートを登録します。メソッドの早見表はコアモジュールAPI - Routerを参照
- ビュー内でリアルタイムログ / イベントストリームを表示したい:ログサブスクリプション(プッシュモード)とライフサイクル管理