OverlayScrollbars
中文文档

// 两种初始化方式的结果是一样的
 
OverlayScrollbars(document.querySelector('#myElement'), {});
OverlayScrollbars({ target: document.querySelector('#myElement') }, {});

OverlayScrollbars({
  target: document.querySelector('#target'),
  elements: {
    viewport: document.querySelector('#viewport'),
  },
}, {});

OverlayScrollbars({
  target: document.querySelector('#target'),
  scrollbars: {
    slot: document.querySelector('#target').parentElement,
  },
}, {});

OverlayScrollbars({
  target: document.querySelector('#target'),
  cancel: {
    nativeScrollbarsOverlaid: true,
    body: null,
  }
}, {});

const defaultOptions = {
  paddingAbsolute: false,
  showNativeOverlaidScrollbars: false,
  update: {
    elementEvents: [['img', 'load']],
    debounce: [0, 33],
    attributes: null,
    ignoreMutation: null,
  },
  overflow: {
    x: 'scroll',
    y: 'scroll',
  },
  scrollbars: {
    theme: 'os-theme-dark',
    visibility: 'auto',
    autoHide: 'never',
    autoHideDelay: 1300,
    autoHideSuspend: false,
    dragScroll: true,
    clickScroll: false,
    pointers: ['mouse', 'touch', 'pen'],
  },
};

// OverlayScrollbars 实例的配置选项。
type Options = {
  // 是否使用绝对定位的内边距。
  paddingAbsolute: boolean;
  // 是否显示原生滚动条。仅当原生滚动条被叠加时有效。
  showNativeOverlaidScrollbars: boolean;
  // 自定义自动更新行为。
  update: {
    /**
     * 来自指定选择器的元素触发的事件将触发更新。
     * 适用于 MutationObserver 和 ResizeObserver 无法检测的内容变化
     * 例如：图片的 `load` 事件或 `transitionend` / `animationend` 事件。
     */
    elementEvents: Array<[elementSelector: string, eventNames: string]> | null;
    /**
     * 用于检测内容变化的防抖设置。
     * 如果传入元组，可以自定义 `timeout` 和 `maxWait`（毫秒）。
     * 如果仅传入一个数字，则仅自定义 `timeout`。
     *
     * 如果 `timeout` 为 `0`，则仍会有防抖（并且使用 `requestAnimationFrame` 代替 `setTimeout`）。
     */
    debounce: [timeout: number, maxWait: number] | number | null;
    /**
     * 需要观察的 HTML 属性，若这些属性发生变化将触发更新。
     * 基本属性如 `id`、`class`、`style` 等始终会被观察，不需要显式添加。
     */
    attributes: string[] | null;
    // 一个函数，允许忽略某个内容变动，如果不需要忽略任何变动则为 null。
    ignoreMutation: ((mutation: MutationRecord) => any) | null;
  };
  // 自定义每个轴的溢出行为。
  overflow: {
    // 水平 (x) 轴的溢出行为。
    x: OverflowBehavior;
    // 垂直 (y) 轴的溢出行为。
    y: OverflowBehavior;
  };
  // 自定义滚动条的外观。
  scrollbars: {
    // 滚动条的主题。主题值将作为 `class` 添加到实例的所有 `scrollbar` 元素中。
    theme: string | null;
    // 滚动条的可见性行为。
    visibility: ScrollbarsVisibilityBehavior;
    // 滚动条的自动隐藏行为。
    autoHide: ScrollbarsAutoHideBehavior;
    // 滚动条自动隐藏的延迟时间（以毫秒为单位）。
    autoHideDelay: number;
    // 是否暂停滚动条自动隐藏行为，直到发生第一次滚动。
    autoHideSuspend: boolean;
    // 是否可以拖动滚动条滑块来滚动视口。
    dragScroll: boolean;
    // 是否可以点击滚动条轨道来滚动视口。
    clickScroll: ScrollbarsClickScrollBehavior;
    // 支持的指针类型数组。
    pointers: string[] | null;
  };
};
 
// 轴的溢出行为。
type OverflowBehavior =
  // 不允许滚动，内容被裁剪。
  | 'hidden'
  // 不允许滚动，内容不被裁剪。
  | 'visible'
  // 如果有溢出，则允许滚动。
  | 'scroll'
  /**
   * 如果另一轴没有溢出，其行为类似于 `visible`。
   * 如果另一轴有溢出，其行为类似于 `hidden`。
   */
  | 'visible-hidden'
  /**
   * 如果另一轴没有溢出，其行为类似于 `visible`。
   * 如果另一轴有溢出，其行为类似于 `scroll`。
   */
  | 'visible-scroll';
 
