refactor(components)！: Code 由 withDecorate 取代 withCopyButton

withDecorate 可以自定义装饰器，withCopyButton 成为一种装饰器的实现。

BREAKING CHANGE 删除了不再需要的 withCopyButton

Author: caixw

apps/docs/src/components/base.tsx

@@ -138,3 +138,62 @@ export function arraySelector<T extends string | number>(
 
 	return [elem, signal[0], signal[1]];
 }
+
+/**
+ * 可多选的下拉框
+ */
+export function arrayMultipleSelector<T extends string | number>(
+	label: string,
+	array: ReadonlyArray<T> | ReadonlyMap<T, string>,
+	preset?: Array<T>,
+	appendUndefined = false,
+): [Component, Accessor<Array<T> | undefined>, Setter<Array<T> | undefined>] {
+	const signal = createSignal<Array<T> | undefined>(preset);
+
+	let options: Array<Choice.Option<T>>;
+
+	if (Array.isArray(array)) {
+		options = array.map(item => {
+			return {
+				type: 'item',
+				value: item,
+				label: item,
+			};
+		});
+	} else {
+		const m = array as ReadonlyMap<T, string>;
+		options = Array.from(m.entries()).map(([key, val]) => {
+			return {
+				type: 'item',
+				value: key,
+				label: val,
+			};
+		});
+	}
+
+	if (appendUndefined) {
+		options.push({
+			type: 'item',
+			value: undefined,
+			label: 'undefined',
+		});
+	}
+
+	const name = createUniqueId(); // 保证一组 radio 一个独立的名称
+
+	const elem = () => {
+		const l = useLocale();
+		return (
+			<Choice.Root
+				closable
+				multiple
+				layout="horizontal"
+				placeholder={l.t(label)}
+				accessor={Form.fieldAccessor(name, signal)}
+				options={options}
+			/>
+		);
+	};
+
+	return [elem, signal[0], signal[1]];
+}

apps/docs/src/components/demo/code/api.yaml

@@ -8,6 +8,11 @@
         types:
             - Code.RootProps
             - Code.RootRef
+
             - Code.Highlighter
             - Code.buildHighlighter
             - Code.highlight
+
+            - Code.decorates
+            - Code.registerDecorate
+            - Code.withDecorate

apps/docs/src/components/demo/code/decorate.tsx

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2025-2026 caixw
+//
+// SPDX-License-Identifier: MIT
+
+import { Code, type MountProps } from '@cmfx/components';
+import type { JSX } from 'solid-js';
+import { Portal } from 'solid-js/web';
+
+import { arrayMultipleSelector, boolSelector, paletteSelector } from '@docs/components/base';
+
+export default function (props: MountProps): JSX.Element {
+	const [Palette, palette] = paletteSelector();
+	const [Editable, editable] = boolSelector('_d.demo.editable');
+	const [Decorate, decorate] = arrayMultipleSelector('装饰器', Code.decorates());
+
+	return (
+		<div>
+			<Portal mount={props.mount}>
+				<Palette />
+				<Editable />
+				<Decorate />
+			</Portal>
+			<Code.Root editable={editable()} ln={0} wrap palette={palette()} class="h-50" lang="css" decorates={decorate()}>
+				{`/*
+ * SPDX-FileCopyrightText: 2025 caixw
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+@reference '../style.css';
+
+@layer components {
+    .code {
+        @apply font-mono w-full h-full overflow-auto rounded-lg relative;
+        @apply border border-palette-bg-low;
+
+        .action {
+            @apply flex justify-end absolute top-0 right-0;
+        }
+    }
+}
+`}
+			</Code.Root>
+		</div>
+	);
+}

apps/docs/src/components/demo/code/doc.zh-Hans.md

@@ -10,4 +10,7 @@
 #### oninput
 @```demo-oninput```@
 
+#### decorate
+@```demo-decorate```@
+
 @```api```@

apps/docs/src/components/demo/code/index.tsx

@@ -7,6 +7,8 @@ import IconCode from '~icons/mingcute/code-fill';
 import type { Info } from '@docs/components/base';
 import { default as Basic } from './basic';
 import { default as basic } from './basic.tsx?raw';
+import { default as Decorate } from './decorate';
+import { default as decorate } from './decorate.tsx?raw';
 import { default as Oninput } from './oninput';
 import { default as oninput } from './oninput.tsx?raw';
 import { default as Scrollable } from './scrollable';
@@ -24,6 +26,7 @@ export default function (): Info {
 			{ component: Basic, source: basic, id: 'basic' },
 			{ component: Scrollable, source: scrollable, id: 'scrollable' },
 			{ component: Oninput, source: oninput, id: 'oninput' },
+			{ component: Decorate, source: decorate, id: 'decorate' },
 		],
 	};
 }

apps/docs/src/docs/docs.tsx

