# @meshmakers/octo-ui 中文文档

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

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

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

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

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

- 包体积（解压后）：4.8 MB，29 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@angular/core ^22\.0\.0，@angular/forms ^22\.0\.0，apollo-angular ^14\.0\.0，@angular/common ^22\.0\.0，@angular/animations ^22\.0\.0，@ngx-translate/core ^17\.0\.0 \|\| ^18\.0\.0，@meshmakers/shared-ui \*，@meshmakers/shared-auth \*，@meshmakers/octo-services \*，@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-popup ^24\.1\.0，@progress/kendo-angular-dialog ^24\.1\.0，@progress/kendo-angular-inputs ^24\.1\.0，@progress/kendo-angular-buttons ^24\.1\.0，@progress/kendo-angular-dropdowns ^24\.1\.0，@progress/kendo-angular-indicators ^24\.1\.0
- 首次发布：2022-11-13T22:10:31.585Z
- 最新版本发布：2026-11-01T19:23:52.603Z
- 已发布版本数：716（近 12 个月 288 个）

## 中文简介

为OctoMesh应用程序提供可重用UI组件的Angular库。

## 安装

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

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

## README

# @meshmakers / octo-ui

为OctoMesh应用程序提供可重用UI组件的Angular库。

## 功能

-   **数据源** -列表视图和层次结构的基于graphql的数据源抽象
-   **属性网格** -具有类型感知值显示的动态属性编辑器
-   **浏览器运行时** -树形/详细视图，为运行时实体创建和更新编辑器
-   **选择器对话框** -属性和CK类型选择对话框
-   **筛选编辑器** —可视化查询过滤器配置
-   **独立的主题** -适用于任何剑道UI主题

## 文档

