From daf93fb72cb5f1cdbd1fcb9c21958a30e75f1d2f Mon Sep 17 00:00:00 2001
From: guqing <38999863+guqing@users.noreply.github.com>
Date: Tue, 2 Jul 2024 12:51:23 +0800
Subject: [PATCH] docs: add docs for check plugin availability by version
 (#383)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

### What this PR does?
添加插件 Finder API 中通过插件名称和版本判断某插件是否可用的 API 的文档

see also https://github.com/halo-dev/halo/pull/6236

```release-note
None
```
---
 .../theme/finder-apis/plugin.md               | 30 +++++++++++++++++++
 .../theme/finder-apis/plugin.md               | 30 +++++++++++++++++++
 2 files changed, 60 insertions(+)

diff --git a/docs/developer-guide/theme/finder-apis/plugin.md b/docs/developer-guide/theme/finder-apis/plugin.md
index a77ec2d..8585e58 100644
--- a/docs/developer-guide/theme/finder-apis/plugin.md
+++ b/docs/developer-guide/theme/finder-apis/plugin.md
@@ -31,3 +31,33 @@ pluginFinder.available(pluginName)
   </a>
 </li>
 ```
+
+## available(pluginName, requiresVersion)
+
+```js
+pluginFinder.available('fake-plugin', '>=2.3.0')
+```
+
+### 描述
+
+判断一个插件是否可用，会同时判断插件是否安装和启用且插件的版本符合 `requiresVersion` 要求，
+
+### 参数
+
+1. `pluginName:string` - 插件的唯一标识 `metadata.name`，不能为空。
+2. `requiresVersion:string` - 插件的版本要求，不能为空，例如：`>1.2.0`，`requiresVersion` 的格式遵循 [Semantic Range Expressions](https://github.com/zafarkhaja/jsemver#range-expressions)。
+
+### 返回值
+
+`boolean` - 插件是否可用
+
+### 示例
+
+```html
+<!-- https://github.com/halo-sigs/plugin-search-widget -->
+<li th:if="${pluginFinder.available('PluginSearchWidget', '>=2.3.0')}">
+  <a href="javascript:SearchWidget.open()" title="搜索">
+    搜索
+  </a>
+</li>
+```
diff --git a/versioned_docs/version-2.17/developer-guide/theme/finder-apis/plugin.md b/versioned_docs/version-2.17/developer-guide/theme/finder-apis/plugin.md
index a77ec2d..8585e58 100644
--- a/versioned_docs/version-2.17/developer-guide/theme/finder-apis/plugin.md
+++ b/versioned_docs/version-2.17/developer-guide/theme/finder-apis/plugin.md
@@ -31,3 +31,33 @@ pluginFinder.available(pluginName)
   </a>
 </li>
 ```
+
+## available(pluginName, requiresVersion)
+
+```js
+pluginFinder.available('fake-plugin', '>=2.3.0')
+```
+
+### 描述
+
+判断一个插件是否可用，会同时判断插件是否安装和启用且插件的版本符合 `requiresVersion` 要求，
+
+### 参数
+
+1. `pluginName:string` - 插件的唯一标识 `metadata.name`，不能为空。
+2. `requiresVersion:string` - 插件的版本要求，不能为空，例如：`>1.2.0`，`requiresVersion` 的格式遵循 [Semantic Range Expressions](https://github.com/zafarkhaja/jsemver#range-expressions)。
+
+### 返回值
+
+`boolean` - 插件是否可用
+
+### 示例
+
+```html
+<!-- https://github.com/halo-sigs/plugin-search-widget -->
+<li th:if="${pluginFinder.available('PluginSearchWidget', '>=2.3.0')}">
+  <a href="javascript:SearchWidget.open()" title="搜索">
+    搜索
+  </a>
+</li>
+```