让开源，少一点语言距离。
npm包中文文档

@meshmakers/shared-ui

中文文档
3.5.550发布于 2026/11/02TypeScriptES Module

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

中文使用文档
中文原文
文档目录24 节
  1. 安装
  2. 环境设置
  3. 构建和测试
  4. 体系结构
  5. 组件
  6. ListViewComponent ( mm-list-view ）
  7. BaseFormComponent ( mm-base-form ）
  8. CronBuilderComponent ( mm-cron-builder ）
  9. TimeRangePickerComponent ( mm-time-range-picker ）
  10. TreeComponent ( mm-tree ）
  11. CopyableTextComponent ( mm-copyable-text ）
  12. 操作( mm-row-actions ， mm-action-button ）
  13. OctoBot ( mm-octobot ， mm-empty-state ）
  14. EntitySelectInputComponent ( mm-entity-select-input ）
  15. 对话框的服务
  16. 数据源
  17. 警卫和指令
  18. 未保存的更改保护
  19. MmListViewDataBindingDirective
  20. 管道
  21. 模型
  22. 依赖关系
  23. 详细的文档
  24. 文件和测试标准

@meshmakers /共享的ui

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

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

注意： 这个图书馆需要一个 Angular的剑道UI 许可证。

部分 @meshmakers 包的生态系统。

安装

npm install @meshmakers/shared-ui

环境设置

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

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

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

构建和测试

# 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) 让他们在点击时清除这些过滤器)。

<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）

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

<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字符串。

看到 时间范围选择器文档 获取详细的API和示例。

TreeComponent (mm-tree）

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

CopyableTextComponent (mm-copyable-text）

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

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

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

<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.

<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）

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

对话框的服务

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

服务方法描述
ConfirmationServiceshowYesNoConfirmationDialog()是的/不确认
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，因此错误或 警告永远不会因为成功或信息而被取消。

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

看到 进度窗口使用情况 进度对话框示例。

数据源

用于数据绑定的基类 ListViewComponent：

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

警卫和指令

未保存的更改保护

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

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

看到 未保存的更改保护文档 作为实施指南。

MmListViewDataBindingDirective

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

管道

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

模型

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

依赖关系

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

详细的文档

文件和测试标准

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

版本与发布记录

@meshmakers/shared-ui 共发布 719 个版本，首次发布于 2022/11/14；过去 12 个月发布了 288 个版本。

版本发布日期距今
3.5.550latest2026/11/021 天前
3.5.5302026/11/012 天前
3.5.5202026/10/313 天前
3.5.5102026/10/303 天前
3.5.5002026/10/304 天前
3.5.4902026/10/304 天前

关于 @meshmakers/shared-ui 的常见问题

@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 和提交记录判断。