日志 log

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

示例

基础用法

root / viewport / content / line 四层；一行写什么由作者定，组件只给身份与等宽排版

12:00:01 boot 读取配置 config/app.yaml

12:00:01 boot 监听 0.0.0.0:8080

12:00:02 db 连接池就绪，最小 4 最大 32

12:00:02 cache 命中率统计已开启

12:00:03 http GET /health 200 3ms

12:00:04 http POST /api/orders 201 118ms

12:00:05 http GET /api/orders/8812 200 21ms

12:00:06 job 对账任务排入队列 batch-2026-08-10

12:00:07 http GET /api/orders/8813 404 9ms

12:00:08 job 对账任务完成，处理 1,204 笔

<script setup lang="ts">
import { XhLogContent, XhLogLine, XhLogRoot, XhLogViewport } from "@xihan-ui/vue";

const lines = [
  "12:00:01  boot     读取配置 config/app.yaml",
  "12:00:01  boot     监听 0.0.0.0:8080",
  "12:00:02  db       连接池就绪，最小 4 最大 32",
  "12:00:02  cache    命中率统计已开启",
  "12:00:03  http     GET  /health            200   3ms",
  "12:00:04  http     POST /api/orders        201  118ms",
  "12:00:05  http     GET  /api/orders/8812   200   21ms",
  "12:00:06  job      对账任务排入队列 batch-2026-08-10",
  "12:00:07  http     GET  /api/orders/8813   404    9ms",
  "12:00:08  job      对账任务完成，处理 1,204 笔",
];
</script>

<template>
  <XhLogRoot :rows="8" style="inline-size: 100%">
    <XhLogViewport>
      <XhLogContent>
        <XhLogLine v-for="(line, i) in lines" :key="i">{{ line }}</XhLogLine>
      </XhLogContent>
    </XhLogViewport>
  </XhLogRoot>
</template>

按行数定高

rows 定的是「看得见几行」，一行有多高归皮肤，改 --xh-log-line-height 两边一起变

12:00:00 http GET /api/items/1000 200

12:00:01 http GET /api/items/1001 200

12:00:02 http GET /api/items/1002 200

12:00:03 http GET /api/items/1003 200

12:00:04 http GET /api/items/1004 200

12:00:05 http GET /api/items/1005 200

12:00:06 http GET /api/items/1006 200

12:00:07 http GET /api/items/1007 200

12:00:08 http GET /api/items/1008 200

12:00:09 http GET /api/items/1009 200

12:01:00 http GET /api/items/1010 200

12:01:01 http GET /api/items/1011 200

12:01:02 http GET /api/items/1012 200

12:01:03 http GET /api/items/1013 200

12:01:04 http GET /api/items/1014 200

12:01:05 http GET /api/items/1015 200

12:01:06 http GET /api/items/1016 200

12:01:07 http GET /api/items/1017 200

12:01:08 http GET /api/items/1018 200

12:01:09 http GET /api/items/1019 200

12:02:00 http GET /api/items/1020 200

12:02:01 http GET /api/items/1021 200

12:02:02 http GET /api/items/1022 200

12:02:03 http GET /api/items/1023 200

12:00:00 http GET /api/items/1000 200

12:00:01 http GET /api/items/1001 200

12:00:02 http GET /api/items/1002 200

12:00:03 http GET /api/items/1003 200

12:00:04 http GET /api/items/1004 200

12:00:05 http GET /api/items/1005 200

12:00:06 http GET /api/items/1006 200

12:00:07 http GET /api/items/1007 200

12:00:08 http GET /api/items/1008 200

12:00:09 http GET /api/items/1009 200

12:01:00 http GET /api/items/1010 200

12:01:01 http GET /api/items/1011 200

12:01:02 http GET /api/items/1012 200

12:01:03 http GET /api/items/1013 200

12:01:04 http GET /api/items/1014 200

12:01:05 http GET /api/items/1015 200

12:01:06 http GET /api/items/1016 200

12:01:07 http GET /api/items/1017 200

12:01:08 http GET /api/items/1018 200

12:01:09 http GET /api/items/1019 200

12:02:00 http GET /api/items/1020 200

12:02:01 http GET /api/items/1021 200

12:02:02 http GET /api/items/1022 200

12:02:03 http GET /api/items/1023 200

12:00:00 http GET /api/items/1000 200

12:00:01 http GET /api/items/1001 200

12:00:02 http GET /api/items/1002 200

12:00:03 http GET /api/items/1003 200

12:00:04 http GET /api/items/1004 200

12:00:05 http GET /api/items/1005 200

12:00:06 http GET /api/items/1006 200

12:00:07 http GET /api/items/1007 200

12:00:08 http GET /api/items/1008 200

12:00:09 http GET /api/items/1009 200

12:01:00 http GET /api/items/1010 200

12:01:01 http GET /api/items/1011 200