// 滚动条的可见性行为。
type ScrollbarsVisibilityBehavior =
  // 滚动条始终可见。
  | 'visible'
  // 滚动条始终隐藏。
  | 'hidden'
  // 只有在发生溢出时，滚动条才会可见。
  | 'auto';
 
// 滚动条的自动隐藏行为。
type ScrollbarsAutoHideBehavior =
  // 滚动条永不自动隐藏。
  | 'never'
  // 滚动条在用户滚动时才会显示。
  | 'scroll'
  // 滚动条在鼠标移动到宿主元素或用户滚动时才会显示。
  | 'move'
  // 滚动条在鼠标离开宿主元素或用户未滚动时隐藏。
  | 'leave';
 
// 滚动条点击滚动行为。
type ScrollbarsClickScrollBehavior = boolean | 'instant';

// 事件名称与其监听器参数之间的映射
type EventListenerArgs = {
  // 在所有元素初始化并添加后触发
  initialized: [instance: OverlayScrollbars];
  // 在更新后触发
  updated: [instance: OverlayScrollbars, onUpdatedArgs: OnUpdatedEventListenerArgs];
  // 在所有元素、观察者和事件销毁后触发
  destroyed: [instance: OverlayScrollbars, canceled: boolean];
  // 在滚动时触发
  scroll: [instance: OverlayScrollbars, event: Event];
};
 
interface OnUpdatedEventListenerArgs {
  // 描述 DOM 中发生了哪些变化的提示信息
  updateHints: {
    // 主机元素的大小是否发生了变化
    sizeChanged: boolean;
    // 主机元素的方向是否发生了变化
    directionChanged: boolean;
    // 主机元素的内在高度行为是否发生了变化
    heightIntrinsicChanged: boolean;
    // 视口元素的溢出边缘（clientWidth / clientHeight）是否发生了变化
    overflowEdgeChanged: boolean;
    // 溢出量是否发生了变化
    overflowAmountChanged: boolean;
    // 溢出样式是否发生了变化
    overflowStyleChanged: boolean;
    // 滚动坐标是否发生了变化
    scrollCoordinatesChanged: boolean;
    // 主机元素是否发生了变动
    hostMutation: boolean;
    // 内容是否发生了变动
    contentMutation: boolean;
  };
  // 变化的选项
  changedOptions: PartialOptions;
  // 是否是强制更新，且缓存被无效化
  force: boolean;
}

// 简化版的 OverlayScrollbars TypeScript 接口。
interface OverlayScrollbars {
  // 获取实例的当前选项。
  options(): Options;
  // 设置实例的当前选项。
  options(newOptions: PartialOptions, pure?: boolean): Options;
 
  // 为实例添加事件监听器。
  on(eventListeners: EventListeners, pure?: boolean): () => void;
  // 为实例添加单个事件监听器。
  on<N extends keyof EventListenerArgs>(name: N, listener: EventListener<N>): () => void;
  // 为实例添加多个事件监听器。
  on<N extends keyof EventListenerArgs>(name: N, listener: EventListener<N>[]): () => void;
 
  // 从实例中移除单个事件监听器。
  off<N extends keyof EventListenerArgs>(name: N, listener: EventListener<N>): void;
  // 从实例中移除多个事件监听器。
  off<N extends keyof EventListenerArgs>(name: N, listener: EventListener<N>[]): void;
 
  // 更新实例。
  update(force?: boolean): boolean;
 
  // 获取实例的状态。
  state(): State;
 
  // 获取实例的元素。
  elements(): Elements;
 
  // 销毁实例并移除所有已添加的元素。
  destroy(): void;
 
  // 获取传入插件的实例模块。
  plugin<P extends InstancePlugin>(osPlugin: P): InferInstancePluginModuleInstance<P> | undefined;
}
 
// 描述 OverlayScrollbars 实例的状态。
interface State {
  // 当前的内边距（单位：像素）。
  padding: TRBL;
  // 当前的内边距是否是绝对定位。
  paddingAbsolute: boolean;
  // 视口的客户端宽度（x）和高度（y）（单位：像素）。
  overflowEdge: XY<number>;
  // 溢出量（单位：像素）。
  overflowAmount: XY<number>;
  // 视口的 CSS 溢出样式。
  overflowStyle: XY<OverflowStyle>;
  // 视口是否有溢出。
  hasOverflow: XY<boolean>;
  // 视口的滚动坐标。
  scrollCoordinates: {
    // 每个轴的起始（原点）滚动坐标。
    start: XY<number>;
    // 每个轴的结束滚动坐标。
    end: XY<number>;
  };
  // 方向是否被视为右到左（rtl）。
  directionRTL: boolean;
  // 实例是否被视为销毁。
  destroyed: boolean;
}
 
