Introduction to the official uni-ui component library

uni-ui is an official component library specifically designed for uni-app, providing a rich set of high-quality components to help developers quickly build cross-platform applications. These components are deeply optimized, compatible with multi-terminal runtime environments, and maintain a unified interactive experience and visual style.

Core Advantages of uni-ui

The core advantage of uni-ui lies in its cross-platform adaptation capability. All components undergo multi-terminal testing to ensure consistent performance across iOS, Android, H5, and various mini-program platforms. For example, the uni-popup component automatically adopts native modal dialogs or custom implementations on different platforms:

<uni-popup ref="popup" type="center">
  <view class="popup-content">This is a centered popup</view>
</uni-popup>

<script>
export default {
  methods: {
    showPopup() {
      this.$refs.popup.open()
    }
  }
}
</script>

The component library adopts a modular design and supports on-demand importing. After a simple npm installation, it can be configured globally in pages.json or imported locally in a single page:

// pages.json
{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^uni-(.*)": "@dcloudio/uni-ui/lib/uni-$1/uni-$1.vue"
    }
  }
}

Detailed Explanation of Common Components

Basic Interactive Components

uni-badge is a typical lightweight badge component that supports three styles: numbers, text, and dots. Preset colors can be quickly set via the type attribute:

<uni-badge text="99+" type="error" />
<uni-badge text="NEW" inverted />

uni-swipe-action enables swipe actions for list items, supporting bidirectional swiping. Configuration options include button groups and trigger thresholds:

<uni-swipe-action>
  <uni-swipe-action-item :options="options">
    <view class="list-item">Swipeable List Item</view>
  </uni-swipe-action-item>
</uni-swipe-action>

<script>
export default {
  data() {
    return {
      options: [
        {
          text: 'Delete',
          style: {
            backgroundColor: '#dd524d'
          }
        }
      ]
    }
  }
}
</script>

Enhanced Form Components

The uni-forms component integrates validation functionality, supporting synchronous/asynchronous validation rules. Form fields are wrapped by uni-forms-item, and validation rules are configured via JSON:

<uni-forms :model="formData" :rules="rules" ref="form">
  <uni-forms-item label="Username" name="username">
    <uni-easyinput v-model="formData.username" />
  </uni-forms-item>
</uni-forms>

<script>
export default {
  data() {
    return {
      formData: { username: '' },
      rules: {
        username: {
          rules: [
            { required: true, errorMessage: 'Required field' },
            { minLength: 3, errorMessage: 'At least 3 characters' }
          ]
        }
      }
    }
  }
}
</script>

uni-data-checkbox supports multi-select group mode, with data sources that can be statically defined or dynamically loaded:

<uni-data-checkbox 
  v-model="selected" 
  :localdata="options"
  multiple
/>

Advanced Layout Components

The uni-collapse accordion component supports single or multiple panels expanding simultaneously. The mode can be toggled via the accordion attribute:

<uni-collapse accordion>
  <uni-collapse-item title="Title 1">
    <text>Content Area 1</text>
  </uni-collapse-item>
  <uni-collapse-item title="Title 2">
    <text>Content Area 2</text>
  </uni-collapse-item>
</uni-collapse>

The uni-grid grid component supports custom column counts and border styles. Content presentation can be fully controlled via slots:

<uni-grid :column="4" :highlight="true">
  <uni-grid-item v-for="(item,index) in 8" :key="index">
    <image :src="'/static/icon'+index+'.png'" />
    <text>Option {{index}}</text>
  </uni-grid-item>
</uni-grid>

Theme Customization Solutions

uni-ui provides a complete CSS variable system for theme customization. Modifying variables in uni.scss applies changes globally:

/* Primary color */
$uni-primary: #5a8bff;
/* Secondary color */
$uni-success: #67c23a;
/* Text color */
$uni-text-color: #333;

The component library includes built-in dark mode support, which can be toggled automatically via the uni-dark class name:

uni.setStorageSync('darkmode', true) // Trigger dark mode

Performance Optimization Strategies

uni-ui components implement the following optimization mechanisms internally:

1. Image lazy loading: The uni-img component automatically monitors the viewport.
2. Virtual lists: uni-list handles large data volume rendering.
3. Animation optimization: CSS hardware-accelerated transitions.

<uni-list>
  <uni-list-item 
    v-for="item in largeData" 
    :key="item.id"
    :title="item.name"
    virtual
  />
</uni-list>

Extending Component Development

Extensions based on uni-ui must follow specific conventions. A typical structure includes the following files:

my-component/
├── components/
│   └── my-component.vue
├── readme.md
└── package.json

Component props should be compatible with uni-app's reactive system:

props: {
  // Supports dynamic type detection
  value: {
    type: [String, Number],
    default: ''
  },
  // Properties with validators
  size: {
    validator(value) {
      return ['small', 'medium', 'large'].includes(value)
    }
  }
}

Multi-Platform Difference Handling

For platform differences, components use conditional compilation internally:

// #ifdef MP-WEIXIN
this.initWechatAPI()
// #endif
// #ifdef APP-PLUS
this.initNativeModule()
// #endif

Special styles are distinguished by suffixes:

/* Mini-program-specific styles */
.button__wx {
  padding: 5px;
}
/* H5-specific styles */
.button__h5 {
  padding: 8px;
}

Debugging and Issue Resolution

uni-ui provides a complete logging system. Internal states can be output by setting the debug attribute:

<uni-popup debug />

Common issue resolution methods:

1. Style conflicts: Check if extra styles are added to the outer layer of the component.
2. Events not triggering: Confirm whether events are correctly declared in custom components.
3. Platform differences: Use conditional compilation to handle platform-specific logic.