@@ -224,7 +224,7 @@ function Doc(props: DocProps): JSX.Element {
 	let page: Page.RootRef;
 
 	onMount(() => {
-		Code.withCopyButton(page.root());
+		Code.withDecorate(page.root());
 	});
 
 	const components = createMemo(() => {

packages/components/src/code/decorate.tsx

@@ -0,0 +1,129 @@
+// SPDX-FileCopyrightText: 2026 caixw
+//
+// SPDX-License-Identifier: MIT
+
+import { getOwner, type JSX, runWithOwner } from 'solid-js';
+import { render } from 'solid-js/web';
+
+import { Button } from '@components/button';
+import { ClipboardAPI } from '@components/clipboard';
+import styles from './style.module.css';
+
+/**
+ * 装饰器的类型
+ *
+ * @param pre - 代码高亮的对象，装饰器最终会被放在此元素上；
+ * @remarks
+ * 这是对代码高亮对象 pre 的各种修改，比如添加按钮，或是改变颜色等。
+ */
+export type Decorate = (pre: HTMLPreElement) => JSX.Element;
+
+/**
+ * 获取的有已经注册的装饰器
+ *
+ * @remarks
+ * 默认情况下，支持以下装饰器：
+ * - toolbar 在顶部显示一个工具栏；
+ * - copyButton 在右上角显示一个复制按钮；
+ * - border 为代码组件显示边框；
+ */
+const decorates = new Map<string, Decorate>();
+
+/**
+ * 注册装饰器
+ * @param name - 装饰器的名称；
+ * @param decorate - 装饰器的实例；
+ */
+export function registerDecorate(name: string, decorate: Decorate): void {
+	if (decorates.has(name)) {
+		throw new Error(`${name} 已经存在`);
+	}
+
+	decorates.set(name, decorate);
+}
+
+/**
+ * 获取装饰器的名称列表
+ */
+export function getDecorates(): Array<string> {
+	return Array.from(decorates.keys());
+}
+
+/**
+ * 为 elem 及其子元素中的所有 shiki 代码块添加指定的组件
+ *
+ * @remarks
+ * 装饰器根据 {@link highlight} 的 decorate 参数而定。
+ */
+export function withDecorate(elem: HTMLElement): void {
+	// 当前元素匹配
+	if (elem.matches('[data-code]')) {
+		mount(elem as HTMLPreElement);
+		return;
+	}
+
+	const elems = elem.querySelectorAll('[data-code]');
+	for (const elem of elems) {
+		mount(elem as HTMLPreElement);
+	}
+}
+
+/**
+ * 根据 pre 上的 data-decorate 属性挂载相应的装饰器
+ */
+function mount(pre: HTMLPreElement) {
+	const names = pre.dataset.decorate;
+	if (!names) {
+		return;
+	}
+
+	const owner = getOwner();
+
+	for (const name of names.split(',')) {
+		const d = decorates.get(name);
+		if (d) {
+			runWithOwner(owner, () => render(() => d(pre), pre));
+		}
+	}
+}
+
+/************************* 注册装饰器 **********************************/
+
+registerDecorate('copy-button', pre => {
+	let clipboardRef: ClipboardAPI.RootRef;
+
+	return (
+		<Button.Root class={styles.copy} square kind="flat" onclick={() => clipboardRef.writeText(pre.dataset.code ?? '')}>
+			<ClipboardAPI.Root ref={el => (clipboardRef = el)} />
+		</Button.Root>
+	);
+});
+
+registerDecorate('toolbar', pre => {
+	let clipboardRef: ClipboardAPI.RootRef;
+
+	// 不需要考虑组件卸载之后如何改回原始的情况。
+	// 因为生成的代码就已经固定了 decorate 属性，不会动态切换。
+	pre.style.flexDirection = 'column-reverse';
+
+	return (
+		<header class={styles.toolbar}>
+			<span>{pre.dataset.lang}</span>
+			<div class={styles.actions}>
+				<Button.Root
+					class={styles.btn}
+					square
+					kind="flat"
+					onclick={() => clipboardRef.writeText(pre.dataset.code ?? '')}
+				>
+					<ClipboardAPI.Root ref={el => (clipboardRef = el)} />
+				</Button.Root>
+			</div>
+		</header>
+	);
+});
+
+registerDecorate('border', pre => {
+	pre.style.border = '1px solid var(--palette-border)';
+	return '';
+});

packages/components/src/code/mod.ts

@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: MIT
 
+export type { Decorate } from './decorate';
+export { getDecorates as decorates, registerDecorate, withDecorate } from './decorate';
 export type { Props as RootProps, Ref as RootRef } from './root';
 export { Root } from './root';
-export { buildHighlighter, type Highlighter, highlight, withCopyButton } from './shiki';
+export { buildHighlighter, type Highlighter, highlight } from './shiki';

packages/components/src/code/root.tsx

@@ -7,7 +7,8 @@ import { createEffect, createSignal, type JSX } from 'solid-js';
 import { template } from 'solid-js/web';
 
 import { type BaseProps, type BaseRef, joinClass, type RefProps } from '@components/base';
-import { highlight, withCopyButton } from './shiki';
+import { withDecorate } from './decorate';
+import { highlight } from './shiki';
 
 export type Ref = BaseRef<HTMLElement>;
 
@@ -63,6 +64,14 @@ export interface Props extends BaseProps, RefProps<Ref> {
 	 * @reactive
 	 */
 	theme?: BundledTheme;
+
+	/**
+	 * 装饰器名称
+	 *
+	 * @remarks
+	 * 该值可由 {@link getDecorates} 获取。
+	 */
+	decorates?: Array<string>;
 }
 
 /**
@@ -77,7 +86,16 @@ export function Root(props: Props): JSX.Element {
 
 	createEffect(async () => {
 		const cls = joinClass(props.palette, props.class);
-		const pre = await highlight(props.children, props.lang, props.ln, props.wrap, cls, props.style, props.theme);
+		const pre = await highlight(
+			props.children,
+			props.lang,
+			props.ln,
+			props.wrap,
+			cls,
+			props.style,
+			props.theme,
+			props.decorates?.join(','),
+		);
 		setHTML(template(pre)() as HTMLElement);
 
 		if (props.ref) {
@@ -102,7 +120,7 @@ export function Root(props: Props): JSX.Element {
 			}
 		});
 
-		withCopyButton(el);
+		withDecorate(el);
 	});
 
 	return <>{html()}</>;