Écrire des exemples tldraw

Le projet exemples (apps/examples) contient des démonstrations minimales de l'utilisation du SDK tldraw. Les exemples sont intégrés sur le site de documentation et déployés sur examples.tldraw.com.

Standards pour les exemples dans apps/examples/src/examples.

Structure des exemples

Chaque exemple vit dans son propre dossier :

apps/examples/src/examples/
└── my-example/
    ├── README.md          # Métadonnées requises
    ├── MyExampleExample.tsx  # Fichier d'exemple principal
    └── my-example.css     # Styles optionnels

Nom du dossier

• Minuscules en kebab-case : custom-canvas, button-demo, magical-wand
• Utilisé comme chemin URL pour l'exemple

README.md

Format frontmatter requis :

---
title: Example title
component: ./ExampleFile.tsx
category: category-id
priority: 1
keywords: [keyword1, keyword2]
---

Résumé d'une ligne de ce que cet exemple démontre.

---

Explication détaillée de l'exemple. Incluez des extraits de code ici s'ils aident à expliquer les concepts qui ne sont pas évidents dans le code de l'exemple lui-même.

Champs du frontmatter

Catégories valides

getting-started, configuration, editor-api, ui, layout, events, shapes/tools, collaboration, data/assets, use-cases

Fichier d'exemple

Nommage

• PascalCase se terminant par « Example » : CustomCanvasExample.tsx, ButtonExample.tsx
• Le nom doit correspondre au nom du dossier et au titre

Structure

import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

export default function MyExampleExample() {
    return (
        <div className="tldraw__editor">
            <Tldraw />
        </div>
    )
}

Exigences :

• Doit avoir un composant React exporté par défaut
• Utilisez la classe tldraw__editor pour les exemples pleine page
• Importez tldraw/tldraw.css pour les styles

Mise en page

• Pleine page : enveloppez dans <div className="tldraw__editor">
• Inséré : consultez les exemples existants pour les modèles de mise en page

Styles

• Placez le CSS dans un fichier séparé nommé d'après l'exemple : my-example.css
• Importez à côté du CSS tldraw : import './my-example.css'
• Évitez les styles inline extensifs via la prop style

Panneaux de contrôle

Pour les exemples qui ont besoin de boutons ou de contrôles, utilisez l'emplacement du composant TopPanel avec TldrawUiButton :

import { Tldraw, TldrawUiButton, useEditor } from 'tldraw'
import 'tldraw/tldraw.css'
import './my-example.css'

function MyControls() {
    const editor = useEditor()
    return (
        <div className="tlui-menu my-controls">
            <TldrawUiButton type="normal" onClick={() => editor.zoomIn()}>
                Zoom in
            </TldrawUiButton>
            <TldrawUiButton type="normal" onClick={() => editor.zoomOut()}>
                Zoom out
            </TldrawUiButton>
        </div>
    )
}

export default function MyExampleExample() {
    return (
        <div className="tldraw__editor">
            <Tldraw components={{ TopPanel: MyControls }} />
        </div>
    )
}

CSS pour les panneaux de contrôle :

.my-controls {
    display: flex;
    flex-wrap: wrap;
    margin: 8px;
}

Commentaires

Utilisez le format de note de bas de page avec des références numérotées :

import { Tldraw, type TLComponents } from 'tldraw'
import 'tldraw/tldraw.css'

// [1]
const components: TLComponents = {
    PageMenu: null,
}

export default function CustomComponentsExample() {
    return (
        <div className="tldraw__editor">
            {/* [2] */}
            <Tldraw components={components} />
        </div>
    )
}

/*
[1]
Définissez les surcharges de composants en dehors du composant React afin qu'elles soient statiques.
Si elles sont définies à l'intérieur, utilisez useMemo pour éviter leur recréation à chaque rendu.

[2]
Transmettez les surcharges de composants via la prop components.
*/

Types d'exemples

Exemples ciblés

• Focus étroit sur une fonctionnalité spécifique du SDK
• Mise en page minimale
• Meant to be read, not used
• Supprimez tout code superflu

Exemples de cas d'usage

• Montrez une expérience utilisateur reconnaissable
• Priorisez la clarté et l'exhaustivité
• Catégorie : use-cases

Fichiers supplémentaires

• Divisez le code complexe en fichiers séparés s'il distrait du but de l'exemple
• Exemple : composant d'entrée complexe dans Input.tsx
• Gardez le fichier d'exemple principal concentré sur la démonstration du concept

Important

• Suivez les bonnes pratiques React et TypeScript
• N'utilisez jamais la casse de titre pour les titres - utilisez la casse de phrase
• Gardez les exemples minimaux et ciblés