github/lowcode-engine
1
0
Fork 0
mirror of https://github.com/alibaba/lowcode-engine.git synced 2025-12-11 02:12:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(props): optimize api doc for model/props, and fix related lint issues

Browse Source
This commit is contained in:
JackLian 2023-01-06 18:14:35 +08:00 committed by 刘菊萍(絮黎)
parent 76f612b29c
commit d3f533d482
6 changed files with 319 additions and 186 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.eslintrc.js
View File

@ -48,5 +48,9 @@ module.exports = {
"afterLineComment": false,
"allowBlockStart": true,
}],
"@typescript-eslint/member-ordering": [
"error",
{ "default": ["signature", "field", "constructor", "method"] }
],
}
};
};

126
docs/docs/api/model/props.md
View File

@ -13,46 +13,148 @@ sidebar_position: 4
### id
id
`@type {string}`
### path
返回当前 props 的路径
`@type {string[]}`
### node
返回当前属性集所属的节点实例
`@type {IPublicModelNode | null}`
相关类型：[IPublicModelNode](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/node.ts)
## 方法签名
### getProp
getProp(path: string): Prop | null
获取指定 path 的属性模型实例
```typescript
/**
* 获取指定 path 的属性模型实例
* get prop by path
* @param path 属性路径，支持 a / a.b / a.0 等格式
*/
getProp(path: string): IPublicModelProp | null;
```
相关类型：[IPublicModelProp](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/prop.ts)
### getPropValue
getPropValue(path: string)
获取指定 path 的属性模型实例值
```typescript
/**
* 获取指定 path 的属性模型实例值
* get value of prop by path
* @param path 属性路径，支持 a / a.b / a.0 等格式
*/
getPropValue(path: string): any;
```
### getExtraProp
getExtraProp(path: string): Prop | null
获取指定 path 的属性模型实例，注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级
```typescript
/**
* 获取指定 path 的属性模型实例，
* 注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级
* get extra prop by path
* @param path 属性路径，支持 a / a.b / a.0 等格式
*/
getExtraProp(path: string): IPublicModelProp | null;
```
相关类型：[IPublicModelProp](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/model/prop.ts)
### getExtraPropValue
getExtraPropValue(path: string)
获取指定 path 的属性模型实例值，注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级
```typescript
/**
* 获取指定 path 的属性模型实例值
* 注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级
* get value of extra prop by path
* @param path 属性路径，支持 a / a.b / a.0 等格式
*/
getExtraPropValue(path: string): any;
```
### setPropValue
setPropValue(path: string, value: CompositeValue)
设置指定 path 的属性模型实例值
```typescript
/**
* 设置指定 path 的属性模型实例值
* set value of prop by path
* @param path 属性路径，支持 a / a.b / a.0 等格式
* @param value 值
*/
setPropValue(path: string, value: IPublicTypeCompositeValue): void;
```
相关类型：[IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts)
### setExtraPropValue
setExtraPropValue(path: string, value: CompositeValue)
设置指定 path 的属性模型实例值
设置指定 path 的属性模型实例值
```typescript
/**
* 设置指定 path 的属性模型实例值
* set value of extra prop by path
* @param path 属性路径，支持 a / a.b / a.0 等格式
* @param value 值
*/
setExtraPropValue(path: string, value: IPublicTypeCompositeValue): void;
```
相关类型：[IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts)
### has
当前 props 是否包含某 prop
```typescript
/**
* 当前 props 是否包含某 prop
* check if the specified key is existing or not.
* @param key
* @since v1.1.0
*/
has(key: string): boolean;
```
**@since v1.1.0**
### add
添加一个 prop
```typescript
/**
* 添加一个 prop
* add a key with given value
* @param value
* @param key
* @since v1.1.0
*/
add(value: IPublicTypeCompositeValue, key?: string | number | undefined): any;
```
相关类型：[IPublicTypeCompositeValue](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/composite-value.ts)
**@since v1.1.0**

298
packages/designer/src/document/node/props/prop.ts
View File

