@liexx/error

ProError —— 基于 Vue 3 + Element Plus 的错误页组件，使用 TypeScript + Vite 构建。v2 起内置 NotFound（404）/ NotPower（401）两个组件，按需引入即用。

安装

npm install @liexx/error element-plus
# 或
pnpm add @liexx/error element-plus

element-plus 为 peer dependency，需一并安装。

快速开始

样式已随组件自动注入，引组件即可用，无需单独引入样式文件：

<script setup lang="ts">
import { NotFound, NotPower } from "@liexx/error";
</script>

<template>
  <NotFound />
  <NotPower />
</template>

如需单独引样式（如 SSR 预渲染注入 <link>），import "@liexx/error/style.css" 仍然可用。

v1 → v2 迁移

v2 是破坏性变更：移除了 ProError 默认导出、code 切换与 errorPresets，改为两个命名导出组件。

- import ProError, { errorPresets } from "@liexx/error";
+ import { NotFound, NotPower } from "@liexx/error";

- <ProError code="404" />
+ <NotFound />

- <ProError code="401" />
+ <NotPower />

组件

左右两栏布局：左侧灰色大字 + 标题/描述 + 圆角按钮（向上移入动画），右侧主视觉插画（深底蓝色扁平插画风，随组件打包、构建时 base64 内联）。

| 组件 | 预设 | 插画 | | ---------- | ------------ | ------------ | | NotFound | 地址输入错误 | UFO 带走 404 | | NotPower | 登录已过期 | 钥匙孔盾牌 |

基础用法

<template>
  <NotFound />
</template>

默认单按钮「返回首页」，右侧展示内置插画，无需传任何 props。

组件默认撑满可用高度：父容器有确定高度时填满父容器，没有时（如直接作为路由组件）兜底撑满视口，路由用法无需额外样式。若嵌入卡片/弹窗等小容器，传 :full="false" 改为内容高度。

自定义文案与图片

hero / title / description 覆盖预设文案；image 传入图片地址替换右侧插画（背景图渲染）：

<template>
  <NotPower
    title="会话已失效"
    description="请重新登录后继续操作"
    image="@/assets/images/error/expired.png"
  />
</template>

按钮控制

• back-text="返回上一页" 显示「返回上一页」按钮（默认只有一个「返回首页」）；
• home-text="" 隐藏「返回首页」；
• home-path 控制返回首页的跳转地址（默认 /）：宿主注册了 vue-router 时走 router.push，否则降级 location.href。

<template>
  <NotFound home-path="/dashboard" back-text="返回上一页" />
</template>

插槽

<template>
  <NotFound>
    <!-- 替换右侧主视觉（优先级：插槽 > image prop > 预设内置插画） -->
    <template #image>
      <img src="@/assets/images/error/404.png" alt="404" />
    </template>

    <!-- 替换按钮区，插槽作用域提供 goHome / goBack -->
    <template #footer="{ goHome, goBack }">
      <el-button round type="primary" @click="goHome">回首页</el-button>
    </template>
  </NotFound>
</template>

API

两个组件的 Props / Events / Slots / Expose 完全一致。

Props

| 属性 | 说明 | 类型 | 默认值 | | ----------- | -------------------------------- | --------- | -------------- | | hero | 覆盖预设的左侧灰色大字 | string | 预设值 | | title | 覆盖预设的标题 | string | 预设值 | | description | 覆盖预设的描述 | string | 预设值 | | image | 右侧主视觉图片地址（背景图渲染） | string | 预设内置插画 | | home-text | 返回首页按钮文案，传空串隐藏 | string | '返回首页' | | back-text | 返回上一页按钮文案，传空串隐藏 | string | ''（不显示） | | home-path | 返回首页的跳转地址 | string | '/' | | full | 是否撑满可用高度（父级无高度时兜底撑满视口） | boolean | true |

Events

| 事件名 | 说明 | 回调参数 | | ------ | ------------------------------ | -------- | | home | 点击「返回首页」，跳转前触发 | — | | back | 点击「返回上一页」，跳转前触发 | — |

Slots

| 插槽名 | 说明 | 作用域参数 | | ------ | -------------- | ------------------- | | image | 替换右侧主视觉 | — | | footer | 替换按钮区 | goHome / goBack |

Expose

| 方法 | 说明 | | ------ | -------------------------------- | | goHome | 返回首页（emit home 后跳转） | | goBack | 返回上一页（emit back 后跳转） |

全局类型（可选）

在 tsconfig.app.json 的 compilerOptions.types 中添加 "@liexx/error/interface/client"，即可无需 import 直接使用 ProErrorProps / ErrorPreset 类型。

本地开发

pnpm install
pnpm dev     # 打开演示页，可切换两个组件
pnpm build   # 生成 dist + interface 全局类型声明