12:01:02 http GET /api/items/1012 200

12:01:03 http GET /api/items/1013 200

12:01:04 http GET /api/items/1014 200

12:01:05 http GET /api/items/1015 200

12:01:06 http GET /api/items/1016 200

12:01:07 http GET /api/items/1017 200

12:01:08 http GET /api/items/1018 200

12:01:09 http GET /api/items/1019 200

12:02:00 http GET /api/items/1020 200

12:02:01 http GET /api/items/1021 200

12:02:02 http GET /api/items/1022 200

12:02:03 http GET /api/items/1023 200

<script setup lang="ts">
import { XhLogContent, XhLogLine, XhLogRoot, XhLogViewport } from "@xihan-ui/vue";

const lines = Array.from(
  { length: 24 },
  (_, i) => `12:0${Math.floor(i / 10)}:${String(i % 10).padStart(2, "0")}  http  GET /api/items/${1000 + i}  200`,
);
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhLogRoot :rows="4">
      <XhLogViewport>
        <XhLogContent>
          <XhLogLine v-for="(line, i) in lines" :key="i">{{ line }}</XhLogLine>
        </XhLogContent>
      </XhLogViewport>
    </XhLogRoot>

    <XhLogRoot :rows="10">
      <XhLogViewport>
        <XhLogContent>
          <XhLogLine v-for="(line, i) in lines" :key="i">{{ line }}</XhLogLine>
        </XhLogContent>
      </XhLogViewport>
    </XhLogRoot>

    <!-- 同样 4 行，行高调宽一档，视口跟着一起长高 -->
    <XhLogRoot :rows="4" style="--xh-log-line-height: 1.75rem">
      <XhLogViewport>
        <XhLogContent>
          <XhLogLine v-for="(line, i) in lines" :key="i">{{ line }}</XhLogLine>
        </XhLogContent>
      </XhLogViewport>
    </XhLogRoot>
  </div>
</template>

自动跟到底部

新行进来时视口自己跟着走；往上滚一段就停住跟随，root 插槽给的 atBottom / scrollToBottom 够自己画一条回到最新

12:00:00 boot 第 1 行 · 往上滚一段试试

12:00:01 boot 第 2 行 · 往上滚一段试试

12:00:02 boot 第 3 行 · 往上滚一段试试

12:00:03 boot 第 4 行 · 往上滚一段试试

12:00:04 boot 第 5 行 · 往上滚一段试试

12:00:05 boot 第 6 行 · 往上滚一段试试

12:00:06 boot 第 7 行 · 往上滚一段试试

12:00:07 boot 第 8 行 · 往上滚一段试试

12:00:08 boot 第 9 行 · 往上滚一段试试

12:00:09 boot 第 10 行 · 往上滚一段试试

<script setup lang="ts">
import { onUnmounted, ref } from "vue";
import { XhButton, XhLogContent, XhLogLine, XhLogRoot, XhLogViewport } from "@xihan-ui/vue";

const lines = ref(
  Array.from({ length: 10 }, (_, i) => `12:00:0${i}  boot  第 ${i + 1} 行 · 往上滚一段试试`),
);

let seq = lines.value.length;
let timer: number | undefined;
const streaming = ref(false);

function append(): void {
  seq += 1;
  lines.value.push(`12:0${Math.floor(seq / 60)}:${String(seq % 60).padStart(2, "0")}  http  第 ${seq} 行 · 新来的`);
}

function toggle(): void {
  streaming.value = !streaming.value;
  if (streaming.value)
    timer = window.setInterval(append, 400);
  else
    window.clearInterval(timer);
}

// 离开页面时把定时器收掉
onUnmounted(() => window.clearInterval(timer));
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhLogRoot v-slot="{ atBottom, sticking, scrollToBottom }" :rows="8">
      <XhLogViewport>
        <XhLogContent>
          <XhLogLine v-for="(line, i) in lines" :key="i">{{ line }}</XhLogLine>
        </XhLogContent>
      </XhLogViewport>

      <!-- 不在底部时才露出来，排在视口下面 -->
      <div
        v-if="!atBottom"
        style="display: flex; align-items: center; justify-content: space-between; gap: 8px; padding: 6px 12px"
      >
        <span style="font-size: 13px">已暂停跟随 · 跟随意图：{{ sticking ? "开" : "关" }}</span>
        <XhButton variant="outline" size="sm" @click="scrollToBottom()">回到最新</XhButton>
      </div>
    </XhLogRoot>

    <div style="display: flex; gap: 8px">
      <XhButton variant="solid" @click="toggle">{{ streaming ? "停止输出" : "开始输出" }}</XhButton>
      <XhButton variant="outline" @click="append">追加一行</XhButton>
    </div>
  </div>
</template>

取行中

loading 让日志区报 aria-busy 并把指针换成忙碌态；「正在拉取」那一行是作者自己渲的

