# @asd20/ui-next 中文文档

规范地址：https://npmcn.com/package/%40asd20/ui-next/

版本：2\.35\.2
npm 元数据更新时间：2026-11-04T18:48:07.202Z
中文译文更新时间：2026-11-06T22:39:52.417Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40asd20/ui-next
原文对照：https://npmcn.com/package/%40asd20/ui-next/?lang=original
项目主页：https://github.com/academydistrict20/asd20-ui-next#readme
源码仓库：https://github.com/academydistrict20/asd20-ui-next

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.1 MB，377 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：9 个
- peer 依赖：vue ^3\.0\.0
- 首次发布：2026-03-20T20:09:59.675Z
- 最新版本发布：2026-11-04T18:48:07.035Z
- 近 30 天下载量：4796（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：175（近 12 个月 175 个）

## 中文简介

Vue 3 的 ASD20 UI 组件库.

## 安装

```sh
npm install @asd20/ui-next
```

也可以使用：`pnpm add @asd20/ui-next`、`yarn add @asd20/ui-next`、`bun add @asd20/ui-next`

## README

# @ast20/ui-next

共享Vue 3 UI包 为学院区20网站和网络应用.

当前本地版本 : `2.34.6`

这个软件包是ASD20网络平台的活性共享演示层. 它提供可重复使用的组件,公共网站模板,app-shell模板, 图标、设计符号、 Sass 助手、 资产、 指令和助手功能 nuxt 网站、独立应用程序和选定的CommCenter预览 表面 .

## 平台作用

这个Repo拥有包装的UI合同:

-   使用的公共网站模板 `asd20-website`
-   按日历、目录、学校使用的程序模板和组件 目录和文件目录应用程序
-   选定的 CommCenter 预览组件和图标/模板导入
-   消费者共享全球设计标志和Sass助手
-   图标元数据和 SVG 组件导出
-   用于事件/信息/页面/文件/人物映射、搜索呼叫、, 组织标签、链接处理、饼干、电子邮件和分析反馈

软件包以 npm 的形式发布 `@asd20/ui-next`. 它应作为 多repo合同,不是作为应用程序本地组件文件夹.

## 运行时间合同

开发、建造和释放使用节点 `24.22.2` 页:1 `11.19.1` (与"节点"发行相并排). `.nvmrc`, (中文(简体) ), `.node-version`, (中文(简体) ), `packageManager`, (中文(简体) ), 和发布工作流程 封住这些版本。 CI 明确安装被绑 npm版本保持本地和发布工具对齐.

出版的图书馆保存着这些消费者要求:

-   节点 `>=20`
-   无 `>=10`
-   Vue 对同伴的依赖 `^3.0.0`

开发工具:

-   演示和包装消费者建设系统:Vite
-   单位测试跑道: Vitest
-   构件开发: 有Vite 的 第10号故事集

## 面包屑导航

网站模板接受可选 `breadcrumbContext` 提供的页面参考文献 由网站的客户端导航跟踪器执行. 来探路的访客 页面在面包屑中看到部分 当目的地是它的其中之一 信件详细链接或相关页面。 相关背景可以继续 详细页面,访问者离开该部分后即可清除.

背景与浏览器历史条目一起存储, 因此刷新和返回/ 前置 能够恢复这次访问的背景。 原生的同塔布链接也可以带短寿命 引用页确认过渡时到达记录 。 直接访问, 未知来源, 无法使用浏览器存储, 并丢弃历史状态 回到现有的面包屑。 水合后恢复上下文.

只有信头链接更改 。 URL、相关页面、, `parentPage`日期 时间, 类别,以及现有的公告/故事导航保留其行为. 没有每页编辑器设置或额外的面包屑数据请求.

推出需要发布这个UI软件包,更新网站的UI依赖, 并部署网站集成。 CommCenter和数据库不需要更改.

## 公共条目

支持的导入路径定义于 `package.json` 并守护着 `scripts/public-api-contract.js`数字 :

-   `@asd20/ui-next`
-   `@asd20/ui-next/components`
-   `@asd20/ui-next/templates`
-   `@asd20/ui-next/templates/*`
-   `@asd20/ui-next/icons`
-   `@asd20/ui-next/helpers`
-   `@asd20/ui-next/directives`
-   `@asd20/ui-next/install`
-   `@asd20/ui-next/styles.css`
-   `@asd20/ui-next/design/*`
-   `@asd20/ui-next/assets/*`
-   `@asd20/ui-next/package.json`

下游重置器应该通过这些路径导入。 私人来源进口 非辅助合同的一部分,除非合同明确涵盖 软件包 `exports` 地图.

## 源版式

