mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
c789e88df2
* docs(locadex): add translations * Apply suggestion from @ethanpalm * Apply suggestion from @ethanpalm --------- Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
550 lines
14 KiB
Plaintext
550 lines
14 KiB
Plaintext
---
|
||
title: "格式化代码"
|
||
description: "显示和自定义行内代码与代码块的样式。"
|
||
keywords: ["代码块", "语法高亮", "代码样式"]
|
||
---
|
||
|
||
<div id="adding-code-samples">
|
||
## 添加代码示例
|
||
</div>
|
||
|
||
你可以添加行内代码片段或代码块。代码块支持用于语法高亮、title、行高亮、icon 等的元选项。
|
||
|
||
<div id="inline-code">
|
||
### 行内代码
|
||
</div>
|
||
|
||
要将某个 `word` 或 `phrase` 标记为代码，请用反引号 (`) 将其括起来。
|
||
|
||
```mdx
|
||
要将 `word` 或 `phrase` 标记为代码,请用反引号(`)将其括起来。
|
||
```
|
||
|
||
<div id="code-blocks">
|
||
### 代码块
|
||
</div>
|
||
|
||
使用[围栏代码块](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks)：将代码包裹在三个反引号中。代码块支持复制，如果你启用了 AI 助手，用户可以让 AI 解释代码。
|
||
|
||
指定编程语言，以启用语法高亮和元选项。在语言后添加任意元选项，比如 title 或 icon。
|
||
|
||
<CodeGroup>
|
||
```java HelloWorld.java example icon=java lines
|
||
class HelloWorld {
|
||
public static void main(String[] args) {
|
||
System.out.println("Hello, World!");
|
||
}
|
||
}
|
||
```
|
||
|
||
````mdx Format
|
||
```java HelloWorld.java example lines icon="java"
|
||
class HelloWorld {
|
||
public static void main(String[] args) {
|
||
System.out.println("Hello, World!");
|
||
}
|
||
}
|
||
```
|
||
````
|
||
</CodeGroup>
|
||
|
||
<div id="code-block-options">
|
||
## 代码块选项
|
||
</div>
|
||
|
||
为代码块添加元选项以自定义其展示效果。
|
||
|
||
<Note>
|
||
在添加任何其他元选项之前，必须先为代码块指定编程语言。
|
||
</Note>
|
||
|
||
<div id="option-syntax">
|
||
### 选项语法
|
||
</div>
|
||
|
||
* **字符串和布尔值选项**：可以使用 `""`、`''`，或不加引号括起来。
|
||
* **表达式选项**：使用 `{}`、`""`，或 `''` 括起来。
|
||
|
||
<div id="syntax-highlighting">
|
||
### 语法高亮
|
||
</div>
|
||
|
||
通过在代码块起始反引号后添加编程语言来启用语法高亮。
|
||
|
||
我们使用 [Shiki](https://shiki.style/) 进行语法高亮，并支持所有可用语言。完整的 [语言](https://shiki.style/languages) 列表请参见 Shiki 文档。
|
||
|
||
在 `docs.json` 文件中使用 `styling.codeblocks` 全局自定义代码块主题。可以设置 `system` 或 `dark` 等简单主题，或为浅色和深色模式配置自定义 [Shiki 主题](https://shiki.style/themes)。配置选项参见 [Settings](/zh/organize/settings#param-styling)。
|
||
|
||
<CodeGroup>
|
||
```java Syntax highlighting example
|
||
class HelloWorld {
|
||
public static void main(String[] args) {
|
||
System.out.println("Hello, World!");
|
||
}
|
||
}
|
||
```
|
||
|
||
````mdx Format
|
||
```java Syntax highlighting example
|
||
class HelloWorld {
|
||
public static void main(String[] args) {
|
||
System.out.println("Hello, World!");
|
||
}
|
||
}
|
||
```
|
||
````
|
||
</CodeGroup>
|
||
|
||
<Accordion title="自定义语法高亮主题">
|
||
对于自定义主题，在 `docs.json` 中将主题设置为 `"css-variables"`，并使用带有 `--mint-` 前缀的 CSS 变量覆盖语法高亮颜色。
|
||
|
||
可用的变量如下：
|
||
|
||
**基础颜色**
|
||
|
||
* `--mint-color-text`: 默认文本颜色
|
||
* `--mint-color-background`: 背景颜色
|
||
|
||
**标记颜色**
|
||
|
||
* `--mint-token-constant`: 常量和字面量
|
||
* `--mint-token-string`: 字符串值
|
||
* `--mint-token-comment`: 注释
|
||
* `--mint-token-keyword`: 关键字
|
||
* `--mint-token-parameter`: 函数参数
|
||
* `--mint-token-function`: 函数名
|
||
* `--mint-token-string-expression`: 字符串表达式
|
||
* `--mint-token-punctuation`: 标点符号
|
||
* `--mint-token-link`: 链接
|
||
|
||
**ANSI 颜色**
|
||
|
||
* `--mint-ansi-black`, `--mint-ansi-black-dim`
|
||
* `--mint-ansi-red`, `--mint-ansi-red-dim`
|
||
* `--mint-ansi-green`, `--mint-ansi-green-dim`
|
||
* `--mint-ansi-yellow`, `--mint-ansi-yellow-dim`
|
||
* `--mint-ansi-blue`, `--mint-ansi-blue-dim`
|
||
* `--mint-ansi-magenta`, `--mint-ansi-magenta-dim`
|
||
* `--mint-ansi-cyan`, `--mint-ansi-cyan-dim`
|
||
* `--mint-ansi-white`, `--mint-ansi-white-dim`
|
||
* `--mint-ansi-bright-black`, `--mint-ansi-bright-black-dim`
|
||
* `--mint-ansi-bright-red`, `--mint-ansi-bright-red-dim`
|
||
* `--mint-ansi-bright-green`, `--mint-ansi-bright-green-dim`
|
||
* `--mint-ansi-bright-yellow`, `--mint-ansi-bright-yellow-dim`
|
||
* `--mint-ansi-bright-blue`, `--mint-ansi-bright-blue-dim`
|
||
* `--mint-ansi-bright-magenta`, `--mint-ansi-bright-magenta-dim`
|
||
* `--mint-ansi-bright-cyan`, `--mint-ansi-bright-cyan-dim`
|
||
* `--mint-ansi-bright-white`, `--mint-ansi-bright-white-dim`
|
||
|
||
**自定义语法高亮**
|
||
|
||
通过提供自定义 TextMate 语法文件，为 Shiki 默认集合中未包含的语言添加语法高亮。创建一个遵循 [TextMate 语法格式](https://macromates.com/manual/en/language_grammars) 的 JSON 文件，然后在 `docs.json` 中引用它。你可以在数组中添加更多路径，以支持多个自定义语言。
|
||
|
||
```json docs.json
|
||
{
|
||
"styling": {
|
||
"codeblocks": {
|
||
"languages": {
|
||
"custom": ["/languages/my-custom-language.json"]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
</Accordion>
|
||
|
||
<div id="twoslash">
|
||
### Twoslash
|
||
</div>
|
||
|
||
在 JavaScript 和 TypeScript 代码块中，使用 `twoslash` 来启用交互式类型信息。用户可以像在 IDE 中一样，将鼠标悬停在变量、函数和参数上查看类型和错误。
|
||
|
||
<CodeGroup>
|
||
```ts twoslash Twoslash example
|
||
type Pet = "cat" | "dog" | "hamster";
|
||
|
||
function adoptPet(name: string, type: Pet) {
|
||
return `${name} the ${type} is now adopted!`;
|
||
}
|
||
|
||
// 将鼠标悬停以查看推断类型
|
||
const message = adoptPet("Mintie", "cat");
|
||
```
|
||
|
||
````mdx Format
|
||
```ts twoslash Twoslash example
|
||
type Pet = "cat" | "dog" | "hamster";
|
||
|
||
function adoptPet(name: string, type: Pet) {
|
||
return `${name} the ${type} is now adopted!`;
|
||
}
|
||
|
||
// 将鼠标悬停以查看推断类型
|
||
const message = adoptPet("Mintie", "cat");
|
||
```
|
||
````
|
||
</CodeGroup>
|
||
|
||
<div id="title">
|
||
### 标题
|
||
</div>
|
||
|
||
为你的代码示例添加一个标题说明。使用 `title="Your title"` 或在单独一行写入字符串。
|
||
|
||
<CodeGroup>
|
||
```javascript 标题示例
|
||
const hello = "world";
|
||
```
|
||
|
||
````mdx 格式
|
||
```javascript 标题示例
|
||
const hello = "world";
|
||
```
|
||
````
|
||
</CodeGroup>
|
||
|
||
<div id="icon">
|
||
### 图标
|
||
</div>
|
||
|
||
使用 `icon` 属性为代码块添加图标。所有可用选项请参见 [图标](/zh/components/icons)。
|
||
|
||
<CodeGroup>
|
||
```javascript Icon example icon=square-js
|
||
const hello = "world";
|
||
```
|
||
|
||
````mdx Format
|
||
```javascript Icon example icon="square-js"
|
||
const hello = "world";
|
||
```
|
||
````
|
||
</CodeGroup>
|
||
|
||
<div id="line-highlighting">
|
||
### 行高亮
|
||
</div>
|
||
|
||
在代码块中使用带有行号或范围的 `highlight` 来高亮特定行。
|
||
|
||
<CodeGroup>
|
||
```javascript Line highlighting example {1,2,5}
|
||
const greeting = "Hello, World!";
|
||
function sayHello() {
|
||
console.log(greeting);
|
||
}
|
||
sayHello();
|
||
```
|
||
|
||
````mdx Format
|
||
```javascript Line highlighting example highlight={1-2,5}
|
||
const greeting = "Hello, World!";
|
||
function sayHello() {
|
||
console.log(greeting);
|
||
}
|
||
sayHello();
|
||
```
|
||
````
|
||
</CodeGroup>
|
||
|
||
<div id="line-focusing">
|
||
### 行聚焦
|
||
</div>
|
||
|
||
在代码块中使用带行号或行范围的 `focus` 来聚焦特定行。
|
||
|
||
<CodeGroup>
|
||
```javascript 行聚焦示例 focus=2,4,5
|
||
const greeting = "Hello, World!";
|
||
function sayHello() {
|
||
console.log(greeting);
|
||
}
|
||
sayHello();
|
||
```
|
||
|
||
````mdx 格式
|
||
```javascript 行聚焦示例 focus={2,4-5}
|
||
const greeting = "Hello, World!";
|
||
function sayHello() {
|
||
console.log(greeting);
|
||
}
|
||
sayHello();
|
||
```
|
||
````
|
||
</CodeGroup>
|
||
|
||
<div id="show-line-numbers">
|
||
### 显示行号
|
||
</div>
|
||
|
||
使用 `lines` 在代码块左侧显示行号。
|
||
|
||
<CodeGroup>
|
||
```javascript Show line numbers example lines
|
||
const greeting = "Hello, World!";
|
||
function sayHello() {
|
||
console.log(greeting);
|
||
}
|
||
sayHello();
|
||
```
|
||
|
||
````mdx 格式
|
||
```javascript Show line numbers example lines
|
||
const greeting = "Hello, World!";
|
||
function sayHello() {
|
||
console.log(greeting);
|
||
}
|
||
sayHello();
|
||
```
|
||
````
|
||
</CodeGroup>
|
||
|
||
<div id="expandable">
|
||
### 可展开
|
||
</div>
|
||
|
||
允许用户使用 `expandable` 展开和折叠较长的代码块。
|
||
|
||
<CodeGroup>
|
||
```python Expandable example expandable
|
||
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"Book with ISBN {book.isbn} already exists")
|
||
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("Book not found")
|
||
|
||
if book.checked_out:
|
||
raise ValueError("Book is already checked out")
|
||
|
||
if len(self.checkouts[patron]) >= 3:
|
||
raise ValueError("Patron has reached checkout limit")
|
||
|
||
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("Book not found or not checked out")
|
||
|
||
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
|
||
|
||
# 从读者的借阅列表中移除
|
||
for patron, books in self.checkouts.items():
|
||
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: ${late_fee:.2f}")
|
||
|
||
if **name** == "**main**":
|
||
main()
|
||
```
|
||
|
||
````text 格式
|
||
```python Expandable example expandable
|
||
from datetime import datetime, timedelta
|
||
from typing import Dict, List, Optional
|
||
from dataclasses import dataclass
|
||
|
||
# ...
|
||
|
||
if __name__ == "__main__":
|
||
main()
|
||
```
|
||
````
|
||
</CodeGroup>
|
||
|
||
<div id="wrap">
|
||
### 自动换行
|
||
</div>
|
||
|
||
使用 `wrap` 为长行文本启用自动换行。这样可以避免水平滚动，并让长行内容更易阅读。
|
||
|
||
<CodeGroup>
|
||
```javascript Wrap example wrap
|
||
const greeting =
|
||
"Hello, World! I am a long line of text that will wrap to the next line.";
|
||
function sayHello() {
|
||
console.log(greeting);
|
||
}
|
||
sayHello();
|
||
```
|
||
|
||
````mdx Format
|
||
```javascript Wrap example wrap
|
||
const greeting =
|
||
"Hello, World! I am a long line of text that will wrap to the next line.";
|
||
function sayHello() {
|
||
console.log(greeting);
|
||
}
|
||
sayHello();
|
||
```
|
||
````
|
||
</CodeGroup>
|
||
|
||
<div id="diff">
|
||
### Diff
|
||
</div>
|
||
|
||
在你的代码块中以可视化方式展示新增或删除的行。新增行会以绿色高亮，删除行会以红色高亮。
|
||
|
||
要创建 diff，请在代码块中每行末尾添加这些特殊注释：
|
||
|
||
* `// [!code ++]`：将该行标记为新增（绿色高亮）。
|
||
* `// [!code --]`：将该行标记为删除（红色高亮）。
|
||
|
||
对于多行连续的情况，可以在冒号后指定行数：
|
||
|
||
* `// [!code ++:3]`：将当前行和接下来的两行标记为新增。
|
||
* `// [!code --:5]`：将当前行和接下来的四行标记为删除。
|
||
|
||
注释语法必须与你所使用的编程语言相匹配（例如，JavaScript 使用 `//`，Python 使用 `#`）。
|
||
|
||
<CodeGroup>
|
||
```js Diff example lines
|
||
const greeting = "Hello, World!"; // [!code ++]
|
||
function sayHello() {
|
||
console.log("Hello, World!"); // [!code --]
|
||
console.log(greeting); // [!code ++]
|
||
}
|
||
sayHello();
|
||
```
|
||
|
||
````text Format
|
||
```js Diff example lines
|
||
const greeting = "Hello, World!"; // [!code ++]
|
||
function sayHello() {
|
||
console.log("Hello, World!"); // [!code --]
|
||
console.log(greeting); // [!code ++]
|
||
}
|
||
sayHello();
|
||
```
|
||
````
|
||
</CodeGroup>
|
||
|
||
<div id="codeblock-component">
|
||
## CodeBlock 组件
|
||
</div>
|
||
|
||
在自定义 React 组件中使用 `<CodeBlock>` 组件，以编程方式渲染代码块，使其具有与 Markdown 代码块相同的样式和功能。
|
||
|
||
<div id="props">
|
||
### Props
|
||
</div>
|
||
|
||
<ResponseField name="language" type="string">
|
||
用于语法高亮的编程语言。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="filename" type="string">
|
||
要在代码块标题中显示的文件名。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="icon" type="string">
|
||
要在代码块标题中显示的 icon。可用选项请参见 [Icons](/zh/components/icons)。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="lines" type="boolean">
|
||
是否显示行号。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="wrap" type="boolean">
|
||
是否对代码块内容进行换行显示。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="expandable" type="boolean">
|
||
代码块是否可展开。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="highlight" type="string">
|
||
需要高亮的行。请提供数字数组的字符串形式。例如：
|
||
`"[1,3,4,5]"`。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="focus" type="string">
|
||
需要聚焦的行。请提供数字数组的字符串形式。例如：
|
||
`"[1,3,4,5]"`。
|
||
</ResponseField>
|
||
|
||
<div id="example">
|
||
### 示例
|
||
</div>
|
||
|
||
```jsx
|
||
export const CustomCodeBlock = ({
|
||
filename,
|
||
icon,
|
||
language,
|
||
highlight,
|
||
children,
|
||
}) => {
|
||
return (
|
||
<CodeBlock
|
||
filename={filename}
|
||
icon={icon}
|
||
language={language}
|
||
lines
|
||
highlight={highlight}
|
||
>
|
||
{children}
|
||
</CodeBlock>
|
||
);
|
||
};
|
||
```
|