# @meshmakers/shared-ui 中文文档

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

版本：3\.5\.550
npm 元数据更新时间：2026-11-01T19:23:14.115Z
中文译文更新时间：2026-11-01T21:43:50.243Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40meshmakers/shared-ui
原文对照：https://npmcn.com/package/%40meshmakers/shared-ui/?lang=original

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

- 包体积（解压后）：2.4 MB，58 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：marked ^18\.0\.0，@angular/core ^22\.0\.0，@angular/forms ^22\.0\.0，@angular/common ^22\.0\.0，@progress/kendo-svg-icons ^4\.8\.0，@progress/kendo-data-query ^1\.7\.3，@meshmakers/shared-services \*，@progress/kendo-angular-grid ^24\.1\.0，@progress/kendo-angular-icons ^24\.1\.0，@progress/kendo-angular-label ^24\.1\.0，@progress/kendo-angular-popup ^24\.1\.0，@progress/kendo-angular-dialog ^24\.1\.0，@progress/kendo-angular-inputs ^24\.1\.0，@progress/kendo-angular-layout ^24\.1\.0，@progress/kendo-angular-buttons ^24\.1\.0，@progress/kendo-angular-treeview ^24\.1\.0，@progress/kendo-angular-dropdowns ^24\.1\.0，@progress/kendo-angular-indicators ^24\.1\.0，@progress/kendo-angular-notification ^24\.1\.0
- 首次发布：2022-11-13T22:11:09.620Z
- 最新版本发布：2026-11-01T19:23:13.950Z
- 已发布版本数：719（近 12 个月 288 个）

## 中文简介

用于OctoMesh平台应用的Angular UI组件库。

## 安装

```sh
npm install @meshmakers/shared-ui
```

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

## README

# @meshmakers /共享的ui

用于OctoMesh平台应用的Angular UI组件库。

提供可重用组件、对话框服务、数据源、管道和守卫，用于跨OctoMesh前端应用程序构建一致的ui。

