# @gemeente-denhaag/modal 中文文档

规范地址：https://npmcn.com/package/%40gemeente-denhaag/modal/

版本：3\.2\.0
npm 元数据更新时间：2026-10-05T10:28:52.536Z
中文译文更新时间：2026-11-16T02:42:29.927Z
软件包许可：EUPL-1\.2

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

原始 npm 页面：https://www.npmjs.com/package/%40gemeente-denhaag/modal
原文对照：https://npmcn.com/package/%40gemeente-denhaag/modal/?lang=original
源码仓库：https://github.com/nl-design-system/denhaag

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

- 包体积（解压后）：49.4 kB，31 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react 18 \|\| 19，react-dom 18 \|\| 19
- 首次发布：2022-01-24T15:17:39.691Z
- 最新版本发布：2026-10-05T10:28:52.203Z
- 近 30 天下载量：3639（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：361（近 12 个月 9 个）

## 中文简介

摩达尔部分

## 安装

```sh
npm install @gemeente-denhaag/modal
```

也可以使用：`pnpm add @gemeente-denhaag/modal`、`yarn add @gemeente-denhaag/modal`、`bun add @gemeente-denhaag/modal`

## README

# 模式

[![npm version](https://img.shields.io/npm/v/@gemeente-denhaag/modal.svg)](https://www.npmjs.com/package/@gemeente-denhaag/modal)

Modals是覆盖的,在采取特定行动之前阻止用户与其余应用程序互动.

## 何时使用

使用一种方式要求信息,使该系统无法继续由用户发起的进程。 还可用来通知用户关于其当前工作的紧急信息。 模块对话框通常用于报告系统错误或传达用户行为的后果。 最后,它可用于确认用户的决定. 明确描述正在确认的行动并解释其可能产生的任何潜在后果。 标题和按钮都应反映将要发生的动作.

## 替代品和相关构成部分

-   用手风琴提供大量不需要确认的额外信息或行动
-   使用横幅来表达一个需要用户在页面上下文中注意的更改或条件

## 解剖学

模式包括:

1.  标题:给用户一个快捷的模式概述.
2.  关闭图标:关闭模式.
3.  文本: 包含完成模式任务所需的信息。 它可以包括消息文本和组件.
4.  按钮(可选):允许用户执行动作或关闭模式的按钮.
5.  重叠:屏幕上覆盖会模糊页面内容.

## (互动)状态

无.

## 设计属性

### 类型

-   标题:Mix/xl/700
-   文本:桑斯语/md/400

### 颜色

-   标题: 文字颜色 Blue/3
-   关闭图标: svg 颜色 Grey/4
-   文字: 文字颜色 Grey/4
-   重叠:背景颜色为白色

### 按钮

按钮只使用文字,中度主音和秒音.

### 结构

-   标题:上行-上行-上行-左行-32px,下行-下行-16px
-   关闭图标:高度和宽度 24px, 贴地- 右 32px
-   文字: 贴地- 左和贴地- 右 32px, 边- 下 48px
-   按钮:贴上右下32px,贴上16px按钮之间的空间

## 无障碍

\[技术无障碍要求\]

### 表单中的错误提醒

#### 错误提醒

如果用户提交长或复杂有出错的表格,使用出错提示来总结出错. 将提示放在表单上方,提交表单时将焦点移动到横幅上. 这将使所有用户能够按逻辑顺序从表格中滚动,解决问题.

#### 内入错误

总是包含特定窗体字段的内置出错消息,这样用户在纠正出错的同时知道上下文中该做什么.

## 内容准则

### 标题

模块标题应:

-   使用清晰的 {动词} 问题或语句 .

### 内容

身体内容应为:

-   可操作性:在告诉用户哪些动作可供使用时(特别是一些新动作),用必须的动词起句. 不要使用“你可以”这样的宽容语言.
    
-   为用户成功安排结构:总是将最关键的信息放在首位.
    
-   清晰:使用动词"需要"帮助用户在被要求做某事时理解.
    

### 初级和二级行动

行动应:

-   明确和可预测的:用户应能够预测点击按钮时会发生什么。 永远不要通过错误地给一个动作贴上标签来欺骗用户.
-   以行动为主导的:行动应始终以强有力的动词来引导,鼓励行动。 要向用户提供足够的上下文, 只需使用 {verb}+{noun} 格式即可操作, 但常见动作如 Save, Close, Cancel 或 OK 除外 .
-   可扫描:避免不必要的单词和文章,如:a,或a.

## 最佳做法

### 编号

在用户必须完成动作后才能继续主工作流程时使用模式. 避免使用模式显示复杂形式或大量信息.

模块应:

-   要求用户采取行动.
-   当用户按下X按钮,取消按钮,或ESC键时关闭,而不是当用户点击或点击模式外的区域时关闭.
-   尽量少用.
-   用于重要的警告,作为防止或纠正重要错误的方法.
-   用于请求用户输入对继续当前进程至关重要的信息.
-   已采取行动后通知用户.

### 不要这样

模块应:

-   不用于与当前用户流无关的非必要信息.
-   底部没有超过两个按钮(一级和二级). 这防止了动作分级不清,移动屏幕上出现拥挤. 由于模式是用于重点任务,因此应当有重点行动.
-   当用户点击或点击模式以外的区域时, 不可拆解 .
-   不包括多个步骤.
-   别挤太多.
-   不包括重要信息.
-   突然间没有打开 一种模式应始终对做(或做了)某事的用户开放.

## Javascript

导入 `@gemeente-denhaag/modal/src/modal.js` javascript文件到您的站点允许模式工作.

见以下例子:

```javascript
import ModalScripts from "@gemeente-denhaag/modal/src/modal";
window.addEventListener("DOMContentLoaded", () => new ModalScripts());
```

## 参考资料

[图像设计](https://www.figma.com/file/JpoY3waVoQGlLQzQXTL9nn/Design-System---Gemeente-Den-Haag?node-id=0%3A1) [http://www.uxforthemasses.com/overlays/ (中文(简体) )](http://www.uxforthemasses.com/overlays/) [https://www.nngroup.com/articles/module-nmodule-dialog/ 互联网档案馆的存檔,存档日期2013-12-22](https://www.nngroup.com/articles/modal-nonmodal-dialog/)

## 常见问题

### @gemeente-denhaag/modal 是什么？

摩达尔部分

### 如何安装 @gemeente-denhaag/modal？

在项目目录运行 npm install @gemeente-denhaag/modal，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（18 \|\| 19）、react-dom（18 \|\| 19）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gemeente-denhaag/modal 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gemeente-denhaag/modal 支持 ESM 还是 CommonJS？

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

### @gemeente-denhaag/modal 可以商用吗？

@gemeente-denhaag/modal 使用 EUPL-1\.2 许可。声明的许可为 EUPL-1\.2，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @gemeente-denhaag/modal 的下载量有多少？

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

### @gemeente-denhaag/modal 还在维护吗？

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

