Resize Observer Directive

v-tui-resize is a high-performance size monitoring directive provided by TechUI. It is based on the browser's native ResizeObserver API and can capture changes in an element's width and height in real-time. Compared to using the native API directly, this directive provides a more convenient declarative syntax, automatically handles the mounting and destruction of listeners, and has a built-in throttling mechanism to optimize performance.

Core Features

• Declarative Call: No need to manually instantiate ResizeObserver; bind directly in the template.
• Performance Optimization: Built-in duration configuration to prevent page stuttering caused by high-frequency triggering (default 200ms).
• Dynamic Control: Supports dynamically enabling or pausing monitoring via the disabled property.
• Automatic Destruction: Automatically disconnects observation when the component is unmounted to prevent memory leaks.

Basic Usage

Simple Mode (Callback Only)

If you only need to monitor changes without extra configuration, you can pass a callback function directly. The callback function will receive an object containing { width, height }.

<script setup>
const handleResize = ({ width, height }) => {
  console.log('Current size:', width, height);
};
</script>

<template>
  <div class="box" v-tui-resize="handleResize">
    Resize Me
  </div>
</template>

Configuration Mode (Object Parameters)

By passing an object, you can configure throttle time, disabled state, or component ID.

<template>
  <div 
    class="chart-container"
    v-tui-resize="{ 
      callback: updateChart, 
      duration: 500,       // Set a throttle delay of 500ms
      disabled: isHidden   // Stop monitoring when element is hidden to save resources
    }"
  >
    </div>
</template>

API Reference

v-tui-resize accepts a Function or an Object. When an object is passed, it supports the following properties:

Parameter Name	Description	Type	Default
callback	Callback Function. Triggered when size changes; parameter is { width, height }.	Function	—
disabled	Disable Switch. When set to true, the listener will be disconnected. Supports dynamic switching.	Boolean	false
duration	Throttle Time. The minimum interval (ms) between two callback triggers, used to reduce high-frequency rendering overhead.	Number	200
uid	Unique Identifier. Used by the internal tResize utility library to distinguish instances; usually generated automatically.	String	genUid('vResize')
cid	Component ID. Used for component validity verification (cidVaild) within the TechUI core system.	String	—

Typical Cases

Adaptive Container

In TechUI's large-screen adaptation solution, it is necessary to monitor container size changes to calculate the scaling ratio. Here, uid is used to ensure instance uniqueness.

<template>
  <div 
    id="tuiAdpt" 
    class="tui-adpt-container"
    v-tui-resize="{ 
      callback: adptResizeCounter, 
      uid: 'adpt-main-observer' 
    }"
  >
    </div>
</template>

Scroll Update

In custom scrollbar components, when the content area size changes (e.g., more data is loaded), the scrollbar length needs to be recalculated. Via the dynamic disabled property, observation can be paused when monitoring is not needed (e.g., when initialization is incomplete).

<template>
  <div
    class="tui-scroller-outer"
    v-tui-resize="{
      callback: initSize,           // Reset scrollbar when size changes
      disabled: !inited,            // Do not listen before initialization
      duration: 100                 // Improve response speed
    }" 
  >
    </div>
</template>

Technical Details

Lifecycle Management

• Mounted: Parses configuration, creates uid, and calls tResize.o (Observe) to start monitoring if not disabled.
• Updated: Compares old and new disabled states. If changing from false to true, calls tResize.d (Disconnect) to stop monitoring; otherwise, reconnects.
• Unmounted: Forcibly calls stopResize to clear all observers, ensuring no residue.

Dependencies

This directive depends on TechUI's utility library:

import { tResize, genUid, tType } from "@techui/utils";

• tResize: A core utility class encapsulating ResizeObserver, responsible for handling specific DOM observations and callback dispatching.
• genUid: Generates unique IDs.