Astro 框架下 Expressive Code 的基础用法

26 年 3 月 25 日星期三

(已编辑)

1972 字

10 分钟

前端开发 / Astro

Astro Expressive Code 代码高亮前端开发

Expressive Code 简介

Expressive Code 是一个用于在网页上展示源代码的引擎，它基于 VS Code 同款的 Shiki 语法高亮引擎，提供精确的语法高亮，同时支持代码注释、差异高亮、编辑器/终端窗口框架等丰富功能。

在 Astro 框架中，Expressive Code 通过 astro-expressive-code 集成包提供支持，可以自动渲染 Markdown/MDX 文件中的代码块，并提供 <Code> 组件用于动态渲染代码。

本文只涉及一些常见的配置方法和用法，更加详细的使用说明，请查阅官方文档

安装与配置

安装依赖

在 Astro 项目中安装 Expressive Code 集成：

1
npm install astro-expressive-code
2
# 或
3
yarn add astro-expressive-code
4
# 或
5
pnpm add astro-expressive-code

配置 astro

直接集成

在 astro.config.mathrmjs 中添加 Expressive Code 集成：

1
import { defineConfig } from 'astro/config'
2
import expressiveCode from 'astro-expressive-code'
3

4
export default defineConfig({
5
  integrations: [
6
    expressiveCode({
7
      // 配置选项
8
      themes: ['github-dark', 'github-light'],
9
      styleOverrides: {
10
        borderRadius: '0.5rem',
11
      },
12
    }),
13
  ],
14
})

使用配置文件

在项目根目录下创建 ec.config.mjs 文件单独存放配置信息：

1
import { defineEcConfig } from 'astro-expressive-code'
2

3
export default defineEcConfig({
4
  // 配置选项
5
  themes: ['github-dark', 'github-light'],
6
  styleOverrides: {
7
    borderRadius: '0.5rem',
8
  },
9
})

两种方法的配置语法几乎一致，接下来我们默认按照使用配置文件的方式来举例

基础的代码块用法

Markdown 代码块用法

在 Markdown/MDX 文件中，使用标准的代码块语法即可自动获得语法高亮：

1
```javascript
2
function hello(name) {
3
  console.log(`Hello, ${name}!`)
4
}
5
```

渲染效果如下：

1
function hello(name) {
2
  console.log(`Hello, ${name}!`)
3
}

指定语言的语法高亮

Expressive Code 支持超过 100 种编程语言，只需在开头的代码围栏后添加语言标识：

1
```python
2
def fibonacci(n):
3
    if n <= 1:
4
        return n
5
    return fibonacci(n-1) + fibonacci(n-2)
6
```

渲染效果如下：

1
def fibonacci(n):
2
    if n <= 1:
3
        return n
4
    return fibonacci(n-1) + fibonacci(n-2)

Expressive Code 使用 Shiki 作为语法高亮的解释器，可以访问 Shiki 的官方文档查看其默认支持的所有内置语言

代码块标题

使用 title 属性为代码块添加标题：

1
```js title="hello.js"
2
console.log('Hello, World!')
3
```

渲染效果如下：

1
console.log('Hello, World!')

而不添加标题属性的渲染效果如下：

1
console.log('Hello, World!')

在 Markdown 语法中，有时会通过在第一行添加注释的方式来确定标题
markdown
1
```js
2
//hello.js
3
console.log('Hello, World!')
4
```
渲染效果如下：
hello.js
1
console.log('Hello, World!')

使用 `<Code>` 组件

在 .astro 或 .mdx 文件中，可以导入并使用 <Code> 组件来渲染代码块：

在 .astro 文件中：

1
---
2
import { Code } from 'astro-expressive-code'
3

4
const codeString = `function add(a, b) {
5
  return a + b;
6
}`
7
---
8

9
<Code code={codeString} lang="javascript" />

在 .mdx 文件中：

1
import { Code } from 'astro-expressive-code'
2

3
<Code code="console.log('Hello!');" lang="javascript" />

从文件导入代码

除此之外，代码块的内容还可以直接链接到外部文件，即使用 Vite 的 ?raw 后缀将代码文件作为字符串导入：

1
---
2
import { Code } from 'astro-expressive-code'
3
import exampleCode from './examples/example.js?raw'
4
---
5

6
<Code code={exampleCode} lang="javascript" title="example.js" />

<Code> 组件支持传入以下常用的属性：

