CodeBlock 代码块

专门用于展示格式化代码或脚本的卡片式容器。内置 Prism 语法高亮，具有高对比度的顶栏、复制动作反馈、并支持开启行号。

预览

Preview

JavaScript + 行号

javascriptapp.js

123456

TypeScript

typescriptuser.ts

Python + 行号

pythonfibonacci.py

1234567891011121314

折叠与展开（maxLines）

javascriptquicksort.js

12345678910

安装

pnpm dlx brutx-vue@latest add code-block

依赖提示

CodeBlock 的语法高亮功能依赖 prismjs（可选 peer 依赖）。如果未安装，组件会自动降级为纯文本渲染。

pnpm add prismjs

用法

<script setup>
import { CodeBlock } from 'brutx-ui-vue/code-block'

const codeString = `const app = createApp(App)
app.mount('#app')`
</script>

<template>
    <CodeBlock
        :code="codeString"
        language="javascript"
        filename="main.js"
        show-line-numbers
    />
</template>

折叠与展开

通过 maxLines 属性可以限制代码区域的最大可见行数。当代码实际行数大于 maxLines 时，代码区域会被裁剪到指定行数，并在底部展示"展开"按钮；展开后按钮切换为"收起"，再次点击可恢复折叠。展开/收起按钮的文本通过 useLocale() 的 t() 国际化，默认为"展开"/"收起"。

<script setup>
import { CodeBlock } from 'brutx-ui-vue/code-block'

const longCode = `function quickSort(arr) {
    if (arr.length <= 1) return arr
    const pivot = arr[0]
    const left = arr.slice(1).filter(x => x < pivot)
    const right = arr.slice(1).filter(x => x >= pivot)
    return [...quickSort(left), pivot, ...quickSort(right)]
}

const sorted = quickSort([3, 1, 4, 1, 5, 9, 2, 6])
console.log(sorted)`
</script>

<template>
    <CodeBlock
        :code="longCode"
        language="javascript"
        filename="quicksort.js"
        :max-lines="6"
    />
</template>

说明

maxLines 默认为 undefined，此时不做任何裁剪；只有当代码实际行数超过该值时才会出现展开/收起按钮。裁剪同时作用于行号栏与代码主体，按钮使用 Button 组件（variant="outline" size="sm"）。

功能特性

• 语法高亮：内置 Prism 语法高亮引擎，支持 JavaScript、TypeScript、Python、Rust、Go 等 20+ 种语言。语言语法按需加载，未使用的语言零体积。
• 一键复制：右上角无缝集成了 CopyToClipboard 按钮，并在复制成功后提供触感物理动画及文本反馈。
• 行号支持：配置 show-line-numbers 属性为 true 后，会自动在左侧展示行号列表，且行号栏伴有经典的右侧实心线条分割。
• 折叠展开：通过 maxLines 属性限制代码区域可见行数，超出部分自动裁剪并提供"展开"/"收起"按钮，适合在有限空间内展示长代码。
• 插槽扩展：使用默认插槽可跳过内置高亮，直接渲染自定义 HTML 内容（如使用 Shiki 等其他高亮引擎时）。
• 自动降级：prismjs 为可选依赖，未安装时组件自动降级为纯文本渲染；传入不支持的语言时同样降级为纯文本。

支持的语言

language 属性支持以下语言（含常见别名）：

语言	可用值
HTML / XML / SVG	markup, html, xml, svg
CSS	css, scss
JavaScript	javascript, js
TypeScript	typescript, ts
JSX / TSX	jsx, tsx
JSON	json
Bash / Shell	bash, sh, shell
Python	python, py
SQL	sql
Java	java
C / C++	c, cpp
Go	go
Rust	rust
YAML	yaml, yml
Markdown	markdown, md

如需额外语言，可自行导入对应的 Prism 语法文件：

import 'prismjs/components/prism-dart'

自定义高亮配色

