umbraco-notifications

Umbraco 通知

这是什么？

通知通过 UMB_NOTIFICATION_CONTEXT 在 Umbraco 后台向用户提供反馈，并通过 Context API 使用。peek() 方法会显示临时的 Toast 样式通知，并支持不同类型（正面、负面、警告）。通知会在界面中短暂显示后自动消失，因此非常适合用于确认操作和显示错误消息。

文档

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

• Context API：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation/context-api
• 使用 Context：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation/context-api/consume-a-context
• 基础：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation

工作流

1. 获取文档 - 使用 WebFetch 访问上述 URL
2. 提问 - 需要哪种类型？成功、错误还是警告？简单内容还是自定义内容？
3. 生成代码 - 根据最新文档实现通知
4. 说明 - 展示创建的内容以及通知出现的时机

最小示例

基本通知

import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';

export class MyElement extends UmbLitElement {
  #notificationContext?: typeof UMB_NOTIFICATION_CONTEXT.TYPE;

  constructor() {
    super();

    this.consumeContext(UMB_NOTIFICATION_CONTEXT, (context) => {
      this.#notificationContext = context;
    });
  }

  showSuccess() {
    this.#notificationContext?.peek('positive', {
      data: { message: 'Operation completed successfully!' }
    });
  }
}

通知类型

// Success notification
this.#notificationContext?.peek('positive', {
  data: { message: 'Saved successfully!' }
});

// Error notification
this.#notificationContext?.peek('danger', {
  data: { message: 'Something went wrong!' }
});

// Warning notification
this.#notificationContext?.peek('warning', {
  data: { message: 'Please review your changes.' }
});

带标题的通知

this.#notificationContext?.peek('positive', {
  data: {
    headline: 'Success!',
    message: 'Your document has been published.'
  }
});

在控制器中使用

import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';

export class MyController extends UmbControllerBase {
  async performAction() {
    try {
      // Do something
      const context = await this.getContext(UMB_NOTIFICATION_CONTEXT);
      context?.peek('positive', {
        data: { message: 'Action completed!' }
      });
    } catch (error) {
      const context = await this.getContext(UMB_NOTIFICATION_CONTEXT);
      context?.peek('danger', {
        data: {
          headline: 'Error',
          message: error.message
        }
      });
    }
  }
}

带通知的按钮

import { html } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';

export class MyElement extends UmbLitElement {
  #notificationContext?: typeof UMB_NOTIFICATION_CONTEXT.TYPE;

  constructor() {
    super();
    this.consumeContext(UMB_NOTIFICATION_CONTEXT, (context) => {
      this.#notificationContext = context;
    });
  }

  #onClick() {
    this.#notificationContext?.peek('positive', {
      data: { message: 'Button clicked!' }
    });
  }

  render() {
    return html`
      <uui-button @click=${this.#onClick}>
        Click me
      </uui-button>
    `;
  }
}

带通知的异步操作

async saveData() {
  try {
    const response = await fetch('/api/save', {
      method: 'POST',
      body: JSON.stringify(this.data)
    });

    if (response.ok) {
      this.#notificationContext?.peek('positive', {
        data: {
          headline: 'Saved',
          message: 'Your changes have been saved.'
        }
      });
    } else {
      this.#notificationContext?.peek('danger', {
        data: {
          headline: 'Save Failed',
          message: 'Could not save your changes.'
        }
      });
    }
  } catch (error) {
    this.#notificationContext?.peek('danger', {
      data: {
        headline: 'Error',
        message: 'An unexpected error occurred.'
      }
    });
  }
}

在操作处理程序中使用通知

import { UmbMenuItemAction } from '@umbraco-cms/backoffice/menu';
import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';

export class MyAction extends UmbMenuItemAction {
  async execute() {
    const context = await this.getContext(UMB_NOTIFICATION_CONTEXT);

    context?.peek('positive', {
      data: { message: 'Action executed!' }
    });
  }
}

使用通知进行验证

validateAndSave() {
  if (!this.title) {
    this.#notificationContext?.peek('warning', {
      data: {
        headline: 'Validation Error',
        message: 'Title is required.'
      }
    });
    return;
  }

  if (this.title.length < 3) {
    this.#notificationContext?.peek('warning', {
      data: {
        message: 'Title must be at least 3 characters.'
      }
    });
    return;
  }

  this.save();
}

通知类型

positive - 成功消息（绿色）

peek('positive', { data: { message: 'Success!' } })

danger - 错误消息（红色）

peek('danger', { data: { message: 'Error occurred!' } })

warning - 警告消息（橙色/黄色）

peek('warning', { data: { message: 'Please review!' } })

关键概念

UMB_NOTIFICATION_CONTEXT：通知的全局 Context

peek() 方法：显示临时通知

Toast 样式：自动消失的界面通知

数据结构：

• headline（可选）- 粗体标题文本
• message（必填）- 通知正文

Context 使用：使用 consumeContext() 进行订阅，或使用 getContext() 一次性获取

使用场景：

• 保存确认
• 错误消息
• 验证警告
• 操作反馈
• 操作状态

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