@koishi-ce/client 1.0.0

package/app/layout/layout.vue

@@ -0,0 +1,194 @@
+<!--
+  三栏布局组件（页面模板中 <k-layout> 的内置实现）：
+  可选的左右侧栏 + 顶部 header + 主区域。
+  移动端（<=768px）下侧栏转为抽屉式展开，由半透明遮罩（aside-mask）点击收起。
+-->
+<template>
+  <div class="layout-container" :class="[container, styles]">
+    <aside class="layout-aside layout-left" :class="left" v-if="$slots.left">
+      <slot name="left"></slot>
+    </aside>
+
+    <div class="main-container">
+      <div class="aside-mask" @click="isLeftAsideOpen = !isLeftAsideOpen"></div>
+      <layout-header
+        v-model:isLeftAsideOpen="isLeftAsideOpen"
+        v-model:isRightAsideOpen="isRightAsideOpen"
+        :menu-key="typeof menu === 'string' ? menu : null"
+        :menu-data="menuData">
+        <template #left>
+          <slot name="header">{{ route.meta.activity?.name }}</slot>
+        </template>
+        <template #right>
+          <slot name="menu">
+            <!-- menu 为字符串时，渲染 ctx.internal.menus 中注册的同名菜单 -->
+            <template v-if="typeof menu === 'string'">
+              <template v-for="item in ctx.internal.menus[menu]" :key="menu">
+                <!-- 以 "." 开头的是相对菜单 id，需拼上所属菜单前缀再查 action -->
+                <layout-menu-item
+                  v-if="item.id !== '@separator'"
+                  :item="{ ...item, ...ctx.internal.actions[item.id.startsWith('.') ? menu + item.id : item.id] }"
+                  :menu-key="menu" :menu-data="menuData"
+                />
+              </template>
+            </template>
+            <template v-else>
+              <layout-menu-item v-for="item in menu" :item="item" />
+            </template>
+          </slot>
+        </template>
+      </layout-header>
+      <main class="layout-main" :class="main">
+        <slot></slot>
+      </main>
+    </div>
+
+    <aside class="layout-aside layout-right" :class="right" v-if="$slots.right">
+      <slot name="right"></slot>
+    </aside>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { type LegacyMenuItem, useContext } from "@koishi-ce/client";
+import { computed, ref, useSlots } from "vue";
+import { useRoute } from "vue-router";
+import LayoutHeader from "./header.vue";
+import LayoutMenuItem from "./menu-item.vue";
+
+// 各 class prop 用于向对应区域追加自定义类名；menu 传数组时作为
+// 菜单项列表直接渲染，menuData 则作为菜单触发时的附加数据传入
+defineProps<{
+	main?: string;
+	left?: string;
+	right?: string;
+	container?: string;
+	menu?: string | LegacyMenuItem[];
+	menuData?: unknown;
+}>();
+
+const slots = useSlots();
+const route = useRoute();
+const ctx = useContext();
+
+// 移动端左右侧栏（抽屉）的展开状态
+const isLeftAsideOpen = ref(false);
+const isRightAsideOpen = ref(false);
+
+// 布局类名：左右插槽是否存在决定骨架形态，开合状态配合移动端抽屉样式
+const styles = computed(() => ({
+	"has-left-aside": slots.left,
+	"has-right-aside": slots.right,
+	"is-left-aside-open": isLeftAsideOpen.value,
+	"is-right-aside-open": isRightAsideOpen.value,
+}));
+</script>
+
+<style lang="scss">
+
+.layout-container {
+  position: fixed;
+  box-sizing: border-box;
+  z-index: 100;
+  top: 0;
+  left: var(--activity-width);
+  bottom: var(--footer-height);
+  right: 0;
+  background-color: var(--k-card-bg);
+  transition: var(--color-transition);
+  display: flex;
+  flex-direction: row;
+
+  .layout-aside {
+    top: 0;
+    bottom: 0;
+    flex: 0 0 auto;
+    position: relative;
+    width: var(--aside-width);
+    transition: var(--color-transition);
+    background-color: var(--k-side-bg);
+    box-sizing: border-box;
+  }
+
+  .layout-right {
+    border-left: var(--k-color-divider-dark) 1px solid;
+  }
+
+  .layout-left {
+    border-right: var(--k-color-divider-dark) 1px solid;
+  }
+
+  .main-container {
+    position: relative;
+    flex: 1;
+    transition: left 0.3s ease;
+    background-color: var(--k-main-bg);
+    min-height: 100%;
+    display: flex;
+    flex-flow: column;
+    overflow: hidden;
+
+    &.darker {
+      background-color: var(--k-side-bg);
+    }
+
+    .layout-main {
+      flex: 1 1 auto;
+      overflow: hidden;
+      position: relative;
+    }
+
+    .aside-mask {
+      pointer-events: none;
+      position: absolute;
+      top: 0;
+      left: 0;
+      right: 0;
+      bottom: 0;
+      background-color: #000;
+      opacity: 0;
+      z-index: 300;
+      transition: opacity 0.3s ease;
+    }
+  }
+}
+
+@media screen and (max-width: 768px) {
+  .layout-container {
+    .layout-left {
+      position: fixed;
+      top: 0;
+      left: var(--activity-width);
+      bottom: 0;
+    }
+
+    .main-container {
+      position: fixed;
+      left: 0;
+      top: 0;
+      width: 100vw;
+      bottom: 0;
+    }
+
+    &.is-left-aside-open {
+      &.has-left-aside {
+        .main-container {
+          left: calc(var(--aside-width) + var(--activity-width));
+        }
+      }
+
+      &:not(.has-left-aside) {
+        .main-container {
+          left: var(--activity-width);
+        }
+      }
+
+      .aside-mask {
+        opacity: 0.25;
+        pointer-events: auto;
+      }
+    }
+  }
+}
+
+</style>