@ -2,7 +2,7 @@ import { untracked, computed, obx, engineConfig, action, makeObservable, mobx, r
import { IPublicTypeCompositeValue, GlobalEvent, IPublicTypeJSSlot, IPublicTypeSlotSchema, IPublicEnumTransformStage, IPublicModelProp } from '@alilc/lowcode-types';
import { uniqueId, isPlainObject, hasOwnProperty, compatStage, isJSExpression, isJSSlot } from '@alilc/lowcode-utils';
import { valueToSource } from './value-to-source';
import { Props } from './props';
import { Props, IProps, IPropParent } from './props';
import { SlotNode, INode } from '../node';
// import { TransformStage } from '../transform-stage';
@ -13,12 +13,12 @@ export type UNSET = typeof UNSET;
export interface IProp extends Omit<IPublicModelProp, 'exportSchema' | 'node'> {
delete(prop: Prop): void;
readonly props: Props;
readonly owner: INode;
delete(prop: Prop): void;
export(stage: IPublicEnumTransformStage): IPublicTypeCompositeValue;
getNode(): INode;
@ -26,7 +26,7 @@ export interface IProp extends Omit<IPublicModelProp, 'exportSchema' | 'node'> {
export type ValueTypes = 'unset' | 'literal' | 'map' | 'list' | 'expression' | 'slot';
export class Prop implements IProp {
export class Prop implements IProp, IPropParent {
readonly isProp = true;
readonly owner: INode;
@ -45,8 +45,152 @@ export class Prop implements IProp {
readonly options: any;
readonly id = uniqueId('prop$');
@obx.ref private _type: ValueTypes = 'unset';
/**
* 属性类型
*/
get type(): ValueTypes {
return this._type;
}
@obx private _value: any = UNSET;
/**
* 属性值
*/
@computed get value(): IPublicTypeCompositeValue | UNSET {
return this.export(IPublicEnumTransformStage.Serilize);
}
private _code: string | null = null;
/**
* 获得表达式值
*/
@computed get code() {
if (isJSExpression(this.value)) {
return this.value.value;
}
// todo: JSFunction ...
if (this.type === 'slot') {
return JSON.stringify(this._slotNode!.export(IPublicEnumTransformStage.Save));
}
return this._code != null ? this._code : JSON.stringify(this.value);
}
/**
* 设置表达式值
*/
set code(code: string) {
if (isJSExpression(this._value)) {
this.setValue({
...this._value,
value: code,
});
this._code = code;
return;
}
try {
const v = JSON.parse(code);
this.setValue(v);
this._code = code;
return;
} catch (e) {
// ignore
}
this.setValue({
type: 'JSExpression',
value: code,
mock: this._value,
});
this._code = code;
}
private _slotNode?: INode;
get slotNode(): INode | undefined | null {
return this._slotNode;
}
@obx.shallow private _items: Prop[] | null = null;
@obx.shallow private _maps: Map<string | number, Prop> | null = null;
/**
* 作为 _maps 的一层缓存机制，主要是复用部分已存在的 Prop，保持响应式关系，比如：
* 当前 Prop#_value 值为 { a: 1 }，当调用 setValue({ a: 2 }) 时，所有原来的子 Prop 均被销毁，
* 导致假如外部有 mobx reaction（常见于 observer），此时响应式链路会被打断，
* 因为 reaction 监听的是原 Prop(a) 的 _value，而不是新 Prop(a) 的 _value。
*/
private _prevMaps: Map<string | number, Prop> | null = null;
/**
* 构造 items 属性，同时构造 maps 属性
*/
private get items(): Prop[] | null {
if (this._items) return this._items;
return runInAction(() => {
let items: Prop[] | null = null;
if (this._type === 'list') {
const data = this._value;
data.forEach((item: any, idx: number) => {
items = items || [];
items.push(new Prop(this, item, idx));
});
this._maps = null;
} else if (this._type === 'map') {
const data = this._value;
const maps = new Map<string, Prop>();
const keys = Object.keys(data);
for (const key of keys) {
let prop: Prop;
if (this._prevMaps?.has(key)) {
prop = this._prevMaps.get(key)!;
prop.setValue(data[key]);
} else {
prop = new Prop(this, data[key], key);
}
items = items || [];
items.push(prop);
maps.set(key, prop);
}
this._maps = maps;
} else {
items = null;
this._maps = null;
}
this._items = items;
return this._items;
});
}
@computed private get maps(): Map<string | number, Prop> | null {
if (!this.items) {
return null;
}
return this._maps;
}
get path(): string[] {
return (this.parent.path || []).concat(this.key as string);
}
/**
* 元素个数
*/
get size(): number {
return this.items?.length || 0;
}
private purged = false;
constructor(
public parent: IProp,
public parent: IPropParent,
value: IPublicTypeCompositeValue | UNSET = UNSET,
key?: string | number,
spread = false,
@ -94,26 +238,6 @@ export class Prop implements IProp {
this.get(propName, false)?.unset();
}
readonly id = uniqueId('prop$');
@obx.ref private _type: ValueTypes = 'unset';
/**
* 属性类型
*/
get type(): ValueTypes {
return this._type;
}
@obx private _value: any = UNSET;
/**
* 属性值
*/
@computed get value(): IPublicTypeCompositeValue | UNSET {
return this.export(IPublicEnumTransformStage.Serilize);
}
export(stage: IPublicEnumTransformStage = IPublicEnumTransformStage.Save): IPublicTypeCompositeValue {
stage = compatStage(stage);
const type = this._type;
@ -186,52 +310,6 @@ export class Prop implements IProp {
}
}
private _code: string | null = null;
/**
* 获得表达式值
*/
@computed get code() {
if (isJSExpression(this.value)) {
return this.value.value;
}
// todo: JSFunction ...
if (this.type === 'slot') {
return JSON.stringify(this._slotNode!.export(IPublicEnumTransformStage.Save));
}
return this._code != null ? this._code : JSON.stringify(this.value);
}
/**
* 设置表达式值
*/
set code(code: string) {
if (isJSExpression(this._value)) {
this.setValue({
...this._value,
value: code,
});
this._code = code;
return;
}
try {
const v = JSON.parse(code);
this.setValue(v);
this._code = code;
return;
} catch (e) {
// ignore
}
this.setValue({
type: 'JSExpression',
value: code,
mock: this._value,
});
this._code = code;
}
getAsString(): string {
if (this.type === 'literal') {
return this._value ? String(this._value) : '';
@ -311,12 +389,6 @@ export class Prop implements IProp {
}
}
private _slotNode?: INode;
get slotNode(): INode | undefined | null {
return this._slotNode;
}
@action
setAsSlot(data: IPublicTypeJSSlot) {
this._type = 'slot';
@ -397,69 +469,6 @@ export class Prop implements IProp {
return this.code === other.code ? 0 : 2;
}
@obx.shallow private _items: Prop[] | null = null;
@obx.shallow private _maps: Map<string | number, Prop> | null = null;
/**
* 作为 _maps 的一层缓存机制，主要是复用部分已存在的 Prop，保持响应式关系，比如：
* 当前 Prop#_value 值为 { a: 1 }，当调用 setValue({ a: 2 }) 时，所有原来的子 Prop 均被销毁，
* 导致假如外部有 mobx reaction（常见于 observer），此时响应式链路会被打断，
* 因为 reaction 监听的是原 Prop(a) 的 _value，而不是新 Prop(a) 的 _value。
*/
private _prevMaps: Map<string | number, Prop> | null = null;
get path(): string[] {
return (this.parent.path || []).concat(this.key as string);
}
/**
* 构造 items 属性，同时构造 maps 属性
*/
private get items(): Prop[] | null {
if (this._items) return this._items;
return runInAction(() => {
let items: Prop[] | null = null;
if (this._type === 'list') {
const data = this._value;
data.forEach((item: any, idx: number) => {
items = items || [];
items.push(new Prop(this, item, idx));
});
this._maps = null;
} else if (this._type === 'map') {
const data = this._value;
const maps = new Map<string, Prop>();
const keys = Object.keys(data);
for (const key of keys) {
let prop: Prop;
if (this._prevMaps?.has(key)) {
prop = this._prevMaps.get(key)!;
prop.setValue(data[key]);
} else {
prop = new Prop(this, data[key], key);
}
items = items || [];
items.push(prop);
maps.set(key, prop);
}
this._maps = maps;
} else {
items = null;
this._maps = null;
}
this._items = items;
return this._items;
});
}
@computed private get maps(): Map<string | number, Prop> | null {
if (!this.items) {
return null;
}
return this._maps;
}
/**
* 获取某个属性
* @param createIfNone 当没有的时候，是否创建一个
@ -552,13 +561,6 @@ export class Prop implements IProp {
}
}
/**
* 元素个数
*/
get size(): number {
return this.items?.length || 0;
}
/**
* 添加值到列表
*
@ -648,8 +650,6 @@ export class Prop implements IProp {
return hasOwnProperty(this._value, key);
}
private purged = false;
/**
* 回收销毁
*/

39
packages/designer/src/document/node/props/props.ts
View File

@ -1,8 +1,8 @@
import { computed, makeObservable, obx, action } from '@alilc/lowcode-editor-core';
import { IPublicTypePropsMap, IPublicTypePropsList, IPublicTypeCompositeValue, IPublicEnumTransformStage } from '@alilc/lowcode-types';
import { IPublicTypePropsMap, IPublicTypePropsList, IPublicTypeCompositeValue, IPublicEnumTransformStage, IPublicModelProps } from '@alilc/lowcode-types';
import { uniqueId, compatStage } from '@alilc/lowcode-utils';
import { Prop, IProp, UNSET } from './prop';
import { Node } from '../node';
import { INode, Node } from '../node';
// import { TransformStage } from '../transform-stage';
interface ExtrasObject {
@ -23,7 +23,30 @@ export function getConvertedExtraKey(key: string): string {
export function getOriginalExtraKey(key: string): string {
return key.replace(new RegExp(`${EXTRA_KEY_PREFIX}`, 'g'), '');
}
export class Props implements IProp {
export interface IPropParent {
readonly props: Props;
readonly owner: INode;
get path(): string[];
delete(prop: Prop): void;
}
export interface IProps extends Omit<IPublicModelProps, 'getProp' | 'getExtraProp' | 'getExtraPropValue' | 'setExtraPropValue' | 'node'> {
/**
* 获取 props 对应的 node
*/
getNode(): INode;
getProp(path: string): IProp | null;
}
export class Props implements IProps, IPropParent {
readonly id = uniqueId('props');
@obx.shallow private items: Prop[] = [];
@ -46,7 +69,7 @@ export class Props implements IProp {
return this;
}
readonly owner: Node;
readonly owner: INode;
/**
* 元素个数
@ -57,7 +80,9 @@ export class Props implements IProp {
@obx type: 'map' | 'list' = 'map';
constructor(owner: Node, value?: IPublicTypePropsMap | IPublicTypePropsList | null, extras?: ExtrasObject) {
private purged = false;
constructor(owner: INode, value?: IPublicTypePropsMap | IPublicTypePropsList | null, extras?: ExtrasObject) {
makeObservable(this);
this.owner = owner;
if (Array.isArray(value)) {
@ -196,7 +221,7 @@ export class Props implements IProp {
}
/**
* 获取某个属性, 如果不存在，临时获取一个待写入
* 获取某个属性，如果不存在，临时获取一个待写入
* @param createIfNone 当没有的时候，是否创建一个
*/
@action
@ -323,8 +348,6 @@ export class Props implements IProp {
});
}
private purged = false;
/**
* 回收销毁
*/

12
packages/shell/src/model/props.ts
View File

@ -1,8 +1,8 @@
import { IProp as InnerProps, getConvertedExtraKey } from '@alilc/lowcode-designer';
import { IProps as InnerProps, getConvertedExtraKey } from '@alilc/lowcode-designer';
import { IPublicTypeCompositeValue, IPublicModelProps, IPublicModelNode, IPublicModelProp } from '@alilc/lowcode-types';
import { propsSymbol } from '../symbols';
import { Node } from './node';
import { Prop } from './prop';
import { Node as ShellNode } from './node';
import { Prop as ShellProp } from './prop';
export class Props implements IPublicModelProps {
private readonly [propsSymbol]: InnerProps;
@ -36,7 +36,7 @@ export class Props implements IPublicModelProps {
* 返回所属的 node 实例
*/
get node(): IPublicModelNode | null {
return Node.create(this[propsSymbol].getNode());
return ShellNode.create(this[propsSymbol].getNode());
}
/**
@ -45,7 +45,7 @@ export class Props implements IPublicModelProps {
* @returns
*/
getProp(path: string): IPublicModelProp | null {
return Prop.create(this[propsSymbol].getProp(path));
return ShellProp.create(this[propsSymbol].getProp(path));
}
/**
@ -64,7 +64,7 @@ export class Props implements IPublicModelProps {
* @returns
*/
getExtraProp(path: string): IPublicModelProp | null {
return Prop.create(this[propsSymbol].getProp(getConvertedExtraKey(path)));
return ShellProp.create(this[propsSymbol].getProp(getConvertedExtraKey(path)));
}
/**

24
packages/types/src/shell/model/props.ts
View File

@ -2,6 +2,7 @@ import { IPublicTypeCompositeValue } from '../type';
import { IPublicModelNode, IPublicModelProp } from './';
export interface IPublicModelProps {
/**
* id
*/
@ -9,8 +10,9 @@ export interface IPublicModelProps {
/**
* 返回当前 props 的路径
* return path of current props
*/
get path(): any[];
get path(): string[];
/**
* 返回所属的 node 实例
@ -19,62 +21,64 @@ export interface IPublicModelProps {
/**
* 获取指定 path 的属性模型实例
* get prop by path
* @param path 属性路径，支持 a / a.b / a.0 等格式
* @returns
*/
getProp(path: string): IPublicModelProp | null;
/**
* 获取指定 path 的属性模型实例值
* get value of prop by path
* @param path 属性路径，支持 a / a.b / a.0 等格式
* @returns
*/
getPropValue(path: string): any;
/**
* 获取指定 path 的属性模型实例，
* 注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级
* get extra prop by path
* @param path 属性路径，支持 a / a.b / a.0 等格式
* @returns
*/
getExtraProp(path: string): IPublicModelProp | null;
/**
* 获取指定 path 的属性模型实例值
* 注：导出时，不同于普通属性，该属性并不挂载在 props 之下，而是与 props 同级
* get value of extra prop by path
* @param path 属性路径，支持 a / a.b / a.0 等格式
* @returns
*/
getExtraPropValue(path: string): any;
/**
* 设置指定 path 的属性模型实例值
* set value of prop by path
* @param path 属性路径，支持 a / a.b / a.0 等格式
* @param value 值
* @returns
*/
setPropValue(path: string, value: IPublicTypeCompositeValue): void;
/**
* 设置指定 path 的属性模型实例值
* set value of extra prop by path
* @param path 属性路径，支持 a / a.b / a.0 等格式
* @param value 值
* @returns
*/
setExtraPropValue(path: string, value: IPublicTypeCompositeValue): void;
/**
* test if the specified key is existing or not.
* 当前 props 是否包含某 prop
* check if the specified key is existing or not.
* @param key
* @returns
* @since v1.1.0
*/
has(key: string): boolean;
/**
* 添加一个 prop
* add a key with given value
* @param value
* @param key
* @returns
* @since v1.1.0
*/
add(value: IPublicTypeCompositeValue, key?: string | number | undefined): any;