umbraco-block-editor-custom-view

Umbraco Block Editor 自定义视图

这是什么？

Block Editor 自定义视图为 Block List、Block Grid 或 Block RTE 编辑器中的块提供自定义的视觉呈现。你可以创建自定义 Web Component，以专门的方式显示块内容，而不是使用默认的块渲染方式。这适用于主题化预览、特定领域的可视化效果或增强的编辑体验。

文档

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

• 主要文档：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/block-custom-view
• Block Editor：https://docs.umbraco.com/umbraco-cms/model-your-content/property-editors/built-in-umbraco-property-editors/block-editor
• Foundation：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation

相关 Foundation 技能

• Umbraco Element：用于实现自定义视图元素
  • 参考技能：umbraco-umbraco-element

参考示例

Umbraco 源码中包含一个可运行示例：

位置：/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/block-custom-view/

此示例展示了自定义块视图的实现。请参考它了解生产环境中的实践模式。

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提出问题 - 涉及哪些块类型？使用哪些编辑器（列表、网格、RTE）？
3. 生成文件 - 根据最新文档创建清单和视图元素
4. 说明 - 展示创建的内容以及如何测试

最简示例

清单（umbraco-package.json）

{
  "name": "My Block Views",
  "extensions": [
    {
      "type": "blockEditorCustomView",
      "alias": "My.BlockView.Hero",
      "name": "Hero Block View",
      "element": "/App_Plugins/MyBlocks/hero-view.js",
      "forContentTypeAlias": "heroBlock",
      "forBlockEditor": "block-list"
    }
  ]
}

清单（TypeScript）

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

const manifest: ManifestBlockEditorCustomView = {
  type: 'blockEditorCustomView',
  alias: 'My.BlockView.Hero',
  name: 'Hero Block View',
  element: () => import('./hero-block-view.element.js'),
  forContentTypeAlias: 'heroBlock',
  forBlockEditor: ['block-list', 'block-grid'],
};

export const manifests = [manifest];

自定义视图元素（hero-block-view.element.ts）

import { html, css, customElement, property } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import type { UmbBlockEditorCustomViewElement, UmbBlockDataType } from '@umbraco-cms/backoffice/block';

@customElement('my-hero-block-view')
export class MyHeroBlockViewElement extends UmbLitElement implements UmbBlockEditorCustomViewElement {
  @property({ attribute: false })
  content?: UmbBlockDataType;

  @property({ attribute: false })
  settings?: UmbBlockDataType;

  render() {
    return html`
      <div class="hero-preview">
        <h2>${this.content?.headline ?? 'No headline'}</h2>
        <p>${this.content?.subheadline ?? ''}</p>
        ${this.content?.backgroundImage
          ? html`<div class="bg-indicator">Has background image</div>`
          : ''}
      </div>
    `;
  }

  static styles = css`
    :host {
      display: block;
    }

    .hero-preview {
      padding: var(--uui-size-space-4);
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      color: white;
      border-radius: var(--uui-border-radius);
      min-height: 100px;
    }

    h2 {
      margin: 0 0 var(--uui-size-space-2);
      font-size: 1.2em;
    }

    p {
      margin: 0;
      opacity: 0.8;
    }

    .bg-indicator {
      margin-top: var(--uui-size-space-2);
      font-size: 0.8em;
      opacity: 0.6;
    }
  `;
}

export default MyHeroBlockViewElement;

declare global {
  interface HTMLElementTagNameMap {
    'my-hero-block-view': MyHeroBlockViewElement;
  }
}

多种内容类型的视图

const manifest: ManifestBlockEditorCustomView = {
  type: 'blockEditorCustomView',
  alias: 'My.BlockView.Cards',
  name: 'Card Blocks View',
  element: () => import('./card-block-view.element.js'),
  forContentTypeAlias: ['cardBlock', 'featureCard', 'testimonialCard'],
  forBlockEditor: 'block-grid',
};

编辑器中所有块的视图

// Omit forContentTypeAlias to apply to all blocks
const manifest: ManifestBlockEditorCustomView = {
  type: 'blockEditorCustomView',
  alias: 'My.BlockView.Universal',
  name: 'Universal Block View',
  element: () => import('./universal-view.element.js'),
  forBlockEditor: 'block-list', // Only specify editor type
};

访问设置数据

@customElement('my-styled-block-view')
export class MyStyledBlockViewElement extends UmbLitElement implements UmbBlockEditorCustomViewElement {
  @property({ attribute: false })
  content?: UmbBlockDataType;

  @property({ attribute: false })
  settings?: UmbBlockDataType;

  render() {
    // Settings contain block configuration (colors, layout options, etc.)
    const bgColor = this.settings?.backgroundColor ?? '#ffffff';
    const padding = this.settings?.padding ?? 'medium';

    return html`
      <div style="background-color: ${bgColor}" class="padding-${padding}">
        <h3>${this.content?.title}</h3>
        <div>${this.content?.text}</div>
      </div>
    `;
  }
}

清单属性

属性	说明
forContentTypeAlias	此视图适用的内容类型别名
forBlockEditor	编辑器类型：block-list、block-grid、block-rte

元素属性

属性	类型	说明
content	UmbBlockDataType	块的内容数据
settings	UmbBlockDataType	块的设置数据

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