@koishi-ce/client 1.0.0

package/app/theme/activity/index.vue

@@ -0,0 +1,119 @@
+<!--
+  活动栏（最左侧图标栏）：分 top / bottom 两区渲染活动项，
+  项与项之间的分隔槽（activity-separator）同时充当拖拽排序的落点。
+  空间不足时放不下的活动项折叠进 "..." 溢出组；
+  整条栏支持右键菜单（theme.activity，如"重置活动栏"）。
+-->
+<template>
+  <nav
+    class="layout-activity flex flex-col justify-evenly"
+    @contextmenu.stop="trigger($event, null)">
+    <template v-for="(data, index) in groups.top" :key="data[0].id">
+      <activity-separator position="top" :index="index" />
+      <activity-item placement="right" :children="data"></activity-item>
+    </template>
+    <activity-separator position="top" :index="groups.top.length" />
+    <activity-item v-if="groups.hidden" placement="bottom" :children="groups.hidden"></activity-item>
+    <div v-else class="spacer"></div>
+    <activity-separator position="bottom" :index="groups.top.length" />
+    <template v-for="(data, index) in groups.bottom" :key="data.id">
+      <activity-item placement="right" :children="data"></activity-item>
+      <activity-separator position="bottom" :index="index" />
+    </template>
+  </nav>
+</template>
+
+<script lang="ts" setup>
+import {
+	type Activity,
+	useConfig,
+	useContext,
+	useMenu,
+} from "@koishi-ce/client";
+import { useWindowSize } from "@vueuse/core";
+import { computed, provide } from "vue";
+import ActivityItem from "./item.vue";
+import ActivitySeparator from "./separator.vue";
+
+const ctx = useContext();
+const config = useConfig();
+const trigger = useMenu("theme.activity");
+const { height, width } = useWindowSize();
+
+// 计算最终的活动栏分组：{ top, bottom, hidden（溢出折叠组，可能为空） }
+const groups = computed(() => {
+	let hidden: Activity[];
+	// 单个活动项占位（与 CSS 中 --activity-width / --activity-padding 对应）
+	const unit = width.value <= 768 ? 52 : 56;
+	// 可用总高度：视口高度减去上下留白（窄屏 4px / 宽屏 8px）
+	const total = height.value - (width.value <= 768 ? 4 : 8);
+	// 初始分组表：每个未禁用页面各自成一组（值为 Activity 数组）
+	const available = Object.fromEntries(
+		Object.entries(ctx.$router.pages)
+			.filter(([, data]) => !data.disabled())
+			.map(([key, data]) => [key, [data]]),
+	);
+	// 应用用户的覆盖配置：hidden 的直接移除；声明 parent 的并入父项所在组
+	for (const id of Object.keys(available)) {
+		const override = config.value.activities?.[id];
+		if (!override) continue;
+		if (override.hidden) {
+			delete available[id];
+			continue;
+		}
+		Object.assign(available[id][0], override);
+		const parent = available[override.parent];
+		if (parent) {
+			parent.push(available[id][0]);
+			delete available[id];
+		}
+	}
+	const list = Object.values(available).sort(([a], [b]) => a.order - b.order);
+	// 放不下时：从头部取出溢出项折叠成一个组，top 位优先、同位再按 order 排，
+	// 并以 "..." 图标作为该组的展示入口
+	if (list.length * unit > total) {
+		hidden = list
+			.splice(0, list.length + 1 - Math.floor(total / unit))
+			.sort(([a], [b]) => {
+				const scale = a.position === "top" ? -1 : 1;
+				if (a.position === b.position) {
+					return scale * (a.order - b.order);
+				}
+				return scale;
+			})
+			.flat();
+		hidden.unshift({ icon: "activity:ellipsis" } as Activity);
+	}
+	// top 区按 order 逆序输出（order 大者靠上），bottom 区保持正序
+	const top = list.filter(([data]) => data.position !== "bottom").reverse();
+	const bottom = list.filter(([data]) => data.position === "bottom");
+	return { top, bottom, hidden };
+});
+
+// 供 separator 子组件注入，用于拖拽落点计算
+provide("groups", groups);
+</script>
+
+<style lang="scss" scoped>
+
+.marker {
+  position: absolute;
+}
+
+.layout-activity {
+  position: fixed;
+  box-sizing: border-box;
+  z-index: 100;
+  top: 0;
+  bottom: 0;
+  width: var(--activity-width);
+  background-color: var(--k-activity-bg);
+  border-right: var(--k-activity-divider, var(--k-color-divider-dark)) 1px solid;
+  transition: var(--color-transition);
+
+  .spacer {
+    flex: 1 0 auto;
+  }
+}
+
+</style>

