Back to Details

umbraco-modals

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Umbraco Modals

Umbraco 模态框

What is it?

什么是模态框？

A modal is a popup layer that darkens the surroundings and comes with a focus lock. The modal extension type is used to configure and present dialogs and sidebars within the Umbraco backoffice. Modals can be opened via routes (for deep-linking) or at runtime using the Modal Manager Context, and they use a token-based system for type-safe communication.
模态框是一种弹出层，会使周围区域变暗并带有焦点锁定。模态框扩展类型用于在Umbraco后台中配置和展示对话框与侧边栏。模态框可通过路由（用于深度链接）或在运行时使用Modal Manager Context打开，它们采用基于令牌的系统实现类型安全的通信。

Documentation

文档

Always fetch the latest docs before implementing:
在实现前请务必获取最新文档：

Reference Examples

参考示例

The Umbraco source includes working examples:
Custom Modal Location: 
/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/custom-modal/
This example demonstrates a basic custom modal with token, element, and manifest.
Routed Modal Location: 
/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/modal-routed/
This example demonstrates modals that can be opened via URL routing for deep-linking support.
Umbraco源码中包含可用示例：
自定义模态框位置：
/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/custom-modal/
该示例展示了一个带有令牌、元素和清单的基础自定义模态框。
路由式模态框位置：
/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/modal-routed/
该示例展示了可通过URL路由打开以支持深度链接的模态框。

Related Foundation Skills

相关基础技能

If you need to explain these foundational concepts when implementing modals, reference these skills:
  • Context API: When implementing modal manager context, consumeContext patterns, or explaining how to open modals
    • Reference skill: 
      umbraco-context-api
  • Umbraco Element: When implementing modal elements, explaining UmbLitElement, or creating modal components
    • Reference skill: 
      umbraco-umbraco-element
  • State Management: When implementing modal data flow, modal values, or state management between modal and caller
    • Reference skill: 
      umbraco-state-management
如果在实现模态框时需要解释这些基础概念，请参考以下技能：
  • Context API：在实现模态管理器上下文、使用consumeContext模式或解释如何打开模态框时
    • 参考技能：
      umbraco-context-api
  • Umbraco Element：在实现模态框元素、解释UmbLitElement或创建模态框组件时
    • 参考技能：
      umbraco-umbraco-element
  • 状态管理：在实现模态框数据流、模态框值或模态框与调用方之间的状态管理时
    • 参考技能：
      umbraco-state-management

Workflow

工作流程

  1. Fetch docs - Use WebFetch on the URLs above
  2. Ask questions - What will the modal do? Dialog or sidebar? What data in/out? Deep-link needed?
  3. Generate files - Create modal token + element + manifest based on latest docs
  4. Explain - Show what was created and how to open the modal
  1. 获取文档 - 使用WebFetch访问上述URL
  2. 提出问题 - 该模态框的功能是什么？是对话框还是侧边栏？需要传入/输出什么数据？是否需要深度链接？
  3. 生成文件 - 根据最新文档创建模态框令牌 + 元素 + 清单
  4. 解释说明 - 展示创建的内容以及如何打开模态框

Minimal Examples

最简示例

Modal Token (modal-token.ts)

模态框令牌（modal-token.ts）

typescript
import { UmbModalToken } from '@umbraco-cms/backoffice/modal';

export interface MyModalData {
  title: string;
}

export interface MyModalValue {
  confirmed: boolean;
}

export const MY_MODAL_TOKEN = new UmbModalToken<MyModalData, MyModalValue>(
  'My.Modal',
  {
    modal: {
      type: 'sidebar',
      size: 'small',
    },
  }
);
typescript
import { UmbModalToken } from '@umbraco-cms/backoffice/modal';

export interface MyModalData {
  title: string;
}

export interface MyModalValue {
  confirmed: boolean;
}

export const MY_MODAL_TOKEN = new UmbModalToken<MyModalData, MyModalValue>(
  'My.Modal',
  {
    modal: {
      type: 'sidebar',
      size: 'small',
    },
  }
);

Modal Element (modal.element.ts)

模态框元素（modal.element.ts）

typescript
import { html, customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { UmbModalExtensionElement } from '@umbraco-cms/backoffice/modal';

@customElement('my-modal')
export class MyModalElement extends UmbLitElement
  implements UmbModalExtensionElement<MyModalData, MyModalValue> {

  modalContext: any;

  #handleSubmit() {
    this.modalContext.updateValue({ confirmed: true });
    this.modalContext.submit();
  }

  render() {
    return html`
      <umb-body-layout headline="${this.modalContext?.data?.title}">
        <uui-box>
          <p>Modal content here</p>
          <uui-button @click="${this.#handleSubmit}">
            Confirm
          </uui-button>
        </uui-box>
      </umb-body-layout>
    `;
  }
}

export default MyModalElement;
typescript
import { html, customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { UmbModalExtensionElement } from '@umbraco-cms/backoffice/modal';

@customElement('my-modal')
export class MyModalElement extends UmbLitElement
  implements UmbModalExtensionElement<MyModalData, MyModalValue> {

  modalContext: any;

  #handleSubmit() {
    this.modalContext.updateValue({ confirmed: true });
    this.modalContext.submit();
  }

  render() {
    return html`
      <umb-body-layout headline="${this.modalContext?.data?.title}">
        <uui-box>
          <p>Modal content here</p>
          <uui-button @click="${this.#handleSubmit}">
            Confirm
          </uui-button>
        </uui-box>
      </umb-body-layout>
    `;
  }
}

export default MyModalElement;

Manifest (manifest.ts)

清单（manifest.ts）

typescript
export const manifests = [
  {
    type: 'modal',
    alias: 'My.Modal',
    name: 'My Modal',
    element: () => import('./modal.element.js'),
  },
];
typescript
export const manifests = [
  {
    type: 'modal',
    alias: 'My.Modal',
    name: 'My Modal',
    element: () => import('./modal.element.js'),
  },
];

Opening the Modal

打开模态框

typescript
import { UMB_MODAL_MANAGER_CONTEXT } from '@umbraco-cms/backoffice/modal';
import { MY_MODAL_TOKEN } from './modal-token.js';

// In your element:
constructor() {
  super();
  this.consumeContext(UMB_MODAL_MANAGER_CONTEXT, (context) => {
    this._modalManager = context;
  });
}

async openModal() {
  const result = await this._modalManager?.open(this, MY_MODAL_TOKEN, {
    data: { title: 'My Modal' }
  });

  if (result?.confirmed) {
    console.log('User confirmed!');
  }
}
typescript
import { UMB_MODAL_MANAGER_CONTEXT } from '@umbraco-cms/backoffice/modal';
import { MY_MODAL_TOKEN } from './modal-token.js';

// In your element:
constructor() {
  super();
  this.consumeContext(UMB_MODAL_MANAGER_CONTEXT, (context) => {
    this._modalManager = context;
  });
}

async openModal() {
  const result = await this._modalManager?.open(this, MY_MODAL_TOKEN, {
    data: { title: 'My Modal' }
  });

  if (result?.confirmed) {
    console.log('User confirmed!');
  }
}

Modal Types

模态框类型

  • Dialog: Centered on screen
  • Sidebar: Slides in from the right
That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.
  • Dialog（对话框）：居中显示在屏幕上
  • Sidebar（侧边栏）：从右侧滑入
就是这样！请务必获取最新文档，保持示例最简，生成完整可运行的代码。