+
+
](https://godban.github.io/browsers-support-badges//)
](https://godban.github.io/browsers-support-badges/)
](https://godban.github.io/browsers-support-badges/)
](https://godban.github.io/browsers-support-badges/)
](https://godban.github.io/browsers-support-badges/)
](https://godban.github.io/browsers-support-badges/)
---
---
order: 7
title: LLMs.txt
tag: new
---
本指南介绍如何让 AI 工具更好地理解 NG-ZORRO 组件库。
## 什么是 LLMs.txt？
我们支持通过 [LLMs.txt](https://llmstxt.org/) 文件向大语言模型（LLMs）提供 `ng-zorro-antd` 文档。此功能可帮助 AI 工具更好地理解我们的组件库、API 及使用模式。
## 可用资源
### LLMs.txt 聚合文件
我们提供多个聚合文件来帮助 AI 工具访问文档：
| 文件 | 说明 |
| ---------------------------------------------------------- | ------------------------------------------ |
| [llms.txt](https://ng.ant.design/llms.txt) | 导航文件，包含所有文档和组件的链接 |
| [llms-full.txt](https://ng.ant.design/llms-full.txt) | 完整的组件文档（英文），包含实现细节和示例 |
| [llms-full-cn.txt](https://ng.ant.design/llms-full-cn.txt) | 完整的组件文档（中文） |
### 单个组件文档
通过 `.md` 后缀直接访问单个组件文档：
- `https://ng.ant.design/components/button.en.md`（英文）
- `https://ng.ant.design/components/button.cn.md`（中文）
## 在 AI 工具中的使用
| 工具 | 说明 | 提示词 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Cursor** | 使用 `@Docs` 功能引入 LLMs.txt，或添加提示词到 `.cursor/rules`。[文档](https://docs.cursor.com/zh/context/@-symbols/@-docs) | `阅读 https://ng.ant.design/llms-full-cn.txt 并理解 NG-ZORRO 组件库，在编写 NG-ZORRO 代码时使用这些知识。` |
| **Windsurf** | 添加提示词到 `.windsurf/rules` 或使用 cascade memories。[文档](https://docs.windsurf.com/windsurf/cascade/memories) | `阅读 https://ng.ant.design/llms-full-cn.txt 并理解 NG-ZORRO 组件库，在编写 NG-ZORRO 代码时使用这些知识。` |
| **Claude Code** | 添加到 CLAUDE.md 或使用 `/memory` 持久化。[文档](https://docs.anthropic.com/en/docs/claude-code) | `阅读 https://ng.ant.design/llms-full-cn.txt 并理解 NG-ZORRO 组件库，在编写 NG-ZORRO 代码时使用这些知识。` |
| **GitHub Copilot** | 添加到 `.github/copilot-instructions.md`。[文档](https://docs.github.com/zh/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) | `阅读 https://ng.ant.design/llms-full-cn.txt 并理解 NG-ZORRO 组件库，在编写 NG-ZORRO 代码时使用这些知识。` |
| **Codex** | 添加到 `.codex/settings.json` 或 AGENTS.md。[文档](https://github.com/openai/codex) | `阅读 https://ng.ant.design/llms-full-cn.txt 并理解 NG-ZORRO 组件库，在编写 NG-ZORRO 代码时使用这些知识。` |
| **Gemini CLI** | 使用 `--context` 参数或添加到 `.gemini/config.json`。[文档](https://ai.google.dev/gemini-api/docs?hl=zh-cn) | `阅读 https://ng.ant.design/llms-full-cn.txt 并理解 NG-ZORRO 组件库，在编写 NG-ZORRO 代码时使用这些知识。` |
| **Trae** | 添加到项目的知识源设置中。[文档](https://trae.ai/docs) | `阅读 https://ng.ant.design/llms-full-cn.txt 并理解 NG-ZORRO 组件库，在编写 NG-ZORRO 代码时使用这些知识。` |
| **Qoder** | 添加到 `.qoder/config.yml` 或在对话中使用 `@docs`。[文档](https://docs.qoder.com/) | `阅读 https://ng.ant.design/llms-full-cn.txt 并理解 NG-ZORRO 组件库，在编写 NG-ZORRO 代码时使用这些知识。` |
| **Neovate Code** | 运行 `neovate` 并使用提示词描述任务。[文档](https://github.com/neovateai/neovate-code) | `阅读 https://ng.ant.design/llms-full-cn.txt 并理解 NG-ZORRO 组件库，在编写 NG-ZORRO 代码时使用这些知识。` |
---
---
order: 7
title: 全局配置项
---
我们给众多组件添加了**全局配置**功能，你可以通过全局配置来定义组件的默认行为，从而减少在模板中需要写的代码（让你的代码更加清爽），还能在运行时修改全局配置项。
## 如何使用
想要为某些组件提供默认配置项, 可以使用 `provideNzConfig` 函数，传入一个符合 `NzConfig` 接口的对象。例如：
```typescript
import { NzConfig, provideNzConfig } from 'ng-zorro-antd/core/config';
const ngZorroConfig: NzConfig = {
// 注意组件名称没有 nz 前缀
message: { nzTop: 120 },
notification: { nzTop: 240 }
};
export const appConfig: ApplicationConfig = {
providers: [provideNzConfig(ngZorroConfig)]
};
```
这些全局配置项将会被注入 `NzConfigService` 当中并保存。
### 提供模板
一些组件支持传递模板 `TemplateRef
src/styles
├── dark.less
├── default.less
└── themes
├── base.less
├── dark.less
├── default.less
└── mixin.less
`src/styles/` 下的主题文件是主题入口文件，它的作用是引入预定义官方 Less 样式入口文件以及 `src/styles/themes/` 下对应的主题样式定制文件。例如，`src/styles/dark.less` 入口文件含有以下代码：
```less
@import '../../node_modules/ng-zorro-antd/ng-zorro-antd';
@import './themes/dark';
```
相应的，`src/styles/themes/dark.less` 文件负责定制暗黑主题的样式：
```less
@import (multiple) '../../../node_modules/ng-zorro-antd/src/style/themes/dark';
@import './base';
@layout-sider-background: @component-background;
@layout-header-background: @component-background;
```
> 当引入对应的预定义主题样式变量文件的时候，会遇到 `.less` 样式文件名跟项目自己的主题样式文件名是一样的情况，这样的话单单使用 `@import '### Angular 是不是打出来的包很大？ `ng-zorro-antd` 打包大小如何？ Angular 的 hello-world 项目（包含路由、动画与 Http 等模块） gzip 之后大概 `30KB`，`ng-zorro-antd` 的官网（包含所有组件，懒加载）打包后 gzip 之后为 `287KB`。这与 React 或者 Vue 增加路由、动画、Http 等模块之后 gzip 的体积不会有太大差异。 如果碰到了打包大小问题，首先请确定使用了 `ng build --prod` 正确的方式进行了打包，如果除 `ng-zorro-antd` 之外还引入了其他第三方组件库，你可以通过 `ng build --prod --sourceMap=true` 命令生成 sourcemap 文件后，再通过 source-map-explorer 检查每个模块所占用的体积，具体操作可以参考[官方文档](https://angular.cn/guide/deployment#inspect-the-bundles)。 ### Angular 是不是过时了，运行会慢吗？`ng-zorro-antd` 性能如何？ Angular 与 angular.js 不是同一种前端框架，angular.js 发布的时间在 2010 年 10 月份，而 Angular 诞生时间在 2016 年 9 月份，比 React 和 Vue 的诞生时间都要晚。 总体而言 Angular Vue 与 React 三种框架的运行速度没有太大差异，也不会是你项目运行时快慢的决定因素，具体的性能参数可以参考[该项目](https://github.com/krausest/js-framework-benchmark)。`ng-zorro-antd` 的所有组件均为原生 Angular 组件，并且默认运行在 `OnPush` 模式下，能够保证以 Angular 支持的最优速度运行。 ### 我可以在 Angular 其他版本中使用 ng-zorro-antd 吗？ `ng-zorro-antd` 与 `@angular/core` 保持相同的主版本号，例如 `ng-zorro-antd@8` 支持 `@angular/core@8` 版本，依次类推，为了获得最好的性能，推荐升级至最新版本的 Angular。升级 Angular 可以参考[此文档](https://angular.cn/update-guide)。 ### 我可以只使用 ng-zorro-antd 的部分组件吗？ `ng-zorro-antd` 的所有组件均支持单独导入使用，与其他的流行组件库可以混用。 ### ng-zorro-antd 为什么使用 less 定制主题？ 我能使用 sass 吗？ ng-zorro-antd 的设计规范遵从 ant design，因此同样使用了 less 文件来定制主题，`@angular/cli` 支持同一个项目中混用多种 css 预处理器， 与 sass 等文件不会互相干扰。 ### ng-zorro-antd 能和 d3, echarts ...一起使用吗？ ng-zorro-antd 本质上是组件库，与用户自己写的 `@Component` 没有任何的区别，也不会与第三方库产生冲突。 ### Can't Bind to since it isn't a known property of 如果使用多 Module 管理方式，NG-ZORRO 的模块需要在每个子 Module 中都要 import，或者在 `ShareModule` 中 export，可以参考[官方文档](https://angular.cn/guide/ngmodules/sharing)。 ### Expression Changed After It Has Been Checked Error 错误 Angular 的数据流是单向数据流，违反数据流走向会引起该问题，[这篇文章](https://blog.angularindepth.com/everything-you-need-to-know-about-the-expressionchangedafterithasbeencheckederror-error-e3fd9ce7dbb4)会帮助你理解原因。 ### Can't bind to 'formGroup' since it isn't a known property of 'form' 使用 Reactive Forms 需要额外引入 `ReactiveFormsModule`，可以参考[官方文档](https://angular.cn/guide/forms/reactive-forms)。 ### 模板中 `[nzValue]="data"` `nzValue="data"` 与 `nzValue="{{data}}"` 有什么区别 `nzValue="data"` 组件收到的是字符串 `data`，`nzValue="{{data}}"` 等价于 `[nzValue]="data.toString()"`。如果你需要传入 `number` 或者 `boolean` 类型时，应当使用 `[nzValue]="data"` 的方式。 ### 数据修改后页面为什么没有更新 为了获得更好的性能，NG-ZORRO 所有组件都运行在 [OnPush](https://angular.cn/guide/components/advanced-configuration#changedetectionstrategy) 模式下，这意味着对 `@Input()` 数据的 mutate 将不会生效，请使用 immutable 方式操作数组或者对象。 ```typescript // 增加数据 this.dataSet = [ ...this.dataSet, { key: `${this.i}`, name: `Edward King ${this.i}`, age: '32', address: `London, Park Lane no. ${this.i}` } ]; // 删除数据 this.dataSet = this.dataSet.filter(d => d.key !== i); ``` 开发者也可以使用 [immer](https://immerjs.github.io/immer/docs/introduction) 获得更好的操作体验 ### 我的页面卡死了，函数不停的在执行 在 Angular 的模板表达式中，绑定带有副作用的属性或者方法都是[危险的](https://angular.cn/guide/template-syntax#avoid-side-effects)，如果你违反了这条规则，很可能会造成性能下降甚至引起死循环。以下的代码会在页面中不停输出 `I will run every time`，因为 `console.log` 本身是一种副作用函数。 ```typescript @Component({ template: ` ` }) export class BugComponent { value(): string { console.log('I will run every time'); return 'value'; } } ``` ### 怎样才能进一步提高 Angular 项目性能？ 推荐 [https://web.dev/angular](https://web.dev/angular) 的系列文章 ### 为什么我的 ISSUE 会被关闭 ISSUE 列表是为了 开发者 和 用户 追踪相关的开发进度而设计的，这意味 ISSUE 只接受 bug 报告或是新功能请求 (feature requests)，这意味着我们不接受用法问题。 另外为了给予 更具体的工作更高的优先级和提高 ISSUE 处理的效率，未按照 格式提交的 ISSUE 也将会被立刻自动关闭。 ### 有些特性为什么不会被支持 `ng-zorro-antd` 是 Angular 版本 Ant Design 的实现，这意味着只有 Ant Design 支持的交互、功能 才会被 `ng-zorro-antd` 实现。 ### 浏览器兼容性问题 首先请确定浏览器版本得到了 Angular 的[官方支持](https://github.com/angular/angular)，并正确引入了 [polyfill](https://angular.cn/reference/versions#polyfills) 文件，另外有些组件的部分使用方式不支持部分浏览器（例如 flex显示方式），如果不是以上问题，请提 ISSUE 给我们。 ### 官网能正常工作，相同的用法本地运行有问题，是组件库的 BUG 吗？ 不会，NG-ZORRO 的官网使用在 npm 上发布的相同版本构建，所有的构建日志都可以在 [Azure](https://dev.azure.com/ng-zorro/NG-ZORRO) 查看，请仔细检查本地运行环境（版本，其他依赖包）等问题。 ### Angular的相关问题在哪里提问 除了Angular的官方文档和相关的论坛之外，Angular的相关问题可以在 Google 或者 百度 上搜索 `关键字 -angularjs` 来避免 `angularjs` 的干扰，例如 `angular ngmodel -angularjs` 就可以获得 Angular 关于 `ngModel` 的相关文章。 --- --- order: 1 title: 快速上手 --- NG-ZORRO 致力于提供给程序员**愉悦**的开发体验。更多常见问题请搜索标有 FAQ 的 issue。
## 在线演示 最简单的使用方式参照以下 StackBlitz 演示，也推荐 Fork 本例来进行 `Bug Report`，注意不要在实际项目中这样使用。 - [NG-ZORRO StackBlitz](https://stackblitz.com/edit/ng-zorro-antd-ivy) ## 第一个本地实例 实际项目开发中，你会需要对 TypeScript 代码的构建、调试、代理、打包部署等一系列工程化的需求。 我们强烈建议使用官方的 `@angular/cli` 工具链辅助进行开发，下面我们用一个简单的实例来说明。 ### 安装脚手架工具 > 如果你想了解更多CLI工具链的功能和命令，建议访问 [Angular](https://angular.cn/cli) 了解更多。 ```bash $ npm install -g @angular/cli ``` ### 创建一个项目 > 在创建项目之前，请确保 `@angular/cli` 已被成功安装。 执行以下命令，`@angular/cli` 会在当前目录下新建一个名称为 `PROJECT-NAME` 的文件夹，并自动安装好相应依赖。 ```bash $ ng new PROJECT-NAME ``` ### 初始化配置 进入项目文件夹，执行以下命令后将自动完成 `ng-zorro-antd` 的初始化配置，包括引入国际化文件，导入模块，引入样式文件等工作。 ```bash $ ng add ng-zorro-antd ```官方指南假设你已了解关于 HTML、CSS 和 JavaScript 的中级知识，并且已经完全掌握了 Angular 及配套设施的正确开发方式。如果你刚开始学习前端或者 Angular ，将框架作为你的第一步可能不是最好的主意 —— 掌握好基础知识再来吧！
开发者可以通过增加参数来完成个性化的初始化配置，例如国际化或者自定义主题等，详细可以参考 [脚手架](/docs/schematics/zh) 部分。
### 开发调试
一键启动调试，运行成功后显示欢迎页面。
```bash
$ ng serve --port 0 --open
```
### 构建和部署
```bash
$ ng build --prod
```
文件会被打包到 `dist` 目录中。
## 手动安装
如果想自己维护工作流，理论上你可以利用 Angular 生态圈中的 各种脚手架进行开发，如果遇到问题可参考我们所使用的 [配置](https://github.com/NG-ZORRO/ng-zorro-antd/tree/master/integration) 进行定制。
### 安装组件
```bash
$ npm install ng-zorro-antd --save
```
### 引入样式
#### 使用全部组件样式
该配置将包含组件库的全部样式，如果只想使用某些组件请查看 [使用特定组件样式](/docs/getting-started/zh#使用特定组件样式) 配置。
在 `angular.json` 中引入了
```json
{
"styles": ["node_modules/ng-zorro-antd/ng-zorro-antd.min.css"]
}
```
在 `style.css` 中引入预构建样式文件
```css
@import '~ng-zorro-antd/ng-zorro-antd.min.css';
```
在 `style.less` 中引入 less 样式文件
```less
@import '~ng-zorro-antd/ng-zorro-antd.less';
```
#### 使用特定组件样式
> 由于组件之间的样式也存在依赖关系，单独引入多个组件的 CSS 可能导致 CSS 的冗余。
使用特定组件样式时前需要先引入基本样式(所有组件的共用样式)。
在 `style.css` 中引入预构建样式文件
```css
@import '~ng-zorro-antd/style/index.min.css'; /* 引入基本样式 */
@import '~ng-zorro-antd/button/style/index.min.css'; /* 引入组件样式 */
```
在 `style.less` 中引入 less 样式文件
```less
@import '~ng-zorro-antd/style/entry.less'; /* 引入基本样式 */
@import '~ng-zorro-antd/button/style/entry.less'; /* 引入组件样式 */
```
### 引入组件模块
最后你需要将想要使用的组件模块引入到你的组件中。
以下面的 `NzButtonModule` 模块为例：
```ts
import { Component } from '@angular/core';
import { NzButtonModule } from 'ng-zorro-antd/button';
@Component({
imports: [NzButtonModule]
})
export class AppComponent {}
```
然后在模板中使用：
```html
```
# 注意事项
- `ng-zorro-antd` 已经包含了 `@angular/cdk/overlay-prebuilt.css` 浮层样式，无需额外导入。
## 其他
- [国际化配置](/docs/i18n/zh)
- [自定义主题](/docs/customize-theme/zh)
- [使用图标](/components/icon/zh)
---
---
order: 9
title: 文字方向
---
设置文字方向（LTR / RTL）。
## 设置默认方向
在文档 `body` 或者 `html` 标签上设置 `dir` 属性。
```html
```
## 在模版中设置
引入 Angular CDK bidi 模块
```typescript
import { BidiModule } from '@angular/cdk/bidi';
```
在模版中为应用或其后代设置方向。
```html
```
## 在服务中设置
例如对话框（Modal）服务。
```typescript
class MyComponent {
private modalService = inject(NzModalService);
private nzConfigService = inject(NzConfigService);
openModal(): void {
this.modal.create({ nzDirection: 'rtl' });
}
setDirWithConfig(): void {
this.nzConfigService.set('modal', { nzDirection: 'rtl' });
}
}
```
## 参考
- [Angular CDK Bidirectionality](https://material.angular.io/cdk/bidi/api)
- [dir - HTML | MDN](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Global_attributes/dir)
---
---
order: 2
title: 脚手架
---
使用脚手架可以更加方便的初始化项目，生成模板代码，节省开发时间。
> 脚手架部分完全基于 [Schematics](https://blog.angular.dev/schematics-an-introduction-dc1dfbc2a2b2) 部分进行开发。
## 项目初始化
在项目下运行命令 `ng add ng-zorro-antd` 跟随选项便可完成初始化配置，包括引入国际化文件，导入模块，引入样式文件等工作。
同时你可以通过选择预设的模板创建一个 Angular 项目，并在此基础上进行开发。
## 生成组件
快速生成模板代码，每个官网的代码演示都附有可生成的模板，开发者可以通过展开每个组件的代码演示部分获取其生成代码。
### 命令
```bash
ng g ng-zorro-antd:[schematic] 
## 生成组件
快速生成模板代码，每个官网的代码演示都附有可生成的模板，开发者可以通过展开每个组件的代码演示部分获取其生成代码。
### 命令
```bash
ng g ng-zorro-antd:[schematic]