package/app/theme/activity/item.vue

@@ -0,0 +1,185 @@
+<!--
+  活动栏条目：children[0] 为组的主图标，其余为并入该组的子活动，
+  悬停 tooltip 中列出组内成员。条目本身也是拖拽落点——
+  把另一个活动拖到本条目上即并入（或互换）分组。
+-->
+<template>
+  <div
+    class="activity-item"
+    :class="{ 'active': isActive, 'drag-over': hasDragOver }"
+    @contextmenu.stop="trigger($event, children[0])"
+    @dragenter="handleDragEnter"
+    @dragleave="handleDragLeave"
+    @drop="handleDrop"
+    @dragover.prevent>
+    <el-tooltip placement="right" :popper-class="`activity-item-tooltip`">
+      <template #content>
+        <div class="activity-info">
+          <div class="title">{{ children[hoverIndex].name }}</div>
+          <div class="desc" v-if="children[hoverIndex].desc">{{ children[hoverIndex].desc }}</div>
+        </div>
+        <div class="activity-group" v-if="children.length > 1">
+          <div class="activity-group-item" v-for="(child, index) in children.slice(1)" :key="child.id">
+            <activity-button
+              :data="child"
+              @mouseenter="hoverIndex = index + 1"
+              @mouseleave="hoverIndex = 0"
+            ></activity-button>
+          </div>
+        </div>
+      </template>
+      <activity-button :data="children[0]" :class="{ 'is-group': children.length > 1 }"></activity-button>
+    </el-tooltip>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { type Activity, useConfig, useMenu } from "@koishi-ce/client";
+import type { Placement } from "element-plus";
+import { computed, ref, watch } from "vue";
+import { useRoute } from "vue-router";
+import ActivityButton from "./button.vue";
+
+const route = useRoute();
+
+const props = defineProps<{
+	children: Activity[];
+	placement: Placement;
+}>();
+
+const isActive = computed(() => {
+	// 组内任一成员命中当前路由即整组高亮
+	return Object.values(props.children).some(
+		(child) => route.meta?.activity?.id === child.id,
+	);
+});
+
+const hasDragOver = ref(false);
+
+const trigger = useMenu("theme.activity");
+
+// tooltip 中当前悬停的成员下标（0 为主图标，其余对应组内子活动）
+const hoverIndex = ref(0);
+
+watch(
+	() => props.children,
+	() => {
+		hoverIndex.value = 0;
+	},
+);
+
+function handleDragEnter(event: DragEvent) {
+	hasDragOver.value = true;
+}
+
+function handleDragLeave(event: DragEvent) {
+	hasDragOver.value = false;
+}
+
+const config = useConfig();
+
+// 原型链保留键：这类键在普通对象上会触发原型链存取器，禁止作为配置键读写
+// （id 来自拖拽事件的 dataTransfer 文本，属外部输入）
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/** 取某活动的覆盖配置（不存在则创建）；保留键返回一次性空对象，防原型污染。
+ * 守卫须用显式字符串比较（Set.has 形式 CodeQL 无法识别为阻断） */
+function ensureOverride(id: string): Record<string, unknown> {
+	const activities = (config.value.activities ??= {});
+	if (id === "__proto__" || id === "constructor" || id === "prototype") {
+		return {};
+	}
+	return (activities[id] ??= {});
+}
+
+function handleDrop(event: DragEvent) {
+	hasDragOver.value = false;
+	const text = event.dataTransfer.getData("text/plain");
+	// 只响应活动栏自身的拖拽协议，忽略外部拖入内容
+	if (!text.startsWith("activity:")) return;
+	const id = text.slice(9);
+	const target = props.children[0].id;
+	// 拖到自身所在组上无需处理
+	if (target === id) return;
+	event.preventDefault();
+
+	const override = ensureOverride(id);
+	if (override.parent === target) {
+		// 原本 id 已是 target 的子项：视为"拖出"，反转父子关系，
+		// 并让原父项（及其它子项）改挂到新的父项 id 之下
+		delete override.parent;
+		ensureOverride(target).parent = id;
+		for (const key in config.value.activities) {
+			// 跳过原型链保留键：JSON 配置可携带自有 "__proto__" 属性，
+			// 普通对象对其 [] 读取会命中原型链存取器
+			if (UNSAFE_KEYS.has(key)) continue;
+			const override = config.value.activities[key];
+			if (override?.parent === target) {
+				override.parent = id;
+			}
+		}
+	} else {
+		// 常规情形：把拖入项并到 target 组
+		override.parent = target;
+	}
+}
+</script>
+
+<style lang="scss">
+
+.activity-item {
+  position: relative;
+  box-sizing: border-box;
+  width: var(--activity-width);
+  padding: 0 var(--activity-padding);
+
+  .layout-activity &::before {
+    content: '';
+    position: absolute;
+    top: 50%;
+    left: 0;
+    width: var(--activity-marker-width);
+    height: var(--activity-marker-height);
+    transform: translateX(-100%) translateY(-50%);
+    display: block;
+    border-radius: 0 var(--activity-marker-width) var(--activity-marker-width) 0;
+    background-color: var(--k-text-active);
+    transition: all 0.3s ease;
+  }
+
+  .layout-activity &.active::before,
+  .layout-activity &.drag-over::before {
+    transform: translateY(-50%);
+  }
+}
+
+.activity-item-tooltip {
+  padding: 0;
+
+  .activity-info {
+    padding: 6px 11px;
+    line-height: 1.6;
+
+    .title {
+      font-size: 13px;
+      font-weight: 500;
+    }
+
+    .desc {
+      font-size: 12px;
+    }
+  }
+
+  .activity-group {
+    display: flex;
+    padding: var(--activity-padding);
+    gap: 0 var(--activity-padding);
+    border-top: 1px solid var(--k-color-divider);
+
+    .activity-group-item {
+      width: calc(var(--activity-width) - 2 * var(--activity-padding));
+    }
+  }
+}
+
+</style>

