feat(toc): add configurable badge style (number/katakana/roman)

Replace the boolean `useJapaneseBadge` with a new `badgeStyle` config
option that supports three TOC badge styles:

- "number": plain numeric badges (1, 2, 3...)
- "katakana": Japanese katakana badges (original style)
- "roman": Roman numeral badges (new)

The old `useJapaneseBadge` boolean is kept as deprecated for backward
compatibility. All TOC components (Sidebar, Floating, Mobile, Card)
are updated to use the new unified `getTOCBadge()` function.

Author: Dawn6666666

src/components/features/toc/FloatingTOC.astro

@@ -14,13 +14,13 @@ interface Props {
 
 const { headings: _ = [] } = Astro.props;
 const tocDepth = siteConfig.toc.depth;
-const useJapaneseBadge = siteConfig.toc.useJapaneseBadge;
+const badgeStyle = siteConfig.toc.badgeStyle || (siteConfig.toc.useJapaneseBadge ? "katakana" : "number");
 ---
 
 <div
 	class="floating-toc-wrapper"
 	data-depth={tocDepth}
-	data-japanese-badge={useJapaneseBadge}
+	data-badge-style={badgeStyle}
 >
 	<FloatingButton
 		id="floating-toc-btn"

src/components/features/toc/SidebarTOC.astro

@@ -18,7 +18,7 @@ const { class: className } = Astro.props;
 </table-of-contents>
 
 <script>
-	import { JAPANESE_KATAKANA } from "./utils/japanese-katakana";
+	import { getTOCBadge } from "./utils/japanese-katakana";
 	import {
 		extractHeadings,
 		generateTOCItems,
@@ -299,11 +299,7 @@ const { class: className } = Astro.props;
 
 					let badgeContent: string;
 					if (item.depth === 0) {
-						badgeContent =
-							config.useJapaneseBadge &&
-							h1Count - 1 < JAPANESE_KATAKANA.length
-								? JAPANESE_KATAKANA[h1Count - 1]
-								: h1Count.toString();
+						badgeContent = getTOCBadge(h1Count - 1, config.badgeStyle);
 						h1Count++;
 					} else if (item.depth === 1) {
 						badgeContent =

src/components/features/toc/hooks/useMobileTOC.ts

@@ -3,6 +3,8 @@
  * 处理移动端目录的状态管理和交互逻辑
  */
 
+import { getTOCBadge, type TOCBadgeStyle } from "../utils/japanese-katakana";
+
 export interface TOCItem {
 	id: string;
 	text: string;
@@ -18,37 +20,14 @@ export interface PostItem {
 }
 
 export interface TOCConfig {
-	useJapaneseBadge: boolean;
+	badgeStyle: TOCBadgeStyle;
 	depth: number;
 }
 
 /**
  * 生成目录项
  */
 export function generateTOCItems(config: TOCConfig): TOCItem[] {
-	const japaneseHiragana = [
-		"ア",
-		"イ",
-		"ウ",
-		"エ",
-		"オ",
-		"カ",
-		"キ",
-		"ク",
-		"ケ",
-		"コ",
-		"サ",
-		"シ",
-		"ス",
-		"セ",
-		"ソ",
-		"タ",
-		"チ",
-		"ツ",
-		"テ",
-		"ト",
-	];
-
 	const headings = document.querySelectorAll("h1, h2, h3, h4, h5, h6");
 	const items: TOCItem[] = [];
 	let h1Count = 0;
@@ -70,15 +49,8 @@ export function generateTOCItems(config: TOCConfig): TOCItem[] {
 
 		// 只为 H1 标题生成 badge
 		if (level === 1) {
+			badge = getTOCBadge(h1Count, config.badgeStyle);
 			h1Count++;
-			if (
-				config.useJapaneseBadge &&
-				h1Count - 1 < japaneseHiragana.length
-			) {
-				badge = japaneseHiragana[h1Count - 1];
-			} else {
-				badge = h1Count.toString();
-			}
 		}
 
 		items.push({ id: heading.id, text, level, badge });
@@ -166,8 +138,11 @@ export function scrollToHeading(id: string, offset = 80): void {
  * 获取 TOC 配置
  */
 export function getTOCConfig(): TOCConfig {
+	const badgeStyle: TOCBadgeStyle =
+		(window.siteConfig?.toc?.badgeStyle as TOCBadgeStyle) ??
+		(window.siteConfig?.toc?.useJapaneseBadge ? "katakana" : "number");
 	return {
-		useJapaneseBadge: window.siteConfig?.toc?.useJapaneseBadge ?? false,
+		badgeStyle,
 		depth: window.siteConfig?.toc?.depth ?? 3,
 	};
 }

src/components/features/toc/hooks/useTocNavigation.ts

@@ -74,18 +74,22 @@ export function createHeadingClickHandler(
  */
 export function getTOCConfig(): {
 	depth: number;
+	badgeStyle: "number" | "katakana" | "roman";
 	useJapaneseBadge: boolean;
 } {
 	const siteConfig = (
 		window as unknown as {
 			siteConfig?: {
-				toc?: { depth?: number; useJapaneseBadge?: boolean };
+				toc?: { depth?: number; badgeStyle?: string; useJapaneseBadge?: boolean };
 			};
 		}
 	).siteConfig;
+	const badgeStyle = (siteConfig?.toc?.badgeStyle as "number" | "katakana" | "roman") ??
+		(siteConfig?.toc?.useJapaneseBadge ? "katakana" : "number");
 	return {
 		depth: siteConfig?.toc?.depth ?? 3,
-		useJapaneseBadge: siteConfig?.toc?.useJapaneseBadge ?? false,
+		badgeStyle,
+		useJapaneseBadge: badgeStyle === "katakana",
 	};
 }
 

src/components/features/toc/index.ts

@@ -73,9 +73,12 @@ export {
 // Calculator utilities
 export {
 	getKatakanaBadge,
+	getTOCBadge,
 	JAPANESE_KATAKANA,
 	KATAKANA_COUNT,
+	ROMAN_NUMERALS,
 } from "./utils/japanese-katakana";
+export type { TOCBadgeStyle } from "./utils/japanese-katakana";
 export {
 	getMinLevel as calcMinLevel,
 	generateTOCItems as calcTOCItems,

src/components/features/toc/types.ts

@@ -14,7 +14,7 @@ export interface TOCItem {
 	level: number;
 	/** 相对深度（0 = 顶级） */
 	depth: number;
-	/** 徽章文本（数字或日语字符） */
+	/** 徽章文本（数字、日语片假名或罗马数字） */
 	badge?: string;
 }
 
@@ -28,7 +28,9 @@ export interface TOCConfig {
 	mode: "float" | "sidebar";
 	/** 标题深度（1-6） */
 	depth: number;
-	/** 是否使用日语徽章 */
+	/** 徽章样式 */
+	badgeStyle: "number" | "katakana" | "roman";
+	/** @deprecated 使用 badgeStyle 代替 */
 	useJapaneseBadge: boolean;
 }
 

src/components/features/toc/types/toc.ts

@@ -11,7 +11,7 @@ export interface TOCItem {
 	level: number;
 	/** 相对深度（0 = 顶级） */
 	depth: number;
-	/** 徽章文本（数字或日语字符） */
+	/** 徽章文本（数字、日语片假名或罗马数字） */
 	badge?: string;
 }
 
@@ -22,7 +22,9 @@ export interface TOCConfig {
 	mode: "float" | "sidebar";
 	/** 标题深度（1-6） */
 	depth: number;
-	/** 是否使用日语徽章 */
+	/** 徽章样式 */
+	badgeStyle: "number" | "katakana" | "roman";
+	/** @deprecated 使用 badgeStyle 代替 */
 	useJapaneseBadge: boolean;
 }
 

src/components/features/toc/utils/japanese-katakana.ts

@@ -1,10 +1,10 @@
 /**
- * 日语片假名字符集
- * 用于 TOC 徽章显示
+ * TOC 徽章字符集
+ * 用于 TOC 徽章显示，支持多种计数方式
  */
 
 /**
- * 完整的日语片假名字符集（46 个字符）
+ * 日语片假名字符集（46 个字符）
  * 按五十音图顺序排列
  */
 export const JAPANESE_KATAKANA = [
@@ -66,19 +66,77 @@ export const JAPANESE_KATAKANA = [
 	"ン",
 ] as const;
 
+/**
+ * 罗马数字字符集（30 个）
+ * Ⅰ-Ⅻ 使用 Unicode 罗马数字字符，XIII-XXX 使用拉丁字母
+ */
+export const ROMAN_NUMERALS = [
+	"Ⅰ",
+	"Ⅱ",
+	"Ⅲ",
+	"Ⅳ",
+	"Ⅴ",
+	"Ⅵ",
+	"Ⅶ",
+	"Ⅷ",
+	"Ⅸ",
+	"Ⅹ",
+	"Ⅺ",
+	"Ⅻ",
+	"XIII",
+	"XIV",
+	"XV",
+	"XVI",
+	"XVII",
+	"XVIII",
+	"XIX",
+	"XX",
+	"XXI",
+	"XXII",
+	"XXIII",
+	"XXIV",
+	"XXV",
+	"XXVI",
+	"XXVII",
+	"XXVIII",
+	"XXIX",
+	"XXX",
+] as const;
+
+export type TOCBadgeStyle = "number" | "katakana" | "roman";
+
 export type JapaneseKatakanaChar = (typeof JAPANESE_KATAKANA)[number];
 
 /**
- * 获取 TOC 徽章文本
+ * 根据 badgeStyle 获取 TOC 徽章文本
  * @param index - 索引（从 0 开始）
- * @param useJapanese - 是否使用日语字符
+ * @param badgeStyle - 徽章样式："number" | "katakana" | "roman"
  * @returns 徽章文本
  */
-export function getKatakanaBadge(index: number, useJapanese: boolean): string {
-	if (useJapanese && index < JAPANESE_KATAKANA.length) {
-		return JAPANESE_KATAKANA[index];
+export function getTOCBadge(index: number, badgeStyle: TOCBadgeStyle): string {
+	switch (badgeStyle) {
+		case "katakana":
+			if (index < JAPANESE_KATAKANA.length) {
+				return JAPANESE_KATAKANA[index];
+			}
+			return (index + 1).toString();
+		case "roman":
+			if (index < ROMAN_NUMERALS.length) {
+				return ROMAN_NUMERALS[index];
+			}
+			return (index + 1).toString();
+		case "number":
+		default:
+			return (index + 1).toString();
 	}
-	return (index + 1).toString();
+}
+
+/**
+ * 兼容旧接口：根据 useJapanese 布尔值获取徽章
+ * @deprecated 请使用 getTOCBadge(index, badgeStyle) 代替
+ */
+export function getKatakanaBadge(index: number, useJapanese: boolean): string {
+	return getTOCBadge(index, useJapanese ? "katakana" : "number");
 }
 
 /**

src/components/features/toc/utils/toc-calculator.ts

@@ -4,7 +4,7 @@
  */
 
 import type { HeadingData, TOCItem } from "../types/toc";
-import { JAPANESE_KATAKANA } from "./japanese-katakana";
+import { getTOCBadge, type TOCBadgeStyle } from "./japanese-katakana";
 
 /**
  * 计算最小标题级别
@@ -23,16 +23,13 @@ export function getBadgeText(
 	index: number,
 	level: number,
 	minLevel: number,
-	useJapaneseBadge: boolean,
+	badgeStyle: TOCBadgeStyle,
 ): string {
 	if (level !== minLevel) {
 		return "";
 	}
 
-	if (useJapaneseBadge && index < JAPANESE_KATAKANA.length) {
-		return JAPANESE_KATAKANA[index];
-	}
-	return (index + 1).toString();
+	return getTOCBadge(index, badgeStyle);
 }
 
 /**
@@ -41,7 +38,7 @@ export function getBadgeText(
 export function generateTOCItems(
 	headings: HeadingData[],
 	depth: number,
-	useJapaneseBadge: boolean,
+	badgeStyle: TOCBadgeStyle,
 ): TOCItem[] {
 	if (headings.length === 0) {
 		return [];
@@ -58,7 +55,7 @@ export function generateTOCItems(
 				h1Count,
 				h.level,
 				minLevel,
-				useJapaneseBadge,
+				badgeStyle,
 			);
 
 			if (h.level === minLevel) {

src/components/features/toc/utils/toc-utils.ts

@@ -3,7 +3,7 @@
  */
 
 import type { HeadingData, TOCConfig, TOCItem } from "../types/toc";
-import { getKatakanaBadge } from "./japanese-katakana";
+import { getTOCBadge } from "./japanese-katakana";
 
 /**
  * 从 DOM 中提取标题数据
@@ -66,7 +66,7 @@ export function generateTOCItems(
 			let badge: string | undefined;
 
 			if (h.level === minLevel) {
-				badge = getKatakanaBadge(h1Count, config.useJapaneseBadge);
+				badge = getTOCBadge(h1Count, config.badgeStyle);
 				h1Count++;
 			}
 
@@ -133,6 +133,7 @@ export function getTOCConfig(): TOCConfig {
 		enable: siteConfig.toc?.enable ?? true,
 		mode: siteConfig.toc?.mode ?? "sidebar",
 		depth: siteConfig.toc?.depth ?? 3,
+		badgeStyle: siteConfig.toc?.badgeStyle ?? (siteConfig.toc?.useJapaneseBadge ? "katakana" : "number"),
 		useJapaneseBadge: siteConfig.toc?.useJapaneseBadge ?? false,
 	};
 }