选项类型

Option 类提供工厂方法，用于定义带类型且可持久化的选项，它们会在工具和格式插件的对话框中生成 UI 控件。

通用参数

所有选项工厂方法都接受以下参数：

参数	类型	说明
`label`	`str`	显示标签（第一个位置参数）
`default`	视类型而定	默认值
`tooltip`	`str`	提示文本
`enabled_when`	`callable`	接收 `self` 并返回 `bool` 的回调——返回 `False` 时控件变灰
`name`	`str`	仅限关键字。覆盖自动生成的选项键

Option.integer()

用于整数值的微调框。

count = Option.integer("Count", default=1, min=0, max=1000)

参数	类型	默认值	说明
`default`	`int`	`0`	默认值
`min`	`int`	`0`	最小值
`max`	`int`	`999999`	最大值

Option.real()

用于浮点值的小数微调框。

scale = Option.real("Scale Factor", default=1.0, min=0.001, max=1e6, decimals=4)

参数	类型	默认值	说明
`default`	`float`	`0.0`	默认值
`min`	`float`	`0.0`	最小值
`max`	`float`	`1e9`	最大值
`decimals`	`int`	`2`	显示的小数位数

Option.boolean()

用于真/假值的复选框。

flatten = Option.boolean("Flatten hierarchy", default=False)

参数	类型	默认值	说明
`default`	`bool`	`False`	默认值

Option.string()

单行文本框。

name = Option.string("Output name", default="output")

参数	类型	默认值	说明
`default`	`str`	`""`	默认值

Option.choice()

下拉选择器。

mode = Option.choice("Mode", choices=["Fast", "Precise", "Custom"], default="Fast")

参数	类型	默认值	说明
`choices`	`list[str]`	必填	可选项
`default`	`str`	第一个选项	默认选择

Option.path()

带浏览按钮的文件路径选择器。

output = Option.path("Output file", file_filter="CSV Files (*.csv)")

参数	类型	默认值	说明
`default`	`str`	`""`	默认路径
`file_filter`	`str`	`"."`	文件类型过滤字符串

Option.color()

颜色选择按钮。

fill = Option.color("Fill color", default="#FF0000")

参数	类型	默认值	说明
`default`	`str`	`"#000000"`	默认颜色（十六进制）

Option.cell_choice()

填充当前图纸所有单元名的下拉列表。

target = Option.cell_choice("Target cell")

参数	类型	默认值	说明
`default`	`str`	`""`	默认单元名

Option.table()

带类型列的可编辑网格。另见面板拼版教程。

entries = Option.table(
    "My Table",
    columns=[
        TableColumn(key="name", label="Name", col_type="string"),
        TableColumn(key="value", label="Value", col_type="real", decimals=3),
    ],
)

参数	类型	默认值	说明
`columns`	`list[TableColumn]`	必填	列定义
`default`	`list[dict]`	`[]`	默认行

取值是一个 list[dict]，每个字典把列键映射到值。

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`	`int\|float`	数值列的最小值
`max_value`	`int\|float`	数值列的最大值

条件可见性

使用 enabled_when 动态启用或禁用选项：

class MyTool(Tool):
    mode = Option.choice("Mode", choices=["Simple", "Advanced"])
    threshold = Option.real(
        "Threshold",
        default=0.5,
        enabled_when=lambda self: self.mode == "Advanced",
    )
    iterations = Option.integer(
        "Iterations",
        default=10,
        enabled_when=lambda self: self.mode == "Advanced",
    )

当 mode 为 “Simple” 时，threshold 和 iterations 字段会变灰。

选项键

每个选项都以字符串键持久化。当 Option 用作类属性时，LinkCAD 会把该键生成为 PyPlugin.<类>.<属性>。保留根 PyPlugin 把插件选项挡在应用程序自身的设置命名空间之外，类名段则把两个都叫 flatten 的插件选项区分开：

class AsciiWriter(FormatWriter):
    flatten = Option.boolean("Flatten hierarchy", default=False)
    # persisted as "PyPlugin.AsciiWriter.flatten"

属性名原样使用，因此键与读取它的 Python 属性拼写一致。每个选项也都可以用该键从命令行设置：

linkcad --PyPlugin.AsciiWriter.flatten=1 ...

传入仅限关键字的 name 参数即可自行指定键：

flatten = Option.boolean("Flatten hierarchy", default=False, name="MyFormatFlatten")

选项值会在调用 run()、read() 或 write() 之前加载到实例上，因此在这些方法内部 self.flatten 就是当前值。直接设置该属性同样有效——正因如此，插件无需打开对话框即可从脚本编辑器驱动。