({}));
+vi.mock("@/live2d/components/Live2dTools", () => ({}));
+vi.mock("@/live2d/components/Live2dTips", () => ({}));
+
+import "../Live2dWidget";
+
+type ConfiguredElement = HTMLElement & {
+ config?: Live2dConfig;
+ updateComplete: Promise;
+};
+
+describe("Live2D stacking layers", () => {
+ beforeEach(() => {
+ localStorage.clear();
+ vi.stubGlobal("matchMedia", () => ({
+ matches: false,
+ addEventListener: vi.fn(),
+ removeEventListener: vi.fn(),
+ }));
+ });
+
+ afterEach(() => {
+ document.body.replaceChildren();
+ vi.unstubAllGlobals();
+ });
+
+ it.each([undefined, 0, 30])(
+ "keeps the widget, restore control and chat in order for layer %s",
+ async (zIndex) => {
+ const config = { ...createDefaultLive2dConfig(), zIndex };
+ const widget = document.createElement(
+ "live2d-widget",
+ ) as ConfiguredElement;
+ const toggle = document.createElement(
+ "live2d-toggle",
+ ) as ConfiguredElement;
+ const chat = document.createElement(
+ "live2d-chat-window",
+ ) as ConfiguredElement;
+ for (const element of [widget, toggle, chat]) {
+ element.config = config;
+ document.body.append(element);
+ }
+ window.dispatchEvent(new ToggleCanvasEvent({ isShow: true }));
+ await Promise.all([
+ widget.updateComplete,
+ toggle.updateComplete,
+ chat.updateComplete,
+ ]);
+
+ const base = zIndex ?? DEFAULT_LIVE2D_Z_INDEX;
+ expect(
+ widget.shadowRoot?.querySelector("#live2d-plugin")?.style
+ .zIndex,
+ ).toBe(String(base));
+ expect(
+ toggle.shadowRoot?.querySelector("#live2d-toggle")?.style
+ .zIndex,
+ ).toBe(String(base + 1));
+ expect(
+ chat.shadowRoot?.querySelector("#live2d-chat-model")?.style
+ .zIndex,
+ ).toBe(String(base + 2));
+ },
+ );
+});
diff --git a/packages/live2d/src/config/__tests__/z-index.test.ts b/packages/live2d/src/config/__tests__/z-index.test.ts
new file mode 100644
index 0000000..6a4b795
--- /dev/null
+++ b/packages/live2d/src/config/__tests__/z-index.test.ts
@@ -0,0 +1,36 @@
+import { normalizeLive2dConfig } from "@/live2d/config/normalize-config";
+import {
+ DEFAULT_LIVE2D_Z_INDEX,
+ MAX_LIVE2D_Z_INDEX,
+} from "@/live2d/config/z-index";
+import { describe, expect, it } from "vitest";
+
+describe("Live2D stacking configuration", () => {
+ it("preserves the existing layer when an older configuration has no setting", () => {
+ expect(normalizeLive2dConfig("/assets/", {}).zIndex).toBe(
+ DEFAULT_LIVE2D_Z_INDEX,
+ );
+ });
+
+ it.each([0, 10, MAX_LIVE2D_Z_INDEX])(
+ "accepts the configured integer %s, including zero",
+ (zIndex) => {
+ expect(normalizeLive2dConfig("/assets/", { zIndex }).zIndex).toBe(zIndex);
+ },
+ );
+
+ it("accepts a numeric string from the saved Halo JSON", () => {
+ const input = JSON.parse('{"zIndex":"25"}');
+ expect(normalizeLive2dConfig("/assets/", input).zIndex).toBe(25);
+ });
+
+ it.each([null, "", -1, 1.5, "invalid", MAX_LIVE2D_Z_INDEX + 1])(
+ "falls back for an invalid saved value %s",
+ (zIndex) => {
+ const input = JSON.parse(JSON.stringify({ zIndex }));
+ expect(normalizeLive2dConfig("/assets/", input).zIndex).toBe(
+ DEFAULT_LIVE2D_Z_INDEX,
+ );
+ },
+ );
+});
diff --git a/packages/live2d/src/config/default-config.ts b/packages/live2d/src/config/default-config.ts
index c16abf4..0b53a58 100644
--- a/packages/live2d/src/config/default-config.ts
+++ b/packages/live2d/src/config/default-config.ts
@@ -1,3 +1,4 @@
+import { DEFAULT_LIVE2D_Z_INDEX } from "@/live2d/config/z-index";
import type { Live2dConfig } from "@/live2d/context/config-context";
export const DEFAULT_TOOL_NAMES = [
@@ -13,6 +14,7 @@ export const DEFAULT_TOOL_NAMES = [
export const createDefaultLive2dConfig = (): Live2dConfig => ({
apiPath: "https://live2d.fghrsh.net/api/",
live2dLocation: "left",
+ zIndex: DEFAULT_LIVE2D_Z_INDEX,
consoleShowStatus: import.meta.env.DEV ?? false,
isForceUseDefaultConfig: false,
modelId: 1,
diff --git a/packages/live2d/src/config/normalize-config.ts b/packages/live2d/src/config/normalize-config.ts
index 09e5e2b..7375bf6 100644
--- a/packages/live2d/src/config/normalize-config.ts
+++ b/packages/live2d/src/config/normalize-config.ts
@@ -7,6 +7,7 @@ import {
pickNumber,
pickString,
} from "@/live2d/config/normalize-helpers";
+import { normalizeLive2dZIndex } from "@/live2d/config/z-index";
import type { Live2dConfig } from "@/live2d/context/config-context";
import { isNotEmptyString } from "@/live2d/utils/isString";
@@ -94,6 +95,7 @@ export const normalizeLive2dConfig = (
...input,
apiPath: ensureTrailingSlash(normalizedApiPath),
live2dLocation: input.live2dLocation === "right" ? "right" : "left",
+ zIndex: normalizeLive2dZIndex(input.zIndex),
consoleShowStatus: pickBoolean(
input.consoleShowStatus,
input.consoleShowStatu,
diff --git a/packages/live2d/src/config/z-index.ts b/packages/live2d/src/config/z-index.ts
new file mode 100644
index 0000000..00628c8
--- /dev/null
+++ b/packages/live2d/src/config/z-index.ts
@@ -0,0 +1,14 @@
+import { pickNumber } from "@/live2d/config/normalize-helpers";
+
+export const DEFAULT_LIVE2D_Z_INDEX = 9998;
+export const MAX_LIVE2D_Z_INDEX = 2147483645;
+
+export const normalizeLive2dZIndex = (value: unknown): number => {
+ const zIndex = pickNumber(value);
+ return zIndex !== undefined &&
+ Number.isInteger(zIndex) &&
+ zIndex >= 0 &&
+ zIndex <= MAX_LIVE2D_Z_INDEX
+ ? zIndex
+ : DEFAULT_LIVE2D_Z_INDEX;
+};
diff --git a/packages/live2d/src/context/config-context.ts b/packages/live2d/src/context/config-context.ts
index abfcb5c..a764a07 100644
--- a/packages/live2d/src/context/config-context.ts
+++ b/packages/live2d/src/context/config-context.ts
@@ -104,6 +104,8 @@ export interface Live2dConfig extends Live2dToolsConfig {
apiPath: string;
// Live2d 定位
live2dLocation: "left" | "right";
+ // 看板娘和工具栏的显示层级
+ zIndex?: number;
// 是否在控制台显示状态
consoleShowStatus?: boolean;
// 兼容旧版控制台状态字段
diff --git a/src/main/java/run/halo/live2d/Live2dSettingProcess.java b/src/main/java/run/halo/live2d/Live2dSettingProcess.java
index 0d1b0e3..c805710 100644
--- a/src/main/java/run/halo/live2d/Live2dSettingProcess.java
+++ b/src/main/java/run/halo/live2d/Live2dSettingProcess.java
@@ -31,7 +31,7 @@ public class Live2dSettingProcess implements Live2dSetting {
private static final List TIPS_FIELDS = List.of(
"firstOpenSite", "backSite", "backSiteTip", "copyContent", "copyContentTip",
"openConsole", "openConsoleTip", "selectorTips", "tipsPath");
- private static final List ADVANCED_FIELDS = List.of("consoleShowStatu", "photoName");
+ private static final List ADVANCED_FIELDS = List.of("consoleShowStatu", "photoName", "zIndex");
private static final List AI_CHAT_PUBLIC_FIELDS = List.of(
"chunkTimeout", "showChatMessageTimeout", "autoContinuationMessageMinVisibleMs",
"requestAcceptedMessage", "reasoningMessages", "reasoningMessageInterval",
diff --git a/src/main/resources/extensions/settings.yaml b/src/main/resources/extensions/settings.yaml
index b5d4f42..45e10e2 100644
--- a/src/main/resources/extensions/settings.yaml
+++ b/src/main/resources/extensions/settings.yaml
@@ -522,6 +522,15 @@ spec:
- group: advanced
label: 高级设置
formSchema:
+ - $formkit: number
+ name: zIndex
+ label: 显示层级
+ help: 看板娘和工具栏的显示层级,值越大越靠前;遮挡音乐按钮等控件时可调低。
+ value: 9998
+ min: 0
+ max: 2147483645
+ step: 1
+ validation: 'required|number|min:0|max:2147483645|matches:/^[0-9]+$/'
- $formkit: switch
name: consoleShowStatu
key: consoleShowStatu
diff --git a/src/test/java/run/halo/live2d/Live2dStackingSettingTest.java b/src/test/java/run/halo/live2d/Live2dStackingSettingTest.java
new file mode 100644
index 0000000..3a8fb4a
--- /dev/null
+++ b/src/test/java/run/halo/live2d/Live2dStackingSettingTest.java
@@ -0,0 +1,35 @@
+package run.halo.live2d;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import com.fasterxml.jackson.databind.node.JsonNodeFactory;
+import java.util.Map;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import reactor.core.publisher.Mono;
+import run.halo.app.plugin.ReactiveSettingFetcher;
+import run.halo.live2d.agent.AgentToolNormalizer;
+import run.halo.live2d.ai.HaloAiFoundationAvailability;
+
+class Live2dStackingSettingTest {
+
+ @ParameterizedTest
+ @ValueSource(ints = {0, 25, 9998})
+ void includesSavedStackingLayerInPublicConfiguration(int zIndex) {
+ var settingFetcher = mock(ReactiveSettingFetcher.class);
+ var availability = mock(HaloAiFoundationAvailability.class);
+ var advanced = JsonNodeFactory.instance.objectNode().put("zIndex", zIndex);
+ when(settingFetcher.getValues()).thenReturn(Mono.just(Map.of("advanced", advanced)));
+ when(availability.isEnabled()).thenReturn(Mono.just(false));
+ var settings = new Live2dSettingProcess(settingFetcher,
+ mock(AgentToolNormalizer.class), availability);
+
+ var config = settings.getPublicConfig(null).block();
+
+ assertThat(config).isNotNull();
+ assertThat(config.get("zIndex").intValue()).isEqualTo(zIndex);
+ assertThat(config.has("advanced")).isFalse();
+ }
+}