// 描述 OverlayScrollbars 实例的元素。
interface Elements {
  // 应用实例的目标元素。
  target: HTMLElement;
  // 主机元素。它是所有其他元素的根元素。
  host: HTMLElement;
  /**
   * 负责正确内边距的元素。
   * 根据初始化，它可能与视口元素相同。
   */
  padding: HTMLElement;
  // 负责滚动的元素。
  viewport: HTMLElement;
  /**
   * 负责持有实际内容的元素。
   * 根据初始化，它可能与视口元素相同。
   */
  content: HTMLElement;
  /**
   * 通过该元素可以获取当前的 `scrollLeft` 或 `scrollTop` 偏移。
   * 根据目标元素，它可能与视口元素相同。
   */
  scrollOffsetElement: HTMLElement;
  /**
   * 通过该元素可以添加 `scroll` 事件。
   * 根据目标元素，它可能与视口元素相同。
   */
  scrollEventElement: HTMLElement | Document;
  // 水平滚动条的元素。
  scrollbarHorizontal: CloneableScrollbarElements;
  // 垂直滚动条的元素。
  scrollbarVertical: CloneableScrollbarElements;
}

// OverlayScrollbars 静态对象
interface OverlayScrollbarsStatic {
  // 获取传入目标的实例，如果目标没有实例则返回 `undefined`。
  (target: InitializationTarget): OverlayScrollbars | undefined;
  // 使用传入的目标、选项和事件监听器初始化 OverlayScrollbars。
  (target: InitializationTarget, options: PartialOptions, eventListeners?: EventListeners): OverlayScrollbars;
 
  // 检查传入的值是否为有效且未销毁的 OverlayScrollbars 实例。
  valid(osInstance: any): osInstance is OverlayScrollbars;
 
  // 获取环境信息。
  env(): Environment;
 
  // 设置内联样式的 `nonce` 属性。
  nonce(newNonce: string | undefined): void;
 
  // 添加单个插件。
  plugin(plugin: Plugin): InferStaticPluginModuleInstance<Plugin>;
  // 添加多个插件。
  plugin(plugins: Plugin[]): InferStaticPluginModuleInstance<Plugin>[];
}
 
// 描述 OverlayScrollbars 环境。
interface Environment {
  // 浏览器/系统的原生滚动条大小。
  scrollbarsSize: XY<number>;
  // 原生滚动条是否为叠加式。
  scrollbarsOverlaid: XY<boolean>;
  // 浏览器是否支持原生滚动条隐藏。
  scrollbarsHiding: boolean;
  // 浏览器是否支持 ScrollTimeline API。
  scrollTimeline: boolean;
  // 如果没有其他指定，默认初始化方式。
  staticDefaultInitialization: Initialization;
  // 如果没有其他指定，默认选项。
  staticDefaultOptions: Options;
 
  // 返回当前默认初始化方式。
  getDefaultInitialization(): Initialization;
  // 返回当前默认选项。
  getDefaultOptions(): Options;
 
  /**
   * 设置新的默认初始化方式。
   * 如果新的默认初始化方式为部分填充，将与当前默认初始化方式进行深度合并。
   * @param newDefaultInitialization 新的默认初始化方式。
   * @returns 当前默认初始化方式。
   */
  setDefaultInitialization(newDefaultInitialization: PartialInitialization): Initialization;
 
  /**
   * 设置新的默认选项。
   * 如果新的默认选项为部分填充，将与当前默认选项进行深度合并。
   * @param newDefaultOptions 新的默认选项。
   * @returns 当前默认选项。
   */
  setDefaultOptions(newDefaultOptions: PartialOptions): Options;
}

