uniapp-styleless-components

uniapp-styleless-components

一套无样式（Unstyled / Styleless）的 uni-app Vue 3 组件库。
组件仅提供功能逻辑，基础布局与语义化 DOM 结构，不包含任何视觉样式，让开发者最大程度掌控 UI 表现。

安装

pnpm add uniapp-styleless-components

需要 vue ^3.4.21 和 @dcloudio/uni-app >= 3.0.0 作为 peer 依赖。

快速开始

注册全局配置

在 main.ts 中注册 ConfigProvider，传入页面配置和初始化逻辑，具体使用方式参见全局配置：

import { createConfigProvider } from "uniapp-styleless-components";
import appPagesConfig from "@/pages.json";

export function createApp() {
  const app = createSSRApp(App);

  app.use(createConfigProvider(), {
    pageContainer: {
      appPagesConfig: appPagesConfig,
      init: async () => {},
    },
    // 可选：主题颜色、组件默认值等
    // theme: { color: { primary: "#1890ff" } },
    // button: { size: "medium" },
    // formContainer: { labelPosition: "left" },
    // listContainer: { rowKey: "id", defaultPageSize: 10 },
  });

  return { app };
}

使用组件

组件有两种使用方式：

方式一：直接导入组件：

<template>
  <form-container v-model="formData" :items="items"></form-container>
</template>

<script setup lang="ts">
import { FormContainer } from "uniapp-styleless-components"
</script>

方式二（推荐）：使用 easycom 自动注册，无需手动导入。在 pages.json 中添加规则：

{
  "easycom": {
    "custom": {
      "^sc-(.*)": "uniapp-styleless-components/components/$1/$1.vue"
    }
  }
}

配置后即可在页面中直接使用 <sc-button>、<sc-field> 等标签。

完整示例

<template>
  <page-container>
    <sc-button label="提交" type="primary" @click="onSubmit" />

    <sc-row gap="16rpx">
      <sc-field v-model="name" type="text" placeholder="请输入姓名" />
      <sc-field v-model="city" type="option" :field-props="{ options }" />
    </sc-row>

    <sc-list-container v-bind="listProps">
      <template #item="{ item }">
        <view>{{ item.name }}</view>
      </template>
    </sc-list-container>
  </page-container>
</template>

<script setup>
import { useListContainer } from "uniapp-styleless-components";

const name = ref("");
const city = ref("");

const { listProps } = useListContainer({
  getListData: async (pagination, params) => {
    const res = await uni.request({ url: "/api/list", data: { ...pagination, ...params } });
    return { records: res.data.list, pagination: res.data.pagination };
  },
});
</script>

组件列表

Hooks

工具函数

详见 docs/utils.md。

核心概念

无样式

组件不包含任何 CSS 样式，仅渲染语义化的 HTML 结构。所有视觉效果由开发者自行定义。

语义化 DOM

每个组件定义一组语义化 DOM 节点，可通过 classNames 和 styles 属性独立控制：

<button
  label="提交"
  :classNames="{ root: 'btn', icon: 'btn-icon', label: 'btn-label' }"
  :styles="{ root: { borderRadius: '8rpx' }, label: { fontWeight: 'bold' } }"
/>

CSS 变量主题

通过 ConfigProvider 配置主题颜色，组件内部自动使用 CSS 变量传递色值：

app.use(createConfigProvider(), {
  theme: { color: { primary: "#1890ff", success: "#52c41a", warning: "#faad14", danger: "#ff4d4f" } },
});

导入路径

所有组件通过 easycom 自动注册，无需手动导入。
Hooks、工具函数和类型可按需导入：

// Hooks
import { usePageContainer, useFormContainer, useListContainer, useField } from "uniapp-styleless-components";

// 配置
import { createConfigProvider, useConfig } from "uniapp-styleless-components";

// 工具函数
import { toastError, toastSuccess } from "uniapp-styleless-components";

// 错误类
import { SilenceError } from "uniapp-styleless-components";

// 类型
import type { FormField, FormRuleItem } from "uniapp-styleless-components";

如需 VSCode 组件参数类型提示，推荐配合 uniapp-easycom-types 使用。

文档

每个组件的详细文档见 docs/ 目录：

License

MIT