linkcad.plugin

插件模块提供用于创建工具、格式读取器和格式写入器的框架。

装饰器

`@tool()`

将类注册为菜单工具。请参阅工具装饰器。

@tool(name="My Tool", menu="Tools/Custom")
class MyTool(Tool):
    def run(self, drawing) -> None:
        ...

`@format_reader()`

将类注册为文件导入格式。请参阅格式装饰器。

@format_reader(name="My Format", extensions=["*.myf"])
class MyReader(FormatReader):
    def read(self, path: Path, drawing: DrawingContext) -> None:
        ...

`@format_writer()`

将类注册为文件导出格式。请参阅格式装饰器。

@format_writer(name="My Format", extensions=["*.myf"])
class MyWriter(FormatWriter):
    def write(self, path: Path, drawing: WriterContext) -> None:
        ...

Option 类

Option 提供用于定义带类型、持久化选项的工厂方法：

工厂方法	结果类型	UI 控件
`Option.integer(label, default, min, max)`	`int`	微调框
`Option.real(label, default, min, max, decimals)`	`float`	双精度微调框
`Option.boolean(label, default)`	`bool`	复选框
`Option.string(label, default)`	`str`	文本字段
`Option.choice(label, choices, default)`	`str`	下拉框
`Option.path(label, default, file_filter)`	`str`	文件选择器
`Option.color(label, default)`	`str`	颜色选择器
`Option.table(label, columns, default)`	`list[dict]`	可编辑网格
`Option.cell_choice(label, default)`	`str`	单元下拉框

所有工厂方法都接受可选的 tooltip 和 enabled_when 参数。

上下文类

DrawingContext

用于格式读取器的构建器接口。方法：

cell(name, main)——用于创建单元的上下文管理器
iter_lines(path)——带进度的行迭代器
iter_binary(path, chunk_size)——带进度的二进制迭代器
progress——获取/设置进度（0.0–1.0）

WriterContext

用于格式写入器的读取器接口。方法：

shapes(cell, layer)——带进度迭代形状
shapes_by_layer(cell)——按图层分组的形状
shapes_by_cell(layer)——按单元分组的形状
cells()——单元名称迭代器
layers()——图层名称迭代器
cell_count() / shape_count()——计数
main_cell_name()——顶层单元名称
flatten——获取/设置层次结构展平

ShapeInfo

由 WriterContext.shapes() 生成的数据类：

layer_name: str——图层名称
cell_name: str——单元名称
vertices: list[tuple]——(x, y) 坐标
is_polygon: bool——多边形还是折线
width: int——折线宽度
is_closed: bool——形状是否闭合

异常

异常	用途
`PluginError`	所有插件错误的基类
`ParseError`	文件解析错误（接受 `line` 和 `path` 关键字参数）
`WriteError`	文件写入错误
`ValidationError`	选项验证错误

TableColumn

用于定义表格选项列的数据类：

key: str——字典键
label: str——列标题
col_type: str——string、integer、real、choice、cell_choice
default: Any——默认值
choices: list[str]——用于 choice 列
decimals: int——用于 real 列
min_value / max_value——用于数值列