fang-ui

[TOC]

组件库目录说明

vue-el-com
  └ archive    // 组件在线展示开发测试库
    └ node    // node运行文件
        docs.ts   // 自动生成vitepress文档的运行文件
      archive.config.ts    // vue-archive 配置文件
      config.ts
  └ bin    // bin 运行文件
      fang.js   // 指令 fang 的运行文件
  └ dist    // 打包生成文件
  └ docs    // vitepress文档输出库
    └ .vitepress    // vitepress配置文件
    └ components    // components组件目录
    └ examples    // 示例目录
  └ node    // node 运行文件
      cli.js    // fang.js 具体实现文件
      package.ts    // 修改package文件配置
      version.ts    // 修改package中的版本号，自动提升
  └ node_modules    // pnpm 引入包文件
  └ packages    // 子包库，开发在这里
    └ components    // 组件库
      └ node    // node 运行文件
          index.ts    // 自动生成index文件
      └ packages    // 库内容文件夹
      └ template    // bin 运行模板文件
        package.json    // 子项目package配置文件
    └ directives    // 指令库
      └ node    // node 运行文件
          index.ts    // 自动生成index文件
      └ packages    // 库内容文件夹
      └ template    // bin 运行模板文件
        package.json    // 子项目package配置文件
    └ hooks    // 组件use方法库
      └ node    // node 运行文件
          index.ts    // 自动生成index文件
      └ packages    // 库内容文件夹
        package.json    // 子项目package配置文件
    └ icons    // 图标库
      └ node    // node 运行文件
          index.ts    // 自动生成index文件
      └ packages    // 库内容文件夹
        package.json    // 子项目package配置文件
    └ locale    // 国际化库
      └ node    // node 运行文件
          index.ts    // 自动生成index文件
      └ packages    // 库内容文件夹
        package.json    // 子项目package配置文件
    └ theme    // 样式库
      └ node    // node 运行文件
          index.ts    // 自动生成index文件
      └ packages    // 库内容文件夹
        package.json    // 子项目package配置文件
    └ types    // typescript的type声明库
      └ node    // node 运行文件
          index.ts    // 自动生成index文件
      └ packages    // 库内容文件夹
        package.json    // 子项目package配置文件
    └ utils    // 工具库
      └ node    // node 运行文件
          index.ts    // 自动生成index文件
      └ packages    // 库内容文件夹
        package.json    // 子项目package配置文件
  .gitignore    //  git上传过滤文件
  .npmrc    //  npm配置文件
  catalogue-filter.json    //  自动生成，组件目录提升数据
  config.json    //  配置json
  index.ts    //  项目入口文件
  LICENSE    //  npm生成证书文件
  package.json    //  package项目配置文件
  pnpm-lock.yaml    //  pnpm 文件引入配置文件
  pnpm-workspace.yaml    //  pnpm workspace配置文件
  README.md    //  项目说明md文件
  tsconfig.json    //  typescript配置文件
  tsconfig.node.json    //  typescript 的node配置文件
  vite.config.ts    //  vite配置文件，打包配置

命令说明

dev:v // 更新 package 中的版本号

dev // 启动在线开发组件文档

dev:docs // 自动生成在线开发的组件文档的 md 文件到 docs 中

build:archive // 打包 在线开发组件文档

docs:dev // 启动 vitepress 文档

docs:build // 打包 vitepress 文档

build // 打包组件库

pub // 发布上传 npm

all // 一键操作 打包，更新版本，发布 npm

dev:index // 自动生成 index 文件

初始化项目

个入推荐使用 ni 来安装 依赖

ni - 使用正确的包管理器 统一了包管理器命令。会自动识别你当前 项目使用的是什么包管理器。支持的包管理器：npm · yarn · pnpm · bun

1. 导入项目

2. pnpm install 下载依赖 进入子目录中 packages/theme 也 pnpm install 一下

3. 如果要使用 docs 或者 archive 功能， 需要进入对应目录 pnpm install 一下

4. 看开发时文档 pnpm run dev

5. 看输出时文档 pnpm run docs:dev

6. 打包 pnpm run build

7. 发布 npm pnpm run pub

8. 一键操作 打包，更新版本，发布 npm pnpm run all

官网链接

ni

pnpm

vite

vitepress

element-plus

组件开发

组件开发在 packages/components/packages 中 进行

推荐使用 fang a 通过模板生成

bin 命令说明

fang // 通过模板自动生成组件开发模板

