mirror of
https://github.com/EstrellaXD/Auto_Bangumi.git
synced 2026-10-30 04:06:04 +08:00
776abfa896
- API 参考按实际路由重写，修正认证方式、请求方法与设置向导端点 - 数据库指南改为异步 Database 与 MIGRATIONS - E2E 指南改为指向 e2e/README.md - 插件快速上手补上安装 SDK 轮子的步骤，ab-plugin dev 加 --config-dir - 发布流程改为手动推送标签触发
53 lines
2.5 KiB
Markdown
53 lines
2.5 KiB
Markdown
# 配置表单
|
||
|
||
插件声明 `config_model`（pydantic 模型），WebUI 在 设置 → 插件 里据此自动生成表单，插件作者不需要写前端。
|
||
|
||
```python
|
||
from pydantic import BaseModel, Field
|
||
from ab_sdk import Plugin, secret_field
|
||
|
||
class Options(BaseModel):
|
||
endpoint: str = Field("https://push.example.com", title="推送地址")
|
||
key: str = secret_field(description="推送密钥")
|
||
retries: int = Field(3, ge=0, le=10, title="重试次数")
|
||
|
||
class MyPlugin(Plugin[Options]):
|
||
config_model = Options
|
||
```
|
||
|
||
## 字段类型
|
||
|
||
| Python 类型 | 表单控件 |
|
||
| --- | --- |
|
||
| `str` | 文本框 |
|
||
| `secret_field()` 声明的 `str` | 密码框 |
|
||
| `int` / `float` | 数字框（`int` 输入后取整） |
|
||
| `bool` | 开关 |
|
||
| `Literal[...]` / `Enum` | 下拉框 |
|
||
| `list[str]` | 标签输入 |
|
||
| `list[<BaseModel>]` | 对象数组：每行一组子字段，可添加和删除行 |
|
||
| 其它（`dict`、嵌套对象） | 显示为「不支持的字段」，请直接编辑 `config.json` |
|
||
|
||
`Field(title=..., description=...)` 成为标签和说明文字。`Optional[T]` 按 `T` 渲染。默认值用于未保存过的字段。
|
||
|
||
## 校验
|
||
|
||
- 保存时 AB 用模型校验。不合法的值返回 HTTP 422，不会写入配置。
|
||
- 在 `field_validator` 里做深度校验：例如内置的 `rename` 在保存时试渲染模板，写错的模板当场被拒绝。
|
||
- 没有默认值的必填字段在首次启用时缺失，插件进入错误状态。用户填写并保存后，插件自动恢复。
|
||
- 未启用的插件也显示表单：AB 导入可信插件的代码，只读取 `config_model`，不调用 `setup`。尚未开启「允许未签名插件」的本地插件不执行任何代码，也就没有表单。
|
||
|
||
## 秘密字段
|
||
|
||
`secret_field()` 声明密码、令牌、Cookie 等。
|
||
|
||
- WebUI 以密码框渲染。
|
||
- 读取配置的接口只返回掩码。浏览器永远拿不到原值。
|
||
- 保存时收到掩码，AB 保留原值。掩码处理覆盖嵌套结构，对象数组行里的秘密字段也会掩码。数组行数被改变而无法对应原行时，该秘密字段被清空，需要用户重新输入。
|
||
|
||
配置保存在 `config.json` 的 `plugins.options.<插件 id>` 下，启用开关在 `plugins.enabled.<插件 id>`。
|
||
|
||
## 超出表单的界面
|
||
|
||
表单满足不了时（图表、操作按钮、列表），插件可以提供前端组件，见 [前端挂载点](/dev/plugins/frontend-slots)。内置 `hardlink` 的「链接已有文件」按钮就是一个 `settings.section` 组件。
|