package/app/layout/menu-item.vue

@@ -0,0 +1,60 @@
+<!--
+  顶栏菜单按钮（图标型）：hidden/disabled/label/icon 均支持 getter，
+  点击时以 action scope 为参调用对应 action。
+-->
+<template>
+  <el-tooltip v-if="!hidden" :disabled="disabled" :content="toValue(item.label)" placement="bottom">
+    <span class="menu-item" :class="[toValue(item.type), { disabled }]" @click="trigger">
+      <k-icon class="menu-icon" :name="toValue(item.icon)"></k-icon>
+    </span>
+  </el-tooltip>
+</template>
+
+<script lang="ts" setup>
+import {
+	type LegacyMenuItem,
+	type MaybeGetter,
+	useContext,
+} from "@koishi-ce/client";
+import { computed } from "vue";
+
+const props = defineProps<{
+	item: LegacyMenuItem;
+	menuKey?: string;
+	menuData?: unknown;
+}>();
+
+const ctx = useContext();
+
+// 未声明 hidden 时直接可见；声明为 getter 的按求值结果判断
+const hidden = computed(() => {
+	if (!props.item.hidden) return false;
+	return toValue(props.item.hidden);
+});
+
+// 没有对应 action 的按钮视为禁用（仅作展示）
+const disabled = computed(() => {
+	if (!props.item.action) return true;
+	if (!props.item.disabled) return false;
+	return toValue(props.item.disabled);
+});
+
+// action scope：以所属菜单 id -> menuData 的映射作为求值上下文
+const scope = computed(() =>
+	ctx.$action.createScope({
+		[props.menuKey]: props.menuData,
+	}),
+);
+
+// label / icon 等字段可能是静态值或以 scope 为参的 getter，这里统一解包
+function toValue<T>(getter: MaybeGetter<T>): T {
+	if (typeof getter !== "function") return getter;
+	// 收窄到 MaybeGetter 的函数分支（以作用域为参的 getter）
+	return (getter as (current: typeof scope.value) => T)(scope.value);
+}
+
+function trigger() {
+	// disabled 计算属性已保证无 action 的按钮不可点击，这里做空值防护
+	return props.item.action?.(scope.value);
+}
+</script>

package/app/settings/index.ts

@@ -0,0 +1,39 @@
+/**
+ * 设置插件：
+ * - 注册用户设置页（/settings/:name*，活动栏底部）；
+ * - 注册 role 为 "theme" 的字符串 schema 渲染组件（主题选择器）；
+ * - 声明 "status"（状态栏设置）设置分组，供其它扩展挂载配置项。
+ */
+
+import type { Context } from "@koishi-ce/client";
+import Settings from "./settings.vue";
+import Theme from "./theme.vue";
+
+export default function (ctx: Context) {
+	ctx.page({
+		path: "/settings/:name*",
+		name: "用户设置",
+		icon: "activity:settings",
+		position: "bottom",
+		order: -100,
+		component: Settings,
+	});
+
+	ctx.schema({
+		type: "string",
+		role: "theme",
+		component: Theme,
+	});
+
+	ctx.settings({
+		id: "status",
+		title: "状态栏设置",
+		order: 800,
+	});
+
+	// ctx.settings({
+	//   id: 'activity',
+	//   title: '活动栏设置',
+	//   order: 800,
+	// })
+}

package/app/settings/settings.vue