先 npm link
可以在components目录和directives目录使用
模板类型 缺省值 type1

fang add 目录名称 模板类型

└ template    // bin 运行模板文件
	└ 模板类型1
		... // 具体的文件
	└ 模板类型2
		... // 具体的文件

示例

└ template    // bin 运行模板文件
	└ type1
		└ src   // 组件内容体
			data.ts   // 组件外部数据
			index.vue   // 组件页面主体
		index.ts    // 组件入口
	└ type2
		└ src   // 组件内容体
			data.ts   // 组件外部数据
			index.ts   // 组件页面主体
		index.ts    // 组件入口

在/components/packages 目录中 运行 fang add date type2 将生 成

components
	└ packages
		└ date
			└ src   // 组件内容体
				data.ts   // 组件外部数据
				index.ts   // 组件页面主体
			index.ts    // 组件入口

示例 date 目录结构

date   // 组件名称 必须是当前组件的目录
└ src   // 组件内容体
    data.ts   // 组件外部数据 props入参, emits事件, slot 插槽, expose 暴露
    index.vue   // 组件页面主体
  index.ts    // 组件入口

同一类型和功能的组件允许用目录包层，方便查找与维护

但组件名称不允许重复

 form    // 表单组件库组
 └ date   // date组件
    └ src   // 组件内容体
        data.ts
        index.vue
    index.ts    // 组件入口
 └ select   // select组件名称
    └ src   // 组件内容体
        data.ts
        index.vue
    index.ts    // 组件入口

index.ts 组件入口 说明

当前文件一般不需要修改 通过命令会自动生成

/**
 * @config cover=false
 * cover 是否覆盖当前文件，默认是false， true 表示不覆盖
 * 当前已经由@fangzhongya/create自动生成
 * Thu Feb 23 2023 11:29:09 GMT+0800 (中国标准时间)
 */
import { withInstall } from '@fang-ui/utils';
import SrcVue from './src/index.vue';
export const FangDate = withInstall(SrcVue, 'FangDate');
export default FangDate;

当前文件可以用 pnpm run dev:index 命令自动生成的

withInstall 是组件注册方法

FangDate 是暴露的组件名称

src/data.ts 组件外部数据 说明

import type { ExtractPropTypes } from 'vue';
import { buildProps } from '@fang-ui/utils';
//组件属性
export const dataProps = buildProps({
    /**
     * @props { String, Number, Array<String> } many= ( )
     * 多类型
     */
    many: {
        type: [],
    },
});
export type DataProps = ExtractPropTypes<typeof dataProps>;
/**
 * @emits change (val:[String, Array])
 * 选择的时间
 */
//组件事件
export const dataEmits = {
    change: (evt: string | string[]) => {},
};
export type DataEmits = typeof dataEmits;
/**
 * @slot default 默认插槽
 */
//组件插槽
export const dataSlot = {
    default: 'default',
};
/**
 * @expose setValue (val:<string>设置的数据 )
 * 设置值
 */
//组件暴露方法和属性
export const dataExpose = {};

src/data.ts 文件提供的入参属性，事件，插槽，暴露方法等，必须 写注释，方便开发文档读取，来自动生成文档

buildProps 构建入参类型

dataProps 组件属性

dataEmits 组件事件

dataSlot 组件插槽

dataExpose 组件暴露方法和属性

注释写法说明

生成文档时只读取有 @title @props @slot @emits @expose 标签的 注释，注释只能是

/**
*/

不支持

/***
*/

注释可以写文件任意位置，但建议还写到你对应的字段上方，方便阅 读与维护

读取以当前组件主体为入口开始读取如果在 archive 组件在线展示 开发测试库 archive.config.ts 配置文件中配置了

components: [
    {
        // 公共参数文件的目录
        comprops: '/common/data/',
        // 当前入口文件中同级的文件名称
        curprops: 'data',
    },
];

将提供引入路径读取对应文件中的注释

组件文件注释说明

/**
 * @title 标题
 * @name 组件名称 组件中文名称
 * @author 作者
 * @description 组件介绍
 * @date 组件更新时间
 */

组件 props 组件属性

/**
 * 多标签
 * @props 是props属性标识
 * @name 属性名
 * @type 类型
 * @default 默认值
 * @selectable 可选值
 * @description 说明
 */
/**
 * 单标签
 * @props {类型} 属性名=默认值 (可选值) 说明
 */

组件 slot 组件插槽

