Skip to content

Commit fec8805

Browse files
JackLianliujuping
JackLian
authored and
liujuping
committed
docs(history): optimize api doc for model/history, and fix related lint issues
1 parent ea08173 commit fec8805

5 files changed

Lines changed: 127 additions & 41 deletions

File tree

‎docs/docs/api/model/history.md‎

Lines changed: 80 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -12,47 +12,113 @@ sidebar_position: 5
1212
## 方法签名
1313
### go
1414

15-
go(cursor: number)
16-
1715
历史记录跳转到指定位置
1816

19-
### back
17+
```typescript
18+
/**
19+
* 历史记录跳转到指定位置
20+
* go to a specific history
21+
* @param cursor
22+
*/
23+
go(cursor: number): void;
24+
```
2025

21-
back()
26+
### back
2227

2328
历史记录后退
2429

30+
```typescript
31+
/**
32+
* 历史记录后退
33+
* go backward in history
34+
*/
35+
back(): void;
36+
```
37+
2538
### forward
2639

2740
forward()
2841

2942
历史记录前进
30-
### savePoint
3143

32-
savePoint()
44+
```typescript
45+
/**
46+
* 历史记录前进
47+
* go forward in history
48+
*/
49+
forward(): void;
50+
```
51+
52+
### savePoint
3353

3454
保存当前状态
35-
### isSavePoint
3655

37-
isSavePoint()
56+
```typescript
57+
/**
58+
* 保存当前状态
59+
* do save current change as a record in history
60+
*/
61+
savePoint(): void;
62+
```
63+
64+
### isSavePoint
3865

3966
当前是否是「保存点」，即是否有状态变更但未保存
4067

41-
### getState
68+
```typescript
69+
/**
70+
* 当前是否是「保存点」，即是否有状态变更但未保存
71+
* check if there is unsaved change for history
72+
*/
73+
isSavePoint(): boolean;
74+
```
4275

43-
getState()
76+
### getState
4477

4578
获取 state，判断当前是否为「可回退」、「可前进」的状态
4679

80+
```typescript
81+
/**
82+
* 获取 state，判断当前是否为「可回退」、「可前进」的状态
83+
* get flags in number which indicat current change state
84+
*
85+
* | 1 | 1 | 1 |
86+
* | -------- | -------- | -------- |
87+
* | modified | redoable | undoable |
88+
* eg:
89+
* 7 means : modified && redoable && undoable
90+
* 5 means : modified && undoable
91+
*/
92+
getState(): number;
93+
```
94+
4795
## 事件
4896
### onChangeState
4997

50-
onChangeState(func: () => any)
51-
5298
监听 state 变更事件
5399

54-
### onChangeCursor
100+
```typescript
101+
/**
102+
* 监听 state 变更事件
103+
* monitor on stateChange event
104+
* @param func
105+
*/
106+
onChangeState(func: () => any): IPublicTypeDisposable;
107+
```
55108

56-
onChangeCursor(func: () => any)
109+
相关类型：[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts)
110+
111+
### onChangeCursor
57112

