feat: 公开嵌入页主题支持外部指定 + 排行榜入口移至左上角
- 公开页(/share、/public、/roundtable-share)新增 ?theme= 与 deerflow:set-theme postMessage 两种外部主题指定方式,经 usePublicEmbedTheme 接成 next-themes forcedTheme,不写 localStorage - 排行榜入口从欢迎语旁移到 workspace-header 左上角应用名旁 - 新增 docs/embed-public-pages-theme.md 嵌入主题使用文档 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
吉鑫升andClaude Fable 5 committed
1 parent
57a87d6322
commit
81f2a48c6d
5 files changed
+245
-24
No files matched your search
@@ -0,0 +1,154 @@
|
||||
# 公开页 · iframe 嵌入外观对接说明（主题 / 背景色）
|
||||
|
||||
本文档面向**嵌入方（宿主系统）**，说明如何在用 `<iframe>` 嵌入 DeerFlow 公开页时，从外部控制页面的**整体明暗主题（light/dark）**与**背景色 / 文字色**，使其与宿主站点的视觉风格保持一致。
|
||||
|
||||
前端实现见：`src/core/embed/background.ts`（参数解析与 postMessage 监听）、`src/App.tsx`（主题接入 `forcedTheme`）。
|
||||
|
||||
---
|
||||
|
||||
## 0. 速读
|
||||
|
||||
| 想做什么 | 怎么做 |
|
||||
|----------|--------|
|
||||
| 嵌入时指定深色主题 | iframe `src` 加 `?theme=dark` |
|
||||
| 嵌入时指定背景/文字色 | iframe `src` 加 `?bg=%23001529&text=%23ffffff`（`#` 需编码为 `%23`） |
|
||||
| 宿主切主题时同步切换 | `postMessage({ type: "deerflow:set-theme", theme: "dark" }, "*")` |
|
||||
| 宿主动态改背景色 | `postMessage({ type: "deerflow:set-bg", bg: "#001529", text: "#fff" }, "*")` |
|
||||
| 什么都不传 | 页面使用 DeerFlow 自带默认配色，互不影响 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 适用页面
|
||||
|
||||
以下公开页（免登录、只读）均支持本文档的全部参数：
|
||||
|
||||
| 页面 | 路由 |
|
||||
|------|------|
|
||||
| 会话分享页 | `/#/share/{shareCode}` |
|
||||
| 圆桌分享页 | `/#/roundtable-share/{shareCode}`、`/#/roundtable-share/{shareCode}/report` |
|
||||
| 用户排行榜 | `/#/public/leaderboard` |
|
||||
| 定时任务公开页 | `/#/public/scheduled-tasks/{taskId}`（含 `/runs/{runId}/fullscreen` 全屏页） |
|
||||
|
||||
> 注意：站点使用 **hash 路由**，路径在 `#` 之后。
|
||||
> 嵌入聊天页（`/#/embed/chats/*`、`/#/embed/roundtable`）有自己的主题约定，见 `embed-iframe-chat.md`，不在本文范围内。
|
||||
|
||||
---
|
||||
|
||||
## 2. URL 查询参数（嵌入时一次性指定）
|
||||
|
||||
### 2.1 参数列表
|
||||
|
||||
| 参数 | 别名 | 作用 | 合法值 |
|
||||
|------|------|------|--------|
|
||||
| `theme` | — | 切整体明暗主题 | 见 2.2 取值映射表 |
|
||||
| `bg` | `background` | 页面根容器背景色 | 见 2.3 颜色格式 |
|
||||
| `text` | `fg` | 页面根容器文字色 | 见 2.3 颜色格式 |
|
||||
|
||||
三个参数相互独立，可任意组合；不传或传非法值时该项忽略、沿用默认。
|
||||
|
||||
### 2.2 `theme` 取值映射
|
||||
|
||||
| 传入值（不区分大小写） | 实际主题 |
|
||||
|------|------|
|
||||
| `dark`、`dark-blue`、`深蓝`、`深色` | 深色 |
|
||||
| `light`、`red`、`红白`、`浅色` | 浅色 |
|
||||
| 其他 / 不传 | 忽略，沿用站内默认（浅色） |
|
||||
|
||||
### 2.3 颜色格式（`bg` / `text`）
|
||||
|
||||
颜色值经过白名单校验，仅接受以下写法，其余一律丢弃（防注入）：
|
||||
|
||||
- **hex**：`#fff`、`#ffffffcc` 等 3/4/6/8 位（`#` 可省略；URL 里 `#` 必须编码为 `%23`）
|
||||
- **函数式**：`rgb()` / `rgba()` / `hsl()` / `hsla()`，括号内仅允许数字、逗号、百分号、空格、`/`
|
||||
- **命名色**：纯英文字母，如 `white`、`transparent`
|
||||
|
||||
### 2.4 参数位置
|
||||
|
||||
参数放在 hash 路由之后（推荐）或 `#` 之前都能识别；两处都传时**hash 路由内的优先**：
|
||||
|
||||
```
|
||||
https://<host>/#/public/leaderboard?theme=dark ← 推荐
|
||||
https://<host>/?theme=dark#/public/leaderboard ← 也支持
|
||||
```
|
||||
|
||||
### 2.5 示例
|
||||
|
||||
```html
|
||||
<!-- 深色主题 -->
|
||||
<iframe src="https://<host>/#/public/leaderboard?theme=dark"></iframe>
|
||||
|
||||
<!-- 浅色主题 + 自定义背景与文字色（# 编码为 %23） -->
|
||||
<iframe src="https://<host>/#/share/Ab3xYz?theme=light&bg=%23f5f7fa&text=%23333333"></iframe>
|
||||
|
||||
<!-- 主题与背景叠加：整页走深色变量，根背景用宿主品牌色 -->
|
||||
<iframe src="https://<host>/#/roundtable-share/Ab3xYz?theme=dark&bg=%23001529"></iframe>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. postMessage（嵌入后动态切换）
|
||||
|
||||
适用于宿主站点支持用户切主题、需要 iframe 实时跟随的场景。向 iframe 的 `contentWindow` 发消息即可，**无需等待子页面回执**（监听器在应用挂载时注册）。
|
||||
|
||||
### 3.1 消息格式
|
||||
|
||||
```js
|
||||
const frame = document.getElementById("deerflow-frame");
|
||||
|
||||
// 切整体明暗主题（theme 取值同 2.2）
|
||||
frame.contentWindow.postMessage({ type: "deerflow:set-theme", theme: "dark" }, "*");
|
||||
|
||||
// 改背景色 / 文字色（字段名与 URL 参数一致，bg/background、text/fg 均可）
|
||||
frame.contentWindow.postMessage({ type: "deerflow:set-bg", bg: "#001529", text: "#fff" }, "*");
|
||||
// 兼容别名：type 也可写 "deerflow:set-background"
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 两类消息相互独立，可只发其一；`set-bg` 里 `bg`、`text` 也可只传其一，未传的字段保持当前值。
|
||||
- 非法颜色值 / 不认识的 `theme` 取值会被忽略，不会清空已有设置。
|
||||
- targetOrigin 建议按需收紧（写 DeerFlow 站点的 origin 而非 `"*"`）。
|
||||
|
||||
### 3.2 宿主主题联动示例
|
||||
|
||||
```js
|
||||
function syncDeerflowTheme(isDark) {
|
||||
const win = document.getElementById("deerflow-frame").contentWindow;
|
||||
win.postMessage({ type: "deerflow:set-theme", theme: isDark ? "dark" : "light" }, "*");
|
||||
win.postMessage(
|
||||
{ type: "deerflow:set-bg", bg: isDark ? "#001529" : "#ffffff" },
|
||||
"*",
|
||||
);
|
||||
}
|
||||
|
||||
// iframe 首次加载用 URL 参数兜底，之后切换走 postMessage
|
||||
myThemeStore.subscribe((theme) => syncDeerflowTheme(theme === "dark"));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 优先级与默认行为
|
||||
|
||||
同一项配置多处传入时，按以下优先级取值（高 → 低）：
|
||||
|
||||
1. **postMessage** 动态设置的值
|
||||
2. hash 路由内的 URL 参数（`#/路由?theme=...`）
|
||||
3. `#` 之前的 URL 参数（`?theme=...#/路由`）
|
||||
4. 都没传 → DeerFlow 默认配色（浅色主题 + 页面自带 Tailwind 配色）
|
||||
|
||||
其他保证：
|
||||
|
||||
- 外部主题只影响**当前 iframe 的渲染**，不写 localStorage——不会污染用户直接访问 DeerFlow 主站时自己选择的主题。
|
||||
- `bg`/`text` 是内联样式，作用在页面根容器上，优先级高于主题变量；与 `theme` 叠加时以 `bg`/`text` 为准。
|
||||
|
||||
---
|
||||
|
||||
## 5. 常见问题排查
|
||||
|
||||
| 现象 | 排查 |
|
||||
|------|------|
|
||||
| `theme=dark` 不生效 | 确认路由属于第 1 节列出的公开页；确认参数拼在 hash 路由后（`/#/share/xx?theme=dark`），而不是写成了 `/#/share/xx#theme=dark` |
|
||||
| `bg=#fff` 不生效 | URL 里 `#` 没编码会被浏览器截断，必须写 `%23fff`；或直接省略 `#` 写 `bg=fff` |
|
||||
| postMessage 无反应 | 确认消息体是对象且 `type` 拼写为 `deerflow:set-theme` / `deerflow:set-bg`；确认在 iframe `load` 之后发送 |
|
||||
| 颜色被忽略 | 检查是否符合 2.3 白名单格式（如 `linear-gradient(...)` 等复杂值不支持） |
|
||||
| 主题切了但个别区域颜色没变 | 该区域可能使用了固定配色；把页面路由与截图反馈给 DeerFlow 维护方补充 `dark:` 样式 |
|
||||
@@ -13,6 +13,7 @@ import {
|
||||
resolveEmbedRoundtableTheme,
|
||||
resolveEmbedTheme,
|
||||
} from "@/core/embed/params";
|
||||
import { usePublicEmbedTheme } from "@/core/embed/background";
|
||||
import { readWujieProps } from "@/core/embed/wujie";
|
||||
|
||||
import { HashRouter, useLocation } from "react-router-dom";
|
||||
@@ -31,9 +32,13 @@ import EmbedRoundtablePage from "./pages/EmbedRoundtablePage";
|
||||
import { ChatRuntime } from "./pages/WorkspaceRoutes";
|
||||
import { NotFoundPage } from "./pages/NotFoundPage";
|
||||
|
||||
// 公开页路由前缀：这些页面会被第三方 iframe 嵌入，主题可由外部指定。
|
||||
const PUBLIC_EMBED_PREFIXES = ["/share/", "/public/", "/roundtable-share/"];
|
||||
|
||||
function AppProviders({ children }: { children: React.ReactNode }) {
|
||||
const locale = useMemo(() => detectLocale(), []);
|
||||
const location = useLocation();
|
||||
const publicEmbedTheme = usePublicEmbedTheme();
|
||||
// 嵌入路由的主题用 forcedTheme 强制：只影响当前渲染，不写 localStorage。
|
||||
// 千万不要在嵌入页里调 ThemeContext.setTheme —— 它会持久化主题并打上
|
||||
// 「用户已显式选择」标记。无界子应用与主站同域共享 localStorage，宿主
|
||||
@@ -52,8 +57,11 @@ function AppProviders({ children }: { children: React.ReactNode }) {
|
||||
const raw = new URLSearchParams(location.search).get("theme")?.trim();
|
||||
return raw ? resolveEmbedTheme(raw) : undefined;
|
||||
}
|
||||
if (PUBLIC_EMBED_PREFIXES.some((p) => location.pathname.startsWith(p))) {
|
||||
return publicEmbedTheme;
|
||||
}
|
||||
return undefined;
|
||||
}, [location.pathname, location.search]);
|
||||
}, [location.pathname, location.search, publicEmbedTheme]);
|
||||
|
||||
return (
|
||||
<NextThemesProvider
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
"use client";
|
||||
|
||||
import { Trophy } from "lucide-react";
|
||||
import { useSearchParams } from "next/navigation";
|
||||
import { useEffect, useMemo } from "react";
|
||||
|
||||
@@ -8,7 +7,6 @@ import { useI18n } from "@/core/i18n/hooks";
|
||||
import { cn } from "@/lib/utils";
|
||||
|
||||
import { AuroraText } from "../ui/aurora-text";
|
||||
import { Button } from "../ui/button";
|
||||
|
||||
let waved = false;
|
||||
|
||||
@@ -47,20 +45,6 @@ export function Welcome({
|
||||
{isUltra ? "🚀" : "👋"}
|
||||
</div>
|
||||
<AuroraText colors={colors}>{t.welcome.greeting}</AuroraText>
|
||||
{/* 用户排行榜入口:紧挨欢迎语的"CM助手",新标签打开免登录的公开排行榜页。 */}
|
||||
<Button
|
||||
type="button"
|
||||
variant="ghost"
|
||||
size="sm"
|
||||
onClick={() =>
|
||||
window.open("#/public/leaderboard", "_blank", "noopener")
|
||||
}
|
||||
title="打开用户排行榜公开页"
|
||||
className="text-muted-foreground hover:text-foreground h-8 shrink-0 gap-1.5 px-2 text-xs font-medium"
|
||||
>
|
||||
<Trophy className="size-4" />
|
||||
<span>排行榜</span>
|
||||
</Button>
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
"use client";
|
||||
|
||||
import { ChevronLeft, ChevronRight } from "lucide-react";
|
||||
import { ChevronLeft, ChevronRight, Trophy } from "lucide-react";
|
||||
import Link from "next/link";
|
||||
|
||||
import { Button } from "@/components/ui/button";
|
||||
@@ -86,6 +86,20 @@ export function WorkspaceHeader({ className }: { className?: string }) {
|
||||
) : (
|
||||
titleBlock
|
||||
)}
|
||||
{/* 用户排行榜入口:紧挨左上角的应用名,新标签打开免登录的公开排行榜页。 */}
|
||||
<Button
|
||||
type="button"
|
||||
variant="ghost"
|
||||
size="sm"
|
||||
onClick={() =>
|
||||
window.open("#/public/leaderboard", "_blank", "noopener")
|
||||
}
|
||||
title="打开用户排行榜公开页"
|
||||
className="text-muted-foreground hover:text-sidebar-foreground h-8 shrink-0 gap-1 px-1.5 text-xs font-medium"
|
||||
>
|
||||
<Trophy className="size-4" />
|
||||
<span>排行榜</span>
|
||||
</Button>
|
||||
<SidebarCollapseButton />
|
||||
</div>
|
||||
)}
|
||||
|
||||
@@ -2,19 +2,23 @@ import { useEffect, useMemo, useState } from "react";
|
||||
import { useLocation } from "react-router-dom";
|
||||
|
||||
/**
|
||||
* 公开页（被第三方 iframe 嵌套）的可配置背景色。
|
||||
* 公开页（被第三方 iframe 嵌套）的可配置外观:背景色 + 整体明暗主题。
|
||||
*
|
||||
* 这些 `/public/*`、`/share/*`、`/roundtable-share/*` 页面会被别的系统用
|
||||
* `<iframe>` 嵌进去。嵌套方希望背景色跟自己的站点保持一致,所以我们把
|
||||
* 「背景色 / 前景文字色」抽成可外部传入的参数,两种传法都支持:
|
||||
* `<iframe>` 嵌进去。嵌套方希望外观跟自己的站点保持一致,所以我们把
|
||||
* 「背景色 / 前景文字色 / light·dark 主题」抽成可外部传入的参数,两种传法都支持:
|
||||
*
|
||||
* 1. URL 查询参数(嵌套时一次性指定,最常用):
|
||||
* `<iframe src=".../#/public/leaderboard?bg=%23ffffff&text=%23111111">`
|
||||
* —— `bg`/`background` 设背景,`text`/`fg` 设文字色。
|
||||
* `<iframe src=".../#/public/leaderboard?theme=dark&bg=%23ffffff&text=%23111111">`
|
||||
* —— `theme` 切整体明暗(`dark`/`light`,兼容 `dark-blue`/`red` 等别名),
|
||||
* `bg`/`background` 设背景,`text`/`fg` 设文字色。
|
||||
* 2. `postMessage`(嵌套后动态切换,比如宿主切主题时同步):
|
||||
* `iframe.contentWindow.postMessage({ type: "deerflow:set-bg", bg: "#fff", text: "#111" }, "*")`
|
||||
* `iframe.contentWindow.postMessage({ type: "deerflow:set-theme", theme: "dark" }, "*")`
|
||||
*
|
||||
* 不传时返回空对象,页面沿用自带的默认配色(Tailwind 类),互不影响。
|
||||
* 不传时沿用页面自带的默认配色(Tailwind 类)与站内主题,互不影响。
|
||||
* 主题经 `usePublicEmbedTheme` 在 App 层接成 next-themes 的 `forcedTheme`,
|
||||
* 只影响当前渲染、不写 localStorage(原因见 App.tsx 内注释)。
|
||||
*/
|
||||
export type PublicBackground = {
|
||||
backgroundColor?: string;
|
||||
@@ -53,6 +57,63 @@ function readFromSearch(search: string): PublicBackground {
|
||||
* `window.location.search`(`?bg=` 在 `#` 前面);路由内的更贴近当前页,优先级更高。
|
||||
* 同时监听 `postMessage` 以支持嵌套后动态改色。
|
||||
*/
|
||||
/**
|
||||
* 把外部传入的主题标识规整成 light/dark;不认识或为空返回 undefined(沿用站内主题)。
|
||||
* 兼容嵌入聊天页已有的取值习惯:`dark-blue`/深蓝 → 深色,`red`/红白 → 浅色。
|
||||
*/
|
||||
export function normalizePublicTheme(
|
||||
raw: string | null | undefined,
|
||||
): "dark" | "light" | undefined {
|
||||
const value = raw?.trim().toLowerCase();
|
||||
if (!value) return undefined;
|
||||
if (value === "dark" || value === "dark-blue" || value === "深蓝" || value === "深色") {
|
||||
return "dark";
|
||||
}
|
||||
if (value === "light" || value === "red" || value === "红白" || value === "浅色") {
|
||||
return "light";
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function readThemeFromSearch(search: string): "dark" | "light" | undefined {
|
||||
const params = new URLSearchParams(search.startsWith("?") ? search : `?${search}`);
|
||||
return normalizePublicTheme(params.get("theme"));
|
||||
}
|
||||
|
||||
/**
|
||||
* 读取公开页的外部主题(`?theme=` 或 `deerflow:set-theme` postMessage)。
|
||||
*
|
||||
* 与 `usePublicBackground` 同样合并两处查询串(hash 路由内优先),
|
||||
* postMessage 的动态值优先级最高。返回 undefined 表示外部未指定。
|
||||
*/
|
||||
export function usePublicEmbedTheme(): "dark" | "light" | undefined {
|
||||
const location = useLocation();
|
||||
|
||||
const fromUrl = useMemo(() => {
|
||||
const outer = readThemeFromSearch(
|
||||
typeof window !== "undefined" ? window.location.search : "",
|
||||
);
|
||||
const inner = readThemeFromSearch(location.search);
|
||||
return inner ?? outer;
|
||||
}, [location.search]);
|
||||
|
||||
const [override, setOverride] = useState<"dark" | "light" | undefined>(undefined);
|
||||
|
||||
useEffect(() => {
|
||||
function onMessage(event: MessageEvent) {
|
||||
const data = event.data as { type?: string; theme?: string } | null;
|
||||
if (!data || typeof data !== "object") return;
|
||||
if (data.type !== "deerflow:set-theme") return;
|
||||
const theme = normalizePublicTheme(data.theme);
|
||||
if (theme) setOverride(theme);
|
||||
}
|
||||
window.addEventListener("message", onMessage);
|
||||
return () => window.removeEventListener("message", onMessage);
|
||||
}, []);
|
||||
|
||||
return override ?? fromUrl;
|
||||
}
|
||||
|
||||
export function usePublicBackground(): PublicBackground {
|
||||
const location = useLocation();
|
||||
|
||||
|
||||
Reference in new issue
Block a user