# agile-core

**Repository Path**: nandy007/agile-core

## Basic Information

- **Project Name**: agile-core
- **Description**: agile+vite+vue3=组件式微前端框架
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-05
- **Last Updated**: 2025-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agile框架使用指南

<div align="center">
    <img src="https://gitee.com/nandy007/agile-core/raw/main/assets/aui.svg" alt="Agile框架" style="width: 120px;border-radius:26px;background-color: #fff;box-shadow: 2px 2px 4px rgba(0,0,0,0.2);"/>
</div>

## 概述

`Agile`框架结合`Vite`和`VUE`的技术栈+自定义组件模块（基于`Web Component`），形成一个组件式的`微前端`框架。该框架旨在实现跨框架调用的`微前端组件`定义和使用。

使用`Agile`框架创建的组件称为`AUI`组件，该组件可以在框架内使用，也可以打包后在任意框架中通过引入js的方式使用，包括任何标准的DOM操作方式调用和样式设置。

## 特性

### 🚀 跨框架兼容
- **原生DOM组件**：基于Web Components标准，编译后的组件是原生HTMLElement扩展
- **多框架支持**：可在Vue、React、Angular等任意框架中使用
- **标准DOM操作**：支持`document.createElement`、`innerHTML`等标准DOM操作方式
- **双模式调用**：框架内可使用Vue组件语法和原生DOM方式，框架外使用原生DOM方式

### 💡 继承VITE+VUE开发体验
- **Vue语法兼容**：`.aui.vue`文件格式，保持Vue开发习惯
- **TypeScript支持**：完整的类型定义和智能提示
- **热更新支持**：基于Vite的现代化开发工具链
- **性能优化**：基于Vue3的性能优化

### 🔧  企业级场景设计
- **全粒度开发**：可以用于组件库、模块、插件、应用等任何粒度开发
- **Hook扩展机制**：为不同客户通过定制化组件实现差异功能
- **技术栈异构**：主应用和子应用使用不同前端框架
- **独立部署**：组件库独立发布，各应用按需引入
- **渐进式集成**：现有微前端项目可逐步引入AUI组件


## 规范

1. AUI组件必须以`.aui.vue`作为文件后缀
2. 组件名是唯一的，同一个组件名对应的实现只有一个，组件可以重复定义，但是后面定义的会覆盖前面的，其中有个名为`auix`的prop属性用于扩展属性
3. 组件名称必须是帕斯卡命名法（Pascal Case），即每个单词的首字母都是大写，单词之间没有分隔符
4. 组件名一般显式的在组件中通过name来定义，否则将取当前文件名的名称作为组件名


## 接口

### 1. AUI初始化事件

当组件`mounted`结束会执行两个动作：
1. 触发`aui-init`事件，事件的detail为`{code: 0}`。（该事件作用在原生DOM上，所以框架内和外都可以监听）
2. 执行组件内部的`auiInit`函数（如果存在），该函数与mounted同级。


### 2. 通用组件间函数调用

函数定义：<code>async $call(name: string, ...args: any[]) : any</code>
该函数是通用的组件间函数调用的定义，AUI原生DOM调用VUE组件函数或者VUE组件调用AUI原生DOM的函数都是使用这个方法。

其中，`name`可以是组件里`暴露`的`函数名`或者`属性名`（支持多级属性访问），前提是这些函数或属性要暴露，当为函数时为执行函数并返回结果；当为属性时，如果没有args则返回属性值，如果有args，将取args的第一个元素赋值给属性，返回null；当匹配不到任何函数和属性将返回一个Error对象。

1. 原生DOM调用VUE组件，则组件内使用`this.$call`调用，框架外使用`el.$call`。

```js
// $call是原生DOM上的扩展函数，用于组件外部调用内部的函数或者取值/赋值之用
const el = document.querySelector('aui-my-com');
const value = await el.$call('echo', 111); // value 为111
```

2. VUE组件调用原生DOM，则组件内使用`this.$call`调用

