WikiEditor

Panoramica

WikiEditor scrive e mostra una pagina wiki in HTML (v-model). Oltre alla formattazione di base offre blocchi di codice evidenziati, tabelle, immagini, callout e sezioni richiudibili; il modulo lo estende con i propri comandi / e i propri blocchi, e ne riceve link e commenti come eventi.

Lo stesso componente serve in modifica e in lettura (readonly): in lettura la barra degli strumenti sparisce, i link si aprono con un clic e, se il modulo lo prevede, si può comunque commentare.

Anteprima

Titoli, elenco, callout, blocco di codice, tabella e sezione richiudibile. Scrivi / all'inizio di una riga per il menu dei comandi; con il cursore in una tabella, in un blocco di codice o in un callout compare la seconda riga della barra.

Quick start

<script setup lang="ts">
import { ref } from 'vue'
import { WikiEditor, type ComandoPowerbox, type CommentoAncorato } from '@pzeta/vue-wiki'

const contenuto = ref('')
const commenti = ref<CommentoAncorato[]>([])

const comandi: ComandoPowerbox[] = [
  {
    id: 'indice',
    etichetta: 'Indice',
    descrizione: 'Articoli annidati del padre',
    icona: 'pi pi-list-check',
    inserisci: ({ inserisciBlocco }) => inserisciBlocco('indice', { idarticolo: 12 }),
  },
]

const caricaAllegato = async (file: File) => {
  const allegato = await allegatiService.carica(file) // servizio del modulo
  return { src: allegato.url, id: String(allegato.idallegato) }
}

const cercaArticoli = async (ricerca: string) =>
  (await articoliService.cerca(ricerca)).map((a) => ({
    etichetta: a.titolo,
    href: `/knowledge/articolo/${a.idarticolo}`,
  }))
</script>

<template>
  <WikiEditor
    v-model="contenuto"
    :readonly="!puoModificare"
    :comandi="comandi"
    :carica-immagine="caricaAllegato"
    :risolvi-link="cercaArticoli"
    :commenti="commenti"
    :max-length="100000"
    @commenta="apriFormCommento"
    @apri-link="(href) => router.push(href)"
    @apri-commento="evidenziaCommento"
  >
    <template #blocco-personalizzato="{ tipo, dati }">
      <IndiceFigli v-if="tipo === 'indice'" :id-articolo="Number(dati.idarticolo)" />
    </template>
  </WikiEditor>
</template>

Props

Eventi

Nel template gli eventi si scrivono in kebab-case: @apri-link, @apri-commento.

Slot

<WikiEditor v-model="contenuto">
  <template #toolbar-extra="{ editor }">
    <button type="button" class="px-2 text-sm" @click="editor.commands.clearContent(true)">
      Svuota
    </button>
  </template>
</WikiEditor>

Metodi esposti

Con un template ref (ref="wiki"):

Barra degli strumenti

Compare solo in modifica. Da sinistra:

Sotto compare una seconda riga con i comandi del blocco in cui si trova il cursore:

Barra sulla selezione

Selezionando del testo compare sopra la selezione una barra con grassetto, corsivo, sottolineato, barrato, codice in linea, link e — se c'è la prop commenti — Commenta. In sola lettura resta solo «Commenta».

Non compare per una selezione vuota o di soli spazi, per un blocco selezionato per intero (immagine, blocco del modulo) e dentro un blocco di codice, dove né formattazione né ancore sono ammesse.

Menu dei comandi /

Digitando / all'inizio di una riga o dopo uno spazio si apre il menu, filtrato mentre si scrive (maiuscole e accenti non contano; ogni parola digitata deve comparire nell'etichetta, nella descrizione o nelle parole chiave). Frecce per scegliere, Invio per eseguire, Esc per chiudere. Non si apre in sola lettura né dentro un blocco di codice.

Seguono i comandi del modulo (comandi): vedi Comandi e blocchi.

Link

• Dialogo: dalla barra, dal menu / o da un comando del modulo (chiediLink()). Con del testo selezionato chiede solo l'indirizzo, senza selezione anche il testo; su un link esistente permette di modificarlo o rimuoverlo.
• Ricerca: con risolviLink, ciò che si scrive nel campo e non sembra un indirizzo (non inizia con uno schema, /, #, . o www.) diventa una ricerca, 250 ms dopo l'ultima battuta; scegliere un risultato inserisce il link. Una ricerca più recente scarta le risposte di quelle prima, e i risultati con indirizzi non sicuri non compaiono.
• Indirizzi: www.esempio.it diventa https://www.esempio.it; uno schema non ammesso mostra «Indirizzo non valido».
• Scrittura: un indirizzo digitato o incollato diventa link da solo.
• Clic: in modifica un clic posiziona il cursore e Ctrl/⌘+clic emette apriLink; in sola lettura il clic emette apriLink.

Immagini

Con caricaImmagine un'immagine si aggiunge dal pulsante o dal comando Immagine, incollandola o trascinandola nel testo (va dove la si rilascia). caricaImmagine riceve il File e restituisce { src, id }: l'immagine viene inserita come blocco con alt uguale al nome del file e data-id uguale all'id. Più file si caricano uno dopo l'altro.

Durante il caricamento sotto l'editor compare «Caricamento dell'immagine…»; se la promessa fallisce, o src non è un indirizzo ammesso (http, https, blob o relativo), compare un avviso (role="alert") che sparisce alla modifica successiva.

Prova: immagini e link

Qui caricaImmagine non carica nulla: restituisce un indirizzo blob: del file, che resta nel browser. risolviLink cerca in un elenco fisso di tre articoli.

Callout e sezioni richiudibili

• Callout: avvolge i blocchi selezionati in un riquadro colorato, di tipo info (predefinito), success, warn o danger. Il tipo si cambia dalla seconda riga della barra.
• Sezione richiudibile: avvolge i blocchi in una sezione con titolo. Nell'editor il titolo è un campo (Invio porta all'inizio del contenuto) e la freccia apre o chiude la sezione: in modifica lo stato viene salvato, in sola lettura no. Nel contenuto salvato è un <details> nativo, che si apre anche mostrato senza editor.

Scorciatoie da tastiera

Sono quelle di Tiptap (Mod = Ctrl, ⌘ su macOS):

Accessibilità

• L'area di testo è role="textbox" con aria-multiline, aria-label (prop ariaLabel), aria-readonly in sola lettura e aria-invalid oltre maxLength.
• Le barre sono role="toolbar" con un nome; i pulsanti hanno aria-label e, se si attivano, aria-pressed.
• Il menu / è un listbox con aria-activedescendant sulla voce selezionata.
• La freccia della sezione richiudibile ha aria-expanded; il titolo è un campo con etichetta.
• Il dialogo del link porta il focus sul primo campo; gli indicatori nel margine hanno un nome («Apri il commento»).
• Gli avvisi di caricamento sono role="status" e role="alert"; il contatore oltre il limite è annunciato (aria-live).

Note

• v-model ed eco: il valore emesso e rimandato dal parent come modelValue è riconosciuto e non reimposta il contenuto (il cursore non salta). Un valore diverso arrivato da fuori sostituisce il contenuto e annulla una modifica non ancora emessa.
• Larghezza: la barra va a capo e le tabelle larghe scorrono dentro il proprio contenitore: l'editor non allarga la pagina.
• Tema scuro: tutte le classi hanno la variante dark:; il blocco di codice è scuro in entrambi i temi.