yp-taro-ui

鱼泡 Taro UI 组件库（抖音小程序）

安装

npm install @yup/taro-ui
# 或
yarn add @yup/taro-ui

按需加载

配合 babel-plugin-import 插件实现按需加载，自动引入组件样式。

安装插件

npm install babel-plugin-import --save-dev

配置 babel

在 babel.config.js 或 .babelrc 中添加：

{
  "plugins": [
    ["import", {
      "libraryName": "@yup/taro-ui",
      "libraryDirectory": "es/components",
      "style": true
    }]
  ]
}

使用

配置后可以直接按需引入组件：

import { Button, Input } from '@yup/taro-ui';

开发指南

环境要求

• Node.js >= 20.19.0
• npm >= 8 或 yarn >= 1.22

开发命令

# 安装依赖
npm install

# 启动文档开发服务（端口 8888）
npm start

# 构建文档
npm run build:doc

# 构建组件库
npm run build:components

发布说明

# 构建并发布（手动更新版本号）
npm run release

# 自动更新 patch 版本并发布（修复 bug）
npm run release:patch

# 自动更新 minor 版本并发布（新增功能）
npm run release:minor

# 自动更新 major 版本并发布（重大变更）
npm run release:major

# 首次发布
npm run release:first

发布前请确保：

1. 代码已通过 lint 检查
2. 组件功能测试通过
3. 文档已更新
4. 已登录阿里云云效制品库（npm login）

组件编写规范

目录结构

每个组件遵循以下目录结构：

src/components/
└── button/                    # 组件目录（小写，kebab-case）
    ├── index.tsx              # 组件主文件
    ├── demos/                 # 示例目录
    │   ├── demo1.tsx          # 示例1
    │   ├── demo2.tsx          # 示例2
    │   └── ...
    └── style/                 # 样式目录
        ├── index.ts           # 样式入口（用于按需加载）导入index.less
        └── index.less         # 组件样式入口

组件编写规范

1. 命名规范

   • 组件目录：小写 + 连字符（如 date-picker-view）
   • 组件名：大驼峰（如 DatePickerView）
   • 样式类名前缀：ypmini-组件名（如 ypmini-button）

2. 类型定义

   • 导出组件的 Props 类型
   • 使用 JSDoc 注释说明每个属性

export interface ButtonProps {
  /**
   * 按钮类型
   */
  type?: 'primary' | 'default';
  /**
   * 是否禁用
   */
  disabled?: boolean;
}

3. 组件导出
   • 在 src/index.ts 中导出组件
   • 同时导出类型定义

export { default as Button } from './components/button';
export type { ButtonProps } from './components/button';

4. 样式规范
   • 使用 Less 编写样式
   • 支持 CSS 变量自定义
   • style/index.ts 内容：

import './index.less';

⚠️ 重要提示： 每新增一个组件时，需要在 src/style/index.less 中手动导入组件的 less 文件，这个样式文件用于提供给全局样式导入。

Demo 编写规范

/**
 * title: 示例标题
 * description: 示例描述
 */
export default () => {
  return (
    <div style={{ padding: 16 }}>
      <h5>基础用法</h5>
      <Button>按钮</Button>
    </div>
  );
};

文档编写

文档目录

docs/components/
└── button/
    └── index.md              # 组件文档

文档模板

---
sidebar: true
toc: content
---

# Button 按钮

组件描述。

## 何时使用

- 使用场景1
- 使用场景2

## 示例

<code src="../../../src/components/button/demos/demo1.tsx"></code>

## API

### 属性

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `type` | 按钮类型 | `'primary'` \| `'default'` | `'default'` |

### CSS 变量

| 变量 | 说明 | 默认值 |
| --- | --- | --- |
| `--button-color` | 按钮颜色 | `#1890ff` |

添加新组件文档

1. 在 docs/components/ 下创建组件目录和 index.md
2. 在 .dumirc.ts 的 sidebars 中添加组件导航
3. 在 .dumirc.ts 的 sidebar 配置中添加路由映射

新增组件流程

1. 在 src/components 中新增组件文件夹
2. 在新增的组件文件目录中增加 index.tsx 出口
3. 在新增的组件文件目录中增加 style 文件目录
4. 在 style 文件目录中增加 index.ts 样式导出入口
5. 在 style 目录下增加 index.less 入口作为 less 文件的导入入口
6. 编写组件
7. 编写 demo，在组件目录下增加 demos 文件目录，并在其中实现 demo
8. 组件编写完成后在 src/style/index.less 中导入组件的 less 文件（提供给全局引入样式的方式使用）
9. 在根目录 docs/components 目录下增加组件文档说明
10. 在 .dumirc.ts 文件中增加文档的配置
11. yarn start 启动文档查看

designWidth 适配说明

@yup/taro-ui 的 designWidth 为 750。

如果你的项目 designWidth 为 375，显示效果会是两倍大。可以通过修改 Less 变量 @hd 进行适配：

// config/index.js
module.exports = {
  // ...
  less: {
    modifyVars: {
      "@hd": "1"
    }
  }
}

License

MIT