管理後台 UI | EmDash CMS Everything

外掛可以透過自訂頁面和儀表板小工具來擴充管理後台。這些都是與核心管理功能一起渲染的 React 元件。

管理入口點

具有管理 UI 的外掛從 admin 入口點匯出元件：

import { SEOSettingsPage } from "./components/SEOSettingsPage";
import { SEODashboardWidget } from "./components/SEODashboardWidget";

// 儀表板小工具
export const widgets = {
	"seo-overview": SEODashboardWidget,
};

// 管理頁面
export const pages = {
	"/settings": SEOSettingsPage,
};

在 package.json 中設定入口點：

{
	"exports": {
		".": "./dist/index.js",
		"./admin": "./dist/admin.js"
	}
}

在外掛定義中參考它：

definePlugin({
	id: "seo",
	version: "1.0.0",

	admin: {
		entry: "@my-org/plugin-seo/admin",
		pages: [{ path: "/settings", label: "SEO Settings", icon: "settings" }],
		widgets: [{ id: "seo-overview", title: "SEO Overview", size: "half" }],
	},
});

管理頁面

管理頁面是透過 hooks 接收外掛上下文的 React 元件。

頁面定義

在 admin.pages 中定義頁面：

admin: {
	pages: [
		{
			path: "/settings", // URL 路徑（相對於外掛基礎路徑）
			label: "Settings", // 側欄標籤
			icon: "settings", // 圖示名稱（選填）
		},
		{
			path: "/reports",
			label: "Reports",
			icon: "chart",
		},
	];
}

頁面掛載於 /_emdash/admin/plugins/<plugin-id>/<path>。

頁面元件

import { useState, useEffect } from "react";
import { usePluginAPI } from "@emdash-cms/admin";

export function SettingsPage() {
  const api = usePluginAPI();
  const [settings, setSettings] = useState<Record<string, unknown>>({});
  const [saving, setSaving] = useState(false);

  useEffect(() => {
    api.get("settings").then(setSettings);
  }, []);

  const handleSave = async () => {
    setSaving(true);
    await api.post("settings/save", settings);
    setSaving(false);
  };

  return (
    <div>
      <h1>Plugin Settings</h1>

      <label>
        Site Title
        <input
          type="text"
          value={settings.siteTitle || ""}
          onChange={(e) => setSettings({ ...settings, siteTitle: e.target.value })}
        />
      </label>

      <label>
        <input
          type="checkbox"
          checked={settings.enabled ?? true}
          onChange={(e) => setSettings({ ...settings, enabled: e.target.checked })}
        />
        Enabled
      </label>

      <button onClick={handleSave} disabled={saving}>
        {saving ? "Saving..." : "Save Settings"}
      </button>
    </div>
  );
}

外掛 API Hook

使用 usePluginAPI() 呼叫外掛的路由：

import { usePluginAPI } from "@emdash-cms/admin";

function MyComponent() {
	const api = usePluginAPI();

	// 對外掛路由發送 GET 請求
	const data = await api.get("status");

	// 帶主體的 POST 請求
	await api.post("settings/save", { enabled: true });

	// 帶 URL 參數
	const result = await api.get("history?limit=50");
}

此 hook 會自動在路由 URL 前加上外掛 ID 前綴。

儀表板小工具

小工具顯示在管理儀表板上，提供一目瞭然的資訊。

小工具定義

在 admin.widgets 中定義小工具：

admin: {
	widgets: [
		{
			id: "seo-overview", // 唯一小工具 ID
			title: "SEO Overview", // 小工具標題（選填）
			size: "half", // "full" | "half" | "third"
		},
	];
}

小工具元件

import { useState, useEffect } from "react";
import { usePluginAPI } from "@emdash-cms/admin";

export function SEOWidget() {
  const api = usePluginAPI();
  const [data, setData] = useState({ score: 0, issues: [] });

  useEffect(() => {
    api.get("analyze").then(setData);
  }, []);

  return (
    <div className="widget-content">
      <div className="score">{data.score}%</div>
      <ul>
        {data.issues.map((issue, i) => (
          <li key={i}>{issue.message}</li>
        ))}
      </ul>
    </div>
  );
}

小工具尺寸