package/app/theme/activity/separator.vue

@@ -0,0 +1,163 @@
+<!--
+  活动栏条目间的分隔槽：平时不可见，拖拽悬停时显示横线提示，
+  松手即把被拖项移动到该位置（拖拽排序的核心落点组件）。
+-->
+<template>
+  <div
+    class="separator"
+    :class="{ 'drag-over': hasDragOver }"
+    @dragenter="handleDragEnter"
+    @dragleave="handleDragLeave"
+    @drop="handleDrop"
+    @dragover.prevent
+  ></div>
+</template>
+
+<script lang="ts" setup>
+import { type Activity, useConfig, useContext } from "@koishi-ce/client";
+import { type ComputedRef, inject, ref } from "vue";
+
+type Position = "top" | "bottom";
+
+const props = defineProps<{
+	index: number;
+	position: Position;
+}>();
+
+const groups = inject("groups") as ComputedRef<Record<Position, Activity[][]>>;
+
+const hasDragOver = ref(false);
+
+function handleDragEnter(event: DragEvent) {
+	hasDragOver.value = true;
+}
+
+function handleDragLeave(event: DragEvent) {
+	hasDragOver.value = false;
+}
+
+const config = useConfig();
+const ctx = useContext();
+
+// 原型链保留键：这类键在普通对象上会触发原型链存取器，禁止作为配置键读写
+// （id 来自拖拽事件的 dataTransfer 文本，属外部输入）
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/** 取某活动的覆盖配置（不存在则创建）；保留键返回一次性空对象，防原型污染。
+ * 守卫须用显式字符串比较（Set.has 形式 CodeQL 无法识别为阻断） */
+function ensureOverride(id: string): Record<string, unknown> {
+	const activities = (config.value.activities ??= {});
+	if (id === "__proto__" || id === "constructor" || id === "prototype") {
+		return {};
+	}
+	return (activities[id] ??= {});
+}
+
+function handleDrop(event: DragEvent) {
+	hasDragOver.value = false;
+	const text = event.dataTransfer.getData("text/plain");
+	// 只响应活动栏自身的拖拽协议
+	if (!text.startsWith("activity:")) return;
+	const id = text.slice(9);
+	const list = groups.value[props.position].map(([item]) => item);
+	const oldIndex = list.findIndex((item) => item.id === id);
+	// 落点即原位（含紧邻原位的前一格）时无需移动
+	if (
+		oldIndex === props.index ||
+		(oldIndex === props.index - 1 && oldIndex !== -1)
+	)
+		return;
+	event.preventDefault();
+
+	// 先在副本上完成移动，得到目标排列，再据此反推各项的 order 覆盖值
+	let index = props.index;
+	const item = ctx.$router.pages[id];
+	if (oldIndex < 0) {
+		list.splice(index, 0, item);
+	} else {
+		// 原位置在落点之前时，移除自身会使落点前移一格，需补偿
+		if (oldIndex < index) index--;
+		list.splice(oldIndex, 1);
+		list.splice(index, 0, item);
+	}
+
+	const override = ensureOverride(id);
+	// 拖拽落在条目之间意味着脱离原分组，清除父项；
+	// 位置（top / bottom）与注册默认不同才记录覆盖，相同则删掉以保持配置干净
+	delete override.parent;
+	if (item.options.position !== props.position) {
+		override.position = props.position;
+	} else {
+		delete override.position;
+	}
+
+	// 左右最近的"未改序"条目（order 仍等于注册默认值）作为锚点，
+	// 介于两锚点之间的项按线性插值重算 order；
+	// 只有一侧锚点时按步长 100 单向递增 / 递减；两侧都没有则恢复默认
+	const anchorL = list.findLastIndex(
+		(item, i) => i < index && item.order === item.options.order,
+	);
+	const anchorR = list.findIndex(
+		(item, i) => i > index && item.order === item.options.order,
+	);
+	if (anchorL === -1) {
+		if (anchorR === -1) {
+			delete override.order;
+		} else {
+			let order = list[anchorR].options.order;
+			for (let index = anchorR - 1; index >= 0; index--) {
+				const override = ensureOverride(list[index].id);
+				override.order = order += 100;
+			}
+		}
+	} else {
+		if (anchorR === -1) {
+			let order = list[anchorL].options.order;
+			for (let index = anchorL + 1; index < list.length; index++) {
+				const override = ensureOverride(list[index].id);
+				override.order = order -= 100;
+			}
+		} else {
+			let orderL = list[anchorL].options.order;
+			let orderR = list[anchorR].options.order;
+			for (let index = anchorL + 1; index < anchorR; index++) {
+				const override = ensureOverride(list[index].id);
+				override.order =
+					orderL +
+					((orderR - orderL) * (index - anchorL)) / (anchorR - anchorL);
+			}
+		}
+	}
+
+	// 覆盖配置为空对象时删除该键，避免残留无意义的配置项
+	if (!Object.keys(override).length && !UNSAFE_KEYS.has(id)) {
+		delete config.value.activities[id];
+	}
+}
+</script>
+
+<style lang="scss" scoped>
+
+.separator {
+  position: relative;
+  height: var(--activity-padding);
+
+  &::before {
+    position: absolute;
+    content: '';
+    top: 50%;
+    left: var(--activity-padding);
+    right: var(--activity-padding);
+    height: 2px;
+    border-radius: 2px;
+    transform: translateY(-50%);
+    transition: var(--color-transition);
+    background-color: transparent;
+  }
+
+  &.drag-over::before {
+    background-color: var(--k-text-active);
+  }
+}
+
+</style>

