umbraco-modals

Umbraco 模态框

这是什么？

模态框是一个弹出层，会使周围环境变暗，并启用焦点锁定。模态框扩展类型用于在 Umbraco 后台配置和显示对话框与侧边栏。模态框可以通过路由打开（用于深度链接），也可以在运行时使用 Modal Manager Context 打开，并采用基于令牌的系统实现类型安全的通信。

文档

实现前，请务必获取最新文档：

• 主要文档：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/modals
• 自定义模态框：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/modals/custom-modals
• 路由注册：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/modals/route-registration
• 基础：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation
• 扩展注册表：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry

参考示例

Umbraco 源代码中包含可运行的示例：

自定义模态框位置：/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/custom-modal/

此示例展示了一个包含令牌、元素和清单的基础自定义模态框。

路由模态框位置：/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/modal-routed/

此示例展示了可通过 URL 路由打开、支持深度链接的模态框。

相关基础技能

如果在实现模态框时需要说明以下基础概念，请参考这些技能：

• Context API：实现模态管理器上下文、consumeContext 模式，或说明如何打开模态框时

  • 参考技能：umbraco-context-api

• Umbraco Element：实现模态框元素、说明 UmbLitElement，或创建模态框组件时

  • 参考技能：umbraco-umbraco-element

• 状态管理：实现模态框数据流、模态框值，或管理模态框与调用方之间的状态时

  • 参考技能：umbraco-state-management

工作流

1. 获取文档 - 对以上 URL 使用 WebFetch
2. 提问 - 模态框要做什么？是对话框还是侧边栏？输入/输出哪些数据？是否需要深度链接？
3. 生成文件 - 根据最新文档创建模态框令牌、元素和清单
4. 说明 - 展示创建的内容以及如何打开模态框

最简示例

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

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

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

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

打开模态框

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!');
  }
}

模态框类型

• 对话框：在屏幕中央显示
• 侧边栏：从右侧滑入

就是这样！务必获取最新文档，保持示例简洁，并生成完整可运行的代码。