高亮颜色通过 --brutal-code-* CSS 变量控制，与 --brutal-primary 等设计令牌解耦，便于在任意主题下结合背景色校准对比度。可通过覆盖这些变量自定义配色：

基础代码文本色由 --brutal-code-foreground 控制，亮色下默认跟随 --brutal-fg，暗色下主题已覆盖为 #f3f4f6：

:root {
    --brutal-code-keyword: #00838f;
    --brutal-code-function: #c62828;
    --brutal-code-string: #2e7d32;
    --brutal-code-number: #c0392b;
    --brutal-code-comment: #6b7280;
    --brutal-code-operator: #1565c0;
    --brutal-code-variable: #9c27b0;
    --brutal-code-punctuation: #4b5563;
}

.dark {
    --brutal-code-foreground: #f3f4f6;
    --brutal-code-keyword: #26c6da;
    --brutal-code-function: #ff7043;
    --brutal-code-string: #66bb6a;
    --brutal-code-number: #ef5350;
    --brutal-code-comment: #9ca3af;
    --brutal-code-operator: #42a5f5;
    --brutal-code-variable: #ce93d8;
    --brutal-code-punctuation: #d1d5db;
}

API 参考

CodeBlock — 属性

名称	类型	默认值	说明
code 必填	string	—	必填的原始代码文本，用于内置语法高亮、行号和复制操作。
详情 声明类型 string 默认值详情 未声明默认值 — 来源 CodeBlock.vue:18 packages/ui/src/components/code-block/CodeBlock.vue
language	string | undefined	undefined	设置语法高亮语言和顶栏徽章；未指定时按 plaintext 处理，支持的语言及别名见页面语言列表。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/code-block/CodeBlock.vue 解析值 undefined 来源 CodeBlock.vue:19 packages/ui/src/components/code-block/CodeBlock.vue
filename	string | undefined	undefined	在代码块顶栏显示文件名或路径。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/code-block/CodeBlock.vue 解析值 undefined 来源 CodeBlock.vue:20 packages/ui/src/components/code-block/CodeBlock.vue
showLineNumbers	boolean | undefined	false	在代码左侧显示与 code 文本行数对应的行号。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/code-block/CodeBlock.vue 解析值 false 来源 CodeBlock.vue:21 packages/ui/src/components/code-block/CodeBlock.vue
maxLines	number | undefined	undefined	限制折叠状态下可见的最大代码行数；超出时提供展开和收起操作，未设置时不限制。
详情 声明类型 number | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/code-block/CodeBlock.vue 解析值 undefined 来源 CodeBlock.vue:22 packages/ui/src/components/code-block/CodeBlock.vue
class	string | undefined	undefined	追加到代码卡片根容器的 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/code-block/CodeBlock.vue 解析值 undefined 来源 CodeBlock.vue:23 packages/ui/src/components/code-block/CodeBlock.vue

CodeBlock — 插槽

名称	签名或类型	说明
#default	{}	可选的自定义代码渲染内容；提供后跳过内置 Prism 高亮并直接渲染插槽。复制文本和行号仍以 code 属性为准。
详情 声明类型 {} 来源 CodeBlock.vue packages/ui/src/components/code-block/CodeBlock.vue

插槽

插槽与 code prop 的契约

使用默认插槽时，复制按钮复制的文本与行号仍基于 code prop（而非插槽渲染内容）。若插槽内容与 code 不一致，行号会与展示内容错位、复制的也是 code 的文本。请确保传入的 code 与插槽内容保持一致（例如都传入同一份代码文本），或仅在无需行号/复制的场景使用插槽。

可访问性

• 键盘操作：复制按钮和展开/收起按钮支持 Tab 键聚焦，Enter/Space 键触发
• ARIA 属性：复制按钮自动设置 aria-label，提供操作说明
• 语义化标记：代码内容使用 <pre> 和 <code> 标签包裹，符合语义化标准
• 高对比度：语法高亮配色通过 CSS 变量控制，确保在深色/浅色主题下均满足对比度要求