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

文件夹名称

• 小写 kebab-case：custom-canvas、button-demo、magical-wand
• 用作示例的 URL 路径

README.md

必需的 frontmatter 格式：

---
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.

Frontmatter 字段

字段	描述
title	句首大写，与文件夹名称对应
component	示例文件的相对路径
category	有效类别 ID 之一（见下文）
priority	类别内的显示顺序（数值越小 = 越靠前）
keywords	搜索词（避免使用诸如 "tldraw" 这类显而易见的词）

有效类别

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

示例文件

命名

• PascalCase 且以 "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 prop 使用大量内联样式

控制面板

对于需要按钮或控件的示例，使用 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 最佳实践
• 标题绝不使用 title case - 使用 sentence case
• 保持示例精简且聚焦