Mídia

Cropper

Um retângulo de recorte sobre uma imagem, sem dependências: trave uma proporção, use uma máscara circular, gire e espelhe, e recorte no servidor ou no navegador.

Testado com WAI-ARIA

Importação

main.ts

import { Cropper } from '@vitral/vue';

Avatar

Um círculo trava a proporção em um e dispensa as alças: arraste o recorte, ou dê zoom nele. A pré-visualização ao lado é a mesma imagem sob uma caixa menor, não uma segunda renderização.

1<script setup lang="ts">2import { Button, Cropper, type CropValue, StackPanel } from '@vitral/vue';3import { ref, useTemplateRef } from 'vue';4 5const portrait = 'https://picsum.photos/id/1027/900/1200';6const avatar = ref<CropValue>({ x: 0, y: 0, width: 0, height: 0, rotate: 0, flipX: false, flipY: false });7 8// The file, when the file is what you want: a canvas, then a Blob to upload.9const cropper = useTemplateRef<InstanceType<typeof Cropper>>('avatarCropper');10const saved = ref<string | null>(null);11const savedSize = ref(0);12 13async function save() {14    const blob = await cropper.value?.toBlob('image/png', { width: 256 });15    if (!blob) return;16    if (saved.value) URL.revokeObjectURL(saved.value);17    saved.value = URL.createObjectURL(blob);18    savedSize.value = blob.size;19}20</script>21 22<template>23    <StackPanel spacing="1rem" style="flex: 1 1 100%; min-width: 0">24        <Cropper ref="avatarCropper" v-model="avatar" :src="portrait" shape="circle" alt="A portrait" height="18rem" :preview-size="96" />25        <StackPanel orientation="horizontal" spacing="0.625rem" align="center" wrap>26            <Button label="Crop to a 256px PNG" size="small" @click="save" />27            <small v-if="saved" style="color: var(--vt-text-muted-color)">{{ Math.round(savedSize / 1024) }} kB</small>28            <img v-if="saved" :src="saved" alt="The cropped avatar" width="48" height="48" style="border-radius: 50%" />29        </StackPanel>30    </StackPanel>31</template>

Uma proporção, com alças

Oito alças para o ponteiro, ocultas para tecnologias assistivas: o próprio retângulo é a única parada de tabulação.

{ x: 160, y: 90, width: 1280, height: 720, rotate: 0 }

1<script setup lang="ts">2import { Cropper, type CropValue } from '@vitral/vue';3import { ref } from 'vue';4 5const photo = 'https://picsum.photos/id/1015/1600/900';6const banner = ref<CropValue>({ x: 0, y: 0, width: 0, height: 0, rotate: 0, flipX: false, flipY: false });7 8const rounded = (value: CropValue) => `{ x: ${Math.round(value.x)}, y: ${Math.round(value.y)}, width: ${Math.round(value.width)}, height: ${Math.round(value.height)}, rotate: ${value.rotate} }`;9</script>10 11<template>12    <Cropper v-model="banner" :src="photo" aspect="16:9" alt="A landscape" height="18rem" />13    <small style="color: var(--vt-text-muted-color)">{{ rounded(banner) }}</small>14</template>

Sem os terços

A guia fica ligada num retângulo e desligada num círculo, onde a regra dos terços não significa nada. `grid` decide por cima, num sentido ou no outro.

1<script setup lang="ts">2import { Cropper, type CropValue } from '@vitral/vue';3import { ref } from 'vue';4 5const photo = 'https://picsum.photos/id/1015/1600/900';6const plain = ref<CropValue>({ x: 0, y: 0, width: 0, height: 0, rotate: 0, flipX: false, flipY: false });7</script>8 9<template>10    <Cropper v-model="plain" :src="photo" aspect="4:3" :grid="false" alt="A landscape" height="16rem" />11</template>

Livre, com proporções e giros

Um seletor trava a proporção; os giros de um quarto e os espelhamentos acompanham o recorte, que continua apontando para a mesma parte da imagem.

const crop = ref<CropValue>({ x: 160, y: 90, width: 1280, height: 720, rotate: 0 });

1<script setup lang="ts">2import { Cropper, type CropValue } from '@vitral/vue';3import { computed, ref } from 'vue';4 5const photo = 'https://picsum.photos/id/1015/1600/900';6const free = ref<CropValue>({ x: 0, y: 0, width: 0, height: 0, rotate: 0, flipX: false, flipY: false });7 8const aspects = [9    { label: 'Free', value: 'free' },10    { label: '1:1', value: '1:1' },11    { label: '4:3', value: '4:3' },12    { label: '16:9', value: '16:9' }13];14 15const model = computed(() => {16    const { x, y, width, height, rotate } = free.value;17    return `const crop = ref<CropValue>({ x: ${Math.round(x)}, y: ${Math.round(y)}, width: ${Math.round(width)}, height: ${Math.round(height)}, rotate: ${rotate} });`;18});19</script>20 21<template>22    <Cropper v-model="free" :src="photo" :aspects="aspects" rotatable alt="A landscape" height="20rem" />23    <code style="font-size: 0.75rem; color: var(--vt-text-muted-color)">{{ model }}</code>24</template>

Num diálogo

