uview-plus Documentation

In WeChat Mini Programs, the u-dragsort component previously suffered from item overlapping after a drag-and-release action. This was caused by the component using array indices for movable-view IDs and event callback parameters during reordering. When the underlying list was spliced, the native node IDs and event closures became desynchronized from the actual data items.

To resolve this, the component now uses a stable identity strategy:

1. Stable IDs: Each movable-view uses a unique ID composed of a component instance prefix and the data item's id (e.g., prefix_itemid), rather than its array index.
2. Visual Order Management: Instead of performing a splice on the primary list during dragging, the component maintains a separate orderIds array to manage the visual sequence. This keeps the rendered native node order stable.
3. Event Integrity: Events like change and touchstart now pass the stable item.id instead of the array index.
4. Coordinate Calculation: The updatePositions logic calculates target coordinates based on the orderIds sequence.

Requirements for Users:

• Ensure every item in your initialList has a unique and stable id property. The component relies on this field to maintain identity during reordering.

Previously, uview-plus used a full props aggregator that statically imported the default configurations of every component. This meant that even if you only used one component, the entire library's prop configuration was loaded into memory.

In the lazy-loading architecture:

1. Shared Store: A central props object is initialized with empty objects for all known component keys (e.g., button, cell, input).
2. Lazy Registration: Each component's props.js file imports its own local default configuration and calls registerComponentProps. This populates the central store only when that specific component is actually used.
3. Deep Merging: When registering props, the system performs a deep merge. If a user has already provided a global configuration via setPropsConfig, the component's local defaults will only fill in the missing fields, preserving the user's overrides.
4. Global Overrides: setPropsConfig uses shallowMerge to apply user-defined settings, which can be done at any time to override existing component defaults.

The up-swipe-action-item component (part of uview-ultra) supports a scrolling state to help prevent unwanted page or container scrolling during swipe gestures.

When a horizontal swipe gesture is active, scrolling is set to true. This allows developers to manually manage scroll-locking on the parent container or page.

Key behaviors:

• scrolling = true indicates an active horizontal swipe gesture.
• The menu's open/closed state does not keep scrolling true; it only tracks the active gesture.
• The component is stateless regarding the parent container; it emits the state, but the user is responsible for binding it to page-meta or a scroll-view to actually implement scroll-locking.

// Example usage for scroll-locking
const swipeScrolling = ref(false);

// In your template
<up-swipe-action-item 
  v-model:scrolling="swipeScrolling"
  @scrolling="handleScrolling"
/>

// Use swipeScrolling to control your scroll-view or page-meta

To optimize bundle size, uview-plus uses a lazy-loading mechanism for component props. Instead of importing a massive global configuration object that includes every component's default props, each component now registers its own props locally.

The Data Flow

1. Initialization: When the app starts via app.use(uviewPlus, upuiParams), any user-provided overrides in upuiParams are written to the global props store via setPropsConfig.
2. Component Loading: When a specific component (e.g., u-button) is used, its local props.js is loaded.
3. Registration: The component calls registerComponentProps(ButtonDefaultProps). This function performs a "fill-in-the-blanks" merge: it takes the component's default values and merges them into the global store only where user overrides do not already exist.
4. Consumption: The component's prop default expressions read from the shared global props object, ensuring that any runtime changes (via setConfig or direct assignment) are reflected in new component instances.

Key Behaviors

• Priority: User configurations (via setConfig or uni.$u.props) always take precedence over component default values.
• Order Independence: Whether you call setConfig before or after a component is loaded, the final merged state remains consistent.
• Runtime Access: You can still access and modify props globally using uni.$u.props.

The inner property in the u-cropper component allows you to constrain the crop box so that it always stays within the boundaries of the image. This is particularly useful for scenarios like avatar cropping where you want to prevent users from including empty/transparent areas in the crop.

Key Behaviors:

• Rotation Disabled: When inner is set to true, rotation (both via gestures and UI buttons) is automatically disabled to ensure the crop box remains aligned with the image boundaries.
• Boundary Clamping: When resizing or moving the crop box, it will be clamped to the image's visible rectangle.
• Default Behavior: The default value is false. Enabling inner does not change the existing drag behavior for standard modes.

<up-cropper
  :inner="true"
  @confirm="cutImage"
  ref="avatarRefInner"
  areaWidth="300rpx"
  areaHeight="300rpx"
  exportWidth="260rpx"
  exportHeight="260rpx"
>
  <!-- slot content -->
</up-cropper>

Starting from version 3.8+, uview-plus uses a three-layer theme system. Understanding these layers is critical for managing styles, especially for the navigation bar and dark mode:

1. theme.json: The declarative default theme entry for uni-app. It is primarily used via @variableName in pages.json for page configurations.
2. --up-* / --u-* CSS Variables: The core layer for component styles, page backgrounds, and semantic colors.
3. Runtime Theme System: Managed via uni.$u.setTheme(), uni.$u.setThemePreference(), or setConfig({ color }). This system handles system synchronization, manual switching, preference memory, and synchronizing native UI elements like the navigation bar, background colors, and tabBar.

Important Note on Priority: While initial default values can come from theme.json, once the uview-plus runtime theme system begins synchronization, the final appearance of the navigation bar, background color, and tabBar is determined by the runtime theme results.

// Example of runtime theme management
uni.$u.setTheme('dark'); // Manually switch to dark mode
uni.$u.setThemePreference('system'); // Follow system settings