代码块 code-block

通用组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

代码原文由宿主给，组件负责数行数、预撑高度并铺记号；语言角标带 aria-hidden，是纯装饰

typescript

export function createTicker(intervalTime: number) {
  let handle = 0
  return {
    start(onTick: () => void) {
      handle = setInterval(onTick, intervalTime)
    },
    stop() {
      clearInterval(handle)
    },
  }
}

<script setup lang="ts">
import { XhCodeBlock } from "@xihan-ui/vue";

const sample = `export function createTicker(intervalTime: number) {
  let handle = 0
  return {
    start(onTick: () => void) {
      handle = setInterval(onTick, intervalTime)
    },
    stop() {
      clearInterval(handle)
    },
  }
}`;
</script>

<template>
  <!-- complete 表示这个块已闭合，可以放心着色 -->
  <XhCodeBlock :code="sample" lang="typescript" complete style="inline-size: 100%;" />
</template>

流式未闭合

complete 为 false 时默认不着色：半截代码的词法本来就不稳，每来一个记号整块变一次色比不着色更难看

plaintext

const stream = await client.chat({
  model: 'demo',
  messages,
  onToken(token) {
    buffer +=

typescript

const stream = await client.chat({
  model: 'demo',
  messages,
  onToken(token) {
    buffer +=

<script setup lang="ts">
import { XhCodeBlock } from "@xihan-ui/vue";

// 吐到一半的样子：最后一行断在半个表达式上，围栏也还没闭合
const partial = `const stream = await client.chat({
  model: 'demo',
  messages,
  onToken(token) {
    buffer +=`;
</script>

<template>
  <!-- 语言标注也没吐出来：空白、半截、不认识的一律落到 plaintext -->
  <XhCodeBlock :code="partial" :complete="false" style="inline-size: 100%;" />

  <!-- 真要看流式着色，把这一条打开 -->
  <XhCodeBlock
    :code="partial"
    lang="typescript"
    :complete="false"
    highlight-while-streaming
    style="inline-size: 100%;"
  />
</template>

着色端口

着色是可换的端口：认不出的语言退回纯文本，接自己的实现组件侧一行不用改，传 null 则整个关掉

yaml

# 部署清单
image: xihan/ui:latest
replicas: 2
env:
  - name: MODE
    value: production

yaml

# 部署清单
image: xihan/ui:latest
replicas: 2
env:
  - name: MODE
    value: production

yaml

# 部署清单
image: xihan/ui:latest
replicas: 2
env:
  - name: MODE
    value: production

<script setup lang="ts">
import { XhCodeBlock } from "@xihan-ui/vue";

const manifest = `# 部署清单
image: xihan/ui:latest
replicas: 2
env:
  - name: MODE
    value: production`;

// 端口只有一个方法：给代码与语言，返回记号序列；返回 null 表示这一次不着色
const yamlComments = {
  highlight(code: string, lang: string) {
    if (lang !== "yaml") return null;
    return code
      .split(/(#[^\n]*)/)
      .filter((text) => text !== "")
      .map((text) => ({
        text,
        kind: text.startsWith("#") ? ("comment" as const) : ("plain" as const),
      }));
  },
};
</script>

<template>
  <!-- 自带的着色实现不认识 yaml，退回纯文本；不着色是合法结果 -->
  <XhCodeBlock :code="manifest" lang="yaml" complete style="inline-size: 100%;" />

  <!-- 换成自己的实现：只把注释挑出来 -->
  <XhCodeBlock
    :code="manifest"
    lang="yaml"
    complete
    :highlighter="yamlComments"
    style="inline-size: 100%;"
  />

  <!-- 显式 null：一个记号都不产，code 里就一个文本节点 -->
  <XhCodeBlock
    :code="manifest"
    lang="yaml"
    complete
    :highlighter="null"
    style="inline-size: 100%;"
  />
</template>

行号栏

行号是作者摆在代码块旁边的一栏，对齐靠行高与内边距这几个公开变量，行数由原文自己数

1

2

3

4

typescript

export function sum(list: number[]) {
  // 空数组按 0 算
  return list.reduce((total, n) => total + n, 0)
}

<script setup lang="ts">
import { XhCodeBlock } from "@xihan-ui/vue";

const sample = `export function sum(list: number[]) {
  // 空数组按 0 算
  return list.reduce((total, n) => total + n, 0)
}`;

// 代码里一条逻辑行就是一个视觉行（记号是 white-space: pre 排的），所以直接数换行
const lineCount = sample.split("\n").length;

// 两栏共用同一组变量，行号才跟代码行严格对齐
const frameStyle = [
  "display: flex",
  "inline-size: 100%",
  "overflow: hidden",
  "border-radius: var(--xh-shape-surface)",
  "background: var(--xh-bg-subtle)",
  "--xh-code-block-line-height: 1.5rem",
  "--xh-code-block-p: 12px",
  "--xh-code-block-label-py: 4px",
  "--xh-code-block-label-font-size: 12px",
].join("; ");

const gutterStyle = [
  "flex: none",
  "padding-block: var(--xh-code-block-p)",
  "padding-inline: 10px",
  "border-inline-end: 1px solid var(--xh-border-default)",
  "color: var(--xh-fg-subtle)",
  "font-family: var(--xh-font-family-mono)",
  "line-height: var(--xh-code-block-line-height)",
  "text-align: right",
  "user-select: none",
].join("; ");

// 与语言角标同高的空位，行号才从代码第一行起算
const spacerStyle
  = "block-size: calc(var(--xh-code-block-label-font-size) + var(--xh-code-block-label-py) * 2)";
</script>

<template>
  <div :style="frameStyle">
    <!-- 行号是纯装饰，读屏跳过它，代码原文照常由 code 部件念 -->
    <div :style="gutterStyle" aria-hidden="true">
      <div :style="spacerStyle" />
      <div v-for="n in lineCount" :key="n">{{ n }}</div>
    </div>

    <XhCodeBlock
      :code="sample"
      lang="typescript"
      complete
      style="flex: 1; min-inline-size: 0; --xh-code-block-radius: 0"
    />
  </div>
</template>

产物

层	值
自定义元素	<xh-code-block>
Vue 组件	XhCodeBlock
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/code-block.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="code-block"：root · lang-label · pre · code · token

Props

属性	类型	必填	说明
code	string	是
complete	boolean		代码块是否已闭合，未闭合时按行数预撑高度。
highlighter	HighlighterPort		着色实现。不给就是纯文本，给了也允许它返回 null（语言不认识之类），同样退回纯文本。 未闭合的块默认不着色，见 {@link highlightWhileStreaming}。
highlightWhileStreaming	boolean		块还没闭合时也着色，默认 false。 默认关是因为半截代码的词法本来就不稳——引号、括号随时会配上， 每来一个 token 整块变一次色，看着比不着色更糟。
lang	string		围栏语言标注，为空时按 plaintext 处理。

connect API

connect 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
lang	string
lineCount	number
tokens	readonly CodeToken[]	着色结果。空数组表示这一次不着色，作者按 code 原样渲染纯文本即可。 非空时逐个记号渲成元素，getTokenProps 给出该带的属性。
getRootProps	() => T['element']
getLangLabelProps	() => T['element']
getPreProps	() => T['element']
getCodeProps	() => T['element']
getTokenProps	(token: CodeToken) => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
Tab	代码块在 Tab 序列中	<pre> 自身可聚焦，随后方向键的横向滚动交给浏览器，组件不接管