tldraw项目中自定义形状与Store结合使用的注意事项

概述

在使用tldraw这个开源白板工具时，开发者经常需要创建自定义形状来满足特定需求。然而，当这些自定义形状与tldraw的Store功能结合使用时，可能会遇到一些验证错误。本文将深入探讨这一问题的原因及解决方案。

问题现象

开发者在尝试创建一个名为"my-custom-shape"的自定义形状时，当启用Store功能后，系统会抛出验证错误。错误信息表明Store无法识别这个自定义形状类型，因为它只接受预设的形状类型如"arrow"、"bookmark"等。

问题根源

这个问题的根本原因在于Store的初始化方式。默认情况下，tldraw的Store只会识别内置的形状类型。当开发者创建自定义形状时，必须明确告知Store这些新形状的存在，否则Store的验证机制会拒绝这些未知的形状类型。

解决方案

方法一：完整方案

最完整的解决方案是在创建Store时，将默认形状工具和自定义形状工具一起传入：

import { defaultShapeUtils } from 'tldraw'

const store = createTLStore({
  shapeUtils: [...defaultShapeUtils, ...customShape]
})

这种方法确保了Store既能识别内置形状，也能识别自定义形状。

方法二：简化方案

如果只需要使用自定义形状而不需要内置形状，可以采用更简洁的方式：

const store = createTLStore({ shapeUtils: customShape })

实现细节

在实现自定义形状时，需要注意以下几点：

1. 形状定义：必须正确定义形状类型和属性

type ICustomShape = TLBaseShape<
  'my-custom-shape',
  {
    w: number
    h: number
    text: string
  }
>

2. 形状工具类：需要继承ShapeUtil并实现必要方法

class MyShapeUtil extends ShapeUtil<ICustomShape> {
  static override type = 'my-custom-shape' as const
  // 其他必要实现...
}

3. Store初始化：关键步骤是正确配置shapeUtils参数

最佳实践

1. 建议在项目中使用完整方案，保留内置形状功能
2. 为自定义形状使用独特的前缀，避免与未来版本的内置形状冲突
3. 考虑形状的序列化和反序列化需求
4. 测试形状在不同缩放比例下的表现

总结

tldraw提供了强大的自定义形状能力，但要与Store功能协同工作，必须正确初始化Store并传入形状工具集。理解这一机制后，开发者可以更灵活地扩展tldraw的功能，创建出满足各种需求的白板应用。

通过本文的解决方案，开发者可以避免验证错误，顺利实现自定义形状与Store的结合使用，从而构建更加强大和个性化的白板应用。