**注意：** 这个图书馆需要一个 [Angular的剑道UI](https://www.telerik.com/kendo-angular-ui) 许可证。

部分 [@meshmakers](https://www.npmjs.com/org/meshmakers) 包的生态系统。

## 安装

```bash
npm install @meshmakers/shared-ui
```

### 环境设置

通过环境提供程序注册所有服务：

```typescript
import { provideMmSharedUi } from '@meshmakers/shared-ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideMmSharedUi(),
    // ...
  ]
};
```

## 构建和测试

```bash
# Build
npm run build:shared-ui

# Lint
npm run lint:shared-ui

# Run tests
npm run test:shared-ui
```

## 体系结构

```
shared-ui/
├── src/
│   ├── public-api.ts                          # Public API exports
│   └── lib/
│       ├── list-view/                         # Configurable grid/table
│       │   ├── list-view.component.ts|html|scss
│       │   └── list-view.model.ts             # TableColumn, StatusIconMapping
│       ├── base-form/                         # Form wrapper with save/cancel
│       │   └── base-form.component.ts|html|scss
│       ├── base-tree-detail/                  # Tree + detail panel layout
│       │   └── base-tree-detail.component.ts|scss
│       ├── tree/                              # Hierarchical tree view
│       │   └── tree.component.ts|html|scss
│       ├── cron-builder/                      # Visual cron expression editor
│       │   ├── cron-builder.component.ts|html|scss
│       │   ├── cron-builder.models.ts
│       │   ├── cron-parser.service.ts
│       │   ├── cron-humanizer.service.ts
│       │   └── cron-builder.constants.ts
│       ├── time-range-picker/                 # Flexible time range selector
│       │   ├── time-range-picker.component.ts|html|scss
│       │   ├── time-range-picker.models.ts
│       │   └── time-range-utils.ts
│       ├── copyable-text/                     # Text with copy-to-clipboard
│       │   └── copyable-text.component.ts|html|scss
│       ├── entity-select-input/               # Entity autocomplete input
│       │   └── entity-select-input.component.ts
│       ├── entity-select-dialog/              # Entity selection modal
│       │   ├── entity-select-dialog.component.ts
│       │   ├── entity-select-dialog.service.ts
│       │   └── entity-select-dialog-data-source.ts
│       ├── confirmation-window/               # Confirmation dialog
│       │   └── confirmation-window.component.ts|html
│       ├── input-dialog/                      # Text input dialog
│       │   └── input-dialog.component.ts|html|scss
│       ├── progress-window/                   # Progress dialog
│       │   ├── progress-window.component.ts|html|scss
│       │   ├── progress-window.service.ts
│       │   └── USAGE.md
│       ├── upload-file-dialog/                # File upload dialog
│       │   └── upload-file-dialog.component.ts|html
│       ├── save-as-dialog/                    # Save-as dialog
│       │   ├── save-as-dialog.component.ts
│       │   ├── save-as-dialog.service.ts
│       │   └── save-as-dialog-data-source.ts
│       ├── import-strategy-dialog/            # Import strategy dialog
│       │   ├── import-strategy-dialog.component.ts|html
│       │   └── import-strategy-dialog.service.ts
│       ├── message-details-dialog/            # Message details dialog
│       │   ├── message-details-dialog.component.ts
│       │   └── message-details-dialog.service.ts
│       ├── data-sources/                      # Base data source classes
│       │   ├── data-source-base.ts
│       │   ├── data-source-typed.ts
│       │   ├── hierarchy-data-source-base.ts
│       │   └── hierarchy-data-source.ts
│       ├── guards/                            # Unsaved changes protection
│       │   ├── unsaved-changes.interface.ts
│       │   ├── unsaved-changes.guard.ts
│       │   └── unsaved-changes.directive.ts
│       ├── directives/
│       │   └── mm-list-view-data-binding.directive.ts
│       ├── pipes/
│       │   ├── pascal-case.pipe.ts
│       │   └── bytes-to-size.pipe.ts
│       ├── models/
│       │   ├── fetchResult.ts                 # FetchResult, FetchResultTyped<T>
│       │   ├── confirmation.ts                # ConfirmationWindowData, DialogType
│       │   ├── progressValue.ts               # ProgressValue
│       │   ├── inputDialogResult.ts
│       │   ├── importStrategyDto.ts
│       │   └── node-dropped-event.ts
│       ├── services/
│       │   ├── confirmation.service.ts
│       │   ├── file-upload.service.ts
│       │   ├── input.service.ts
│       │   ├── notification-display.service.ts
│       │   └── message-listener.service.ts
│       └── svg-icons.ts                       # Kendo SVG icon re-exports
├── docs/
│   ├── time-range-picker.md                   # Time Range Picker guide
│   └── unsaved-changes-guard.md               # Unsaved Changes Guard guide
```

## 组件

### ListViewComponent (`mm-list-view`）

可配置的数据网格与剑道网格集成。

**特点:** 分页、排序、过滤、行选择、搜索、上下文菜单、操作菜单、Excel/PDF导出、工具栏操作、列类型（文本、数字、布尔、日期、字节、状态图标、cron表达式）。

空状态（ab# 3444）： `[emptyState]="{ title, text }"` 显示共享的 `mm-empty-state` (OctoBot `idle`)用于没有记录的列表和“无结果”变体(OctoBot `look`)，而搜索或过滤是活跃的； `[emptyTemplate]` 取代它。如果没有这两种情况，列表将保留简单的“No records available.”行。

工具栏动作(`leftToolbarActions` / `rightToolbarActions`（AB#6211）渲染 **平淡和中性** 默认情况下：一个页面只有一个固定的主操作，它位于页面头(`[mmPageActions]`，工作室行动指南§9)。集 `primary: true` 在一个 `CommandItem` 仅适用于没有页头的列表（列表就是页面）。的工具栏操作 `isDisabled` + `disabledReason` -普通，拆分或下拉按钮-保持可聚焦(`aria-disabled`)，公布原因(`aria-describedby`)，显示在工具提示（“运行脚本-没有修复脚本运行”）和键盘焦点上的提示气泡；单击和菜单被阻止。一个 `disabledReason` 回调接收当前选择。

工具栏的“重置过滤器”按钮只出现在缩小默认视图的情况下：行过滤器、列排序、自由文本搜索或主机端过滤器。主机与他们自己的快速查看/栏过滤器宣布他们通过 `[hasExternalFilters]="myBarFilterIsSet"` 因此按钮显示（和） `(resetFilters)` 让他们在点击时清除这些过滤器)。

```html
<mm-list-view
  appMyDataSource
  #dir="appMyDataSource"
  [sortable]="true"
  [rowFilterEnabled]="true"
  [searchTextBoxEnabled]="true"
  [selectable]="{mode: 'single', enabled: true}"
  [pageable]="{buttonCount: 3, pageSizes: [10, 20, 50, 100]}"
  [pageSize]="20"
  [columns]="columns"
  [contextMenuCommandItems]="contextMenu"
  [leftToolbarActions]="toolbarActions"
  (rowClicked)="onRowClicked($event)">
</mm-list-view>
```

### BaseFormComponent (`mm-base-form`）

带有保存/取消按钮、标题、验证和未保存更改检测的表单包装器。

```html
<mm-base-form [form]="form" [config]="formConfig" (saveForm)="onSave()" (cancelForm)="onCancel()">
  <!-- Form fields -->
</mm-base-form>
```

### CronBuilderComponent (`mm-cron-builder`）

支持6字段格式的可视化cron表达式编辑器，预置的快速选择，人类可读的描述，下一次执行预览，以及 `ControlValueAccessor` 集成。

### TimeRangePickerComponent (`mm-time-range-picker`）

灵活的时间范围选择器，具有年、季度、月、相对和自定义模式。输出两个 `Date` 对象和ISO 8601字符串。

看到 [时间范围选择器文档](https://npmcn.com/package/%40meshmakers/shared-ui/docs/time-range-picker.md) 获取详细的API和示例。

### TreeComponent (`mm-tree`）

层次树视图与剑道树视图，拖放支持，和可扩展的节点。

### CopyableTextComponent (`mm-copyable-text`）

用一键复制到剪贴板按钮显示文本。

### 操作(`mm-row-actions`， `mm-action-button`）

从一个共享的行、工具栏和页面操作 `MmAction` 定义(id、标签、图标、危险、 禁用原因，可见)：带有工具提示和行特定可访问名称的图标按钮，max。3 带有“更多动作”菜单的内联插槽，可聚焦的禁用动作宣布其原因， 和一个规范动词→图标映射(`MM_ACTION_ICONS`）. 看到 [行动](https://npmcn.com/package/%40meshmakers/shared-ui/docs/actions.md).

```html
<mm-row-actions [actions]="actionsFor(row)" [rowLabel]="row.name" (triggered)="onAction($event, row)" />
<mm-action-button [action]="refresh" context="toolbar" (triggered)="reload()" />
```

### OctoBot (`mm-octobot`， `mm-empty-state`）

网格制作者将吉祥物作为一个小的动画像素艺术图像(`idle`， `blink`， `look`， `swim`， `thinking`， `wave`； `sm`/`md`/`lg`)，通过URL从库资源中加载(拷贝 `node_modules/@meshmakers/shared-ui/assets/octobot` 来 `/assets/octobot` 在 `angular.json`； base URL via `OCTOBOT_ASSET_BASE_URL`）. 装饰性的，除非有标签；仍在框架下 `prefers-reduced-motion`. `mm-empty-state` 是共享空/无结果/错误块，和 `mm-list-view [emptyState]` 每个列表渲染一次。放置规则(游戏邦注：不能成行、成片、 按钮，祝酒或错误)：见 [OctoBot](https://npmcn.com/package/%40meshmakers/shared-ui/docs/octobot.md).

```html
<mm-octobot animation="wave" size="md" playOnce />
<mm-list-view [emptyState]="{ title: 'No data flows yet', text: 'Create your first data flow.' }" ...></mm-list-view>
```

### EntitySelectInputComponent (`mm-entity-select-input`）

带有对话框回退的实体选择自动完成输入。

## 对话框的服务

所有复杂的对话框都是通过注入服务打开的：

| 服务 | 方法 | 描述 |
| --- | --- | --- |
| `ConfirmationService` | `showYesNoConfirmationDialog()` | 是的/不确认 |
|  | `showYesNoCancelConfirmationDialog()` | 是/否/取消有结果 |
|  | `showOkCancelConfirmationDialog()` | 好的/取消确认 |
|  | `showOkDialog()` | Ok-only信息对话框 |
|  | `showDestructiveConfirmationDialog(title, message, confirmLabel, cancelLabel = 'Cancel')` | 破坏性动作：动词标签（例如旋转/取消），确认按钮样式为危险 |

所有确认对话框都是 `min(320px, 100vw − 32px)` 来 `min(560px, 100vw − 32px)` 宽，所以一个长消息包装，而不是拉伸对话框横跨视口。 | `InputService` | - |文本输入对话框| | `FileUploadService` | - |文件上传对话框 | `ProgressWindowService` | `showDeterminateProgress()` 带百分比|的进度条 | | `showIndeterminateProgress()` |旋转装载机| | `NotificationDisplayService` | `showSuccess()`， `showError()`， `showWarning()`， `showInfo()` |吐司通知| | `EntitySelectDialogService` | - |实体选择模式| | `SaveAsDialogService` | - |保存为对话框与路径导航| | `ImportStrategyDialogService` | - |导入策略选择| | `MessageDetailsDialogService` | - |详细消息/错误显示|

土司堆叠是可配置的 `NOTIFICATION_DISPLAY_OPTIONS`：相同的可见敬酒（相同） 类型、文本和详细信息)永远不会堆叠两次(`dedupe`，默认开启)； `errorHideAfter` / `warningHideAfter` （ms，默认0 =直到交互或导航）自动隐藏非关键错误 还有警告——来电者经过 `hideAfter: 0` 还是很粘，而且 `stickyWithDetails` 保留每个有细节的错误/警告；有时间的祝酒词在悬停或集中时停顿； `maxVisible` （默认0 = unlimited）隐藏最低严重性的最老toast，因此错误或 警告永远不会因为成功或信息而被取消。

```typescript
{ provide: NOTIFICATION_DISPLAY_OPTIONS, useValue: { errorHideAfter: 10000, warningHideAfter: 8000, stickyWithDetails: true, maxVisible: 3 } }
```

看到 [进度窗口使用情况](https://npmcn.com/package/%40meshmakers/shared-ui/src/lib/progress-window/USAGE.md) 进度对话框示例。

## 数据源

用于数据绑定的基类 `ListViewComponent`：

| 类 | 描述 |
| --- | --- |
| `DataSourceBase` | 抽象基具有分页、过滤、排序功能 |
| `DataSourceTyped<T>` | 泛型类型数据源 |
| `HierarchyDataSourceBase` | 树/分层数据的基础 |
| `HierarchyDataSource` | 树形结构的实现 |

## 警卫和指令

### 未保存的更改保护

防止意外数据丢失的两级保护：

| 组件 | 防止 |
| --- | --- |
| `UnsavedChangesDirective` | 浏览器返回/刷新/关闭（beforeunload） |
| `UnsavedChangesGuard` | 应用内导航（Angular Router canDeactivate） |
| `HasUnsavedChanges` | 组件要实现的接口 |

看到 [未保存的更改保护文档](https://npmcn.com/package/%40meshmakers/shared-ui/docs/unsaved-changes-guard.md) 作为实施指南。

### MmListViewDataBindingDirective

的数据绑定指令 `ListViewComponent`，管理数据源和分页。

## 管道

| 管 | 使用 | 例子 |
| --- | --- | --- |
| `PascalCasePipe` | `{{ value | pascalCase }}` | `"my_field"` → `"MyField"` |
| `BytesToSizePipe` | `{{ value | bytesToSize }}` | `1048576` → `"1.0 MB"` |

## 模型

| 模型 | 描述 |
| --- | --- |
| `FetchResult` / `FetchResultTyped<T>` | 分页查询结果包装器 |
| `TableColumn` / `ColumnDefinition` | ListViewComponent的列定义 |
| `StatusIconMapping` / `StatusFieldConfig` | 状态图标配置 |
| `ProgressValue` | 进度状态文本+百分比 |
| `TimeRange` / `TimeRangeISO` / `TimeRangeSelection` | 时间范围类型 |
| `CronBuilderConfig` / `CronSchedule` / `CronFields` | Cron构建器类型 |
| `ImportStrategyDto` | 导入配置 |
| `NodeDroppedEvent` | 树式拖放事件数据 |
| `ConfirmationWindowData` / `ConfirmationWindowResult` | 对话框中配置 |

## 依赖关系

-   **角21** 具有独立的组件和信号
-   **剑道UI Angular 21** （网格，按钮，对话框，下拉框，输入，指示器，布局，通知，树视图）
-   **@meshmakers /共享服务** (兄弟姐妹库)

## 详细的文档

-   [行动](https://npmcn.com/package/%40meshmakers/shared-ui/docs/actions.md) - - - - - - `mm-row-actions`， `mm-action-button`， `MmAction`、规范图标
-   [OctoBot](https://npmcn.com/package/%40meshmakers/shared-ui/docs/octobot.md) - - - - - - `mm-octobot`， `mm-empty-state`、资产、配售规则
-   [时间范围选择器](https://npmcn.com/package/%40meshmakers/shared-ui/docs/time-range-picker.md) -完整的API参考，配置，示例
-   [未保存的更改保护](https://npmcn.com/package/%40meshmakers/shared-ui/docs/unsaved-changes-guard.md) -附有检查清单的实施指南
-   [进度窗口使用情况](https://npmcn.com/package/%40meshmakers/shared-ui/src/lib/progress-window/USAGE.md) 进度对话框示例，从Angular Material迁移

## 文件和测试标准

-   **所有开发人员文档必须用英语编写**
-   **每次代码更改都必须包含更新的文档** -更新自述文件。医学博士,克劳德。在添加、修改或删除功能时使用
-   **必须执行单元测试和集成测试** 每次代码更改之后
-   **必须更新现有的测试** 当被测试代码的行为发生变化时
-   **必须添加新的测试** 当实现新的特性、组件或服务时
-   永远不要提交测试失败的代码

## 常见问题

### @meshmakers/shared-ui 是什么？

用于OctoMesh平台应用的Angular UI组件库。

### 如何安装 @meshmakers/shared-ui？

在项目目录运行 npm install @meshmakers/shared-ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@angular/core（^22\.0\.0）、@angular/forms（^22\.0\.0）、@angular/common（^22\.0\.0）、@progress/kendo-svg-icons（^4\.8\.0）、@progress/kendo-data-query（^1\.7\.3）、@meshmakers/shared-services（\*）、@progress/kendo-angular-grid（^24\.1\.0）、@progress/kendo-angular-icons（^24\.1\.0）、@progress/kendo-angular-label（^24\.1\.0）、@progress/kendo-angular-popup（^24\.1\.0）、@progress/kendo-angular-dialog（^24\.1\.0）、@progress/kendo-angular-inputs（^24\.1\.0）、@progress/kendo-angular-layout（^24\.1\.0）、@progress/kendo-angular-buttons（^24\.1\.0）、@progress/kendo-angular-treeview（^24\.1\.0）、@progress/kendo-angular-dropdowns（^24\.1\.0）、@progress/kendo-angular-indicators（^24\.1\.0）、@progress/kendo-angular-notification（^24\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @meshmakers/shared-ui 支持 TypeScript 吗？

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

### @meshmakers/shared-ui 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @meshmakers/shared-ui 可以商用吗？

@meshmakers/shared-ui 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @meshmakers/shared-ui 还在维护吗？

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