@@ -0,0 +1,82 @@
+<!--
+  用户设置页：左侧 el-tree 分组导航 + 右侧当前分组的内容。
+  分组内的条目三种形态二选一渲染：组件型（component）、表单型（schema），
+  disabled 的条目直接跳过。
+-->
+<template>
+  <k-layout main="page-settings">
+    <template #header>
+      {{ ctx.internal.settings[path][0]?.title }}
+    </template>
+
+    <template #left>
+      <el-scrollbar>
+        <el-tree
+          ref="tree"
+          :data="data"
+          :default-expand-all="true"
+          @node-click="handleClick"
+        ></el-tree>
+      </el-scrollbar>
+    </template>
+
+    <keep-alive>
+      <k-content :key="path">
+        <template v-for="item of ctx.internal.settings[path]">
+          <template v-if="item.disabled?.()"></template>
+          <component v-else-if="item.component" :is="item.component" />
+          <k-form v-else-if="item.schema" :schema="item.schema" v-model="config" :initial="config" />
+        </template>
+      </k-content>
+    </keep-alive>
+  </k-layout>
+</template>
+
+<script lang="ts" setup>
+import { useConfig, useContext } from "@koishi-ce/client";
+import { computed } from "vue";
+import { useRoute, useRouter } from "vue-router";
+
+const route = useRoute();
+const router = useRouter();
+
+// 全局控制台配置（双向可写），表单型条目直接绑定到此对象
+const config = useConfig(true);
+const ctx = useContext();
+
+// el-tree 的数据源：由 internal.settings 中各分组的首个条目标题生成
+interface Tree {
+	id: string;
+	label: string;
+	children?: Tree[];
+}
+
+const data = computed(() =>
+	Object.entries(ctx.internal.settings).map<Tree>(([id, [{ title }]]) => ({
+		id,
+		label: title,
+	})),
+);
+
+function handleClick(tree: Tree) {
+	// 仅叶子节点（无 children）可切换分组
+	if (tree.children) return;
+	path.value = tree.id;
+}
+
+// 当前分组与路由参数双向同步；无效分组名回退为空串
+const path = computed({
+	get() {
+		const name = route.params.name?.toString();
+		return name in ctx.internal.settings ? name : "";
+	},
+	set(value) {
+		if (!(value in ctx.internal.settings)) value = "";
+		void router.replace(`/settings/${value}`);
+	},
+});
+</script>
+
+<style lang="scss">
+
+</style>

package/app/settings/theme.vue

@@ -0,0 +1,123 @@
+<!--
+  主题选择器：role 为 "theme" 的字符串 schema 的专用渲染组件。
+  下拉选项按明 / 暗模式过滤（主题 id 以 -light / -dark 结尾），
+  每个选项以三色块 + 标题的形式预览主题配色。
+-->
+<template>
+  <schema-base>
+    <template #title><slot name="title"></slot></template>
+    <template #desc><slot name="desc"></slot></template>
+    <template #menu><slot name="menu"></slot></template>
+    <template #prefix><slot name="prefix"></slot></template>
+    <template #suffix><slot name="suffix"></slot></template>
+    <template #control>
+      <el-select popper-class="theme-select" v-model="model">
+        <template v-for="(_, key) in ctx.internal.themes" :key="key">
+          <el-option :value="key" v-if="key.endsWith('-' + schema.meta.extra.mode)">
+            <div class="theme-root" :class="key.endsWith('-dark') ? 'dark' : 'light'" :theme="key">
+              <div class="theme-block-1"></div>
+              <div class="theme-block-2"></div>
+              <div class="theme-block-3"></div>
+              <div class="theme-title">
+                {{ tt(ctx.internal.themes[key].name) }}
+              </div>
+            </div>
+          </el-option>
+        </template>
+      </el-select>
+    </template>
+  </schema-base>
+</template>
+
+<script setup lang="ts">
+import { useContext, useI18nText } from "@koishi-ce/client";
+import { type Schema, SchemaBase } from "@koishi-ce/components";
+import { computed, type PropType } from "vue";
+
+defineProps({
+	schema: {} as PropType<Schema>,
+	modelValue: {} as PropType<unknown[]>,
+	disabled: {} as PropType<boolean>,
+	prefix: {} as PropType<string>,
+	initial: {} as PropType<Record<never, never>>,
+});
+
+const emit = defineEmits(["update:modelValue"]);
+
+const ctx = useContext();
+
+const tt = useI18nText();
+
+const config = SchemaBase.useModel();
+
+// el-select 的双向绑定：get 返回当前主题的显示名（供下拉框回显），
+// set 把选中的主题 id（即 el-option 的 value）透传给父级表单
+const model = computed({
+	get() {
+		return tt(ctx.internal.themes[config.value]?.name);
+	},
+	set(value) {
+		emit("update:modelValue", value);
+	},
+});
+</script>
+
+<style lang="scss">
+
+.el-select-dropdown.theme-select {
+  overflow: hidden;
+
+  .el-select-dropdown__list {
+    margin: 0 !important;
+  }
+
+  .el-select-dropdown__item {
+    padding: 0;
+  }
+
+  .theme-root {
+    width: 100%;
+    height: 100%;
+    position: relative;
+
+    .theme-block-1 {
+      position: absolute;
+      width: 33%;
+      height: 100%;
+      background-color: var(--bg1);
+    }
+
+    .theme-block-2 {
+      position: absolute;
+      left: 33%;
+      width: 34%;
+      height: 100%;
+      background-color: var(--bg2);
+    }
+
+    .theme-block-3 {
+      position: absolute;
+      left: 67%;
+      width: 33%;
+      height: 100%;
+      background-color: var(--bg3);
+    }
+
+    .theme-title {
+      position: absolute;
+      left: 0;
+      width: 100%;
+      height: 100%;
+      display: flex;
+      flex-direction: row;
+      align-items: center;
+      justify-content: center;
+      font-size: 1em;
+      z-index: 100;
+      font-family: var(--font-family);
+      color: var(--k-color-primary);
+    }
+  }
+}
+
+</style>

