第27章 UI 插件 API 详解：属性、路由注册与组件管理
UI 插件 API¶
PluginApi 对象是 window 对象中的一个全局对象。
PluginApi 目前仍处于实验阶段，随时可能在不另行通知的情况下发生变更。本文档仅涵盖插件专用的 API，不一定包含核心 UI API，相关方法请参考 UI 源代码。
关于 PluginApi 各方面用法的示例，可查看源代码中 pkg/plugin/examples/react-component 目录。
属性（Properties）¶
React
React 库的实例。
ReactDOM
ReactDOM 库的实例。
GQL
该命名空间包含自动生成的 graphql 客户端接口，属于底层接口。多数情况下应改用 StashService。
libraries
libraries 提供对以下 UI 库的访问：
ReactRouterDOM Bootstrap Apollo Intl FontAwesomeRegular FontAwesomeSolid FontAwesomeBrands Mousetrap MousetrapPause ReactFontAwesome ReactSelect
register
该命名空间包含用于注册页面路由和组件的方法。
PluginApi.register.route
在 React Router 中注册一个路由。
参数 类型 说明
path string 要注册的路径，通常应使用 /plugin/ 前缀。
component React.FC 路由加载时渲染的 React 函数组件。
返回 void。
PluginApi.register.component
注册一个供插件使用的组件，注册后可在 components 命名空间中使用。
参数 类型 说明
name string 要注册的组件名称，必须唯一，建议以 plugin- 作为前缀。
component React.FC 一个 React 函数组件。
返回 void。
components
该命名空间包含插件可用的所有组件，包括部分核心组件以及通过 PluginApi.register.component 注册的组件。
utils
该命名空间提供对 NavUtils、StashService 和 InteractiveUtils 命名空间的访问，还提供 loadComponents 方法。
PluginApi.utils.loadComponents
由于采用了代码分割，插件页面渲染时部分组件可能尚未加载。loadComponents 会加载插件页面可能需要的所有组件。
通常应改用 PluginApi.hooks.useLoadComponents hook。
参数 类型 说明
components Promise[] 要加载的组件列表，这些值应来自 PluginApi.loadableComponents 命名空间。
返回一个 Promise
PluginApi.utils.InteractiveUtils
该命名空间提供对 interactiveClientProvider 和 getPlayer 的访问： - getPlayer 返回当前的 videojs 播放器对象 - interactiveClientProvider 接收 IInteractiveClientProvider，让开发者能够介入 funscript 的生命周期 export interface IDeviceSettings { connectionKey: string; scriptOffset: number; estimatedServerTimeOffset?: number; useStashHostedFunscript?: boolean; [key: string]: unknown; }
export interface IInteractiveClientProviderOptions { handyKey: string; scriptOffset: number; defaultClientProvider?: IInteractiveClientProvider; stashConfig?: GQL.ConfigDataFragment; } export interface IInteractiveClientProvider { (options: IInteractiveClientProviderOptions): IInteractiveClient; }
/
* Interface that is used for InteractiveProvider
*/
export interface IInteractiveClient {
connect(): Promise
示例¶
比如我想在 IInteractiveClient.connect() 被调用时添加额外的日志。
在我的插件中，可以像下面这样安装自己的客户端 provider：
InteractiveUtils.interactiveClientProvider = ( opts ) => { if (!opts.defaultClientProvider) { throw new Error('invalid setup'); }
const client = opts.defaultClientProvider(opts); const connect = client.connect; client.connect = async () => { console.log('patching connect method'); return connect.call(client); };
return client; };
hooks
该命名空间提供对以下核心工具 hooks 的访问：
useGalleryLightbox useLightbox useSpriteInfo useToast
此外还提供若干插件专用的 hooks。
PluginApi.hooks.useLoadComponents
这是一个用于加载组件的 hook，内部使用 PluginApi.utils.loadComponents 方法。
参数 类型 说明
components Promise[] 要加载的组件列表，这些值应来自 PluginApi.loadableComponents 命名空间。
返回一个布尔值，组件正在加载时为 true。
loadableComponents
该命名空间包含所有可能需要通过 loadComponents 方法加载的组件。组件会按需加入该命名空间。如果所需的组件不在其中，请提交开发请求。
该命名空间还包含官方 UI 中所有懒加载 import 的粗粒度条目。如果页面加载时某个组件不在 components 中，可以通过粗粒度条目来加载。例如，PerformerCard 可以通过 loadableComponents.Performers 加载。
patch
该命名空间提供修补（patch）组件以改变其行为的方法。
PluginApi.patch.before
注册一个 before 函数。before 函数会在组件的 render 函数调用之前执行，它接收与组件 render 函数相同的参数，并应返回一个新参数列表，供后续传给 render。
参数 类型 说明
component string 要修补的组件名称。
fn Function before 函数。它接收与组件 render 函数相同的参数，并应返回传给 render 函数的参数列表。
返回 void。
PluginApi.patch.instead
为组件注册一个替换函数。该函数会接收传给原 render 函数的参数，最后一个参数是 next render 函数。替换函数按注册顺序依次调用。如果某个替换函数没有调用 next render 函数，则后续的替换函数将不会被调用或应用。
参数 类型 说明
component string 要修补的组件名称。
fn Function 替换函数。它接收与原 render 函数相同的参数，外加 next render 函数，并应返回替换后的组件。
返回 void。
PluginApi.patch.after
注册一个 after 函数。after 函数会在组件的 render 函数执行之后调用，它接收传给原 render 函数的参数以及原 render 函数的返回结果，并应返回最终渲染的组件。
参数 类型 说明
component string 要修补的组件名称。
fn Function after 函数。它接收与原 render 函数相同的参数，外加原 render 函数的返回结果，并应返回渲染后的组件。
返回 void。
可修补的组件和函数（Patchable components and functions）¶
AlertModal App BackgroundImage BooleanSetting ChangeButtonSetting CompressedPerformerDetailsPanel ConstantSetting CountrySelect CustomFieldInput CustomFields CustomFieldsInput DateInput DetailImage ExternalLinkButtons ExternalLinksButton FilteredGalleryList FilteredGroupList FilteredImageList FilteredPerformerList FilteredSceneList FilteredSceneMarkerList FilteredStudioList FilteredTagList FolderSelect FrontPage GalleryCard GalleryCard.Details GalleryCard.Image GalleryCard.Overlays GalleryCard.Popovers GalleryCardGrid GalleryIDSelect GalleryList GalleryRecommendationRow GallerySelect GallerySelect.sort GridCard GroupCard GroupCardGrid GroupIDSelect GroupList GroupRecommendationRow GroupSelect GroupSelect.sort HeaderImage HoverPopover Icon ImageCard ImageCard.Details ImageCard.Image ImageCard.Overlays ImageCard.Popovers ImageDetailPanel ImageGridCard ImageInput ImageList ImageRecommendationRow LightboxLink LoadingIndicator MainNavBar.MenuItems MainNavBar.UtilityItems ModalSetting NumberSetting Pagination PaginationIndex PerformerAppearsWithPanel PerformerCard PerformerCard.Details PerformerCard.Image PerformerCard.Overlays PerformerCard.Popovers PerformerCard.Title PerformerCardGrid PerformerDetailsPanel PerformerDetailsPanel.DetailGroup PerformerGalleriesPanel PerformerGroupsPanel PerformerHeaderImage PerformerIDSelect PerformerImagesPanel PerformerList PerformerPage PerformerRecommendationRow PerformerScenesPanel PerformerSelect PerformerSelect.sort PluginRoutes PluginSettings RatingNumber RatingStars RatingSystem RecommendationRow SceneCard SceneCard.Details SceneCard.Image SceneCard.Overlays SceneCard.Popovers SceneCard.SceneSpecs SceneCardsGrid SceneFileInfoPanel SceneIDSelect SceneMarkerCard SceneMarkerCard.Details SceneMarkerCard.Image SceneMarkerCard.Popovers SceneMarkerCardsGrid SceneMarkerList SceneMarkerRecommendationRow SceneList ScenePage ScenePage.TabContent ScenePage.Tabs ScenePlayer SceneRecommendationRow SceneSelect SceneSelect.sort SelectSetting Setting SettingGroup SettingModal StringListSetting StringSetting StudioCard StudioCardGrid StudioDetailsPanel StudioIDSelect StudioList StudioRecommendationRow StudioSelect StudioSelect.sort SweatDrops TabTitleCounter TagCard TagCard.Details TagCard.Image TagCard.Overlays TagCard.Popovers TagCard.Title TagCardGrid TagIDSelect TagLink TagList TagRecommendationRow TagSelect TagSelect.sort TruncatedText
PluginApi.Event
允许插件监听 Stash 的事件。 PluginApi.Event.addEventListener("stash:location", (e) => console.log("Page Changed", e.detail.data.location.pathname))