58113
监听历史记录游标位置变更事件
114+
115+
```typescript
116+
/**
117+
* 监听历史记录游标位置变更事件
118+
* monitor on cursorChange event
119+
* @param func
120+
*/
121+
onChangeCursor(func: () => any): IPublicTypeDisposable;
122+
```
123+
124+
相关类型：[IPublicTypeDisposable](https://github.com/alibaba/lowcode-engine/blob/main/packages/types/src/shell/type/disposable.ts)

‎packages/designer/src/document/history.ts‎

Lines changed: 19 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
import { reaction, untracked, globalContext, IEventBus, createModuleEventBus } from '@alilc/lowcode-editor-core';
22
import { IPublicTypeNodeSchema, IPublicModelHistory } from '@alilc/lowcode-types';
3+
import { Logger } from '@alilc/lowcode-utils';
4+
5+
const logger = new Logger({ level: 'warn', bizName: 'history' });
36

47
export interface Serialization<K = IPublicTypeNodeSchema, T = string> {
58
serialize(data: K): T;
@@ -30,11 +33,15 @@ export class History<T = IPublicTypeNodeSchema> implements IHistory {
3033
},
3134
};
3235

33-
setSerialization(serialization: Serialization<T, string>) {
34-
this.currentSerialization = serialization;
36+
get hotData() {
37+
return this.session.data;
3538
}
3639

37-
constructor(dataFn: () => T | null, private redoer: (data: T) => void, private timeGap: number = 1000) {
40+
constructor(
41+
dataFn: () => T | null,
42+
private redoer: (data: T) => void,
43+
private timeGap: number = 1000,
44+
) {
3845
this.session = new Session(0, null, this.timeGap);
3946
this.records = [this.session];
4047

@@ -68,8 +75,8 @@ export class History<T = IPublicTypeNodeSchema> implements IHistory {
6875
}, { fireImmediately: true });
6976
}
7077

71-
get hotData() {
72-
return this.session.data;
78+
setSerialization(serialization: Serialization<T, string>) {
79+
this.currentSerialization = serialization;
7380
}
7481

7582
isSavePoint(): boolean {
@@ -84,16 +91,18 @@ export class History<T = IPublicTypeNodeSchema> implements IHistory {
8491
this.asleep = false;
8592
}
8693

87-
go(cursor: number) {
94+
go(originalCursor: number) {
8895
this.session.end();
8996

90-
const currentCursor = this.session.cursor;
97+
let cursor = originalCursor;
9198
cursor = +cursor;
9299
if (cursor < 0) {
93100
cursor = 0;
94101
} else if (cursor >= this.records.length) {
95102
cursor = this.records.length - 1;
96103
}
104+
105+
const currentCursor = this.session.cursor;
97106
if (cursor === currentCursor) {
98107
return;
99108
}
@@ -106,7 +115,7 @@ export class History<T = IPublicTypeNodeSchema> implements IHistory {
106115
this.redoer(this.currentSerialization.unserialize(hotData));
107116
this.emitter.emit('cursor', hotData);
108117
} catch (e) /* istanbul ignore next */ {
109-
console.error(e);
118+
logger.error(e);
110119
}
111120

112121
this.wakeup();
@@ -174,6 +183,7 @@ export class History<T = IPublicTypeNodeSchema> implements IHistory {
174183
}
175184
return state;
176185
}
186+
177187
/**
178188
* 监听 state 变更事件
179189
* @param func
@@ -209,6 +219,7 @@ export class History<T = IPublicTypeNodeSchema> implements IHistory {
209219
this.emitter.removeAllListeners();
210220
this.records = [];
211221
}
222+
212223
/**
213224
*
214225
* @deprecated

‎packages/editor-core/src/utils/preference.ts‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,12 @@ import store from 'store';
22
import { getLogger } from './logger';
33
import { IPublicModelPreference } from '@alilc/lowcode-types';
44

5-
const logger = getLogger({ level: 'log', bizName: 'Preference' });
5+
const logger = getLogger({ level: 'warn', bizName: 'Preference' });
66
const STORAGE_KEY_PREFIX = 'ale';
77

8-
98
/**
109
* used to store user preferences, such as pinned status of a pannel.
1110
* save to local storage.
12-
*
13-
* @class PreferenceStore
1411
*/
1512
export default class Preference implements IPublicModelPreference {
1613
getStorageKey(key: string, module?: string): string {
@@ -24,7 +21,7 @@ export default class Preference implements IPublicModelPreference {
2421
return;
2522
}
2623
const storageKey = this.getStorageKey(key, module);
27-
logger.log('storageKey:', storageKey, 'set with value:', value);
24+
logger.debug('storageKey:', storageKey, 'set with value:', value);
2825
store.set(storageKey, value);
2926
}
3027

@@ -35,16 +32,15 @@ export default class Preference implements IPublicModelPreference {
3532
}
3633
const storageKey = this.getStorageKey(key, module);
3734
const result = store.get(storageKey);
38-
logger.log('storageKey:', storageKey, 'get with result:', result);
35+
logger.debug('storageKey:', storageKey, 'get with result:', result);
3936
return result;
4037
}
38+
4139
/**
4240
* check if local storage contain certain key
4341
*
4442
* @param {string} key
4543
* @param {string} module
46-
* @returns {boolean}
47-
* @memberof Preference
4844
*/
4945
contains(key: string, module: string): boolean {
5046
if (!key || typeof key !== 'string' || key.length === 0) {

‎packages/shell/src/model/history.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { DocumentModel as InnerDocumentModel } from '@alilc/lowcode-designer';
22
import { historySymbol, documentSymbol } from '../symbols';
3-
import { IPublicModelHistory } from '@alilc/lowcode-types';
3+
import { IPublicModelHistory, IPublicTypeDisposable } from '@alilc/lowcode-types';
44

55
export class History implements IPublicModelHistory {
66
private readonly [documentSymbol]: InnerDocumentModel;
@@ -54,7 +54,7 @@ export class History implements IPublicModelHistory {
5454
* 获取 state，判断当前是否为「可回退」、「可前进」的状态
5555
* @returns
5656
*/
57-
getState(): any {
57+
getState(): number {
5858
return this[historySymbol].getState();
5959
}
6060

@@ -63,7 +63,7 @@ export class History implements IPublicModelHistory {
6363
* @param func
6464
* @returns
6565
*/
66-
onChangeState(func: () => any): () => void {
66+
onChangeState(func: () => any): IPublicTypeDisposable {
6767
return this[historySymbol].onStateChange(func);
6868
}
6969

@@ -72,7 +72,7 @@ export class History implements IPublicModelHistory {
7272
* @param func
7373
* @returns
7474
*/
75-
onChangeCursor(func: () => any): () => void {
75+
onChangeCursor(func: () => any): IPublicTypeDisposable {
7676
return this[historySymbol].onCursor(func);
7777
}
7878
}

‎packages/types/src/shell/model/history.ts‎

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,62 @@
1+
import { IPublicTypeDisposable } from '../type';
2+
13
export interface IPublicModelHistory {
24

35
/**
46
* 历史记录跳转到指定位置
7+
* go to a specific history
58
* @param cursor
69
*/
710
go(cursor: number): void;
811

912
/**
1013
* 历史记录后退
14+
* go backward in history
1115
*/
1216
back(): void;
1317

1418
/**
1519
* 历史记录前进
20+
* go forward in history
1621
*/
1722
forward(): void;
1823

1924
/**
2025
* 保存当前状态
26+
* do save current change as a record in history
2127
*/
2228
savePoint(): void;
2329

2430
/**
2531
* 当前是否是「保存点」，即是否有状态变更但未保存
26-
* @returns
32+
* check if there is unsaved change for history
2733
*/
2834
isSavePoint(): boolean;
2935

3036
/**
3137
* 获取 state，判断当前是否为「可回退」、「可前进」的状态
32-
* @returns
38+
* get flags in number which indicat current change state
39+
*
40+
* | 1 | 1 | 1 |
41+
* | -------- | -------- | -------- |
42+
* | modified | redoable | undoable |
43+
* eg:
44+
* 7 means : modified && redoable && undoable
45+
* 5 means : modified && undoable
3346
*/
34-
getState(): any;
47+
getState(): number;
3548

3649
/**
3750
* 监听 state 变更事件
51+
* monitor on stateChange event
3852
* @param func
39-
* @returns
4053
*/
41-
onChangeState(func: () => any): () => void;
54+
onChangeState(func: () => any): IPublicTypeDisposable;
4255

4356
/**
4457
* 监听历史记录游标位置变更事件
58+
* monitor on cursorChange event
4559
* @param func
46-
* @returns
4760
*/
48-
onChangeCursor(func: () => any): () => void;
61+
onChangeCursor(func: () => any): IPublicTypeDisposable;
4962
}

0 commit comments

Comments
 (0)