尺寸	說明
`full`	儀表板全寬
`half`	儀表板半寬
`third`	儀表板三分之一寬

小工具會根據螢幕寬度自動換行。

匯出結構

管理入口點匯出兩個物件：

import { SettingsPage } from "./components/SettingsPage";
import { ReportsPage } from "./components/ReportsPage";
import { StatusWidget } from "./components/StatusWidget";
import { OverviewWidget } from "./components/OverviewWidget";

// 依路徑為鍵的頁面
export const pages = {
	"/settings": SettingsPage,
	"/reports": ReportsPage,
};

// 依 ID 為鍵的小工具
export const widgets = {
	status: StatusWidget,
	overview: OverviewWidget,
};

使用管理元件

EmDash 提供預建元件用於常見模式：

import {
  Card,
  Button,
  Input,
  Select,
  Toggle,
  Table,
  Pagination,
  Alert,
  Loading
} from "@emdash-cms/admin";

function SettingsPage() {
  return (
    <Card title="Settings">
      <Input label="API Key" type="password" />
      <Toggle label="Enabled" defaultChecked />
      <Button variant="primary">Save</Button>
    </Card>
  );
}

自動產生的設定 UI

如果外掛只需要設定表單，可使用 admin.settingsSchema 而不必建立自訂元件：

admin: {
  settingsSchema: {
    apiKey: { type: "secret", label: "API Key" },
    enabled: { type: "boolean", label: "Enabled", default: true }
  }
}

EmDash 會自動產生設定頁面。只有在需要超出基本設定的功能時才需新增自訂頁面。

導覽

外掛頁面會在管理側欄的外掛名稱下方顯示。順序與 admin.pages 陣列一致。

admin: {
	pages: [
		{ path: "/settings", label: "Settings", icon: "settings" }, // 第一
		{ path: "/history", label: "History", icon: "history" },    // 第二
		{ path: "/reports", label: "Reports", icon: "chart" },      // 第三
	];
}

建置設定

管理元件需要獨立的建置入口點。設定你的打包器：

tsdown

export default {
  entry: {
    index: "src/index.ts",
    admin: "src/admin.tsx"
  },
  format: "esm",
  dts: true,
  external: ["react", "react-dom", "emdash", "@emdash-cms/admin"]
};

tsup

export default {
  entry: ["src/index.ts", "src/admin.tsx"],
  format: "esm",
  dts: true,
  external: ["react", "react-dom", "emdash", "@emdash-cms/admin"]
};

將 React 和 EmDash admin 設為外部依賴，避免打包重複項。

外掛啟用/停用

當外掛在管理後台被停用時：

側欄連結會隱藏
儀表板小工具不會渲染
管理頁面回傳 404
後端鉤子仍會執行（為了資料安全）

外掛可檢查自身的啟用狀態：

const enabled = await ctx.kv.get<boolean>("_emdash:enabled");

範例：完整的管理 UI

import { definePlugin } from "emdash";

export default definePlugin({
	id: "analytics",
	version: "1.0.0",

	capabilities: ["network:fetch"],
	allowedHosts: ["api.analytics.example.com"],

	storage: {
		events: { indexes: ["type", "createdAt"] },
	},

	admin: {
		entry: "@my-org/plugin-analytics/admin",
		settingsSchema: {
			trackingId: { type: "string", label: "Tracking ID" },
			enabled: { type: "boolean", label: "Enabled", default: true },
		},
		pages: [
			{ path: "/dashboard", label: "Dashboard", icon: "chart" },
			{ path: "/settings", label: "Settings", icon: "settings" },
		],
		widgets: [{ id: "events-today", title: "Events Today", size: "third" }],
	},

	routes: {
		stats: {
			handler: async (ctx) => {
				const today = new Date().toISOString().split("T")[0];
				const count = await ctx.storage.events!.count({
					createdAt: { gte: today },
				});
				return { today: count };
			},
		},
	},
});

import { EventsWidget } from "./components/EventsWidget";
import { DashboardPage } from "./components/DashboardPage";
import { SettingsPage } from "./components/SettingsPage";

export const widgets = {
	"events-today": EventsWidget,
};

export const pages = {
	"/dashboard": DashboardPage,
	"/settings": SettingsPage,
};