属性	类型	说明
`code`	`string`	代码内容（必填）
`lang`	`string`	编程语言标识（用于语法高亮）
`title`	`string`	代码块标题
`frame`	`'auto'\|'code'\|'terminal'\|'none'`	框架类型
`wrap`	`boolean`	是否启用自动换行
`mark`	`MarkerDefinition[]`	普通标记
`ins`	`MarkerDefinition[]`	插入标记（绿色）
`del`	`MarkerDefinition[]`	删除标记（红色）

文本与行标记

Expressive Code 支持在代码块中标记特定的行或文本片段。

整行标记

在代码块元信息中用 { } 指定行号来进行标记：

1
```js {2, 4-6}
2
function processData(data) {
3
  if (!data) return null
4

5
  const result = data.map((item) => {
6
    return item.value * 2
7
  })
8

9
  return result
10
}
11
```

渲染效果如下：

1
function processData(data) {
2
  if (!data) return null
3

4
  const result = data.map((item) => {
5
    return item.value * 2
6
  })
7

8
  return result
9
}

需要注意的是，如果代码块的标题是通过如前所述的第一行注释的方式来设置的，花括号里的行号需要 +1，例如：

1
```js {5-9}
2
// ec.config.mjs
3
import { defineEcConfig } from 'astro-expressive-code'
4

5
export default defineEcConfig({
6
  // 配置选项
7
  themes: ['github-dark', 'github-light'],
8
  styleOverrides: {
9
    borderRadius: '0.5rem',
10
  },
11
})
12
```

其渲染效果如下：

1
import { defineEcConfig } from 'astro-expressive-code'
2

3
export default defineEcConfig({
4
  // 配置选项
5
  themes: ['github-dark', 'github-light'],
6
  styleOverrides: {
7
    borderRadius: '0.5rem',
8
  },
9
})

标记类型

整行的标记还有两种衍生类型： ins={ } （插入 insert）、 del={ } （删除 delete），例如：

1
```js ins={2} del={4-5}
2
function processData(data) {
3
  if (!data) return []
4

5
  const result = data.map((item) => {
6
    return item.value
7
  })
8

9
  return result
10
}
11
```

1
function processData(data) {
2
  if (!data) return []
3

4
  const result = data.map((item) => {
5
    return item.value
6
  })
7

8
  return result
9
}

添加标签

此外，还可以为标记的行添加标签：

1
```js ins={"新增":2} mark={"关键":4-6}
2
function processData(data) {
3
  if (!data) return null
4

5
  const result = data.map((item) => {
6
    return item.value * 2
7
  })
8

9
  return result
10
}
11
```

1
function processData(data) {
2
  if (!data) return null
3

4
  const result = data.map((item) => {
5
    return item.value * 2
6
  })
7

8
  return result
9
}

Diff 语法

可以使用 diff 语言快速的创建插入和删除标记：

1
```diff
2
function processData(data) {
3
-  if (!data) return null;
4
+  if (!data) return [];
5

6
  const result = data.map(item => {
7
    return item.value * 2;
8
  });
9

10
  return result;
11
}
12
```

1
function processData(data) {
2
  if (!data) return null;
3
  if (!data) return [];
4

5
  const result = data.map(item => {
6
    return item.value * 2;
7
  });
8

9
  return result;
10
}

行内文本标记

可以使用字符串或者正则表达式来标记行内的特定文本：

1
```js "return" /data/
2
function processData(data) {
3
  if (!data) return null
4
  return data
5
}
6
```

1
function processData(data) {
2
  if (!data) return null
3
  return data
4
}

代码框架的插件

Expressive Code 内置了一些框架的插件，可以将代码块渲染成编辑器或者终端等风格。

终端风格

使用 frame="terminal" 可以获得终端窗口的风格：

1
```bash frame="terminal" title="~"
2
npm install astro-expressive-code
3
```

1
npm install astro-expressive-code

也可以直接通过声明语言为 bash 来调整成终端风格：
markdown
1
```bash
2
npm install astro-expressive-code
3
```
Terminal window
1
npm install astro-expressive-code

编辑器风格

默认风格是编辑器样式，也可以显式指定 frame="code"：

1
```js frame="code" title="app.js"
2
import { Code } from 'astro-expressive-code'
3
```

1
import { Code } from 'astro-expressive-code'

无框架风格

设置 frame="none" 可以移除框架，只显示代码：

1
```js frame="none" title="js"
2
console.log('No frame')
3
```

1
console.log('No frame')

可见这种风格不会显示标题等内容，不过高亮和标记仍然会显示。

配置颜色主题

配置内置主题

可以通过传递 theme 选项来配置内置的颜色主题：

