mirror of
https://github.com/EstrellaXD/Auto_Bangumi.git
synced 2026-10-30 12:14:27 +08:00
3258fcca4b
- docs/dev/plugins.md 改为总览与导航，旧内容拆入 docs/dev/plugins/ - 新增核心概念、配置表单、事件、前端挂载点、命令行、签名与分发、内置插件、示例页 - 每个扩展点一页，侧边栏由页面表生成 - 改正旧文档中下载器配置、hardlink path_map 与补链按钮的过时描述
53 lines
3.7 KiB
Markdown
53 lines
3.7 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>]` | オブジェクトの配列：1 行ごとにサブフィールドの組。行の追加と削除ができます |
|
||
| その他（`dict`、入れ子のオブジェクト） | 「未対応のフィールド」と表示されます。`config.json` を直接編集してください |
|
||
|
||
`Field(title=..., description=...)` はラベルと説明文になります。`Optional[T]` は `T` として描画されます。保存されていないフィールドには既定値が入ります。
|
||
|
||
## 検証
|
||
|
||
- 保存時に AB がモデルで検証します。不正な値には HTTP 422 を返し、設定には書き込みません。
|
||
- 詳しい検証は `field_validator` で行います。たとえば、組み込みの `rename` は保存時にテンプレートを一度描画します。間違ったテンプレートはその場で拒否されます。
|
||
- 既定値のない必須フィールドは、初回の有効化時に未設定です。このときプラグインはエラー状態になります。ユーザーが入力して保存すると、プラグインは自動で復旧します。
|
||
- 無効なプラグインでもフォームは表示されます。AB は信頼済みのプラグインのコードを import し、`config_model` だけを読みます。`setup` は呼びません。まだ許可されていないローカルプラグイン（未署名で「未署名プラグインを許可」がオフ）はコードを実行しないため、フォームもありません。
|
||
|
||
## 秘密フィールド
|
||
|
||
`secret_field()` はパスワード、トークン、Cookie などを宣言します。
|
||
|
||
- WebUI はパスワードボックスで表示します。
|
||
- 設定を読み取る API はマスクだけを返します。ブラウザが元の値を受け取ることはありません。
|
||
- 保存時にマスクを受け取ると、AB は元の値を保持します。マスク処理は入れ子の構造にも働き、オブジェクト配列の行の中の秘密フィールドも対象です。行数が変わって元の行と対応付けられない場合、その秘密フィールドは空になり、ユーザーが再入力します。
|
||
|
||
設定は `config.json` の `plugins.options.<プラグイン id>` に保存されます。有効化スイッチは `plugins.enabled.<プラグイン id>` です。
|
||
|
||
## フォームを超える UI
|
||
|
||
フォームで足りない場合（グラフ、操作ボタン、一覧）は、プラグインがフロントエンドコンポーネントを提供できます。[フロントエンドスロット](/ja/dev/plugins/frontend-slots) を参照してください。組み込みの `hardlink` の「既存ファイルをリンク」ボタンは `settings.section` のコンポーネントです。
|