docs: update useMaterial api docs (#1389)
This commit is contained in:
chilingling
GitHub
parent
2dbade3098
commit
cbf580370a
|
|
@ -62,40 +62,334 @@ return {
|
|||
|
||||
#### API
|
||||
|
||||
1. `materialState`：reative 对象，存放物料插件面板里的状态数据，包括组件、区块、第三方依赖等，具体数据结构如下：
|
||||
1. `materialState`：reactive 对象，存放物料插件面板里的状态数据，包括组件、区块、第三方依赖等，具体数据结构如下：
|
||||
|
||||
```js
|
||||
|
||||
const materialState = reactive({
|
||||
components: [], // 这里存放的是物料插件面板里所有显示的组件
|
||||
blocks: [], // 这里存放的是物料插件面板里所有显示的区块
|
||||
thirdPartyDeps: { scripts: [], styles: new Set() } // 这里存放的是物料第三方依赖相关信息
|
||||
componentsDepsMap: { scripts: [], styles: new Set() }, // 这里存放组件依赖的映射
|
||||
packages: [] // 物料依赖的包
|
||||
})
|
||||
|
||||
```
|
||||
> **使用示例**
|
||||
>
|
||||
> ```useMaterial().materialState```
|
||||
|
||||
**使用示例**
|
||||
|
||||
2. 暴露出来的方法函数如下
|
||||
```useMaterial().materialState```
|
||||
|
||||
2. 暴露出来的方法函数详情
|
||||
|
||||
```js
|
||||
{
|
||||
initMaterial, // 物料模块初始化
|
||||
fetchMaterial, // 请求物料并进行处理
|
||||
getMaterialsRes, // 获取物料，并返回符合物料协议的bundle.json内容，getMaterialsRes: () => Promise<Materials>
|
||||
generateNode, // 根据 包含{ type, componentName }的组件信息生成组件schema节点，结构：
|
||||
clearMaterials, // 清空物料
|
||||
clearBlockResources, // 清空区块缓存，以便更新最新版区块
|
||||
getMaterial, // 获取单个物料，(property) getMaterial: (name: string) => Material
|
||||
setMaterial, // 设置单个物料 (property) setMaterial: (name: string, data: Material) => void
|
||||
addMaterials, // 添加多个物料
|
||||
registerBlock, // 注册新的区块
|
||||
updateCanvasDependencies, //传入新的区块，获取新增区块的依赖，更新画布中的组件依赖
|
||||
getConfigureMap // 获取物料组件的配置信息
|
||||
}
|
||||
// 状态对象
|
||||
materialState, // 存放着组件、物料侧区块、第三方依赖信息
|
||||
|
||||
// 初始化和请求方法
|
||||
initMaterial, // 物料模块初始化，参数: { isInit = true, appData = {} }
|
||||
fetchMaterial, // 请求物料并进行处理
|
||||
refreshMaterial, // 刷新物料，清空后重新初始化和获取
|
||||
|
||||
// 物料资源获取方法
|
||||
getMaterialsRes, // 获取物料，并返回符合物料协议的bundle.json内容，返回: Promise<Materials>
|
||||
getMaterial, // 获取单个物料，参数: (name: string) => Material
|
||||
getComponentsByGroup, // 根据组名获取指定分组组件，参数: (components: Component[], groupName: string) => Component[]
|
||||
|
||||
// 物料操作方法
|
||||
generateNode, // 根据包含{ type, component }的组件信息生成组件schema节点
|
||||
setMaterial, // 设置单个物料，参数: (name: string, data: Material) => void
|
||||
addMaterials, // 添加多个物料，参数: (materials: Material) => void
|
||||
|
||||
// 物料清理方法
|
||||
clearMaterials, // 清空所有物料
|
||||
clearBlockResources, // 清空区块缓存，以便更新最新版区块
|
||||
|
||||
getBlockByName, // 通过区块名称获取区块
|
||||
getBlockCompileRes, // 获取区块编译结果
|
||||
addBlockResources, // 增加区块缓存，参数: (id: string, resource: BlockResource) => void
|
||||
updateBlockCompileCache, // 更新区块编译缓存
|
||||
|
||||
// 依赖相关方法
|
||||
getCanvasDeps, // 组装画布依赖，包含物料和工具类的依赖
|
||||
updateCanvasDeps, // 通知画布更新依赖
|
||||
|
||||
// 配置相关方法
|
||||
getConfigureMap // 获取物料组件的配置信息，返回组件名到配置的映射
|
||||
}
|
||||
```
|
||||
|
||||
**使用示例**
|
||||
|
||||
```js
|
||||
// 初始化物料
|
||||
useMaterial().initMaterial({ isInit: true, appData }) // appData为远程拉取的应用数据
|
||||
|
||||
// 获取单个物料
|
||||
const material = useMaterial().getMaterial('ComponentName')
|
||||
|
||||
// 生成组件节点
|
||||
const node = useMaterial().generateNode({ type: 'component', component: 'Button' })
|
||||
|
||||
// 注册新区块
|
||||
await useMaterial().registerBlock('blockName')
|
||||
|
||||
// 刷新物料
|
||||
await useMaterial().refreshMaterial()
|
||||
```
|
||||
|
||||
#### 主要API详解
|
||||
|
||||
##### 初始化和请求相关方法
|
||||
|
||||
1. `initMaterial`：初始化物料模块
|
||||
|
||||
```js
|
||||
/**
|
||||
* 初始化物料模块，设置组件映射，处理依赖
|
||||
* @param {object} options - 初始化选项
|
||||
* @param {boolean} options.isInit - 是否为首次初始化，默认为true
|
||||
* @param {object} options.appData - 应用数据，包含组件映射等信息
|
||||
*/
|
||||
initMaterial({ isInit = true, appData = {} })
|
||||
```
|
||||
|
||||
2. `fetchMaterial`：请求并处理物料
|
||||
|
||||
```js
|
||||
/**
|
||||
* 请求物料数据并进行处理，将物料添加到系统中
|
||||
* @returns {Promise<void>}
|
||||
*/
|
||||
fetchMaterial()
|
||||
```
|
||||
|
||||
3. `refreshMaterial`：刷新物料
|
||||
|
||||
```js
|
||||
/**
|
||||
* 刷新物料，先清空所有物料，再重新初始化和请求
|
||||
* @returns {Promise<void>}
|
||||
*/
|
||||
refreshMaterial()
|
||||
```
|
||||
|
||||
使用场景：二开工程中，允许用户上传物料，或者是动态更新物料后，需要刷新物料，此时可以调用该方法。
|
||||
|
||||
|
||||
##### 物料资源获取方法
|
||||
|
||||
1. `getMaterialsRes`：获取物料资源
|
||||
|
||||
```js
|
||||
/**
|
||||
* 获取物料，并返回符合物料协议的bundle.json内容
|
||||
* @returns {Promise<Material[]>} - 返回物料数据数组
|
||||
*/
|
||||
getMaterialsRes()
|
||||
```
|
||||
|
||||
2. `getMaterial`：获取单个物料
|
||||
|
||||
```js
|
||||
/**
|
||||
* 获取单个物料信息
|
||||
* @param {string} name - 物料名称
|
||||
* @returns {Partial<Resource & BlockResource>} - 返回物料信息
|
||||
*/
|
||||
getMaterial(name)
|
||||
```
|
||||
|
||||
3. `getComponentsByGroup`：按组获取组件
|
||||
|
||||
```js
|
||||
/**
|
||||
* 根据组名获取指定分组下的组件
|
||||
* @param {Component[]} components - 组件列表
|
||||
* @param {string} groupName - 组名
|
||||
* @returns {Component[]} - 返回组内的组件
|
||||
*/
|
||||
getComponentsByGroup(components, groupName)
|
||||
```
|
||||
|
||||
##### 物料操作方法
|
||||
|
||||
1. `generateNode`：生成组件节点
|
||||
|
||||
```js
|
||||
/**
|
||||
* 根据组件信息生成组件schema节点
|
||||
* @param {object} params - 组件参数
|
||||
* @param {string} params.type - 组件类型，如'component'或'block'
|
||||
* @param {string} params.component - 组件名称
|
||||
* @returns {Schema} - 返回组件Schema
|
||||
*/
|
||||
generateNode({ type, component })
|
||||
```
|
||||
|
||||
2. `setMaterial`：设置单个物料
|
||||
|
||||
```js
|
||||
/**
|
||||
* 设置单个物料信息
|
||||
* @param {string} name - 物料名称
|
||||
* @param {Resource} data - 物料数据
|
||||
*/
|
||||
setMaterial(name, data)
|
||||
```
|
||||
|
||||
3. `addMaterials`：添加多个物料
|
||||
|
||||
```js
|
||||
/**
|
||||
* 添加多个物料到系统中
|
||||
* @param {Material} materials - 物料包数据
|
||||
*/
|
||||
addMaterials(materials)
|
||||
```
|
||||
|
||||
##### 区块相关方法
|
||||
|
||||
1. `addBlockResources`：添加区块资源
|
||||
|
||||
```js
|
||||
/**
|
||||
* 增加区块缓存
|
||||
* @param {string} id - 区块ID(即label字段)
|
||||
* @param {BlockResource} resource - 区块资源信息
|
||||
*/
|
||||
addBlockResources(id, resource)
|
||||
```
|
||||
|
||||
##### 依赖管理方法
|
||||
|
||||
1. `getCanvasDeps`：获取画布依赖
|
||||
|
||||
```js
|
||||
/**
|
||||
* 获取画布所需的依赖
|
||||
* @returns {object} - 返回包含scripts和styles的对象
|
||||
*/
|
||||
getCanvasDeps()
|
||||
```
|
||||
|
||||
2. `updateCanvasDeps`：更新画布依赖
|
||||
|
||||
```js
|
||||
/**
|
||||
* 通知画布更新依赖
|
||||
*/
|
||||
updateCanvasDeps()
|
||||
```
|
||||
|
||||
使用场景：如果需要画布刷新 script 或者 import-map 的时候，可以调用此方法让画布重新加载。（该方法会调用 getCanvasDeps 方法，获取画布依赖，并通知画布更新依赖）
|
||||
|
||||
#### 物料类型结构
|
||||
主要的物料类型定义包括：
|
||||
|
||||
1. `Material`: 物料包定义，符合物料协议的bundle.json内容
|
||||
```ts
|
||||
interface Material {
|
||||
components: Component[]; // 组件列表
|
||||
blocks?: Block[]; // 区块列表
|
||||
snippets?: Snippet[]; // 物料分组列表
|
||||
packages?: Dependency[]; // 物料依赖的包
|
||||
}
|
||||
```
|
||||
|
||||
2. `Component`: 组件物料定义
|
||||
```ts
|
||||
interface Component {
|
||||
component: string; // 组件名称
|
||||
group: string; // 组件分组
|
||||
npm?: { // 组件NPM包信息
|
||||
package: string; // 包名
|
||||
script?: string; // 脚本路径
|
||||
exportName: string; // 导出名称
|
||||
css?: string; // 样式路径
|
||||
};
|
||||
schema?: Schema; // 组件配置信息
|
||||
}
|
||||
```
|
||||
|
||||
3. `Block`: 区块物料定义
|
||||
```ts
|
||||
interface Block {
|
||||
label: string; // 区块标识
|
||||
blockName: string; // 区块名称
|
||||
version?: string; // 区块版本
|
||||
description?: string; // 区块描述
|
||||
screenshot?: string; // 区块截图
|
||||
content?: BlockResource; // 区块内容
|
||||
}
|
||||
```
|
||||
|
||||
#### 使用场景示例
|
||||
|
||||
1. 初始化物料并加载到系统
|
||||
|
||||
```js
|
||||
import { useMaterial } from '@opentiny/tiny-engine'
|
||||
|
||||
// 初始化物料
|
||||
export const initApp = async (appData) => {
|
||||
const material = useMaterial()
|
||||
// 初始化物料，传入应用数据
|
||||
material.initMaterial({ isInit: true, appData })
|
||||
// 请求并处理物料
|
||||
await material.fetchMaterial()
|
||||
// 更新画布依赖
|
||||
material.updateCanvasDeps()
|
||||
}
|
||||
```
|
||||
|
||||
2. 创建新组件并添加到画布
|
||||
|
||||
```js
|
||||
import { useMaterial, useCanvas } from '@opentiny/tiny-engine'
|
||||
|
||||
export const addComponent = (componentName) => {
|
||||
const material = useMaterial()
|
||||
const canvas = useCanvas()
|
||||
|
||||
// 生成组件节点
|
||||
const schema = material.generateNode({
|
||||
type: 'component',
|
||||
component: componentName
|
||||
})
|
||||
|
||||
// 添加到画布
|
||||
canvas.canvasApi.value.addComponent(schema)
|
||||
}
|
||||
```
|
||||
|
||||
3. 获取物料配置信息
|
||||
|
||||
```js
|
||||
import { useMaterial } from '@opentiny/tiny-engine'
|
||||
|
||||
export const getComponentConfigure = (componentName) => {
|
||||
const material = useMaterial()
|
||||
|
||||
// 获取单个物料信息
|
||||
const componentInfo = material.getMaterial(componentName)
|
||||
|
||||
// 获取组件配置
|
||||
const configureMap = material.getConfigureMap()
|
||||
const configure = configureMap[componentName]
|
||||
|
||||
return { componentInfo, configure }
|
||||
}
|
||||
```
|
||||
|
||||
4. 刷新物料
|
||||
|
||||
```js
|
||||
import { useMaterial } from '@opentiny/tiny-engine'
|
||||
|
||||
export const handleUploadMaterial = async (material) => {
|
||||
// 1. 允许用户上传物料
|
||||
getMetaApi(META_SERVICE.Http).post('xxx/upload', material)
|
||||
// 2. 刷新物料, 让画布重新加载，并在物料插件更新列表。
|
||||
const material = useMaterial()
|
||||
await material.refreshMaterial()
|
||||
}
|
||||
```
|
||||
> **使用示例**
|
||||
>
|
||||
> ```useMaterial().initMaterial({ isInit: true, appData }) // appData为远程拉取的应用数据```
|
||||
|
|
@ -121,3 +121,83 @@ const register = {
|
|||
plugins: [Materials, Tree, customPlugin],
|
||||
}
|
||||
```
|
||||
|
||||
## engine.config 配置项详解
|
||||
|
||||
engine.config 是注册表中的重要配置项，它控制着低代码引擎的核心行为。
|
||||
|
||||
engine.config 配置示例：
|
||||
|
||||
```javascript
|
||||
const registry = {
|
||||
config: {
|
||||
id: 'engine.config',
|
||||
theme: 'light',
|
||||
material: ['/mock/bundle.json'],
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
以下是 engine.config 中关键配置项的详细说明：
|
||||
|
||||
### material 配置
|
||||
|
||||
material 配置用于指定物料资源的来源，它接受一个数组，每个元素表示一个物料资源的 URL 路径, 也可以是 JSON 对象。
|
||||
注：JSON 对象的格式需要符合 TinyEngine 的物料格式。直接配置 JSON 对象的形式 v2.5+ 版本开始支持。
|
||||
|
||||
```javascript
|
||||
import bundle from './bundle.json'
|
||||
// engine.config.js 示例
|
||||
export default {
|
||||
// ...
|
||||
material: ['/mock/bundle.json', bundle],
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
- 物料资源通常是 JSON 格式的文件，包含了组件的元数据信息
|
||||
- 支持配置多个物料源，引擎会按照顺序加载这些物料
|
||||
- 如果多个物料源中存在同名组件，后加载的会覆盖先加载的
|
||||
|
||||
### theme 配置
|
||||
|
||||
theme 配置用于指定低代码平台的主题，它接受一个字符串值，对应注册表中 themes 数组里定义的主题 type。
|
||||
|
||||
```javascript
|
||||
// engine.config.js 示例
|
||||
export default {
|
||||
// ...
|
||||
theme: 'light', // 或 'dark'，对应 themes 数组中的主题 type
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
主题的定义示例：
|
||||
|
||||
```javascript
|
||||
const registry = {
|
||||
// ...
|
||||
// 默认的 theme 配置
|
||||
themes: [
|
||||
{
|
||||
id: 'engine.theme.light',
|
||||
text: '浅色主题',
|
||||
type: 'light',
|
||||
icon: 'light',
|
||||
oppositeTheme: 'dark'
|
||||
},
|
||||
{
|
||||
id: 'engine.theme.dark',
|
||||
text: '深色主题',
|
||||
type: 'dark',
|
||||
icon: 'dark',
|
||||
oppositeTheme: 'light'
|
||||
}
|
||||
],
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
- theme 的值需要与注册表中 themes 数组里某个主题的 type 相匹配
|
||||
- 主题切换可以通过修改此配置项的值来实现
|
||||
- 主题会影响整个低代码平台的视觉样式
|
||||
|
|
|
|||
Loading…
Reference in New Issue