write-example

tldraw のサンプルを作成する

サンプルプロジェクト（apps/examples）には、tldraw SDK の使用方法を示す最小限のデモが含まれています。サンプルはドキュメントサイトに埋め込まれ、examples.tldraw.comにデプロイされます。

apps/examples/src/examples にあるサンプルの基準です。

サンプルの構造

各サンプルはそれぞれのフォルダーに配置します。

apps/examples/src/examples/
└── my-example/
    ├── README.md          # Required metadata
    ├── MyExampleExample.tsx  # Main example file
    └── my-example.css     # Optional styles

フォルダー名

• 小文字のケバブケース：custom-canvas、button-demo、magical-wand
• サンプルの URL パスとして使用されます

README.md

必須のフロントマター形式：

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

One-line summary of what this example demonstrates.

---

Detailed explanation of the example. Include code snippets here if they help explain concepts not obvious from the example code itself.

フロントマターのフィールド

フィールド	説明
title	センテンスケースで、フォルダー名に対応します
component	サンプルファイルへの相対パス
category	有効なカテゴリ ID のいずれか（以下を参照）
priority	カテゴリ内での表示順（小さいほど上位）
keywords	検索語（「tldraw」のような自明な語は避けてください）

有効なカテゴリ

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

サンプルファイル

命名

• 「Example」で終わるパスカルケース：CustomCanvasExample.tsx、ButtonExample.tsx
• 名前はフォルダー名とタイトルに対応させる必要があります

構造

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

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

要件：

• デフォルトエクスポートの React コンポーネントが必要です
• 全ページのサンプルには tldraw__editor クラスを使用します
• スタイルには tldraw/tldraw.css をインポートします

レイアウト

• 全ページ：<div className="tldraw__editor"> でラップします
• インセット：ページレイアウトのパターンについては既存のサンプルを参照してください

スタイル

• CSS はサンプル名の付いた別ファイルに配置します：my-example.css
• tldraw の CSS と一緒にインポートします：import './my-example.css'
• style プロップによる過度なインラインスタイルは避けてください

コントロールパネル

ボタンやコントロールが必要なサンプルでは、TopPanel コンポーネントスロットと 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：

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

コメント

番号付き参照の脚注形式を使用します：

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]
Define component overrides outside the React component so they're static.
If defined inside, use useMemo to prevent recreation on every render.

[2]
Pass component overrides via the components prop.
*/

サンプルの種類

タイトなサンプル

• 特定の SDK 機能に焦点を絞ります
• 最小限のスタイリング
• 使用するためではなく、読むためのものです
• 不要なコードは削除します

ユースケースサンプル

• 認識できるユーザー体験を示します
• 明瞭さと完全性を優先します
• カテゴリ：use-cases

追加ファイル

• 複雑なコードがサンプルの目的から逸れる場合は、別ファイルに分割します
• 例：Input.tsx にある複雑な入力コンポーネント
• メインのサンプルファイルはコンセプトのデモに集中させてください

重要

• React と TypeScript のベストプラクティスに従ってください
• タイトルにタイトルケースを絶対に使用しないでください - センテンスケースを使用します
• サンプルは最小限で焦点を絞ったものにしてください