```js
// $call也是VUE组件的扩展函数，用于组件内调用原生DOM的函数或者取值/赋值之用
export default {
    ...
    methods: {
        setDomStyle() {
            this.$call('setAttribute', 'style', 'color: red;');
        }
    }
    ...
}
```


### 3. MVVM使用

由于AUI组件本身是`原生DOM`，所以都是通过value值作为MVVM绑定的依据（注意区分通过setAttribute设置的value属性，非同一个意思）。

VUE组件扩展了两个重要的方法：`$value`和`$anyToArray`。
`$value`: 该方法用于获取或设置组件的原生DOM的value值，主要用于MVVM绑定值传递给原生DOM。
`$anyToArray`: 该方法用于将任意类型的值转换为数组类型，主要用于处理多选场景。

使用方式如下：

```html
<aui-tradition-comp v-model="msg" />
<!-- 使用Vue方式引用时，注意要加v-model:value，而使用标签名时只需要写v-model -->
<TraditionComp v-model:value="msg" />
```

在组件内部需要绑定一个额外的变量做内部的MVVM，并同时监听value值和该变量的变化，如下：

```js
{
    ...
    data() {
        return {
            localValue: ''
        }
    },
    watch: {
        value(v) {
            // 当原生DOM的value值变化，同时更新内部变量
            this.localValue = v;
        },
        localValue(v) {
            // 当内部变量变化，同时设置原生DOM的value值
            this.$value(v);
        },
    }
    ...
}
```

注意：
1. 如果绑定的是多选类型，比如checkbox或者multiple类型的select以及一些自定义的组件，则内部变量的值必须是数组，而其他的则为字符串
2. value值默认是String类型，所以通过el.value获取到的值都是string类型，并且在设置value时也会被转为字符串，在多选场景下，如果希望直接获取到数组，可以在组件里为value添加prop，并设置type为Array即可
3. 如果多选场景没有单独设置value的type为Array，则需要自行在watch监听value变化的时候将字符串转为数组。VUE的`methods`上已经扩展里`$anyToArray`函数来转数组，比如：

```js

{
    ...
    watch: {
        value(v) {
            this.localArray = this.$anyToArray(v);
        },
        localArray(v) {
            this.$value(v);
        }
    },
    ...
}

```

### 4. slot插槽使用

由于AUI组件是原生DOM，所以使用上跟VUE本身的插槽使用方式有所不同。类似于DIV等标签，理论上所有子节点都是默认插槽的内容，而没有具名插槽，为了扩展具名插槽，AUI组件内部使用了`aui-slot`元素来实现具名插槽。

使用规范：
1. `aui-slot`仅在通过原生DOM方式时使用，通过标准VUE组件则仍使用`template`。
2. `aui-slot`元素使用for属性指定需要插入的插槽名称。
3. `aui-slot`不支持VUE插槽的高级用法。

比如：

```html
<!-- 使用原生DOM方式调用需要使用aui-slot包装 -->
<aui-my-comp>
    <aui-slot for="header">
        <div>这是header</div>
    </aui-slot>
</aui-my-comp>

<!-- 使用VUE标准方式调用需要包使用template -->
<MyComp>
    <template #header>
        <div>这是header</div>
    </template>
</MyComp>
```

### 5. 其他

在框架内部调用组件，可以直接使用标签名（`aui-comp-name`）方式调用，也可以使用Vue风格的组件调用方式，如果是在框架外调用则只能通过标准的DOM操作方式调用，比如：

```html
<!-- 该方式可以在框架内和框架外调用 -->
<aui-my-comp @aui-init="onInit" :my-msg="msg||'这是第一个AUI组件'"/>
<!-- 该方式只能在框架在调用 -->
<MyComp @aui-init="onInit" :my-msg="msg||'这是通过VUE组件方式引入的AUI组件'"/>
```

