NetNexus UI

Appearance

快速开始 ​

环境要求 ​

  • Vue 3.5.0 或更高版本。Vue 是 peer dependency，不会重复打进 NetNexus UI。
  • 包声明的开发与构建环境为 Node.js >=16.20.0、npm >=8.19.0。
  • 文档站使用 VitePress；在仓库中运行文档需要 Node.js 18 或更高版本，GitHub Pages 使用 Node.js 20 构建。

安装 ​

bash
npm install netnexus-ui

全量注册 ​

在应用入口引入完整样式，初始化主题，再安装组件插件：

js
import { createApp } from 'vue';
import NetNexusUi, { initializeTheme } from 'netnexus-ui';
import 'netnexus-ui/style.css';
import App from './App.vue';

initializeTheme();

createApp(App).use(NetNexusUi).mount('#app');

插件会注册全部 62 个组件。注册后可直接使用全局组件：

vue
<template>
    <nn-space>
        <nn-button type="primary">保存</nn-button>
        <nn-button>取消</nn-button>
    </nn-space>
</template>

initializeTheme() 会读取本地保存的 preset，并把主题属性写到 <html>。只需要静态默认蓝色主题时，CSS 本身已有默认值；需要运行时切换或保存选择时，应调用该函数。完整行为见主题文档。

具名导入 ​

不安装全量插件时，可以在组件内导入所需组件。组件也可从根入口具名导入；推荐使用语义明确的 netnexus-ui/components 子入口。

vue
<script setup>
    import { NnButton, NnTable } from 'netnexus-ui/components';
    import 'netnexus-ui/style.css';

    const columns = [
        { title: '名称', dataIndex: 'name', key: 'name' },
        { title: '状态', dataIndex: 'status', key: 'status' }
    ];

    const rows = [
        { key: 'gateway', name: 'Gateway', status: '运行中' },
        { key: 'worker', name: 'Worker', status: '已停止' }
    ];
</script>

<template>
    <NnButton type="primary">新建</NnButton>
    <NnTable :columns="columns" :data-source="rows" :pagination="false" />
</template>

样式是包的副作用入口，仍需由应用显式引入一次。当前包没有导出 netnexus-ui/components/NnButton 这类逐组件路径，请不要构造未在 package.json 中声明的深层导入。

样式入口 ​

入口用途
netnexus-ui/style.css推荐的完整入口：组件样式、主题 Token、服务样式和图标样式
netnexus-ui/theme.css主题 preset 与 --nn-* CSS 变量
netnexus-ui/services.css通知和确认弹窗样式；单独使用时还需要主题 Token
netnexus-ui/icons.css图标基础样式与旋转动画
netnexus-ui/reset.css可选的页面 reset，会影响全局元素
netnexus-ui/base.css可选的基础页面与 body 样式，会影响全局布局

多数应用只需引入：

js
import 'netnexus-ui/style.css';

若应用已有自己的 reset 和页面基础样式，不要再引入 reset.css、base.css。若只使用服务而不使用组件，可以缩小到：

js
import 'netnexus-ui/theme.css';
import 'netnexus-ui/services.css';

JavaScript 子入口 ​

入口导出
netnexus-ui插件、全部组件、图标、主题 API 和服务
netnexus-ui/components与根组件入口相同的组件导出
netnexus-ui/icons43 个图标组件
netnexus-ui/theme主题常量、辅助函数和主题管理器
netnexus-ui/services通知与确认弹窗服务

在仓库中运行示例 ​

examples/ 展示六组跨组件场景；每个组件的独立页面还会加载 docs/demos/ 中对应的 Vue 单文件组件，并把同一个文件作为可展开源码。

bash
npm ci
npm run dev

终端会输出本地文档站地址。验证 GitHub Pages 的生产构建时运行：

bash
npm run docs:build

检查 62 个组件是否都有 API、导航条目和独立 demo，并检查六个组合示例：

bash
npm run test:docs

完成修改后运行仓库的完整验证：

bash
npm run verify

verify 会执行文档结构检查、源码 lint、CI 测试、包构建及真实 npm tarball 消费测试。文档站生产构建由独立的 Node 20 CI 与 GitHub Pages 工作流验证。

浏览器端 E2E 需要先安装 Playwright Chromium：

bash
npx playwright install chromium
npm run test:e2e

已知边界 ​

  • 当前组件类型声明统一为 Vue Component，组件级 Props、Events、Slots 的 IDE 推断仍有限；使用时请同时查阅组件参考和实现。
  • style.css 是完整组件样式，当前没有逐组件 CSS 入口。
  • 通知、确认弹窗及多数浮层交互依赖浏览器 DOM；服务端渲染场景应在客户端挂载后调用。主题管理器在没有 DOM 时会跳过属性写入。
  • CI 的浏览器 E2E 当前只覆盖 Chromium，没有声明完整的浏览器兼容矩阵。
  • 图标不会随 app.use(NetNexusUi) 全局注册，需要在使用它们的组件中显式导入。

相关源码 ​

Released under the MIT License.

NetNexus UI