/**
 * 多标签
 * @slot 是slot插槽标识
 * @name 插槽名
 * @selectable 子标签
 * @description 说明
 */
/**
 * 单标签
 * @props 插槽名 (可选值) 说明
 */

组件 emits 组件事件

/**
 * 多标签
 * @emits 是emits事件标识
 * @name 事件名
 * @selectable 回调参数
 * @description 说明
 */
/**
 * 单标签
 * @emits 事件名 (回调参数) 说明
 */

组件 expose 组件方法

/**
 * 多标签
 * @expose 是expose方法标识
 * @name 方法名
 * @type 返回值
 * @selectable 参数
 * @description 说明
 */
/**
 * 单标签
 * @expose {返回值} 方法名 (参数) 说明
 */

index.vue 组件页面主体 说明

<template>
    <div :class="cs.z()">
        <div>{{getLocale('cs')}}</div>
        <slot :name="dataSlot.default"></slot>
    </div>
</template>
<script lang="ts" setup>
import {
    dataProps,
    dataEmits,
    dataExpose,
    dataSlot,
} from './data';
import { useCssName, useLocale } from '@fang-ui/hooks';
// 获取国际化字段
const { getLocale } = useLocale();
// 样式设置方法
const cs = useCssName('date');
// 组件属性
const props = defineProps(dataProps);
// 组件事件
const emit = defineEmits(dataEmits);
// 组件暴露方法和属性
defineExpose({
    ...dataExpose,
});
</script

getLocale 国际化取值方法

useCssName 样式名称生成器 'date' 当前组件目录名称

JS 工具库的编写

Vue 组件库的封装

结构说明

文件结构 ts 包含的内容 vue 文件包含的内容函数说明

Element-plus 封装

文档编写与生成

dev // 启动在线开发组件文档

dev:docs // 自动生成在线开发的组件文档的 md 文件到 docs 中

build:archive // 打包 在线开发组件文档

docs:dev // 启动 vitepress 文档

docs:build // 打包 vitepress 文档

构建与发布

build // 打包组件库

pub // 发布上传 npm

all // 一键操作 打包，更新版本，发布 npm

项目引用

全局引用

// 全局引入组件
import FangUi from 'fang-ui';
// 全局引入样式
import 'fang-ui/dist/theme/index.css';

const app = createApp(App);
app.use(router);
app.use(FangUi);
app.mount('#app');

单独引用

// 单独引入组件
import { FangDate } from 'fang-ui';
// 全局引入样式 目前还不支持单独引入样式，后期开发
import 'fang-ui/dist/theme/index.css';

const app = createApp(App);
app.use(router);
app.use(FangDate);
app.mount('#app');

vue 中引用

<template>
    <div>
        <FangDate> </FangDate>
    </div>
</template>
<script lang="ts" setup>
import { FangDate } from 'fang-ui';
</script>
<style lang="scss"></style>

vue 中最小化引用

<template>
    <div>
        <FangDate> </FangDate>
    </div>
</template>
<script lang="ts" setup>
import { FangDate } from 'fang-ui/dist/components/date';
</script>
<style lang="scss"></style>

##按需导入您需要使用额外的插件来导入要使用的组件。

###自动导入 推荐首先你需要安装 unplugin-vue-components 插件

npm install -D unplugin-vue-components

然后把下列代码插入到你的 Vite 的配置文件中

Vite

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import AutoImport from 'unplugin-auto-import/vite';
import Components from 'unplugin-vue-components/vite';
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers';

// fang-ui 自动导入 需要引入的方法
import { FangComponentResolver } from 'fang-ui/dist/expand/components';
export default defineConfig({
    plugins: [
        vue(),
        AutoImport({
            imports: ['vue', 'vue-router', 'pinia'],
            resolvers: [ElementPlusResolver()],
        }),
        Components({
            dirs: [],
            dts: true,
            resolvers: [
                ElementPlusResolver(),
                //  自动导入 需要引入的方法, 添加方法
                FangComponentResolver(),
            ],
        }),
    ],
});

type Config = {
	/**
     * 别名
     */
    alias?: string;
    /**
     * 只支持别名
     */
    onlyAlias?: boolean;
};
FangComponentResolver(config:Config)

示例

FangComponentResolver({
alias:"com"
})

ComFangDate 和 FangDate 都是会引入 FangDate 组件

onlyAlias = true 就只能是 ComFangDate 才会引入 FangDate 组件

JS 工具库使用

Vue 组件使用