```js
// 通过标准创建原生DOM方式在框架内和框架外都可使用
const el = document.createElement('aui-my-comp');
document.body.append(el);
// 通过标准插入代码片段方式在框架内和框架外都可使用
document.body.innerHTML = '<aui-my-comp />'

```




## 使用

Agile3.0框架目前只支持在`Vite`项目中开发，但是编译后可以在任何框架中使用。

版本要求：
1. node22+
2. vite7+
3. vue3+

[->直达示例](https://gitee.com/nandy007/agile-vite-vue)

### 第一步：安装模块

```bash
npm install agile-core
```
安装完成会在当前工程的`types`目录生成必要的代码模块定义，如果没有生成，可以到已安装的模块的`types`目录下把所有`d.ts`文件拷贝到项目的types目录，并且设置项目自身的tsconfig.json文件，添加`types`目录到`include`节点下

### 第二步：在Vite.config.ts配置中添加aui插件

```js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { getAuiConfig } from 'agile-core'
import { mergeConfig } from 'vite'

// 引入aui插件
const { userConfig, isCustomElement } = getAuiConfig();

const baseConfig = {
  plugins: [vue({
    template: {
      compilerOptions: {
        // 设置以aui开头的原生DOM为自定义元素
        isCustomElement
      }
    }
  })],
}

// https://vite.dev/config/
export default defineConfig(async () => {
  // 合并aui配置到vite配置中
  return mergeConfig(baseConfig, userConfig)
})

```

### 第三步：在项目中使用.aui.vue文件

所有aui组件都需要以.aui.vue文件的格式进行定义，ExampleComp.aui.vue文件：

```html
<template>
  <div>
    <button>按钮</button>
  </div>
</template>

<script setup lang="ts">
import { onMounted } from 'vue'

onMounted(() => {
  console.log('aui组件渲染完毕');
});

defineOptions({
  // 如果不想以文件名做组件名，可以显示指定name
  name: 'ExampleComp',
})
</script>

<style>
aui-example-comp {
    button {
        background-color: red;
    }
}

</style>
```

组件内容与`VUE`组件规范一致，但是需要遵循前面提到的`规范`。

注：如果是在框架内使用，在import一个`.aui.vue`文件时可能会报错，需要添加类型定义，即在合适的`d.ts`文件中添加：

```ts
// vite-env.d.ts文件内容
/// <reference types="vite/client" />

declare module '*.aui.vue' {
    import { DefineComponent } from 'vue';
    const component: DefineComponent<{}, {}, any>;
    export default component;
}
```


## 插件

### 介绍

AUI组件可通过插件机制对原组件的定义进行修改，或者对组件重新进行定义。

需要注意的是，对组件更新只有在组件创建前有效，请注意时机。

```js

// 引入AUI核心
import { default as auiCore, type Component } from 'agile-core';

```

### 组件HOOK

组件hook即对组件内部的行为进行变更，主要通过函数`hookStructure(tagName: string, handle: HookHandler): void;`实现

其中：
`tagName`是组件的完整标签名，比如：aui-my-comp
`handle`是一个函数，用于对组件内部的行为进行变更，函数的参数为组件的定义，返回值为变更后的组件定义，也可以不返回。

比如：
```js
auiCore.hookStructure('aui-example-comp', function (structure: Component) {
    const originMounted = structure.mounted;

    structure.mounted = function () {
        console.log('from hook aui-example-comp');
        originMounted?.call(this);
    }

    console.log('hook aui-example-comp');
});

```


### 组件定义

组件定义即对AUI组件进行定义，主要通过函数`define(v: Component, force?: boolean): Component;`实现。

其中：
`v`为组件的定义
`force`为是否强制定义，默认值为false。仅在当组件已经被定义时生效，true则会覆盖定义，false则本次定义无效

比如：
```js
auiCore.define({
    name: 'ExampleComp',
    props: {
        myMsg: {
            type: String,
            default: ''
        }
    },
    render() {
        return h('div', { class: 'container' }, ['这是强制定义的组件', h('div', this.myMsg)]);
    }
}, true);

```