1
expressiveCode({
2
  themes: ['github-dark', 'github-light'],
3
  useDarkModeMediaQuery: true, // 自动响应系统主题，如要根据网页主题切换需要设为 false 并自行配置
4
})

自定义样式覆盖

可以使用 styleOverrides 来自定义代码块的外观：

1
expressiveCode({
2
  styleOverrides: {
3
    borderRadius: '0.75rem',
4
    borderWidth: '1px',
5
    codeFontSize: '0.875rem',
6
    frames: {
7
      shadowColor: 'rgba(0, 0, 0, 0.1)',
8
    },
9
  },
10
})

可以访问 Expressive Code 的官方文档查看支持自定义的所有参数

进阶使用以及常用插件

更多的使用技巧以及插件可以访问 Expressive Code 的官方文档详细了解，这里只列举一些常用的插件以及技巧

行号插件

默认的代码块不显示行号，如果想加上的话，可以通过以下指令安装插件：

1
npm i @expressive-code/plugin-line-numbers
2
# 或
3
pnpm add @expressive-code/plugin-line-numbers
4
# 或
5
yarn add @expressive-code/plugin-line-numbers

然后向 ec.config.mjs 中导入并声明这个插件

1
import { defineEcConfig } from 'astro-expressive-code'
2
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'
3

4
export default defineEcConfig({
5
  plugins: [pluginLineNumbers()],
6
})

这样就可以通过参数 showLineNumbers: boolean （默认为 true）来开关显示行号了

1
```js showLineNumbers
2
// This code block will show line numbers
3
console.log('Greetings from line 2!')
4
console.log('I am on line 3')
5
```
6

7
```js showLineNumbers=false
8
// Line numbers are disabled for this block
9
console.log('Hello?')
10
console.log('Sorry, do you know what line I am on?')
11
```

渲染效果分别如下

1
// This code block will show line numbers
2
console.log('Greetings from line 2!')
3
console.log('I am on line 3')

// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')

也可以使用 startLineNumber: numbers （默认为 1 ）来调整行号起始的编号

1
```js showLineNumbers startLineNumber=5
2
console.log('Greetings from line 5!')
3
console.log('I am on line 6')
4
```

5
console.log('Greetings from line 5!')
6
console.log('I am on line 6')

当然，我们也可以向 ec.config.mjs 传递默认的参数来调控行号的显示：

1
import { defineEcConfig } from 'astro-expressive-code'
2
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'
3

4
export default defineEcConfig({
5
  plugins: [pluginLineNumbers()],
6
  defaultProps: {
7
    // Disable line numbers by default
8
    showLineNumbers: false,
9
    // But enable line numbers for certain languages
10
    overridesByLang: {
11
      'js,ts,html': {
12
        showLineNumbers: true,
13
      },
14
    },
15
  },
16
})

或者行号的样式：

1
import { defineEcConfig } from 'astro-expressive-code'
2
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'
3

4
export default defineEcConfig({
5
  plugins: [pluginLineNumbers()],
6
  styleOverrides: {
7
    lineNumbers: {
8
      // Example: Change the line number foreground colors
9
      foreground: '#578298a6',
10
      highlightForeground: '#85c7ebb3',
11
    },
12
  },
13
})

Astro Expressive Code 代码高亮前端开发

·文章标题：Astro 框架下 Expressive Code 的基础用法

·文章作者：NeoWangKing

·文章概要：本文介绍在 Astro 框架中使用 Expressive Code 的方法，包括安装配置、基础代码块渲染、动态代码组件、文本标记功能、代码框架插件等核心特性，帮助你在博客或文档中优雅地展示代码。

·文章链接：https://www.neowangking.top/posts/front-end/astro/expressive-code-basics[点击复制]

·上次修改：

商业转载请联系站长获得授权，非商业转载请注明本文出处及文章链接，您可以自由地在任何媒体以任何形式复制和分发作品，也可以修改和创作，但是分发衍生作品时必须采用相同的许可协议。
本文采用CC BY-NC-SA 4.0进行许可。

Astro 框架中配置与使用 Tailwind CSS

单层 TMD 材料的三能带紧束缚模型构建

Expressive Code 简介

安装与配置

安装依赖

配置 astro

直接集成

使用配置文件

基础的代码块用法

Markdown 代码块用法

指定语言的语法高亮

代码块标题

使用 <Code> 组件

从文件导入代码

文本与行标记

整行标记

标记类型

添加标签

Diff 语法

行内文本标记

代码框架的插件

终端风格

编辑器风格

无框架风格

配置颜色主题

配置内置主题

自定义样式覆盖

进阶使用以及常用插件

行号插件

使用 `<Code>` 组件