Back to Details

umbraco-file-upload-preview

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Umbraco File Upload Preview

Umbraco 文件上传预览

What is it?

什么是文件上传预览？

File Upload Previews are custom web components that render previews for specific file types during upload in Umbraco. They allow you to create visual representations for files based on their MIME types, such as displaying thumbnails for images, waveforms for audio, or custom icons for specific file formats.
文件上传预览是自定义Web组件，可在Umbraco上传过程中为特定文件类型渲染预览。你可以根据文件的MIME类型创建可视化展示，例如显示图片缩略图、音频波形图，或为特定文件格式显示自定义图标。

Documentation

文档

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

Related Foundation Skills

相关基础技能

  • Umbraco Element: Base class for creating UI components
    • Reference skill: 
      umbraco-umbraco-element
  • Umbraco Element：用于创建UI组件的基类
    • 参考技能：
      umbraco-umbraco-element

Workflow

工作流程

  1. Fetch docs - Use WebFetch on the URLs above
  2. Ask questions - What MIME types? What preview display?
  3. Generate files - Create manifest + element based on latest docs
  4. Explain - Show what was created and how to test
  1. 获取文档 - 使用WebFetch访问上述URL
  2. 确认需求 - 支持哪些MIME类型？预览如何展示？
  3. 生成文件 - 根据最新文档创建清单文件（manifest）和元素文件
  4. 说明解释 - 展示创建的内容以及测试方法

Minimal Examples

最简示例

Manifest (manifests.ts)

清单文件（manifests.ts）

typescript
export const manifests: Array<UmbExtensionManifest> = [
  {
    type: 'fileUploadPreview',
    alias: 'My.FileUploadPreview.Custom',
    name: 'Custom File Upload Preview',
    weight: 100,
    element: () => import('./my-file-preview.element.js'),
    forMimeTypes: ['application/pdf', 'application/x-pdf'],
  },
];
typescript
export const manifests: Array<UmbExtensionManifest> = [
  {
    type: 'fileUploadPreview',
    alias: 'My.FileUploadPreview.Custom',
    name: 'Custom File Upload Preview',
    weight: 100,
    element: () => import('./my-file-preview.element.js'),
    forMimeTypes: ['application/pdf', 'application/x-pdf'],
  },
];

Element Implementation (my-file-preview.element.ts)

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

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

@customElement('my-file-preview')
export class MyFilePreviewElement extends UmbLitElement implements UmbFileUploadPreviewElement {
  @property({ type: Object })
  file?: File;

  @state()
  private _previewUrl?: string;

  override updated(changedProperties: Map<string, unknown>) {
    if (changedProperties.has('file') && this.file) {
      this._previewUrl = URL.createObjectURL(this.file);
    }
  }

  override disconnectedCallback() {
    super.disconnectedCallback();
    if (this._previewUrl) {
      URL.revokeObjectURL(this._previewUrl);
    }
  }

  override render() {
    if (!this.file) return html``;

    return html`
      <div class="preview-container">
        <uui-icon name="icon-document"></uui-icon>
        <span>${this.file.name}</span>
      </div>
    `;
  }
}

export default MyFilePreviewElement;
typescript
import { html, customElement, property, state } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import type { UmbFileUploadPreviewElement } from '@umbraco-cms/backoffice/media';

@customElement('my-file-preview')
export class MyFilePreviewElement extends UmbLitElement implements UmbFileUploadPreviewElement {
  @property({ type: Object })
  file?: File;

  @state()
  private _previewUrl?: string;

  override updated(changedProperties: Map<string, unknown>) {
    if (changedProperties.has('file') && this.file) {
      this._previewUrl = URL.createObjectURL(this.file);
    }
  }

  override disconnectedCallback() {
    super.disconnectedCallback();
    if (this._previewUrl) {
      URL.revokeObjectURL(this._previewUrl);
    }
  }

  override render() {
    if (!this.file) return html``;

    return html`
      <div class="preview-container">
        <uui-icon name="icon-document"></uui-icon>
        <span>${this.file.name}</span>
      </div>
    `;
  }
}

export default MyFilePreviewElement;

Interface Reference

接口参考

typescript
interface ManifestFileUploadPreview extends ManifestElement<UmbFileUploadPreviewElement> {
  type: 'fileUploadPreview';
  forMimeTypes: string | Array<string>; // e.g., 'image/*', ['image/png', 'image/jpeg']
}

interface UmbFileUploadPreviewElement {
  file?: File;
}
typescript
interface ManifestFileUploadPreview extends ManifestElement<UmbFileUploadPreviewElement> {
  type: 'fileUploadPreview';
  forMimeTypes: string | Array<string>; // 例如：'image/*', ['image/png', 'image/jpeg']
}

interface UmbFileUploadPreviewElement {
  file?: File;
}

Common MIME Type Patterns

常见MIME类型模式

  • image/*
    - All image types
  • video/*
    - All video types
  • audio/*
    - All audio types
  • application/pdf
    - PDF files
  • */*
    - Fallback for all types (use with lower weight)
That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.
  • image/*
    - 所有图片类型
  • video/*
    - 所有视频类型
  • audio/*
    - 所有音频类型
  • application/pdf
    - PDF文件
  • */*
    - 所有类型的回退（使用较低权重）
就是这样！请务必获取最新文档，保持示例最简，生成可运行的完整代码。