| 路径 | 目的 |
| --- | --- |
| `components.js` | 公共部件出口. |
| `templates.js` | 公共模板导出. |
| `icons.js` | 生成图标组件导出 . |
| `helpers.js` | 公共帮手出口. |
| `directives.js` | 公共指令出口. |
| `install.js` | Vue 插件安装助手 . |
| `src/components/atoms/` | 基础UI组件. |
| `src/components/molecules/` | 综合控制和显示单元. |
| `src/components/organisms/` | 较大的站点/应用程序部分. |
| `src/components/templates/` | 网站和应用程序模板. |
| `src/design/` | CSS标志, 萨斯帮手,打字,模板堆栈,图像. |
| `src/assets/icons/` | Raw SVG 图标资产 . |
| `src/helpers/` | 共享帮助者执行. |
| `src/directives/` | 指令的执行. |
| `scripts/` | 构建,软件包,发布,以及校验脚本. |
| `docs/migration/` | 历史迁徙与出行笔记. |

## 地方发展

```sh
nvm install
nvm use
npm install --global npm@11.19.1
node --version # v24.22.2
npm --version # 11.19.1
npm ci
npm run storybook
npm test
npm run build
```

可供选择的带子可以促进可重复的物理设备 检查滚动、触摸、焦点、键盘和视图的更改:

```sh
npm run test:mobile:storybook
npm run test:mobile:package
```

这些命令是人工测试辅助. 他们不是测试,CI,释放,或 软件包出版要求.

见 [物理移动设备测试](https://npmcn.com/package/%40asd20/ui-next/docs/mobile-device-testing.md) 联 合 国 设备核对表、包装消费者工作流程、选项和故障排除.

添加、删除或重命名 SVG 图标资产后再生成图标元数据 :

```sh
npm run generate:icons
npm run verify:icon-metadata
```

## 软件包验证

建造有舞台的出版文物:

```sh
npm run build:package
```

核查来源和已设计的包件合同:

```sh
npm run verify:publish
```

这个命令重建 `dist/package`,核实公共出口,核实Vue 3 输入/使用周期/安装式合同,核实已安装的软件包,并运行 `npm pack --dry-run`。 。 。 .

验证包装的消费者安装路径 :

```sh
npm run verify:release
```

命令检查图标元数据,运行单元测试和 `verify:publish`, (中文(简体) ), 然后将已上演的软件包装入临时 Vue 3 Vite 烟雾应用程序, 与此退出连接的依赖关系 。 进口大众 组件/平板/凸轮/扶手/方向/样式,验证包件 从一个干净的缓存中完成 Vite 开发优化器输入集,并确认 生产消费建筑以Vite默认的 CSS 修饰成功.

## 释放

```sh
npm run release
```

发行流出版自 `dist/package`标记为 `ui-next-v${version}`, (中文(简体) ), 运行 `npm run verify:release` 发表前.

主分支工作流程自动发布. 为本地验证, 运行 `npm run lint`, (中文(简体) ), `npm run verify:release`,以及 `npm run build-storybook`· ; `verify:release` 包含 `verify:publish`。这些检查不公布. 仅凭开发运行时间升级就不需要新的图书馆发行.

## 变革指导

这个 [PDF 服务实施概况](https://npmcn.com/package/%40asd20/ui-next/docs/projects/pdf-service/README.md) 记录共享 PDF 出版提案、 Azure 调查结果、背景标题 (c) 执行工作.

在修改该套件之前,确定哪些公共入境点受到影响 它在下游重新吞噬它。 模板、样式/托盘、图标、输入模式和 帮助更改特别可能要求下游网站或应用 核查.

关于更广泛的建筑背景,见 `../asd20-website/docs/platform/shared-ui-contract.md`。 。 。 .

移民记录 `docs/migration/` 用于审计历史, 和未来的清理规划.

## 常见问题

### @asd20/ui-next 是什么？

Vue 3 的 ASD20 UI 组件库\.

### 如何安装 @asd20/ui-next？

在项目目录运行 npm install @asd20/ui-next，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @asd20/ui-next 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/asd20\_\_ui-next 是否存在。

### @asd20/ui-next 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @asd20/ui-next 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @asd20/ui-next 可以商用吗？

@asd20/ui-next 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @asd20/ui-next 的下载量有多少？

根据 npm 官方下载统计，@asd20/ui-next 在 2026/10/07 – 2026/11/05 这 30 天内被下载 4,796 次，日均约 160 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @asd20/ui-next 还在维护吗？

最新版本 2\.35\.2 发布于 2026/11/05（3 天前）；至今共发布 175 个版本，其中过去 12 个月发布了 175 个；首次发布于 2026/03/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。