package/app/theme/activity/utils.ts

@@ -0,0 +1,27 @@
+/**
+ * 活动栏（activity bar）相关的类型扩充：
+ * - 为 ActionContext 补充 "theme.activity" 菜单的求值上下文类型；
+ * - 为控制台 Config 声明 activities 覆盖配置（隐藏 / 归组 / 排序 / 上下位置）。
+ */
+
+import type { Activity, Dict } from "@koishi-ce/client";
+
+declare module "@koishi-ce/client" {
+	interface ActionContext {
+		"theme.activity": Activity;
+	}
+
+	interface Config {
+		// 运行时的默认配置(initial fallback)并不包含该字段,
+		// 故声明为可选(exactOptionalPropertyTypes 下不显式赋 undefined)
+		activities?: Dict<ActivityOverride>;
+	}
+}
+
+// 单个活动项的覆盖配置：不声明的字段沿用页面注册时的默认值
+interface ActivityOverride {
+	hidden?: boolean;
+	parent?: string;
+	order?: number;
+	position?: "top" | "bottom";
+}

package/app/theme/blank.vue

@@ -0,0 +1,24 @@
+<!-- 404 空白页：控制台本体加载成功但没有任何扩展页面时的兜底展示 -->
+<template>
+  <div class="blank">
+    <h1>404</h1>
+    <p>如果你看到了这个页面，说明控制台插件已经加载成功，但你尚未安装任何控制台扩展。</p>
+  </div>
+</template>
+
+<style lang="scss" scoped>
+
+.blank {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 0 2rem;
+}
+
+</style>

