# NsUI > A Vue 3 component library: 92 components, themeable, dark mode built in, written in TypeScript. --- # Quick Start NsUI is a Vue 3 component library made up of 4 packages: | Package | Contents | | ----------- | --------------------------------------------------------------------------------- | | `@ns/ui` | All components (86), the `v-loading` directive, and functional APIs like Message | | `@ns/theme` | Theme: CSS variables, dark theme, 6 color palettes, reset styles, utility classes | | `@ns/icons` | SVG icons | | `@ns/utils` | Utilities (type checks, debounce and throttle, DOM helpers) | Most projects only need to install `@ns/ui`. The other three packages are its dependencies and are installed along with it. ## Requirements - Vue 3.5 or later (Modal, Drawer and Popover use `useId`, added in Vue 3.5) - Node.js 18 or later - Browsers: Chrome / Edge 111, Firefox 113, Safari 16.2 or later (the theme's light color scale uses CSS `color-mix`; older browsers fall back to fixed colors) ## Installation The packages are currently published to the company's Nexus registry. First add a line to the `.npmrc` at your project root so that packages starting with `@ns` are installed from Nexus: ```ini @ns:registry=https://nexus.nscode.cn/repository/npm-group/ ``` Then install: ```bash pnpm add @ns/ui # or npm install @ns/ui ``` ## Full Import Register the library once in your entry file. After that every component can be used in templates directly, without importing them one by one. ```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)` does two things: - Registers every component. Tag names are PascalCase with an `Ns` prefix, such as ``, `` and ``; - Registers the `v-loading` directive. ```vue ``` ## On-demand Import If you only use a few components, skip `app.use(NsUI)` and import them where they are used. The style file still needs to be imported once in the entry file. ```ts // main.ts import '@ns/ui/style.css' ``` ```vue ``` With on-demand import, register the `v-loading` directive yourself: ```ts import { vLoading } from '@ns/ui' app.directive('loading', vLoading) ``` Inside ` ``` Many components have props like `icon` that also take an icon name, for example `Add`. ## Icon List `name` can only be one of the names below. A name outside this list doesn't throw, but the icon becomes a blank 1em×1em box (16px by default) that pushes the text next to it. | Group | Icon names | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Direction and navigation | `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` | | Actions | `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` | | Status | `success` `warning` `error` `info` `help` `loading` `star` `star-half` `heart` `clock` `calendar` | | User and general | `user` `users` `setting` `search` `bell` `phone` `location` `mail` | | Files | `file` `folder` `image` `table` | ## Custom Icons The default slot of `NsIcon` accepts any SVG, and size, color and rotation props still apply: ```vue ``` The SVG needs a `viewBox`, and its fill should be `currentColor` so it follows the `color` prop. When the slot is provided, it takes precedence and the built-in icon for `name` isn't rendered. `name` is still required and is read out by screen readers as the `aria-label`: `name="custom"` above is read as "custom", so give custom icons a meaningful name. ## Using Icon Data Directly `@ns/icons` exports the raw icon data for rendering icons yourself: ```ts import { icons, iconList, iconGroups } from '@ns/icons' icons['arrow-up'] // { name: 'arrow-up', svg: '...' } iconList // all icons as an array, handy for an icon picker iconGroups.navigation // by group: navigation, action, status, user, file ``` Each icon can also be imported on its own by its camelCase name: `import { arrowUp, chevronLeft } from '@ns/icons'`. --- # Utilities `@ns/utils` contains small helpers used inside the component library. They are also exported from `@ns/ui`, so your code can use them directly: ```ts import { debounce, isEmpty, addClass } from '@ns/ui' // or import { debounce, isEmpty, addClass } from '@ns/utils' ``` ## Type Checks | Function | Description | | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `isString(val)`, `isNumber(val)`, `isBoolean(val)`, `isFunction(val)` | Check primitive types | | `isArray(val)` | Same as `Array.isArray` | | `isObject(val)` | Not `null` and `typeof` is `object` (arrays included) | | `isEmpty(val)` | `true` for `null`, `undefined`, empty strings, empty arrays and plain objects without properties; Map and Set are checked by `size`; `0`, `false`, `Date` and other values return `false` | ## Functions and Strings | Function | Description | | --------------------- | --------------------------------------------------------------------------------------------- | | `debounce(fn, delay)` | Debounce: when called repeatedly, runs once `delay` ms after the last call | | `throttle(fn, delay)` | Throttle: the first call runs immediately; the last call within an interval runs when it ends | | `noop()` | Empty function | | `identity(val)` | Returns its argument | | `capitalize(str)` | Uppercase the first letter: `'button'` → `'Button'` | | `camelize(str)` | Kebab-case to camelCase: `'date-picker'` → `'datePicker'` | | `kebabCase(str)` | camelCase to kebab-case: `'datePicker'` → `'date-picker'` | ```ts import { debounce } from '@ns/ui' const search = debounce((keyword: string) => { // Sends the request only after typing stops for 300 ms }, 300) ``` Functions returned by `debounce` and `throttle` have a `cancel()` method; call it when the component unmounts to drop the pending call. When called as an object method, `this` is passed to the original function. ## DOM | Function | Description | | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `isClient` | Constant: whether running in a browser | | `inBrowser()` | Same as above, as a function | | `isDocumentVisible()` | Whether the page is visible (not in a background tab) | | `isWindow(val)` | Whether the value is the `window` object | | `addEventListener(el, event, handler, options?)`, `removeEventListener(...)` | Typed event binding; event names depend on the target (`beforeunload` on `window`, `visibilitychange` on `document`) | | `getComputedStyle(el)` | Get the computed style of an element | | `getScrollTop(el)`, `setScrollTop(el, value)` | Read and write the scroll position; `el` can be an element or `window` | | `getOffset(el)` | `top` and `left` of an element relative to the document | | `addClass(el, ...classes)`, `removeClass(el, ...classes)`, `hasClass(el, className)`, `toggleClass(el, className, force?)` | Class name helpers | ## Types ```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 The docs are also published as Markdown for LLMs and agents, following [llms.txt](https://llmstxt.org/). ## Files | File | Content | | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | | en/llms.txt | Index of all pages, grouped like the sidebar, one line per page | | en/llms-full.txt | All pages in one file | | llms.txt, llms-full.txt | Chinese version | Component docs are not fully translated yet, so untranslated pages are in Chinese. ## A page as Markdown Replace `.html` with `.md` in any docs or component page URL to get that page as Markdown, for example /en/components/button.md. Component pages include props, events, slots and the full code of every example. ## With an agent Give the agent the full URL of llms.txt (the site's domain followed by `/en/llms.txt`) and ask it to read the component pages it needs. It reads the index first and fetches only the pages it uses. llms-full.txt contains the code of every example and is large. It suits tools that can index a whole file; llms.txt is usually enough. --- # ActionGroup 操作按钮组 > This page hasn't been translated into English yet, so the content below is in Chinese. 一排操作按钮,最多显示 `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 按钮 > This page hasn't been translated into English yet, so the content below is in Chinese. 触发一个操作,例如提交表单、打开弹窗、跳转页面。 ## 引入 ```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` 是原生 `