DOCSEARCHbyAlgolia
Submit Docs

Hy Design Uni Documentation

repository·master·Indexed 18 days ago

https://github.com/mrgao-hy/hy-design-uni

A modern component library for Vue 3, TypeScript, and UniApp, providing over 80 components for APP, H5, and WeChat/Alipay mini-programs. Features include theme switching, dark/light modes, internationalization, and global utility functions via the $hy object. The library is distributed as @hy-app/ui (version 1.0.4) and supports on-demand loading via easycom.

Tokens
13.8K
Snippets
52
Records
53
Agent score
63%

What's inside Hy Design Uni

  2. Register Hy Design Uni globally in main.ts

    master

    To use the component library globally in your UniApp project, import globalRegister from @hy-app/ui and use it within your createApp function in main.ts.

    import { globalRegister } from "@hy-app/ui";
import { createSSRApp } from "vue";

export function createApp() {
  const app = createSSRApp(App);
  app.use(globalRegister);
  return { app };
}

  3. Configure Volar for type recognition

    master

    To enable proper TypeScript type recognition and IntelliSense for the library in your IDE (via Volar), add @hy-app/ui/global to the types array in your tsconfig.json.

    // tsconfig.json
{
  "compilerOptions": {
    "types": ["@hy-app/ui/global"]
  }
}

  4. Install the Hy Design Uni component library

    master

    The @hy-app/ui component library is designed specifically for projects using Vue 3 + UniApp + TypeScript.

    Ensure your environment meets the following requirement:

    • Node.js version: >= 16.14.0

    Install the library and its required dependency dayjs using pnpm:

    # Install the component library
pnpm add @hy-app/ui

# Install required dependency
pnpm add dayjs

  5. Configure on-demand component loading via easycom

    master

    To enable automatic component resolution (on-demand loading) in UniApp, configure the easycom field in your pages.json. This allows you to use components prefixed with hy- without manual imports.

    {
  "easycom": {
    "custom": {
      "^hy-(.*)": "@hy-app/ui/components/hy-$1/hy-$1.vue"
    }
  }
}

  6. Install hy-design-uni components globally

    master

    To use all UI components globally in your Vue 3 / UniApp project, import the install function from the component entry point and call it with your Vue instance. This registers all available components (e.g., HyButton, HyInput, HyModal) so they can be used in any template without local registration.

    import { install } from '@/package/components/index.ts';

// In your main.ts or entry file
const app = createApp(App);
app.use(install);

  7. Use Hy Design Uni utility functions

    master

    The library provides global utility functions accessible via the $hy object in your Vue templates. For example, you can generate a random number between two values using $hy.random(min, max).

    <template>
  <!-- Get a random number between 0 and 10 -->
  <div>{{ $hy.random(1, 10) }}</div>