package/app/theme/index.ts

@@ -0,0 +1,37 @@
+/**
+ * 主题插件（控制台外壳）：
+ * - 向 "root" 插槽注册应用根组件（活动栏 + 路由视图 + 状态栏 + 全局菜单层）；
+ * - 注册活动栏右键菜单 "theme.activity" 及其动作（重置活动栏自定义配置）。
+ */
+
+import { type Context, router, useConfig } from "@koishi-ce/client";
+import App from "./index.vue";
+
+export default function (ctx: Context) {
+	ctx.slot({
+		type: "root",
+		component: App,
+		order: -1000,
+	});
+
+	const config = useConfig();
+
+	ctx.action("theme.activity.settings", {
+		action: () => router.push("/settings/activity"),
+	});
+
+	ctx.action("theme.activity.reset", {
+		// 清空 activities 覆盖配置，活动栏恢复默认排序与分组
+		action: () => (config.value.activities = {}),
+	});
+
+	ctx.menu("theme.activity", [
+		{
+			//   id: '.settings',
+			//   label: '活动栏设置',
+			// }, {
+			id: ".reset",
+			label: "重置活动栏",
+		},
+	]);
+}

package/app/theme/index.vue

@@ -0,0 +1,34 @@
+<!--
+  控制台根组件：活动栏 + 路由页面（keep-alive 缓存） + 状态栏 + 全局菜单层。
+  路由声明了所需 store 字段（route.meta.activity.fields）时，
+  等全部字段就绪才渲染页面，期间显示全屏 loading。
+-->
+<template>
+  <activity-bar></activity-bar>
+  <router-view v-if="loaded" #="{ Component }">
+    <keep-alive>
+      <component :is="Component"></component>
+    </keep-alive>
+  </router-view>
+  <div class="loading" v-else v-loading="true" element-loading-text="正在加载数据……"></div>
+  <status-bar></status-bar>
+  <menu-list></menu-list>
+</template>
+
+<script lang="ts" setup>
+import { store } from "@koishi-ce/client";
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+import ActivityBar from "./activity/index.vue";
+import MenuList from "./menu/index.vue";
+import StatusBar from "./status.vue";
+
+const route = useRoute();
+
+// 页面就绪判定：未声明所需字段的页面恒为已就绪；
+// 否则要求 meta.activity.fields 中每个 store 字段都有数据
+const loaded = computed(() => {
+	if (!route.meta.activity?.fields) return true;
+	return route.meta.activity.fields.every((key) => store[key]);
+});
+</script>

