DOCSEARCHbyAlgolia
Submit Docs

PiUI Component Library

repository·master·Indexed 41 days ago

https://github.com/sadais-org/piui

A high-quality mobile UI component library built on top of uniapp and Vue.js, featuring over 50 components with support for theme customization and on-demand loading. Version 1.2.7-beta177.

Tokens
68.7K
Snippets
146
Records
233
Agent score
99%

What's inside PiUI

  1. Install PiUI using the recommended scaffolding

    master

    For a zero-configuration setup that includes sadais-core, use the vue-cli scaffolding method. This is the recommended approach for new projects.

    1. Install vue-cli

    If you don't have vue-cli installed, run:

    npm install -g @vue/cli
# OR
yarn global add @vue/cli

    Verify the installation with vue --version.

    2. Generate the project

    Initialize your project using the sadais-org/uni-preset-vue preset. Replace my-project with your desired project name:

    nvue create -p sadais-org/uni-preset-vue my-project

    3. Start development

    Navigate to your project directory and start the local development server:

    cd my-project && npm run dev
    vue create -p sadais-org/uni-preset-vue my-project

  2. Integrate PiUI into existing HbuilderX or Uniapp Vue-Cli projects

    master

    If you are adding PiUI to an existing project, follow these steps:

    1. Install dependencies

    Install the core library and the toolset:

    yarn add sadais-piui @sadais/piui-tool

    2. Configure Transpilation

    Since @sadais/piui-tool and sadais-piui use ES6 syntax, you must declare them in transpileDependencies within your vue.config.js to ensure compatibility in vue-cli projects:

    // vue.config.js
module.exports = {
  transpileDependencies: ['@sadais/piui-tool', 'sadais-piui']
}

    3. Register PiUI in Vue

    In your main entry file, import and use the library:

    import Vue from 'vue';
import piui from "sadais-piui";

// Global configuration object
const piuiConfig = {}

Vue.use(piui, piuiConfig);

    4. Import Styles

    Import the required SCSS files in your global style files:

    • In App.vue: @import 'sadais-piui/scss/index.scss';
    • In uni.css: @import 'sadais-piui/scss/variable.scss';

    5. Enable automatic component loading (easycom)

    To use components without manual imports, configure the easycom rule in your pages.json file:

    "easycom": {
  "^pi-(.*)": "sadais-piui/components/pi-$1/index.vue"
}
    yarn add sadais-piui @sadais/piui-tool

  3. Use PiUI components via easycom

    master

    Once the easycom configuration is added to your pages.json, PiUI components are automatically loaded on demand. You can use any component starting with the pi- prefix directly in your templates without manual imports.

    "easycom": {
  "^pi-(.*)": "sadais-piui/components/pi-$1/index.vue"
}

  4. How PiDatePicker handles date boundaries

    master

    The PiDatePicker component automatically enforces date boundaries using the minDate and maxDate props.

    When a user scrolls the picker, the component calls correctDateBoundary() to ensure the internal date state does not fall outside the allowed range. If the selected value is invalid, it is automatically corrected to the nearest boundary (minDate or maxDate). This logic applies to years, months, days, hours, and minutes based on the current selection to ensure a valid date is always maintained.

  5. How PiGridItem handles hover and tap states

    master

    The PiGridItem component provides built-in support for visual feedback during user interaction.

    • hoverClass: Defines the CSS class applied when the item is pressed. If set to "none", no hover effect is applied.
    • hoverStartTime: Controls the sensitivity of the press. The hover state triggers only after the user has held the item for this many milliseconds.
    • hoverStayTime: Controls the persistence of the visual feedback. The hover state remains visible for this many milliseconds after the user releases their finger.

    These properties can be configured individually on the item or inherited from the parent PiGrid component.

  6. Configure column slots for images and links

    master

    The PiTable component allows you to customize cell rendering using the slot property within a column configuration object. This is useful for displaying images or interactive links instead of plain text.

    Image Slots

    • Standard Image: Use type: 'img' to render the value of the specified prop as an image source.
    • Conditional Rank Image: Use type: 'rank' and provide a condition (number). The image will only render if the current row index is less than the condition value.

    Link Slots

    Use type: 'link' to render multiple clickable text elements. You must provide a links array where each object contains a name and an optional style.

    Note: Link clicks trigger the @link event on the component.

    // Example column configuration for links
{
  "name": "Actions",
  "prop": "action_key",
  "slot": {
    "type": "link",
    "links": [
      { "name": "Edit", "style": { "color": "#007aff" } },
      { "name": "Delete", "style": { "color": "#ff3b30" } }
    ]
  }
}
    {
  "name": "Status",
  "prop": "status_img",
  "slot": {
    "type": "rank",
    "condition": 3
  }
}

  7. How PiCollapseItem and PiCollapse work together

    master

    The PiCollapseItem is a child component that relies on a PiCollapse parent to manage its state.

    • Accordion Mode: If the parent pi-collapse has accordion set to true, the parent's value must be a single identifier (not an array). The PiCollapseItem with the matching name prop will be the only one expanded.
    • Non-Accordion Mode: If accordion is false, the parent's value must be an array of identifiers. Any PiCollapseItem whose name is present in that array will be expanded.
    • Requirement: You must use pi-collapse-item inside a pi-collapse component. Using it standalone will result in a console error.

  8. Understand PiPicker selection modes

    master

    The type prop determines how the columns are structured and how selection works:

    • single: A single column of items. defaultValue should be an object or a single index.
    • multi: Multiple independent columns. defaultValue must be an array where each element corresponds to the index of the selected item in that column (e.g., [0, 2] selects the 1st item in column 1 and the 3rd item in column 2).
    • multi-auto: Cascading multi-column mode. The columns are linked via the childField (default 'children'). When a value in a parent column changes, the subsequent columns are reset. defaultValue must be an array of indices matching the depth of the hierarchy.

  9. Implement remote search in PiSelect

    master

    To use remote searching, enable it via remoteSearchConfig and provide a parsing function. The component will call this function when the user searches or scrolls to the bottom of the list.

    Configuration

    Set remoteSearchConfig.enable to true. You must provide a way to parse the results via parseRemoteSearchResult or by passing a method name to remoteMethod that exists on the parent component.

    Remote Search Function Signature

    The parsing function is called with (pageNo, pageSize, keyword) and must return a Promise that resolves to an Array of items.

    Example

    // In your parent component