package/app/shims.d.ts

@@ -0,0 +1 @@
+/// <reference path="../client/shims.d.ts" />

package/app/status/index.ts

@@ -0,0 +1,21 @@
+/**
+ * 状态栏插件：向全局 "status" 插槽注册状态栏主体（可悬停出 tooltip 的
+ * 状态项容器），并向 "status-right" 插槽注册页面组件加载进度条。
+ */
+
+import type { Context } from "@koishi-ce/client";
+import Loading from "./loading.vue";
+import Status from "./status.vue";
+
+export default function (ctx: Context) {
+	ctx.slot({
+		type: "status",
+		component: Status,
+		order: -1000,
+	});
+
+	ctx.slot({
+		type: "status-right",
+		component: Loading,
+	});
+}

package/app/status/loading.vue

@@ -0,0 +1,23 @@
+<!--
+  页面组件按需加载进度条：按当前路由所需扩展（ctx.$loader.extensions）
+  的完成比例显示进度；store.entry 尚未就绪时以不确定进度（indeterminate）展示。
+-->
+<template>
+  <k-status v-if="progress < 1">
+    <el-progress :indeterminate="!store.entry" :percentage="progress * 100">
+      正在加载页面组件
+    </el-progress>
+  </k-status>
+</template>
+
+<script lang="ts" setup>
+import { store, useContext } from "@koishi-ce/client";
+import { computed } from "vue";
+
+const ctx = useContext();
+
+const progress = computed(() => {
+	const states = Object.values(ctx.$loader.extensions);
+	return states.filter((state) => state.done.value).length / states.length;
+});
+</script>

package/app/status/status.vue

@@ -0,0 +1,56 @@
+<!--
+  通用状态项容器（页面模板中 <k-status> 的内置实现）：
+  内容区 + 悬停时的 tooltip（内容经 el-scrollbar 限高滚动）。
+  inheritAttrs 关闭，让外部透传的属性落到内层 div 而非根组件。
+-->
+<template>
+  <el-tooltip placement="top" effect="light" popper-class="k-status-tooltip">
+    <template #content>
+      <el-scrollbar max-height="calc(100vh - 4rem)">
+        <slot name="tooltip">
+          <span class="el-popper__empty"></span>
+        </slot>
+      </el-scrollbar>
+    </template>
+    <div class="k-status" v-bind="$attrs">
+      <slot></slot>
+    </div>
+  </el-tooltip>
+</template>
+
+<script lang="ts" setup>
+defineOptions({
+	inheritAttrs: false,
+});
+</script>
+
+<style lang="scss" scoped>
+
+.k-status {
+  cursor: default;
+  padding: 0 0.5rem;
+  display: inline-flex;
+  align-items: center;
+  transition: var(--color-transition);
+  user-select: none;
+  cursor: pointer;
+
+  &:hover {
+    background-color: var(--k-hover-bg);
+  }
+}
+
+</style>
+
+<style lang="scss">
+
+.el-popper.k-status-tooltip {
+  padding: 0 0;
+  border-radius: 8px;
+
+  .el-popper__empty + .el-popper__arrow {
+    display: none;
+  }
+}
+
+</style>