umbraco-preview-app-provider

Umbraco 预览应用提供程序

这是什么？

预览应用提供程序会在 Umbraco 的预览窗口菜单中添加自定义项。内容编辑者预览内容时，这些应用会显示在预览菜单中，提供设备模拟、无障碍检查、SEO 分析或其他与预览相关的工具等额外功能。

文档

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

• Foundation：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 Element：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation/umbraco-element

相关 Foundation 技能

• Umbraco Element：用于创建 UI 组件的基类

  • 参考技能：umbraco-umbraco-element

• Context API：访问预览状态时使用

  • 参考技能：umbraco-context-api

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提问 - 需要什么预览功能？需要什么 UI？
3. 生成文件 - 根据最新文档创建清单和元素
4. 说明 - 展示创建的内容以及测试方法

最小示例

清单（manifests.ts）

import type { ManifestPreviewAppProvider } from '@umbraco-cms/backoffice/extension-registry';

export const manifests: Array<ManifestPreviewAppProvider> = [
  {
    type: 'previewApp',
    alias: 'My.PreviewApp',
    name: 'My Preview App',
    element: () => import('./my-preview-app.element.js'),
  },
];

元素实现（my-preview-app.element.ts）

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

@customElement('my-preview-app')
export class MyPreviewAppElement extends UmbLitElement {
  @state()
  private _isActive = false;

  override render() {
    return html`
      <uui-box headline="My Preview Tool">
        <p>Custom preview functionality</p>

        <uui-button
          look=${this._isActive ? 'primary' : 'default'}
          @click=${this.#toggle}
        >
          ${this._isActive ? 'Disable' : 'Enable'}
        </uui-button>
      </uui-box>
    `;
  }

  #toggle() {
    this._isActive = !this._isActive;
    // Apply your preview functionality
    this.#applyPreviewMode(this._isActive);
  }

  #applyPreviewMode(active: boolean) {
    // Access the preview iframe or apply styles
    const previewFrame = document.querySelector('iframe.preview-frame');
    if (previewFrame && active) {
      // Apply custom preview mode
    }
  }
}

export default MyPreviewAppElement;

设备模拟器示例

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

@customElement('device-preview-app')
export class DevicePreviewAppElement extends UmbLitElement {
  @state()
  private _selectedDevice = 'desktop';

  private _devices = [
    { name: 'desktop', width: '100%', label: 'Desktop' },
    { name: 'tablet', width: '768px', label: 'Tablet' },
    { name: 'mobile', width: '375px', label: 'Mobile' },
  ];

  override render() {
    return html`
      <uui-box headline="Device Preview">
        ${this._devices.map(
          (device) => html`
            <uui-button
              look=${this._selectedDevice === device.name ? 'primary' : 'default'}
              @click=${() => this.#selectDevice(device)}
            >
              ${device.label}
            </uui-button>
          `
        )}
      </uui-box>
    `;
  }

  #selectDevice(device: { name: string; width: string }) {
    this._selectedDevice = device.name;
    // Dispatch event to resize preview
    this.dispatchEvent(
      new CustomEvent('preview-resize', {
        detail: { width: device.width },
        bubbles: true,
        composed: true,
      })
    );
  }
}

export default DevicePreviewAppElement;

接口参考

interface ManifestPreviewAppProvider extends ManifestElement {
  type: 'previewApp';
}

最佳实践

• 保持 UI 简洁，因为它会显示在菜单中
• 提供清晰的启用／禁用状态
• 考虑预览上下文和可用的 iframe
• 使用恰当的图标，便于快速识别

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