export default {
  data() {
    return {
      searchOptions: {
        enable: true,
        pageSize: 10,
        filterPlaceholder: 'Search users...'
      }
    }
  },
  methods: {
    // This method is called by PiSelect
    async fetchUsers(page, size, keyword) {
      const res = await api.getUsers({ page, size, keyword });
      return res.data; // Must return an array
    }
  }
}
    <pi-select 
  :remote-search-config="searchOptions"
  remote-method="fetchUsers"
/>

  10. How PiDropdown and PiDropdownItem synchronize data

    master

    The PiDropdown component acts as a controller for its children. It uses the ValueSync mixin and parentInit to manage the relationship between the parent's value array and the individual val properties of each pi-dropdown-item child.

    Key Lifecycle Behavents:

    1. Initialization: On mounted, the dropdown maps its children to create a tabs array, ensuring the child's val matches the parent's value array index.
    2. Selection: When a tab is clicked via handleClickTab, the dropdown calculates the container position, opens the mask, and shows the corresponding child item.
    3. Submission: When submit() is called, the dropdown collects the current val from all children and updates the parent's val (triggering v-model updates).

  11. How PiRadioGroup handles selection and cancellation

    master

    The PiRadioGroup manages selection via the emitChange(childName) method, which is called by its child pi-radio components.

    Cancellation Logic:

    1. If canCancel is true on the group, or if the specific child being clicked has getCanCancel set to true, clicking the already-selected item will set the group's value to an empty string ('').
    2. Otherwise, the group value is updated to the name of the clicked child.

    Events: When the value changes, the group dispatches form-change events to both PiForm and PiFormItem parents to ensure integration with form validation and state management.

  12. How PiWaterfall distributes items

    master

    The PiWaterfall component uses a height-based distribution strategy to balance the two columns:

    1. It queries the current height of the .left-column and .right-column using $pi.common.queryRect.
    2. If the left column is shorter, the next item is pushed to the left slot.
    3. If the right column is shorter, the next item is pushed to the right slot.
    4. If heights are equal, it balances based on the current number of items in each column (preferring the left if counts are equal) to ensure both columns start populating immediately.
    5. After each insertion, it waits for the duration specified by the wait prop before processing the next item in the queue.

    Note: Because the component uses await for DOM measurements and setTimeout for the insertion loop, ensure your value array contains stable items to avoid race conditions during rapid updates.