12:00:01 boot 服务已启动

12:00:02 db 连接池就绪

12:00:03 http GET /health 200

<script setup lang="ts">
import { ref } from "vue";
import { XhButton, XhLogContent, XhLogLine, XhLogRoot, XhLogViewport } from "@xihan-ui/vue";

const lines = ref([
  "12:00:01  boot   服务已启动",
  "12:00:02  db     连接池就绪",
  "12:00:03  http   GET /health  200",
]);

const loading = ref(false);

// 取回来的一批行追加在后面，取的过程里 loading 立着
function fetchMore(): void {
  if (loading.value)
    return;
  loading.value = true;
  window.setTimeout(() => {
    const base = lines.value.length;
    for (let i = 1; i <= 5; i += 1)
      lines.value.push(`12:00:0${base + i}  http   GET /api/items/${1000 + base + i}  200`);
    loading.value = false;
  }, 1200);
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhLogRoot :rows="7" :loading="loading">
      <XhLogViewport>
        <XhLogContent>
          <XhLogLine v-for="(line, i) in lines" :key="i">{{ line }}</XhLogLine>
          <XhLogLine v-if="loading" style="color: var(--xh-fg-muted)">正在拉取下一批…</XhLogLine>
        </XhLogContent>
      </XhLogViewport>
    </XhLogRoot>

    <div>
      <XhButton variant="solid" :disabled="loading" @click="fetchMore">再取 5 行</XhButton>
    </div>
  </div>
</template>

行的样子归作者

line 只发身份与等宽排版，级别配色、时间戳、行内标记这些都写在插槽里

12:00:01 [INFO] 读取配置 config/app.yaml

12:00:02 [OK] 数据库连接池就绪

12:00:04 [INFO] POST /api/orders 201 118ms

12:00:05 [WARN] 慢查询 1,240ms select * from orders

12:00:06 [ERROR] 支付网关超时，第 1 次重试

12:00:08 [OK] 支付网关恢复，订单 8812 已确认

<script setup lang="ts">
import { XhLogContent, XhLogLine, XhLogRoot, XhLogViewport } from "@xihan-ui/vue";

const LEVEL_COLOR: Record<string, string> = {
  info: "var(--xh-fg-muted)",
  ok: "var(--xh-fg-success)",
  warn: "var(--xh-fg-brand)",
  error: "var(--xh-fg-danger)",
};

const raw = [
  { time: "12:00:01", level: "info", text: "读取配置 config/app.yaml" },
  { time: "12:00:02", level: "ok", text: "数据库连接池就绪" },
  { time: "12:00:04", level: "info", text: "POST /api/orders  201  118ms" },
  { time: "12:00:05", level: "warn", text: "慢查询 1,240ms  select * from orders" },
  { time: "12:00:06", level: "error", text: "支付网关超时，第 1 次重试" },
  { time: "12:00:08", level: "ok", text: "支付网关恢复，订单 8812 已确认" },
];

// 级别既写成定宽文字标签也上色；段与段的间隔补进字符串，模板里不留会被折叠的空白
const entries = raw.map(entry => ({
  text: entry.text,
  time: `${entry.time}  `,
  label: `[${entry.level.toUpperCase()}]`.padEnd(9, " "),
  color: LEVEL_COLOR[entry.level],
}));
</script>

<template>
  <XhLogRoot :rows="6" style="inline-size: 100%">
    <XhLogViewport>
      <XhLogContent>
        <XhLogLine v-for="(entry, i) in entries" :key="i">
          <span style="color: var(--xh-fg-subtle)">{{ entry.time }}</span>
          <span :style="{ color: entry.color }">{{ entry.label }}</span>
          <span>{{ entry.text }}</span>
        </XhLogLine>
      </XhLogContent>
    </XhLogViewport>
  </XhLogRoot>
</template>

产物

层	值
自定义元素	<xh-log>
Vue 组件	XhLogContent XhLogLine XhLogRoot XhLogViewport
组合式函数	useLog
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/log.css

解剖

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

data-scope="log"：root · viewport · content · line

Props

属性	类型	必填	说明
loading	boolean		行还在路上：日志区报 aria-busy，根落 data-loading。
rows	number		视口按多少行定高；缺省时高度由皮肤给。
translations	Partial<LogTranslations>

connect API

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

成员	类型	说明
rows	number | undefined	取整后的行数；rows 缺席或不是正数时为 undefined。
loading	boolean
atBottom	boolean	当前滚动位置是否落在底部阈值内。
sticking	boolean	新行进来时是否自动跟到底。
scrollToBottom	() => void	滚到底部并恢复粘附。
getRootProps	() => T['element']
getViewportProps	() => T['element']
getContentProps	() => T['element']
getLineProps	() => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
Tab	焦点进入日志区	日志区自身可聚焦，方向键/PageUp/PageDown/Home/End 交给浏览器滚动，组件不接管