Schema — campo video

Contrato público do setting video, valores salvos, blocks e fallbacks em temas Corvex React.

Schema — campo video

Contrato normativo para temas Corvex. Sem detalhes internos de armazenamento.

---

Setting video

{
  "type": "video",
  "id": "heroVideo",
  "label": "Vídeo"
}

Alias aceito pelo Editor: video_url (mesmo comportamento).

Aspecto	Comportamento
Valor salvo	string — UUID da biblioteca ou URL externa
No React	settings.heroVideo (ou o id definido)
Não é	Objeto resolvido, caminho de arquivo local, embed HTML

O tipo video é experimental: o validador aceita (SETTING_FIELD_TYPES), mas não está em STABLE_SETTING_TYPES. Teste no editor.

---

Editor — três modos de entrada

O VideoPickerModal oferece:

Aba	Resultado em settings
Biblioteca	UUID do vídeo na biblioteca de vídeos da loja
Enviar	Upload → UUID após processamento
URL	String URL (YouTube, Vimeo, MP4/WebM)

Detecção no código do tema

const LIBRARY_ID =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

export function classifyVideoValue(value) {
  if (!value || typeof value !== 'string') return 'empty';
  const trimmed = value.trim();
  if (!trimmed) return 'empty';
  if (/youtube\.com|youtu\.be|vimeo\.com/i.test(trimmed)) return 'embed';
  if (/^https?:\/\//i.test(trimmed)) return 'url';
  if (LIBRARY_ID.test(trimmed)) return 'library';
  return 'unknown';
}

---

Quando usar

Situação	Use
Lojista escolhe/troca o vídeo	type: "video"
YouTube / Vimeo	type: "video" (aba URL)
MP4 em CDN externa	type: "video" ou type: "url"
Só imagem estática	type: "image"
Campo texto com URL manual sem picker	Evite — perde biblioteca e validação

Quando NÃO usar

• Embed com HTML customizado no schema → use html (experimental) ou snippet fixo.
• Duplicar UUID como URL inventada no JSON.

---

Renderização — nível section

export default function HeroSection({ settings = {} }) {
  const mode = settings.mediaMode ?? 'image';
  const videoValue = settings.heroVideo;
  const poster = settings.heroPoster;

  if (mode !== 'video' || !videoValue) {
    return settings.heroImage ? (
      <img src={settings.heroImage} alt={settings.title ?? ''} />
    ) : null;
  }

  return (
    <CorvexVideo
      value={videoValue}
      poster={poster}
      autoplay={settings.videoAutoplay}
      muted
      loop={settings.videoLoop}
      controls={false}
      ariaLabel={settings.title}
    />
  );
}

Ver implementação de CorvexVideo em Padrões.

---

Renderização — nível block

Blocks com video expõem o valor em settings do block:

export default function ReelBlock({ settings = {} }) {
  return (
    <CorvexVideo
      value={settings.videoId}
      poster={settings.poster}
      autoplay={false}
      muted
      loop
      controls={false}
      preload="none"
    />
  );
}

Regra	Detalhe
Namespace	Sempre settings.{id} do schema do block
Snippets	Passe value e poster explicitamente
Mapa por id de block	Use settings do block diretamente

---

Fallbacks (obrigatórios)

Estado	O que mostrar
Valor vazio	image alternativa ou placeholder
UUID + vídeo processando	Poster (image) + badge opcional
UUID sem playback resolvido	Poster — nunca <video src={uuid}>
prefers-reduced-motion	Poster estático; sem autoplay
Embed indisponível	Poster ou mensagem curta

function HeroMedia({ settings }) {
  const poster = settings.heroPoster || settings.heroImage;
  const video = settings.heroVideo;

  if (!video) {
    return poster ? <img src={poster} alt="" /> : null;
  }

  const kind = classifyVideoValue(video);

  if (kind === 'library') {
    // useCorvexVideoPlayback devolve playbackUrl; até lá, o snippet mostra o poster
    return <CorvexVideo value={video} poster={poster} />;
  }

  if (kind === 'embed' || kind === 'url') {
    return <CorvexVideo value={video} poster={poster} />;
  }

  return poster ? <img src={poster} alt="" /> : null;
}

---

Combinar imagem e vídeo

Padrão recomendado no schema.json:

{
  "type": "select",
  "id": "mediaMode",
  "label": "Tipo de mídia",
  "options": [
    { "value": "image", "label": "Imagem" },
    { "value": "video", "label": "Vídeo" }
  ],
  "default": "image"
},
{
  "id": "heroImage",
  "type": "image",
  "label": "Imagem"
},
{
  "id": "heroPoster",
  "type": "image",
  "label": "Poster do vídeo"
},
{
  "id": "heroVideo",
  "type": "video",
  "label": "Vídeo"
},
{
  "id": "videoAutoplay",
  "type": "checkbox",
  "label": "Autoplay",
  "default": true
},
{
  "id": "videoLoop",
  "type": "checkbox",
  "label": "Loop",
  "default": true
}

Mantenha imagem + poster + vídeo no schema; o JSX usa só o modo ativo.

---

Live preview

Mudanças em settings re-renderizam a section React automaticamente no canvas.

Para texto editável inline, use isEditing + InlineText do @corvex/runtime — ver Runtime API.

---

Snippet reutilizável (recomendado)

Extraia markup de vídeo para snippets/corvex-video/snippet.jsx quando houver mais de uma section com vídeo. Parâmetros sugeridos:

Prop	Obrigatório	Descrição
value	Sim	UUID ou URL do setting
poster	Recomendado	URL da imagem de capa
autoplay, muted, loop, controls	Não	Booleanos
preload	Não	none | metadata | auto
className, ariaLabel	Não	Acessibilidade e estilo

Implementação de referência: Padrões — CorvexVideo.

---

Leitura relacionada

• Conceitos
• Padrões
• Field type video
• Hub — Biblioteca