package/app/theme/menu/index.vue

@@ -0,0 +1,26 @@
+<!--
+  全局菜单层：渲染当前处于活动状态的所有上下文菜单（activeMenus）。
+  任意 click / contextmenu 事件都视为点击了菜单外区域，关闭全部活动菜单。
+-->
+<template>
+  <template v-for="menu of ctx.internal.activeMenus" :key="menu.id">
+    <k-menu v-bind="menu"></k-menu>
+  </template>
+</template>
+
+<script lang="ts" setup>
+import { useContext } from "@koishi-ce/client";
+import { useEventListener } from "@vueuse/core";
+import KMenu from "./menu.vue";
+
+const ctx = useContext();
+
+// useEventListener 会随组件卸载自动解绑，无需手动清理
+useEventListener("click", () => {
+	ctx.internal.activeMenus.splice(0);
+});
+
+useEventListener("contextmenu", () => {
+	ctx.internal.activeMenus.splice(0);
+});
+</script>

package/app/theme/menu/menu-item.vue

@@ -0,0 +1,58 @@
+<!--
+  上下文菜单的单个菜单项：点击时调用对应 action。
+  id 支持两种特殊写法："!" 前缀会被去除（兼容旧的否定式 id），
+  "." 开头则是相对 id，需拼上所属菜单前缀（props.prefix）再查找 action。
+  label / icon / hidden / disabled 同样支持以 scope 为参的 getter。
+-->
+<template>
+  <div
+    class="k-menu-item"
+    v-if="!hidden"
+    :class="[toValue(type), { disabled }]"
+    @click.prevent="item?.action(ctx.$action.createScope())"
+  >
+    <span v-if="icon" class="k-menu-icon"><k-icon :name="icon"/></span>
+    {{ toValue(label) }}
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { type MaybeGetter, type MenuItem, useContext } from "@koishi-ce/client";
+import { computed } from "vue";
+
+const props = defineProps<MenuItem & { prefix: string }>();
+
+const ctx = useContext();
+
+// 解析出实际的 action：去掉 "!" 前缀、拼接相对 id 后查注册表
+const item = computed(() => {
+	let id = props.id.replace(/^!/, "");
+	if (id.startsWith(".")) id = props.prefix + id;
+	return ctx.internal.actions[id];
+});
+
+// action 不存在（未注册）时整项隐藏；声明了 hidden 的按求值结果判断
+const hidden = computed(() => {
+	if (!item.value) return true;
+	if (!item.value.hidden) return false;
+	return toValue(item.value.hidden);
+});
+
+// action 不存在或声明禁用时置灰不可点
+const disabled = computed(() => {
+	if (!item.value) return true;
+	if (!item.value.disabled) return false;
+	return toValue(item.value.disabled);
+});
+
+const icon = computed(() => toValue(props.icon));
+
+// label / icon 等字段可能是静态值或以 action scope 为参的 getter，统一解包
+function toValue<T>(getter: MaybeGetter<T>): T {
+	if (typeof getter !== "function") return getter;
+	// 收窄到 MaybeGetter 的函数分支（以作用域为参的 getter）
+	return (getter as (current: ReturnType<typeof ctx.$action.createScope>) => T)(
+		ctx.$action.createScope(),
+	);
+}
+</script>