# NsUI > 一套 Vue 3 组件库:92 个组件,主题可调,暗色开箱即用,TypeScript 编写。 --- # 快速开始 NsUI 是一套 Vue 3 组件库,由 4 个包组成: | 包 | 内容 | | ----------- | --------------------------------------------------------- | | `@ns/ui` | 全部组件(86 个)、`v-loading` 指令、Message 等函数式调用 | | `@ns/theme` | 主题:CSS 变量、暗色主题、6 套配色方案、重置样式和工具类 | | `@ns/icons` | SVG 图标 | | `@ns/utils` | 工具函数(类型判断、防抖节流、DOM 操作) | 业务项目一般只需要安装 `@ns/ui`,其余三个包是它的依赖,会一起装上。 ## 环境要求 - Vue 3.5 及以上(Modal、Drawer、Popover 用到了 Vue 3.5 新增的 `useId`) - Node.js 18 及以上 - 浏览器:Chrome / Edge 111、Firefox 113、Safari 16.2 及以上(主题里的浅色阶用了 CSS 的 `color-mix`,更老的浏览器会退回到固定色) ## 安装 包发布在公司的 Nexus 上。先在项目根目录的 `.npmrc` 里加一行,让 `@ns` 开头的包从 Nexus 装: ```ini @ns:registry=https://nexus.nscode.cn/repository/npm-group/ ``` 然后安装: ```bash pnpm add @ns/ui # 或 npm install @ns/ui ``` ## 全量引入 在入口文件里注册一次,之后所有组件都可以直接在模板里用,不需要再逐个 import。 ```ts // main.ts import { createApp } from 'vue' import NsUI from '@ns/ui' import '@ns/ui/style.css' import App from './App.vue' const app = createApp(App) app.use(NsUI) app.mount('#app') ``` `app.use(NsUI)` 做了两件事: - 注册所有组件,标签名是 `Ns` 开头的大驼峰,例如 ``、``、``; - 注册 `v-loading` 指令。 ```vue ``` ## 按需引入 只用到少数组件时,不调用 `app.use(NsUI)`,在用到的地方直接 import。样式文件仍然要在入口引入一次。 ```ts // main.ts import '@ns/ui/style.css' ``` ```vue ``` 按需引入时 `v-loading` 指令要自己注册: ```ts import { vLoading } from '@ns/ui' app.directive('loading', vLoading) ``` 在 ` ``` 很多组件有 `icon` 这类属性,传的也是图标名,例如 `新增`。 ## 图标清单 `name` 只能用下面这些名字。写了清单以外的名字不会报错,但图标位置是一块 1em×1em(默认 16px)的空白,会把旁边的文字推开。 | 分组 | 图标名 | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 方向和导航 | `home` `menu` `apps` `top` `arrow-up` `arrow-down` `arrow-left` `arrow-right` `chevron-up` `chevron-down` `chevron-left` `chevron-right` `double-left` `double-right` `caret-up` `caret-down` `caret-left` `caret-right` `more-horizontal` `more-vertical` | | 操作 | `close` `check` `plus` `minus` `edit` `trash` `refresh` `copy` `save` `share` `link` `upload` `download` `filter` `sort` `drag` `lock` `eye` `eye-off` `zoom-in` `zoom-out` `rotate-left` `rotate-right` `fullscreen` | | 状态 | `success` `warning` `error` `info` `help` `loading` `star` `star-half` `heart` `clock` `calendar` | | 用户和通用 | `user` `users` `setting` `search` `bell` `phone` `location` `mail` | | 文件 | `file` `folder` `image` `table` | ## 用自己的图标 `NsIcon` 的默认插槽可以放任意 SVG,尺寸、颜色、旋转这些属性照样生效: ```vue ``` SVG 要带 `viewBox`,填充色写 `currentColor`,这样才能跟着 `color` 属性变色。 传了插槽时插槽内容优先,不再渲染 `name` 对应的内置图标。`name` 仍然必填,并且会作为 `aria-label` 被读屏软件读出来,上面的 `name="custom"` 会被读成 “custom”,自定义图标最好给一个有意义的名字。 ## 直接使用图标数据 `@ns/icons` 导出了图标的原始数据,需要自己渲染时可以用: ```ts import { icons, iconList, iconGroups } from '@ns/icons' icons['arrow-up'] // { name: 'arrow-up', svg: '...' } iconList // 全部图标的数组,适合做图标选择器 iconGroups.navigation // 按分组取:navigation、action、status、user、file ``` 每个图标也可以按驼峰名单独导入:`import { arrowUp, chevronLeft } from '@ns/icons'`。 --- # 工具函数 `@ns/utils` 里是组件库自己用到的一些小工具,也从 `@ns/ui` 一并导出,业务代码可以直接用: ```ts import { debounce, isEmpty, addClass } from '@ns/ui' // 或 import { debounce, isEmpty, addClass } from '@ns/utils' ``` ## 类型判断 | 函数 | 说明 | | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `isString(val)`、`isNumber(val)`、`isBoolean(val)`、`isFunction(val)` | 判断基本类型 | | `isArray(val)` | 等同于 `Array.isArray` | | `isObject(val)` | 不是 `null` 且 `typeof` 为 `object`(数组也算) | | `isEmpty(val)` | `null`、`undefined`、空字符串、空数组、没有属性的普通对象返回 `true`;Map、Set 按 `size` 判断;数字 `0`、`false`、`Date` 等其他值返回 `false` | ## 函数和字符串 | 函数 | 说明 | | --------------------- | ---------------------------------------------------------------- | | `debounce(fn, delay)` | 防抖:连续调用时只在最后一次调用之后 `delay` 毫秒执行一次 | | `throttle(fn, delay)` | 节流:第一次调用立即执行,间隔内的最后一次调用在间隔结束时补执行 | | `noop()` | 空函数 | | `identity(val)` | 原样返回参数 | | `capitalize(str)` | 首字母大写:`'button'` → `'Button'` | | `camelize(str)` | 短横线转驼峰:`'date-picker'` → `'datePicker'` | | `kebabCase(str)` | 驼峰转短横线:`'datePicker'` → `'date-picker'` | ```ts import { debounce } from '@ns/ui' const search = debounce((keyword: string) => { // 停止输入 300 毫秒后才真正发请求 }, 300) ``` `debounce` 和 `throttle` 返回的函数带 `cancel()`,组件卸载时调用它取消还没执行的那一次;作为对象方法调用时,`this` 会传给原函数。 ## DOM | 函数 | 说明 | | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `isClient` | 常量,是否在浏览器环境 | | `inBrowser()` | 同上,函数形式 | | `isDocumentVisible()` | 当前页面是否可见(没被切到后台) | | `isWindow(val)` | 是不是 `window` 对象 | | `addEventListener(el, event, handler, options?)`、`removeEventListener(...)` | 带类型的事件绑定和解绑,事件名按目标区分(`window` 上能用 `beforeunload`,`document` 上能用 `visibilitychange`) | | `getComputedStyle(el)` | 取元素的计算样式 | | `getScrollTop(el)`、`setScrollTop(el, value)` | 读写滚动位置,`el` 可以是元素或 `window` | | `getOffset(el)` | 元素相对整个文档的 `top`、`left` | | `addClass(el, ...classes)`、`removeClass(el, ...classes)`、`hasClass(el, className)`、`toggleClass(el, className, force?)` | 类名操作 | ## 类型 ```ts import type { ComponentSize, ComponentType, MaybeArray, Nullable } from '@ns/ui' type ComponentSize = 'large' | 'default' | 'small' type ComponentType = 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'help' | 'default' type MaybeArray = T | T[] type MaybeFunction = T | (() => T) type Nullable = T | null type Optional = T | undefined ``` --- # LLMs 官网的文档也按 [llms.txt](https://llmstxt.org/) 约定发布了 Markdown 版本,方便大模型和 Agent 读取。 ## 文件 | 文件 | 内容 | | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | | llms.txt | 所有页面的索引,按侧边栏分组,每页一行说明 | | llms-full.txt | 所有页面合成的一个文件 | | en/llms.txt、en/llms-full.txt | 英文版。组件文档还没翻译完,没翻译的页面是中文内容 | ## 单页的 Markdown 把文档页、组件页地址里的 `.html` 换成 `.md`,就是这一页的 Markdown,例如 /components/button.md。组件页包含 Props、事件、插槽和每个示例的完整代码。 ## 交给 Agent 把 llms.txt 的完整地址(浏览器地址栏里的域名加上 `/llms.txt`)交给 Agent,告诉它按需读取用到的组件页。它会先读索引,再只取需要的页面。 llms-full.txt 包含所有示例代码,文件很大,适合能给整个文件建索引的工具;一般直接用 llms.txt 就够了。 --- # ActionGroup 操作按钮组 一排操作按钮,最多显示 `max` 个位置,放不下的收进“更多”下拉菜单。“更多”默认显示文字,用 `more-display` 可以显示收起的数量,或者换成图标。常用在表格的操作列:每一行传自己的 `row`,按行数据决定哪些操作显示、哪些禁用。 ## 引入 ```ts import { NsActionGroup } from '@ns/ui' import type { ActionItem } from '@ns/ui' ``` ## 基础用法 `actions` 是操作项数组,每项至少有 `key` 和 `label`。点了某个操作时触发 `action-click`,参数是这个操作项和 `row`。 ```vue ``` ## 最多显示几个 `max` 默认 3,“更多”也算一个位置: - 可见的操作不超过 `max` 个时全部直接显示,没有“更多”; - 超过时显示前 `max - 1` 个,其余收进“更多”。所以“更多”里至少有两项,不会出现只收了一个操作的“更多”。 | 可见的操作数 | max | 直接显示 | 收进“更多” | | ------------ | --- | -------- | ---------- | | 3 | 3 | 3 个 | - | | 4 | 3 | 2 个 | 2 个 | | 5 | 2 | 1 个 | 4 个 | | 5 | 1 | - | 5 个 | `max` 是小数时向下取整;小于 1(0、负数、`NaN`)时按 1 处理,并在控制台警告;传 `Infinity` 表示全部直接显示。下面每一行是同样的 5 个操作,行首是 `max` 的值: ```vue ``` ## 按行数据显示和禁用 `visible`、`disabled` 可以是布尔值,也可以是函数,函数的参数是 `row`。先按 `visible` 过滤,再按 `max` 计算哪些收进“更多”,隐藏的操作不占位置。 操作项写成 `ActionItem[]` 时,回调的 `row` 就是 `User` 类型。 ```vue ``` 下面每一行是一个用户,状态不同,显示的操作也不同:正常的用户能“锁定”,锁定的用户能“解锁”、不能“删除”;“导出”对所有人隐藏(`visible: false`),不占位置。点“锁定”“解锁”会改这一行的状态。 ```vue ``` ## 放在表格里 在表格的操作列插槽里使用,传当前行的 `row`。表格里一般用 `size="small"`,和表格的尺寸一致。 按钮用的是 `NsButton` 的 `variant="link"`(链接按钮)并去掉了左右内边距:没有底色和边框,悬停时只是变淡,不会和表格行的悬停底色叠在一起;文字和单元格左边对齐,按钮之间按尺寸隔开 16 / 12 / 8px。 ```vue ``` ## 每个操作自己的点击回调 操作项的 `onClick(row)` 在 `action-click` 事件之后调用。两种写法可以只用一种,也可以一起用:`onClick` 适合每个操作各写各的逻辑,`action-click` 适合统一按 `key` 分发。 ```vue ``` 两种一起用时的调用顺序,点一下看看: ```vue ``` ## 按钮类型、图标和“更多”的显示 - `type` 是按钮类型,默认 `primary`(主色文字),可以用 `NsButton` 的所有类型。收进“更多”后,只有 `danger` 会把菜单项的文字染成危险色(例如“删除”),其他类型的菜单项和普通菜单项一样。 - `icon` 是图标名(只能用 `NsIcon` 认识的名字,见《图标》),显示在文字前面;收进“更多”后显示在菜单项文字前面。 ```vue ``` `more-display` 是“更多”按钮的样式,默认 `text`: - `text`:`more-text` 的文字(默认“更多”)加向下箭头,菜单打开时箭头朝上,不显示数量。 - `text-count`:文字后面跟收起的操作数(浅色小圆角底),再加向下箭头。 - `count`:浅色底的胶囊,写着 `+N`;悬停或菜单打开时加一圈主色边框。 - `icon`:只有一个横向省略号图标(`more-horizontal`),适合放在窄的表格操作列里。 N 是菜单里收起的操作数,隐藏(`visible` 为 `false`)的不算。后三种样式的无障碍名称是 `more-text` 加数量,如“更多 2”。英文界面写 `more-text="More"`。下面每一行是一种样式: ```vue ``` ## 触发方式 `trigger` 是“更多”下拉菜单的触发方式:`hover`(默认,悬停打开,也可以点击打开)或 `click`(点击打开、再点收起)。 ```vue ``` ## 不同尺寸 `size` 有 `large`、`default`、`small` 三种,按钮高度 40 / 32 / 24px、字号 16 / 14 / 12px、图标 18 / 16 / 14px、按钮间距 16 / 12 / 8px;“更多”下拉菜单的菜单项也跟着变(行高 40 / 约 36 / 28px,字号 16 / 14 / 12px)。不写时跟随 `NsConfigProvider` 的 `size`,都没有时是 `default`。 ```vue ``` ## 键盘操作 - Tab 逐个聚焦按钮(禁用的按钮跳过);回车、空格触发。 - 在“更多”上按回车、空格或向下键打开菜单,焦点移到第一个可用的菜单项;上下键移动,Home / End 到第一项 / 最后一项,回车、空格选中。 - 按 Esc 或选中一项后菜单收起,焦点回到“更多”按钮。 ## Props | 属性 | 类型 | 默认值 | 说明 | | ----------- | --------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------- | | actions | `ActionItem[]` | `[]` | 操作项,见下面的 ActionItem | | max | `number` | `3` | 最多占几个位置(含“更多”)。超过时显示前 `max - 1` 个,其余收进“更多”;小于 1 时按 1 处理 | | row | `any` | - | 当前行数据,原样传给 `disabled`、`visible`、`onClick` 和 `action-click` 事件 | | moreText | `string` | `'更多'` | “更多”按钮的文字。`moreDisplay` 不是 `text` 时,这段文字加数量作为无障碍名称(如“更多 2”) | | moreDisplay | `'text' \| 'text-count' \| 'count' \| 'icon'` | `'text'` | “更多”按钮的样式:文字加箭头、文字加数量、`+N` 胶囊、省略号图标。数量不含隐藏的操作 | | trigger | `'hover' \| 'click'` | `'hover'` | “更多”下拉菜单的触发方式 | | size | `'large' \| 'default' \| 'small'` | - | 尺寸。不写时跟随 `NsConfigProvider` 的 `size`,都没有时是 `'default'`;放在表格里一般用 `small` | ### ActionItem | 属性 | 类型 | 默认值 | 说明 | | -------- | ------------------------------- | ----------- | -------------------------------------------------------- | | key | `string` | - | 必填,唯一标识 | | label | `string` | - | 必填,按钮文字,也是按钮的可读名称 | | icon | `string` | - | 图标名 | | type | `ButtonType` | `'primary'` | 按钮类型;收进“更多”后只有 `danger` 会改菜单项的文字颜色 | | disabled | `boolean \| ((row) => boolean)` | `false` | 是否禁用。禁用的操作点了不触发事件,也不调用 `onClick` | | visible | `boolean \| ((row) => boolean)` | `true` | 是否显示。先按它过滤,再按 `max` 计算 | | onClick | `(row) => void` | - | 点击时调用,在 `action-click` 事件之后 | ## Events | 事件 | 回调参数 | 说明 | | ------------ | -------------------------------- | ----------------------------------------------------------------------- | | action-click | `(action: ActionItem, row: any)` | 点了直接显示的按钮或“更多”里的菜单项时触发;`@actionClick` 写法也能监听 | ## Slots 没有插槽。按钮由 `actions` 生成;需要完全自定义的按钮时,直接用 `NsButton`、`NsDropdown` 组合。 ## 方法 没有对外暴露的方法。 ## 类型 ```ts import type { ActionGroupProps, ActionGroupEmits, ActionGroupSize, ActionGroupMoreDisplay, ActionGroupTrigger, ActionItem, ActionRow } from '@ns/ui' type ActionGroupSize = 'large' | 'default' | 'small' type ActionGroupMoreDisplay = 'text' | 'text-count' | 'count' | 'icon' type ActionGroupTrigger = 'hover' | 'click' /** 行数据,组件不读取里面的字段,所以不限制类型 */ type ActionRow = any interface ActionItem { key: string label: string icon?: NsIconName type?: ButtonType disabled?: boolean | ((row: R) => boolean) visible?: boolean | ((row: R) => boolean) onClick?: (row: R) => void } interface ActionGroupProps { actions?: ActionItem[] max?: number row?: ActionRow moreText?: string moreDisplay?: ActionGroupMoreDisplay trigger?: ActionGroupTrigger size?: ActionGroupSize } interface ActionGroupEmits { 'action-click': [action: ActionItem, row: ActionRow] } ``` ## 注意事项 - `max` 把“更多”也算一个位置:4 个操作、`max` 为 3 时显示 2 个加“更多”,不是 3 个加“更多”。 - `visible`、`disabled` 的函数在渲染时调用,`row` 或 `actions` 变了会重新计算;函数里不要做耗时的事。 - 收进“更多”的菜单挂在 `body` 上,菜单的层级跟随 `NsConfigProvider` 的 `zIndex`,放在对话框、抽屉里也不会被遮住。 - 菜单默认向下、右对齐(`bottom-end`)弹出,放在表格最右边的操作列里也不会超出表格;下方放不下时自动翻到上方。 - 不跟随 `NsTable` 的 `size`,放在表格里时要自己写 `size`,一般和表格一致。 - `key` 要唯一,重复时 Vue 会警告;菜单项按位置对应操作,`key` 重复也不会点错。 --- # Button 按钮 触发一个操作,例如提交表单、打开弹窗、跳转页面。 ## 引入 ```ts import { NsButton } from '@ns/ui' ``` ## 基础用法 `type` 决定颜色,共 7 种:`default`、`primary`、`success`、`warning`、`danger`、`info`、`help`。每种颜色都可以加 `plain`(朴素)、`round`(圆角)、`circle`(圆形)。 ```vue ``` ## 变体 `variant` 决定外观:`solid`(实心,默认)、`outline`(描边)、`plain`(朴素)、`text`(文字)、`link`(链接)。`plain` 属性是 `variant="plain"` 的简写。描边按钮是透明底、彩色边框,悬停时只变化底色;朴素按钮是浅色底、浅色边框(和 Tag 的浅色效果一样),悬停时变成实心按钮;文字按钮没有边框,悬停时出现浅色底;链接按钮只有文字,悬停时变淡。 下面每一行是一种变体,从左到右是 7 种颜色: ```vue ``` ## 尺寸 `size` 可选 `large`、`default`、`small`,高度分别是 40、32、24px,带图标、圆角和圆形按钮也一样。高度来自主题变量 `--ns-component-size-large`、`--ns-component-size`、`--ns-component-size-small`,改这三个变量可以统一调整所有控件的高度。 ```vue ``` ## 形状 `round` 是圆角按钮,`circle` 是圆形按钮。圆形按钮只显示图标,不显示文字。两种形状都能和任意变体搭配。 ```vue ``` ## 图标 `icon` 传图标名,`icon-position` 可选 `left`(默认)、`right`、`top`、`bottom`。图标在上、下时按钮竖排,高度随内容增加。各种变体都能带图标。 ```vue ``` 只有图标、没有文字的按钮是正方形,边长等于按钮高度(large 40px、default 32px、small 24px),图标居中,根元素带 `ns-button--icon-only` 类。下面两种情况算只有图标: - 传了 `icon`,默认插槽没有内容(只有空白也算没有内容)。 - 没传 `icon`,默认插槽里只有一个 `NsIcon`。这个图标也跟着按钮尺寸变成 18 / 16 / 14px。 `round` 只有图标时显示成圆形,和 `circle` 一样。加载中图标换成转圈,按钮仍然是正方形;显示 `loading-text` 时有文字,不算只有图标。`variant="text"` 和 `variant="link"` 不限制宽高,保持原来的内边距。在按钮组里也一样。只有图标的按钮要写 `aria-label`,屏幕阅读器才能读出按钮的用途。 ```vue ``` ## 加载状态 `loading` 时显示加载圈,按钮不能点击,图标隐藏。传了 `loading-text` 时显示这段文字,否则显示原来的按钮文字。`loading-progress-bar` 在按钮底边加一条进度条动画。各种颜色和变体都能加载。 ```vue ``` 点击后加载 2 秒,期间不能再点: ```vue ``` ## 禁用 `disabled` 后按钮变淡、不能点击,也不触发 `click`。每种颜色和变体都有对应的禁用样式;链接按钮(传了 `href`)禁用时去掉 `href`。 ```vue ``` ## 自定义颜色 `color` 是自定义主色:实心按钮用它作底色和边框,文字白色;其他变体用它作文字颜色(描边按钮也作边框颜色,朴素按钮用它混出浅色底和浅色边框)。`text-color`、`bg-color`、`border-color` 分别单独设置文字、底色、边框,优先于 `color`。自定义颜色写在内联样式里,悬停时颜色不再变化。 ```vue ``` ## 虚线和透明 `dashed` 把边框改成虚线,常用于“新增一项”这类次要操作。`transparent` 去掉底色,实心按钮的文字改用对应的主题色,适合放在有底色或图片的区域上。 ```vue ``` ## 层级 `secondary`、`tertiary`、`quaternary` 把整个按钮的透明度降到 0.85、0.7、0.55,用来区分同一组按钮的主次。 ```vue ``` ## 宽度和高度 `width`、`height` 设置按钮的宽高,数字按 px,字符串原样使用(如 `'50%'`)。高度小于当前尺寸的最小高度时不生效。 ```vue ``` ## 链接按钮 传了 `href` 时渲染成 ``,`target` 设置打开方式(`_blank`、`_self`、`_parent`、`_top`)。禁用或加载时去掉 `href`,并加上 `aria-disabled="true"`。`underline` 只在 `variant="link"` 时生效。 ```vue ``` ## 徽标 `badge` 在按钮角上显示徽标,内容可以是数字或文字;`badge-position` 可选 `top-right`(默认)、`top-left`、`bottom-right`、`bottom-left`;`badge-color` 改底色,默认危险色。 ```vue ``` ## 气泡提示 `popover` 打开按钮自带的气泡提示,内容写在 `popover-content`,标题写在 `popover-title`。`popover-trigger` 是触发方式: - `hover`(默认):悬停显示,移开后关闭。 - `click`:点击显示,再点一次、点按钮和提示以外的地方或按 Esc 关闭。 - `focus`:聚焦时显示(用 Tab 或点击),失去焦点后关闭。 - `manual`:不响应鼠标和焦点,用 `showPopover()`、`hidePopover()` 方法打开、关闭,按 Esc 也不关闭。 `popover-disabled` 或按钮被禁用时,提示自动收起。 ```vue ``` `popover-placement` 是提示的位置,默认 `top`,共 12 个方向;放不下时自动翻到另一侧。把鼠标移到下面的按钮上看效果: ```vue ``` 勾选后提示不再弹出,已经打开的会收起: ```vue ``` ## 防抖和节流 `debounce` 是防抖时间(毫秒):连续点击时,停下来过了这段时间才触发一次 `click`。`throttle` 是节流时间:这段时间内只触发第一次点击。两者都是 0 表示不处理。 ```vue ``` ## 点击波纹 `ripple` 在点击位置扩散一圈波纹,颜色跟着按钮的文字颜色。 ```vue ``` ## 原生类型 `native-type` 是原生 `