-   [开发人员文档](https://npmcn.com/package/%40meshmakers/octo-ui/CLAUDE.md) -完整的API参考和使用示例

## 快速入门

### 1\. 导入组件

```typescript
import {
  PropertyGridComponent,
  CkTypeSelectorInputComponent,
  AttributeSelectorDialogService
} from '@meshmakers/octo-ui';

@Component({
  imports: [PropertyGridComponent, CkTypeSelectorInputComponent],
  // ...
})
export class MyComponent {}
```

### 2\. 使用属性网格

```typescript
import { PropertyGridComponent, PropertyGridItem, AttributeValueTypeDto } from '@meshmakers/octo-ui';

@Component({
  template: `
    <mm-property-grid
      [properties]="properties"
      [readOnlyMode]="false"
      (propertyChange)="onPropertyChange($event)">
    </mm-property-grid>
  `
})
export class EntityDetailComponent {
  properties: PropertyGridItem[] = [
    {
      id: 'name',
      name: 'name',
      displayName: 'Customer Name',
      value: 'Acme Corp',
      type: AttributeValueTypeDto.StringDto,
      readOnly: false,
      category: 'General'
    }
  ];

  onPropertyChange(event: PropertyChangeEvent) {
    console.log('Property changed:', event.propertyId, event.newValue);
  }
}
```

### 3\. 使用CK类型选择器

```typescript
import { CkTypeSelectorInputComponent, CkTypeSelectorItem } from '@meshmakers/octo-ui';

@Component({
  template: `
    <mm-ck-type-selector-input
      [(ngModel)]="selectedType"
      [ckModelIds]="['OctoSdkDemo']"
      (ckTypeSelected)="onTypeSelected($event)">
    </mm-ck-type-selector-input>
  `
})
export class TypeSelectorComponent {
  selectedType: CkTypeSelectorItem | null = null;

  onTypeSelected(type: CkTypeSelectorItem) {
    // Use type.rtCkTypeId for runtime queries
    console.log('Selected:', type.rtCkTypeId);
  }
}
```

### 4\. 与列表视图一起使用数据源

```typescript
import { OctoGraphQlDataSource, FetchDataOptions, FetchResultTyped } from '@meshmakers/octo-ui';
import { DataSourceBase, ListViewComponent } from '@meshmakers/shared-ui';

@Directive({
  selector: '[appCustomerDataSource]',
  exportAs: 'appCustomerDataSource',
  providers: [{ provide: DataSourceBase, useExisting: forwardRef(() => CustomerDataSourceDirective) }]
})
export class CustomerDataSourceDirective extends OctoGraphQlDataSource<CustomerDto> {
  private readonly getCustomersGQL = inject(GetCustomersDtoGQL);

  constructor() {
    super(inject(ListViewComponent));
    this.searchFilterAttributePaths = ['name', 'email'];
  }

  fetchData(options: FetchDataOptions): Observable<FetchResultTyped<CustomerDto>> {
    return this.getCustomersGQL.fetch({
      variables: {
        first: options.state.take,
        after: GraphQL.offsetToCursor(options.state.skip ?? 0),
        sortOrder: this.getSortDefinitions(options.state),
        fieldFilter: this.getFieldFilterDefinitions(options.state),
        searchFilter: this.getSearchFilterDefinitions(options.textSearch)
      },
      fetchPolicy: 'network-only'
    }).pipe(map(result => new FetchResultTyped<CustomerDto>(
      result.data?.runtime?.customers?.items ?? [],
      result.data?.runtime?.customers?.totalCount ?? 0
    )));
  }
}
```

## 可用的组件

| 组件 | 描述 |
| --- | --- |
| `PropertyGridComponent` | 具有类型感知编辑功能的动态属性网格 |
| `PropertyValueDisplayComponent` | 具有类型格式的只读值显示 |
| `CkTypeSelectorInputComponent` | 自动完成输入的CK类型选择 |
| `FieldFilterEditorComponent` | 用于查询的可视化过滤器编辑器 |
| `EntityIdInfoComponent` | 实体ID显示与复制到剪贴板下拉 |
| `OctoLoaderComponent` | 动画OctoMesh标志加载指示器 |
| `PageComponent` （`MM_PAGE`） | `<mm-page>` 页面布局：可选的页眉（标题，副标题，动作）+滚动内容，没有页脚 |

## 可用的服务

| 服务 | 描述 |
| --- | --- |
| `PropertyConverterService` | 将实体转换为属性网格项 |
| `AttributeSelectorDialogService` | 打开属性选择对话框 |
| `AttributeSortSelectorDialogService` | 使用排序顺序打开属性选择 |
| `CkTypeSelectorDialogService` | 打开CK类型选择对话框 |

## 数据源类

| 类 | 描述 |
| --- | --- |
| `OctoGraphQlDataSource` | GraphQL列表数据源的基类 |
| `OctoGraphQlHierarchyDataSource` | 树/层次数据源的基类 |
| `FetchResultTyped` | 带有项目和totalCount的键入结果包装器 |

## 品牌

每个租户的品牌（标识、标题、调色板）具有亮/暗模式和可配置的 设置页面。看到 [`src/lib/branding/BRANDING_USAGE.md`](https://npmcn.com/package/%40meshmakers/octo-ui/src/lib/branding/BRANDING_USAGE.md).

```typescript
// app.config.ts
import { provideOctoBranding } from '@meshmakers/octo-ui';

providers: [
  provideOctoBranding({
    defaults: { appName: 'MyApp', appTitle: 'MyApp' },
    fallbackAssets: { headerLogo: '/logo.svg', favicon: '/favicon.ico' },
  }),
];
```

线 `/settings` 路线:

```typescript
// app.routes.ts
import { BRANDING_ROUTES } from '@meshmakers/octo-ui';

{ path: 'settings', canActivate: [adminGuard], children: BRANDING_ROUTES }
```

将独立组件放到它们所属的shell中，然后 绑定你的页眉/页脚chrome到CSS变量库写入：

```html
<header class="my-header">
  <mm-theme-switcher />
  <!-- Render the logo inline; inject BrandingDataSource and bind .branding().headerLogoUrl -->
  <img [src]="logoUrl()" alt="" class="my-header-logo" />
</header>
```

```scss
.my-header {
  background: linear-gradient(
    to right,
    var(--app-header-gradient-start),
    var(--app-header-gradient-end)
  );
  color: var(--app-header-text);
}
```

看到 [`src/lib/branding/BRANDING_USAGE.md`](https://npmcn.com/package/%40meshmakers/octo-ui/src/lib/branding/BRANDING_USAGE.md) 获取库更新的CSS变量的完整列表和host-app 地面梯架合同。

## 页面布局(`mm-page`）

`<mm-page>` （`PageComponent`)是基于令牌的页面框架，它取代 LCARS header / content panel / footer三元组：一个可选的header (title， 副标题, `[mmPageActions]`)和滚动内容区，没有页脚。进口 `MM_PAGE` （组件+插槽指令）；标题默认为标题级别2 标题是一个plain `<div>`． 看到 [`src/lib/page/README.md`](https://npmcn.com/package/%40meshmakers/octo-ui/src/lib/page/README.md).

```html
<mm-page pageTitle="Adapters" pageSubtitle="12 registered">
  <div mmPageActions><button kendoButton themeColor="primary">New adapter</button></div>
  <mm-list-view …></mm-list-view>
</mm-page>
```

## 主题标记（可重写的CSS变量）

`@include octo.theme()` 发出“Deep Sea”令牌 `:root` (黑 默认为light via `prefers-color-scheme` 或者 `data-theme="light"`);来源: `src/lib/runtime-browser/styles/_theme.scss`． 主机可以覆盖其中的任何一个 包含后的自定义属性。所有 `--theme-*` 前者的名字 主题保持不变；令牌标志 _新_ 添加到ab# 5519中。

| 集团 | 令牌 |
| --- | --- |
| 表面 | `--theme-bg-app`， `--theme-bg-app-end`， `--theme-bg-surface`， `--theme-bg-elevated`， `--theme-bg-overlay`， `--theme-bg-input`， _新:_ `--theme-bg-sunken`， `--theme-bg-selected`， `--theme-bg-hover` |
| 文本 | `--theme-text-primary`， `--theme-text-secondary`， `--theme-text-muted`， `--theme-text-on-accent`， `--theme-text-accent`， _新:_ `--theme-text-code` |
| 边界 | `--theme-border-subtle`， `--theme-border-strong`， `--theme-border-divider` (=微妙的), _新:_ `--theme-border-default`， `--theme-focus-ring` (一个 `box-shadow` 值) |
| 口音/ AI (_新_） | `--theme-accent`， `--theme-accent-hover`， `--theme-accent-subtle`， `--theme-accent-2`， `--theme-ai`， `--theme-ai-subtle` |
| 状态 | `--theme-status-success`， `-warning`， `-error`， `-info`， _新:_ `--theme-status-neutral`， `--theme-status-{success,warning,error,info,neutral}-subtle` |
| 影响 | `--theme-shadow-panel`， `--theme-shadow-popup`； `--theme-glow-primary`， `--theme-glow-accent` (包括 `none`); `--theme-gradient-page`， `--theme-gradient-header`， `--theme-accent-bar`， `--theme-accent-line`， `--theme-panel-rule` （现为平面色） |
| 图表 | `--theme-chart-1` … `--theme-chart-8` |
| 油墨覆盖 | `--theme-ink-02` … `--theme-ink-70` （文字颜色为n % -随主题变化） |
| 排版(_新_theme-invariant) | `--theme-font-display` (蒙特塞拉特岛), `--theme-font-ui` (Roboto), `--theme-font-mono` (Roboto Mono) |
| 间距(_新_） | `--theme-space-1` … `--theme-space-8` （4像素网格：4,8,12,16,20,24,28,32像素） |
| 半径(_新_） | `--theme-radius-xs` 2像素（芯片）， `-sm` 4px（按钮，输入）， `-md` 6px（卡片，面板）， `-lg` 8px（对话框，弹出窗口） |
| 运动(_新_） | `--theme-motion-fast` 120毫秒, `--theme-motion-base` 200毫秒, `--theme-motion-easing`;两个持续时间都变成 `0ms` 下 `prefers-reduced-motion: reduce` |

遗留别名（AB#5526阶段2）：仅限 `--lcars-font-primary` → `--theme-font-display`， `--lcars-font-mono` → `--theme-font-mono` 和 `--lcars-transition-fast` → `--theme-motion-fast` +宽松的保留，保留为该 Meshmakers App，直到它迁移。所有其他的 `--lcars-*` 变量(发光, 按键基础，输入焦点，半径，面板标记， `--lcars-transition-normal`） 被删除-使用 `--theme-*` 令牌。

正文: `octo.styles()` 集合 `body { font-family: var(--theme-font-ui) }` （Roboto）自AB#5526； `h1`–`h3`、页面和对话标题； `mm-page` 标题和 KPI数字使用 `--theme-font-display` (600年蒙特塞拉特岛)。

### 组件样式 `octo.styles()` （深海，AB#5526）

-   **按钮是平的**： primary = `--theme-accent` 与 `--theme-text-on-accent` (悬停 `--theme-accent-hover`), base = `--theme-bg-elevated` 与一个 `--theme-border-default` 发际线(悬停 `--theme-bg-hover` + `--theme-border-strong`)，轮廓/平面变体透明；错误= `--theme-status-error`． 句子的情况下, `--theme-font-ui`， `--theme-radius-sm`， 键盘焦点 `--theme-focus-ring`． 两个主题使用相同的规则，所以 以前的仅亮按钮覆盖是无操作的。
-   **没有装饰**：没有渐变（包括滑块），发光，脉冲，扫描线 或text-shadows;网格标题，选项卡（Kendo和dockview），进程设计器 调色板/检查器标题、对话框标题和上下文菜单都是句子大小写 在 `--theme-font-ui` （唯一的左大写字母是头像的首字母）；弹出窗口, 对话框和菜单的使用 `--theme-bg-overlay` + `--theme-border-default` + `--theme-shadow-popup`;抽屉是平的 `--theme-bg-elevated`.
-   **`theme-overrides()`**： `light-theme-surface-overrides` 被降到什么程度 代币不能表达(旧的轻卡， `#d7ebe5` 桌带、抽屉 应用程序栏的治疗方法也消失了——这两个主题现在一致)。它也会发出 句格规则(`html:root .k-label, kendo-label, .section-title`), 在两个主题中都超过宿主组件样式。
-   **遗留的LCARS页面类-仅为Meshmakers App保留** (AB # 5526 第二阶段;精炼厂工作室不再使用它们)： `.lcars-page-header`， `.page-title` / `.title-prefix` / `.title-main`， `.header-content` 和 `.lcars-content-panel` 面卡，带其 `.k-grid` 规则)保持中立 深海定义； `.lcars-header-accent`， `.lcars-header-line`， `.panel-accent-top/-bottom`， `.lcars-footer` 和 `.footer-*` 使什么 （`display: none`）. 其他的都被删除了： `.header-stats`， `.stat-badge`， `.lcars-panel`， `.lcars-panel-asymmetric`， `.lcars-header-bar`， `.lcars-divider`， `.lcars-text-*`， `.lcars-bg-*`， `.lcars-border-mint`, 辉光/扫描线/脉冲实用程序，以及 `_lcars-button.scss`， `_lcars-flat-btn.scss` 和 `_lcars-input.scss` Mixin文件(现在是内部的 `_button.scss` / `octo-button`， `_flat-button.scss` / `flat-button` 和 `_field-input.scss` / `field-input`）. 新页面使用 `<mm-page>`.

偏离概念§6.2（对比驱动）：光 `--theme-text-accent` / `--theme-accent` `#2c7d6d` (概念 `#2e8473`， 4.16:1轻帆布→ 4.55: 1),光 `--theme-accent-hover` `#24685a` (概念 `#266f61`)， `--theme-text-muted` 黑暗 `#77869c` (概念 `#687890`)和灯光 `#657189` (概念 `#75829a`)，均≥4.5:1 on `--theme-bg-input`． 剑道桥指向 `--kendo-color-primary`， `--kendo-color-surface(-alt)`， `--kendo-color-border`， `--kendo-color-base*`， `--kendo-border-radius-*` 和 `--kendo-font-family` 看这些记号。

字体没有捆绑：主机加载Montserrat， Roboto和Roboto Mono (炼油厂工作室通过谷歌字体在 `index.html`）。

## 次级入境点

繁重的管理编辑器驻留在它们自己的入口点，所以不使用它们的应用程序可以保留它们 主束小。的公共API `@meshmakers/octo-ui`.

| 入口点 | 目录 |
| --- | --- |
| `@meshmakers/octo-ui/branding` | 品牌服务, `provideOctoBranding`，主题切换器 |
| `@meshmakers/octo-ui/branding-settings` | 品牌设置页面(`BRANDING_ROUTES`） |
| `@meshmakers/octo-ui/tree-navigation-settings` | 编辑 `System.UI/TreeNavigationConfiguration` |
| `@meshmakers/octo-ui/entity-forms` | 表单驱动的实体列表/创建/编辑页面(`<mm-entity-page>`， `<mm-entity-list>`， `<mm-entity-form>`， `entityFormRoutes()`)，由 `System.UI/EntityForm` ——看 [`entity-forms/README.md`](https://npmcn.com/package/%40meshmakers/octo-ui/entity-forms/README.md) |

## 构建

```bash
# From frontend-libraries directory
npm run build:octo-ui
```

## 测试

```bash
npm run test:octo-ui
```

## 线头

```bash
npm run lint:octo-ui
```

## 常见问题

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

为OctoMesh应用程序提供可重用UI组件的Angular库。

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

在项目目录运行 npm install @meshmakers/octo-ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@angular/core（^22\.0\.0）、@angular/forms（^22\.0\.0）、apollo-angular（^14\.0\.0）、@angular/common（^22\.0\.0）、@angular/animations（^22\.0\.0）、@meshmakers/shared-ui（\*）、@meshmakers/shared-auth（\*）、@meshmakers/octo-services（\*）、@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-popup（^24\.1\.0）、@progress/kendo-angular-dialog（^24\.1\.0）、@progress/kendo-angular-inputs（^24\.1\.0）、@progress/kendo-angular-buttons（^24\.1\.0）、@progress/kendo-angular-dropdowns（^24\.1\.0）、@progress/kendo-angular-indicators（^24\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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