代码块 | astryx-vue

    
      
      
        
          useUser.ts — typescript
        
      
      
    
    import {useState, useEffect} from 'react';
export function useUser(id: string) {
  const [user, setUser] = useState<User | null>(null);
  useEffect(() => {
    fetch(`/api/users/${id}`)
      .then(res => res.json())
      .then(setUser);
  }, [id]);
  return user;
}

使用方法

CodeBlock 展示一段只读代码。从 @astryx-vue/core/Code 引入，和行内的 Code 在一起。code 字符串既是读者看到的内容，也是复制按钮写下的内容。

language 选择分词器。title 在顶栏写上文件名。hasLineNumbers 画出行号槽。highlightLines 接收从 1 开始的行号，给这些行铺一层底色。maxHeight 限制正文高度，超出后纵向滚动。hasCopyButton 在有顶栏时放在顶栏里，没有顶栏时浮在右上角。

isDiff 按 unified diff 给整行上色。行首 + 是新增，- 是删除，@@ 是差异头。--- 后面带空格、下一行是带空格的 +++、再下一行是 @@ 时，前两行也是文件头。符号单独占一列，其余文本仍按 language 高亮。复制下去的还是原来的整段，符号也在里面。顶栏和视口名称会写成 diff，有语言时写成 typescript diff 这种。高亮行会盖住差异底色，不和它叠在一起。颜色用 --astryx-code-syntax-added、--astryx-code-syntax-removed、--astryx-code-syntax-diff-header，标记用对应的 added-marker 和 removed-marker，和其它语法色是同一套名字。

SyntaxTheme 给内部的代码块写入语法颜色变量。包里带的深色预设是 githubDark。浅色页面上的命令要读起来像终端时，用它包住 bash 代码块。defineSyntaxTheme 用同一组 token 名字再做一个预设。

vue

<script setup lang="ts">
import { CodeBlock, githubDark, SyntaxTheme } from '@astryx-vue/core/Code'

const commands = `$ astryx init --features agents`
</script>

<template>
  <SyntaxTheme :theme="githubDark">
    <CodeBlock :code="commands" language="bash" has-copy-button width="100%" />
  </SyntaxTheme>
</template>

建议

建议	做法
推荐	`language` 和这段代码一致。代码来自某个文件时加上 `title`。
推荐	一行命令不要行号。读者需要指出某一行时再打开行号。
推荐	教程里刚改过的几行用 `highlightLines` 标出来。已经是 diff 文本时用 `isDiff`，不要再给整行涂一层颜色。
推荐	命令要看起来像终端时，用 `SyntaxTheme` 套上 `githubDark`。
避免	用一次性 CSS 涂一个深色盒子。预设会把 token 颜色和边框一起换掉。
避免	把一整段说明文字放进代码块。

解剖

部分	说明
顶栏	有顶栏时显示标题、可见的语言名和复制按钮。标题或可见语言名会生成顶栏；只有复制按钮时，它浮在没有顶栏的代码块末端上方。
顶栏标题	把可选标题、可见语言名和折叠箭头收在顶栏里。
行号	左侧的编号槽。用 hasLineNumbers 打开。
代码正文	做了语法高亮的代码。
高亮行	给指定行加上背景，把注意力引过去。
复制按钮	把代码字符串复制到剪贴板。默认显示。

示例

Code — 片段

    
      
      
        
          bash
        
      
      
    
    npm install @astryxdesign/core

    
      
      
        
          bash
        
      
      
    
    yarn add @astryxdesign/theme-neutral

短命令，带复制按钮，没有行号。适合安装说明，或读者会直接粘贴的一行命令。

Code — 高亮

    
      
      
        
          useUser.ts — typescript
        
      
      
    
    interface User {
  id: string;
  name: string;
}
export function useUser(id: string) {
  const [user, setUser] = useState<User>();
  useEffect(() => {
    fetchUser(id).then(setUser);
  }, [id]);
  return user;
}

高亮几行 TypeScript，把注意力引到关键段落。教程和变更说明里用 highlightLines 标出新增或重要的代码。

Code — 差异

    
      
      
        
          useUser.ts — tsx diff
        
      
      
    
     --- a/useUser.ts
 +++ b/useUser.ts
 @@ -1,6 +1,6 @@
 export function useUser(id: string) {
-  const [user, setUser] = useState<User>()
+  const [user, setUser] = useState<User | null>(null)
   useEffect(() => {
-    fetchUser(id).then(setUser)
+    void fetchUser(id).then(setUser)
   }, [id])
   return user
 }

同一段 TypeScript 按 diff 显示。新增和删除整行着色，符号后面的代码仍按 tsx 高亮。文件头和 @@ 行保持安静。

Code — 配置

    
      
      
        
          package.json — json
        
      
      
    
    {
  "name": "@astryxdesign/core",
  "version": "0.0.5",
  "dependencies": {
    "@astryxdesign/theme-neutral": "^0.1.0",
    "react": "^19.0.0"
  },
  "scripts": {
    "build": "tsup",
    "test": "vitest"
  }
}

带标题栏和行号的 JSON 配置。title 在顶栏写上文件名，读者知道这段代码属于哪个文件。

Code — 可滚动

    
      
      
        
          many-lines.ts — typescript
        
      
      
    
    const line1 = 1;
const line2 = 2;
const line3 = 3;
const line4 = 4;
const line5 = 5;
const line6 = 6;
const line7 = 7;
const line8 = 8;
const line9 = 9;
const line10 = 10;
const line11 = 11;
const line12 = 12;
const line13 = 13;
const line14 = 14;
const line15 = 15;
const line16 = 16;
const line17 = 17;
const line18 = 18;
const line19 = 19;
const line20 = 20;
const line21 = 21;
const line22 = 22;
const line23 = 23;
const line24 = 24;
const line25 = 25;
const line26 = 26;
const line27 = 27;
const line28 = 28;
const line29 = 29;
const line30 = 30;
const line31 = 31;
const line32 = 32;
const line33 = 33;
const line34 = 34;
const line35 = 35;
const line36 = 36;
const line37 = 37;
const line38 = 38;
const line39 = 39;
const line40 = 40;
const line41 = 41;
const line42 = 42;
const line43 = 43;
const line44 = 44;
const line45 = 45;
const line46 = 46;
const line47 = 47;
const line48 = 48;
const line49 = 49;
const line50 = 50;

用最大高度限制长代码块，超出后纵向滚动。展示大文件时用 maxHeight，避免代码块占满整页。

Code — 终端

    
      
      
        
          bash
        
      
      
    
    $ astryx init --features agents
✓ AI agent docs installed → AGENTS.md
$ pnpm astryx component CodeBlock --dense

深色终端风格的命令块：用 SyntaxTheme 的 GitHub Dark 预设包住 bash 代码块，打开复制按钮，不显示行号。浅色页面上的 shell 会话或命令输出用这个。

使用方法 ​

建议 ​

解剖

示例 ​