</template>

  8. Configure the TabBar using defineUniPages

    master

    The tabBar object in defineUniPages allows you to define the bottom navigation bar for your UniApp project.

    Available properties:

    • color: The default color of the icon and text.
    • selectedColor: The color of the icon and text when the tab is active.
    • borderStyle: The style of the tab bar border ('black' or 'white').
    • backgroundColor: The background color of the tab bar.
    • list: An array of tab objects, each containing:
      • pagePath: The path to the page.
      • text: The label for the tab.
      • iconPath: The path to the unselected icon.
      • selectedIconPath: The path to the selected icon.
    tabBar: {
    color: '#7A7E83',
    selectedColor: '#3cc51f',
    borderStyle: 'black',
    backgroundColor: '@bgColor',
    list: [
        {
            pagePath: 'pages/index/Index',
            text: '首页',
            iconPath: './static/tabbar/home.png',
            selectedIconPath: './static/tabbar/homeHL.png'
        },
        {
            pagePath: 'pages/mine/Index',
            text: '我的',
            iconPath: './static/tabbar/personal.png',
            selectedIconPath: './static/tabbar/personalHL.png'
        }
    ]
}

  9. Configure component auto-import via easycom

    master

    The easycom configuration enables automatic component scanning and registration, allowing you to use components without explicit imports.

    • autoscan: Set to true to enable automatic scanning.
    • custom: Defines regex patterns to map component names to their file paths.

    In this project, the following patterns are used:

    • ^hy-(.*): Maps components starting with hy- to @/package/components/hy-$1/hy-$1.vue.
    • ^the-(.*): Maps components starting with the- to @/components/the-$1.vue.
    easycom: {
    autoscan: true,
    custom: {
        '^hy-(.*)': '@/package/components/hy-$1/hy-$1.vue',
        '^the-(.*)': '@/components/the-$1.vue'
    }
}

  10. View the global library configuration

    master

    The config object contains global constants used by the library, such as default image URLs, avatar placeholders, the default logo path, and the official documentation URL. While this is an internal configuration object, it defines the default assets used across the component library.

    export const config = {
    image: 'https://img11.360buyimg.com/n1/s450x450_jfs/t1/281169/10/14028/31748/67ecf51dF384c5bd6/1ec0c214ea7a914e.png',
    avatar: 'https://q9.itc.cn/q_70/images03/20250211/6ee1b8e0f4704083ba715986c8c3795f.jpeg',
    logo: '~@/static/logo.png',
    url: 'https://h5.hy-design-uni.top'
}

  11. Configure useUniPages for page generation

    master

    The useUniPages object is used to configure the @uni-helper/vite-plugin-uni-pages plugin. It allows you to define which files to exclude from page generation, specify sub-packages, set the home page, and intercept the file writing process via onBeforeWriteFile to inject metadata or styles into generated pages.

    Key configuration properties:

    • exclude: An array of glob patterns for files to ignore during page discovery.
    • subPackages: An array of directory paths to be treated as sub-packages.
    • homePage: The path to the application's entry/home page.
    • onBeforeWriteFile(ctx: PageContext): A lifecycle hook that receives the PageContext. You can use this to modify page metadata, such as adding h5 specific configurations like titleNView buttons.
    export const useUniPages = {
    exclude: ['**/components/**/**.*'],
    subPackages: ['src/pages-design'],
    homePage: 'pages/index/Index',
    onBeforeWriteFile(ctx: PageContext) {
        if (!ctx.subPageMetaData) return
        ctx.subPageMetaData.forEach((item) => {
            if (item.root === 'pages-design') {
                item.pages.forEach((p) => {
                    if (!p.style) p.style = {}
                    p.style.h5 = {
                        titleNView: {
                            buttons: [{ type: 'share' }]
                        }
                    }
                })
            }
        })
    }
}

  12. Configure global styles and navigation via defineUniPages

    master

    Use defineUniPages to configure global application settings such as navigation bar appearance and background colors. This configuration is applied across the entire application. Note that some values use design tokens (e.g., @navBgColor, @bgColor) which are likely resolved by the project's design system or build pipeline.

    Key configuration areas:

    • globalStyle: Controls the navigationBarTitleText, navigationBarBackgroundColor, navigationBarTextStyle, and various background color properties (backgroundColor, backgroundColorTop, backgroundColorBottom).
    • enablePullDownRefresh: A boolean to enable or disable pull-to-refresh functionality.
    • mp-alipay: Platform-specific settings for Alipay Mini Programs, such as allowsBounceVertical.
    import { defineUniPages } from '@uni-helper/vite-plugin-uni-pages'

export default defineUniPages({
    globalStyle: {
        navigationBarTitleText: '华玥组件库',
        navigationBarBackgroundColor: '@navBgColor',
        navigationBarTextStyle: '@navTxtStyle',
        backgroundColor: '@bgColor',
        backgroundTextStyle: '@bgTxtStyle',
        backgroundColorTop: '@bgColorTop',
        backgroundColorBottom: '@bgColorBottom',
        enablePullDownRefresh: false,
        'mp-alipay': {
            allowsBounceVertical: 'NO'
        }
    }
})