代码

展示行内代码与代码块

​

添加代码示例

你可以添加内联代码片段或代码块。代码块支持用于语法高亮、标题、行高亮、图标等的元参数。

​

行内代码

要将 word 或 phrase 标记为代码，请用反引号（`）将其括起来。

要将 `word` 或 `phrase` 标记为代码，请用反引号 (`) 将其包围。

​

代码块

使用围栏代码块，将代码用三个反引号包裹起来。代码块可复制；如果启用了文档助手，用户还可以让 AI 解释代码。

为语法高亮指定编程语言，并启用元选项。在语言后添加任意元选项，如标题或图标。

HelloWorld.java

class HelloWorld {
    public static void main(String[] args) {
        System.out.println("你好，世界！");
    }
}

```java HelloWorld.java lines icon="java"
class HelloWorld {
    public static void main(String[] args) {
        System.out.println("你好，世界！");
    }
}
```

​

代码块选项

你可以为代码块添加元选项来自定义其外观。

在添加任何其他元选项之前，你必须先为代码块指定编程语言。

​

选项语法

• 字符串与布尔选项：可用 ""、''，或不加引号进行包裹。
• 表达式选项：可用 {}、"" 或 '' 进行包裹。

​

语法高亮

在代码块的起始反引号后注明编程语言即可启用语法高亮。

我们使用 Shiki 提供语法高亮，并支持其所有可用语言。请参阅 Shiki 文档中的完整语言列表。

在 docs.json 的 styling.codeblocks 中可全局自定义代码块主题。可设置如 system 或 dark 的简单主题，或为明暗模式配置自定义的 Shiki 主题。详细配置选项见 Settings。

class HelloWorld {
    public static void main(String[] args) {
        System.out.println("你好，世界！");
    }
}

```java
class HelloWorld {
    public static void main(String[] args) {
        System.out.println("你好，世界！");
    }
}
```

​

标题

为代码示例添加标题。使用 title="Your title" 或在单独一行提供字符串。

Code Block Example

const hello = "world";

```javascript 代码块示例
const hello = "world";
```

​

图标

使用 icon 属性为代码块添加图标。参见 Icons 查看所有可用选项。

const hello = "world";

```javascript icon="square-js"
const hello = "world";
```

​

行高亮

在代码块中使用 highlight，通过指定要突出显示的行号或范围来高亮特定行。

Line Highlighting Example

const greeting = "你好，世界！";
function sayHello() {
  console.log(greeting);
}
sayHello();

```javascript 行高亮示例 highlight={1-2,5}
const greeting = "Hello, World!";
function sayHello() {
  console.log(greeting);
}
sayHello();
```

​

行聚焦

在代码块中使用 focus 搭配行号或范围来高亮特定行。

Line Focus Example

const greeting = "你好，世界！";
function sayHello() {
  console.log(greeting);
}
sayHello();

```javascript 行聚焦示例 focus={2,4-5}
const greeting = "Hello, World!";
function sayHello() {
  console.log(greeting);
}
sayHello();
```

​

显示行号

使用 lines 在代码块左侧显示行号。

Show Line Numbers Example

const greeting = "你好，世界！";
function sayHello() {
  console.log(greeting);
}
sayHello();

```javascript 显示行号示例
const greeting = "Hello, World!";
function sayHello() {
  console.log(greeting);
}
sayHello();
```

​

可展开

使用 expandable 让用户展开或折叠较长的代码块。

Expandable Example

from datetime import datetime, timedelta
from typing import Dict, List, Optional
from dataclasses import dataclass

@dataclass
class Book:
    title: str
    author: str
    isbn: str
    checked_out: bool = False
    due_date: Optional[datetime] = None

class Library:
    def __init__(self):
        self.books: Dict[str, Book] = {}
        self.checkouts: Dict[str, List[str]] = {}  # 借阅者 -> ISBN列表

    def add_book(self, book: Book) -> None:
        if book.isbn in self.books:
            raise ValueError(f"ISBN为 {book.isbn} 的图书已存在")
        self.books[book.isbn] = book

    def checkout_book(self, isbn: str, patron: str, days: int = 14) -> None:
        if patron not in self.checkouts:
            self.checkouts[patron] = []

        book = self.books.get(isbn)
        if not book:
            raise ValueError("未找到图书")

        if book.checked_out:
            raise ValueError("图书已被借出")

        if len(self.checkouts[patron]) >= 3:
            raise ValueError("借阅者已达到借阅限制")

        book.checked_out = True
        book.due_date = datetime.now() + timedelta(days=days)
        self.checkouts[patron].append(isbn)

    def return_book(self, isbn: str) -> float:
        book = self.books.get(isbn)
        if not book or not book.checked_out:
            raise ValueError("未找到图书或图书未被借出")

        late_fee = 0.0
        if datetime.now() > book.due_date:
            days_late = (datetime.now() - book.due_date).days
            late_fee = days_late * 0.50

        book.checked_out = False
        book.due_date = None

        # Remove from patron's checkouts
        # 从借阅者的借阅记录中移除
            if isbn in books:
                books.remove(isbn)
                break

        return late_fee

    def search(self, query: str) -> List[Book]:
        query = query.lower()
        return [
            book for book in self.books.values()
            if query in book.title.lower() or query in book.author.lower()
        ]

def main():
    library = Library()

    # 添加一些图书
    books = [
        Book("The Hobbit", "J.R.R. Tolkien", "978-0-261-10295-4"),
        Book("1984", "George Orwell", "978-0-452-28423-4"),
    ]

    for book in books:
        library.add_book(book)

    # 借阅和归还示例
    library.checkout_book("978-0-261-10295-4", "patron123")
    late_fee = library.return_book("978-0-261-10295-4")
    print(f"滞纳金: ${late_fee:.2f}")

if __name__ == "__main__":
    main()

```python 可展开示例 expandable
from datetime import datetime, timedelta
from typing import Dict, List, Optional
from dataclasses import dataclass

# ...

if __name__ == "__main__":
    main()
```

​

Wrap

使用 wrap 为长行启用自动换行。这样可避免水平滚动，并使长行更易读。

Wrap Example

const greeting = "你好，世界！我是一行很长的文本，会换行到下一行。";
function sayHello() {
  console.log(greeting);
}
sayHello();

```javascript Wrap Example wrap
const greeting = "你好，世界！我是一行很长的文本，会换行到下一行。";
function sayHello() {
  console.log(greeting);
}
sayHello();
```

​

Diff

在代码块中直观展示新增或删除的行。新增行以绿色高亮，删除行以红色高亮。

要创建 diff，请在代码块的行尾添加以下特殊注释：

• // [!code ++]: 将该行标记为新增（绿色高亮）。
• // [!code --]: 将该行标记为删除（红色高亮）。

对于多行连续更改，可在冒号后指定行数：

• // [!code ++:3]: 将当前行及其后两行标记为新增。
• // [!code --:5]: 将当前行及其后四行标记为删除。

注释语法必须与所用编程语言一致（例如，JavaScript 使用 //，Python 使用 #）。

Diff Example

const greeting = "Hello, World!"; 
function sayHello() {
  console.log("Hello, World!"); 
  console.log(greeting); 
}
sayHello();

```js 差异示例 icon="code" lines
const greeting = "Hello, World!"; // [!code ++]
function sayHello() {
  console.log("Hello, World!"); // [!code --]
  console.log(greeting); // [!code ++]
}
sayHello();
```