.os-scrollbar {
  // 滚动条的大小
  --os-size: 0;
  // 滚动条的轴垂直内边距（水平：padding-y，垂直：padding-x）
  --os-padding-perpendicular: 0;
  // 滚动条的轴内边距（水平：padding-x，垂直：padding-y）
  --os-padding-axis: 0;
  // 滚动条轨道的边框半径
  --os-track-border-radius: 0;
  // 滚动条轨道的背景
  --os-track-bg: none;
  // 滚动条轨道的 :hover 背景
  --os-track-bg-hover: none;
  // 滚动条轨道的 :active 背景
  --os-track-bg-active: none;
  // 滚动条轨道的边框
  --os-track-border: none;
  // 滚动条轨道的 :hover 边框
  --os-track-border-hover: none;
  // 滚动条轨道的 :active 边框
  --os-track-border-active: none;
  // 滚动条滑块的边框半径
  --os-handle-border-radius: 0;
  // 滚动条滑块的背景
  --os-handle-bg: none;
  // 滚动条滑块的 :hover 背景
  --os-handle-bg-hover: none;
  // 滚动条滑块的 :active 背景
  --os-handle-bg-active: none;
  // 滚动条滑块的边框
  --os-handle-border: none;
  // 滚动条滑块的 :hover 边框
  --os-handle-border-hover: none;
  // 滚动条滑块的 :active 边框
  --os-handle-border-active: none;
  // 滚动条滑块的最小尺寸
  --os-handle-min-size: 33px;
  // 滚动条滑块的最大尺寸
  --os-handle-max-size: none;
  // 滚动条滑块的轴垂直尺寸（水平：高度，垂直：宽度）
  --os-handle-perpendicular-size: 100%;
  // 滚动条滑块的 :hover 轴垂直尺寸（水平：高度，垂直：宽度）
  --os-handle-perpendicular-size-hover: 100%;
  // 滚动条滑块的 :active 轴垂直尺寸（水平：高度，垂直：宽度）
  --os-handle-perpendicular-size-active: 100%;
  // 增加滚动条滑块的交互区域。
  --os-handle-interactive-area-offset: 0;
}

// 水平和垂直滚动条的大小均为 10px
.os-theme-custom {
  --os-size: 10px;
}
 
// 水平滚动条的大小为 10px
.os-theme-custom.os-scrollbar-horizontal {
  --os-size: 10px;
}
 
// 垂直滚动条的大小为 20px
.os-theme-custom.os-scrollbar-vertical {
  --os-size: 20px;
}

OverlayScrollbars(document.body, {
  scrollbars: {
    theme: 'os-theme-custom'
  }
});

<div class="os-scrollbar os-scrollbar-horizontal">
    <div class="os-scrollbar-track">
        <div class="os-scrollbar-handle">
        </div>
    </div>
</div>
<div class="os-scrollbar os-scrollbar-vertical">
    <div class="os-scrollbar-track">
        <div class="os-scrollbar-handle">
        </div>
    </div>
</div>

const staticPlugin = {
  // 插件名称为 `examplePlugin`。
  examplePlugin: {
    // `static` 函数描述了一个静态模块，并返回模块实例，或者如果不需要实例则返回 `void` 或 `undefined`。
    // `osStatic` 参数是全局的 `OverlayScrollbars` 对象。
    static: (osStatic) => {
      let count = 0;
      const staticPluginModuleInstance = {
        getCount: () => count,
        increment: () => { count++ },
      }
      return staticPluginModuleInstance;
    }
  }
}

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

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("实例已初始化");
      });
 
      // 视口滚动时触发的事件。
      const removeScrollEvent = event('scroll', () => {
        console.log("视口已滚动");
        removeScrollEvent(); // 滚动后移除事件。
      });
 
      return instancePluginModuleInstance;
    }
  }
}

OverlayScrollbars.plugin(instancePlugin); // 插件被添加
 
const osInstance = OverlayScrollbars(document.body, {}); // 插件的实例模块被调用
const instancePluginInstance = osInstance.plugin(instancePlugin);
 
instancePluginInstance.count; // 0
instancePluginInstance.increment();
instancePluginInstance.count; // 1

// 描述一个 OverlayScrollbar 插件。
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 插件。
type StaticPlugin<
  Name extends string = string,
  T extends PluginModuleInstance = PluginModuleInstance
> = Plugin<Name, T, void>;
 
// 描述一个只有实例模块的 OverlayScrollbar 插件。
type InstancePlugin<
  Name extends string = string,
  T extends PluginModuleInstance = PluginModuleInstance
> = Plugin<Name, void, T>;
 
// 推断传入插件的静态模块实例类型。
type InferStaticPluginModuleInstance<T extends StaticPlugin>;
 
// 推断传入插件的实例模块实例类型。
type InferInstancePluginModuleInstance<T extends InstancePlugin>;

const { viewport } = osInstance.elements();
const { scrollLeft, scrollTop } = viewport; // 获取滚动偏移
viewport.scrollTo({ top: 0 }); // 设置滚动偏移

/* 水平边界 */
.os-scrollbar-horizontal .os-scrollbar-handle {
  min-width: 50px;
  max-width: 200px;
}
/* 垂直边界 */
.os-scrollbar-vertical .os-scrollbar-handle {
  min-height: 40px;
  max-height: 40px;
}