插件

所有被认为是非核心功能或用于旧浏览器兼容性的内容都通过插件形式提供。这样做的原因是所有未使用的插件都会被摇树优化（tree-shaken），因此不会最终包含在你的打包文件中。OverlayScrollbars 附带了以下插件：

• ScrollbarsHidingPlugin：对于不支持原生滚动条样式特性的旧浏览器，这个插件是必需的。你可以在这里找到需要此插件的浏览器列表（请注意，尽管 iOS Safari >= 14 被标记为不支持，但你实际上只需要在 iOS < 7.1 中使用此插件）。
• SizeObserverPlugin：对于不支持 ResizeObserver API 的旧浏览器，这个插件是必需的。你可以在这里找到需要此插件的浏览器列表。
• ClickScrollPlugin：如果你想使用选项 scrollbars: { clickScroll: true }。

使用插件

插件的使用方式如下：

import {
  OverlayScrollbars,
  ScrollbarsHidingPlugin,
  SizeObserverPlugin,
  ClickScrollPlugin,
} from "overlayscrollbars";

// 单个插件
OverlayScrollbars.plugin(ScrollbarsHidingPlugin);

// 多个插件
OverlayScrollbars.plugin([SizeObserverPlugin, ClickScrollPlugin]);

插件是仅包含单一字段的普通对象，该字段的名称即为插件的名称。这个名称是插件的标识符，必须在所有插件中唯一。如果有多个插件具有相同的名称，那么后添加的插件会覆盖之前添加的插件。

插件模块

插件模块是插件模块实例的构造器。有两种类型的插件模块：静态插件模块和实例插件模块。单个插件必须有一个或多个模块。插件模块可以返回一个实例，但并非必须这么做。

静态插件模块

当插件通过 OverlayScrollbars.plugin 函数添加时，会调用静态插件模块。

带有静态模块的示例插件：

const staticPlugin = {
  // 插件名称 `examplePlugin`
  examplePlugin: {
    // 静态函数用来描述一个静态模块，它会返回模块实例，如果没有需要实例的情况则返回 void 或 undefined。
    // 这里的 osStatic 参数是指全局的 OverlayScrollbars 对象。
    static: (osStatic) => {
      let count = 0;
      const staticPluginModuleInstance = {
        getCount: () => count,
        increment: () => {
          count++;
        },
      };
      return staticPluginModuleInstance;
    },
  },
};

当插件通过 OverlayScrollbars.plugin 函数添加时，会返回静态模块的实例：

const staticModuleInstance = OverlayScrollbars.plugin(staticPlugin); // 插件的静态模块被调用时
staticModuleInstance.count; // 0
staticModuleInstance.increment();
staticModuleInstance.count; // 1

实例插件模块

在创建新的 OverlayScrollbars 实例时被调用，但在触发 "initialized" 事件之前。

下面是带有实例模块的插件示例：

const instancePlugin = {
  // 插件名称 `examplePlugin`
  examplePlugin: {
    // instance 函数描述了一个实例模块，根据需要返回模块实例，如果不需实例则返回 void 或 undefined
    // `osInstance` 参数是插件绑定到的 OverlayScrollbar 实例
    // `event` 参数是一个函数，用于向实例添加事件，这些事件无法从插件外部移除
    // `osStatic` 参数是全局的 OverlayScrollbar 对象
    instance: (osInstance, event, osStatic) => {
      let count = 0;

      const instancePluginModuleInstance = {
        getCount: () => count,
        increment: () => {
          count++;
        },
      };

      // 实例初始化完成后触发的事件
      event("initialized", () => {
        console.log("instance initialized");
      });

      // 当视口滚动时触发的事件
      const removeScrollEvent = event("scroll", () => {
        console.log("viewport scrolled");
        removeScrollEvent(); // 在首次滚动后移除该事件监听器
      });

      return instancePluginModuleInstance;
    },
  },
};

当插件通过 OverlayScrollbars.plugin 方法添加后，从那一刻起所有新创建的 OverlayScrollbar 实例都将自动添加该插件。而已存在的实例则不会拥有该插件。可以通过 osInstance.plugin 函数获取实例模块的实例：

OverlayScrollbars.plugin(instancePlugin); // 添加插件

const osInstance = OverlayScrollbars(document.body, {}); // 插件的实例模块被调用时
const instancePluginInstance = osInstance.plugin(instancePlugin);

instancePluginInstance.count; // 0
instancePluginInstance.increment();
instancePluginInstance.count; // 1

Typescript

// 描述一个 OverlayScrollbar 插件。
// 参数类型定义：
// - Name: 插件的名称，默认为字符串类型。
// - S: 静态模块的实例类型，默认为 PluginModuleInstance 或 void。
// - I: 实例模块的实例类型，默认为 PluginModuleInstance 或 void。
type Plugin<Name extends string = string, S extends PluginModuleInstance | void = PluginModuleInstance | void, I extends PluginModuleInstance | void = PluginModuleInstance | void> = {
  [pluginName in Name]: PluginModule<S, I>;
};

// 描述仅包含静态模块的 OverlayScrollbar 插件。
// 参数类型定义：
// - Name: 插件的名称，默认为字符串类型。
// - T: 静态模块实例的具体类型，默认为 PluginModuleInstance。
type StaticPlugin<Name extends string = string, T extends PluginModuleInstance = PluginModuleInstance> = Plugin<Name, T, void>;

// 描述仅包含实例模块的 OverlayScrollbar 插件。
// 参数类型定义：
// - Name: 插件的名称，默认为字符串类型。
// - T: 实例模块实例的具体类型，默认为 PluginModuleInstance。
type InstancePlugin<Name extends string = string, T extends PluginModuleInstance = PluginModuleInstance> = Plugin<Name, void, T>;

// 根据传入的静态插件类型推断静态模块实例的类型。
type InferStaticPluginModuleInstance<T extends StaticPlugin<any, any>>;

// 根据传入的实例插件类型推断实例模块实例的类型。
type InferInstancePluginModuleInstance<T extends InstancePlugin<any, any>>;