Onde um cropper costuma morar: uma foto é escolhida, recortada sobre a página, e o perfil só muda depois que ela é aceita. O diálogo dá a largura ao palco, então o recorte é medido em relação ao tamanho em que é de fato exibido.

1<script setup lang="ts">2import { Avatar, Button, Cropper, Dialog, StackPanel, type CropValue } from '@vitral/vue';3import { ref, useTemplateRef } from 'vue';4 5// The whole flow, which is where a cropper usually lives: a picture is6// chosen, cropped in a dialog, and only then does the profile change.7const portrait = 'https://picsum.photos/id/1027/900/1200';8const dialog = ref(false);9const pending = ref<CropValue>({ x: 0, y: 0, width: 0, height: 0, rotate: 0, flipX: false, flipY: false });10const profile = ref<string | null>(null);11const modalCropper = useTemplateRef<InstanceType<typeof Cropper>>('modalCropper');12 13async function apply() {14    const blob = await modalCropper.value?.toBlob('image/png', { width: 192 });15    dialog.value = false;16    if (!blob) return;17    if (profile.value) URL.revokeObjectURL(profile.value);18    profile.value = URL.createObjectURL(blob);19}20</script>21 22<template>23    <StackPanel orientation="horizontal" spacing="0.625rem" align="center" wrap>24        <Avatar :image="profile ?? undefined" :label="profile ? undefined : 'AF'" shape="circle" size="large" :alt="profile ? 'Your photo' : undefined" />25        <Button :label="profile ? 'Change the photo' : 'Upload a photo'" severity="secondary" variant="outlined" size="small" @click="dialog = true" />26        <small v-if="profile" style="color: var(--vt-text-muted-color)">Cropped to a 192px PNG</small>27    </StackPanel>28 29    <Dialog v-model:visible="dialog" modal header="Crop your photo" :style="{ width: 'min(30rem, 92vw)' }">30        <Cropper ref="modalCropper" v-model="pending" :src="portrait" shape="circle" alt="The photograph being cropped" height="16rem" />31        <template #footer>32            <Button label="Cancel" severity="secondary" variant="text" @click="dialog = false" />33            <Button label="Use this photo" @click="apply" />34        </template>35    </Dialog>36</template>

Como usar

1<script setup lang="ts">2import { Button, Cropper, type CropValue } from '@vitral/vue';3import { ref, useTemplateRef } from 'vue';4 5const src = 'https://picsum.photos/id/1027/900/1200';6const crop = ref<CropValue>({ x: 0, y: 0, width: 0, height: 0, rotate: 0, flipX: false, flipY: false });7const cropper = useTemplateRef<InstanceType<typeof Cropper>>('cropper');8 9// The file, when you want the file rather than the numbers.10async function upload() {11    const blob = await cropper.value?.toBlob('image/png', { width: 256 });12    if (blob) console.log(blob);13}14</script>15 16<template>17    <Cropper ref="cropper" v-model="crop" :src="src" shape="circle" :preview-size="96" alt="A portrait" />18    <Button label="Get the file" size="small" @click="upload" />19</template>

API

Lido de packages/vue/src/components/Cropper/types.ts, então diz o que o componente aceita de fato.

Props

Nome	Tipo	Descrição
src	string	A imagem. Qualquer coisa que um `<img>` aceite, incluindo uma URL de dados ou de objeto.
alt	string	Descreve a imagem, não o controle. Sem ele a imagem é decorativa.
aspect	number \| string \| null	Trava o recorte numa proporção: `1`, `'16:9'`, ou null para deixá-lo livre.
aspects	readonly CropAspect[]	Proporções a oferecer na barra de ferramentas. Omita-o e nenhum seletor é desenhado.
shape	'rect' \| 'circle'	`'circle'` mascara o recorte e a prévia, e trava a proporção em 1.
handles	boolean	Desenha as oito alças de redimensionamento. O padrão é true para um retângulo e false para um círculo.
rotatable	boolean	Oferece os giros de um quarto de volta e os espelhamentos.
zoomable	boolean	Oferece um controle deslizante de zoom.
grid	boolean	Desenha os terços sobre o recorte enquanto ele é movido. Ligado por padrão num retângulo e desligado num círculo, onde a regra dos terços não significa nada: a guia serve para compor um quadro, e um recorte redondo não tem cantos para onde compor.
minWidth	number	O menor recorte, nos pixels da própria imagem.
minHeight	number	—
height	number \| string	A altura do palco: um número é em pixels.
previewSize	number	O tamanho da prévia ao vivo, em pixels. Zero não desenha nenhuma.
disabled	boolean	—

Mais pt, dt e unstyled de BaseProps; veja pass-through e modo sem estilo.

Emits

Evento	Payload	Descrição
update:modelValue	value: CropValue	O recorte, à medida que muda.
load	event: { width: number; height: number }	A imagem carregou e seu tamanho natural é conhecido.
change	value: CropValue	Um arrasto do recorte ou de uma alça terminou.

Slots

Nome	Props do slot	Descrição
toolbar	(props: { value: CropValue; reset: () => void })	Substitui a barra de ferramentas.
preview	(props: { value: CropValue })	Ao lado da prévia, ou no lugar dela.

Cropper

Importação

API

Props

Emits

Slots

Componentes relacionados