lcap-frontend-library 0.0.1

package/packages/lcap-frontend-library/references/lcap-extension-component/platform/accessibility.md

@@ -0,0 +1,185 @@
+---
+outline: deep
+---
+
+# 可访问性属性 <Badge type="tip" text="^3.9.0" />
+
+
+组件的[可访问属性](https://community.codewave.163.com/CommunityParent/fileIndex?filePath=20.%E5%BA%94%E7%94%A8%E5%BC%80%E5%8F%91%2F10.%E9%A1%B5%E9%9D%A2%E8%AE%BE%E8%AE%A1%2F19.%E7%BB%84%E4%BB%B6%E5%8F%AF%E8%AE%BF%E9%97%AE%E5%B1%9E%E6%80%A7.md&version=3.13)是指在逻辑或表达式的可视化编辑面板中能够直接被访问和操作的组件属性。
+
+在设计组件的可访问属性时，需定义可访问属性的能力，主要包括以下两个方面：
+
+- [设置组件属性状态支持同步](#设置组件属性状态支持同步)；\[必要]
+- [设置组件属性状态支持赋值](#设置组件属性状态支持赋值)。\[选配]
+
+当前该功能仅支持在 Vue框架使用。
+
+## 设置组件属性状态支持同步
+
+### 1. 功能说明
+
+支持将组件状态同步到定义的可访问属性，由可访问属性传递组件的状态。
+
+例如在事件逻辑中将数据表格的可访问属性disabled（禁用）赋值给局部变量，即通过可访问属性disabled（禁用）使局部变量获取到组件的禁用状态。
+
+
+
+### 2. 功能实现
+
+1.  在 api.ts文件中增加可读属性配置。例如“值”、“禁用”、“只读”属性。
+
+    ```typescript
+    export class UTabs<T, V> extends ViewComponent {
+    @Prop({
+        title: '值',
+    })
+    value: V;
+
+    @Prop({
+        title: '禁用',
+    })
+    disabled: nasl.core.Boolean;
+
+    @Prop({
+        title: '只读',
+    })
+    readonly: nasl.core.Boolean;
+
+    //...
+    }
+    ```
+
+1.  通过组件同步sync\:state事件来同步内部状态。
+
+    ```typescript
+    // sync mixin
+    import type { ComponentOptions, WatchOptionsWithHandler } from 'vue';
+
+    export type SyncOption = string | { [name: string]: string | (() => any) };
+    export interface SyncOptionItem {
+    name: string;
+    stateKey: string;
+    computed?: () => any;
+    }
+
+    function createWatch(name: string): WatchOptionsWithHandler<any> {
+    return {
+        handler(val, oldVal) {
+        if (val === oldVal) {
+            return;
+        }
+
+        this.$emit('sync:state', name, val);
+        },
+        immediate: true,
+    };
+    }
+
+    function normalizeSyncOptions(options: SyncOption[]) {
+    const syncMap: { [key: string]: SyncOptionItem } = {};
+    const computedMap: { [key: string]: () => any } = {};
+    const watchMap: Record<string, WatchOptionsWithHandler<any>> = {};
+
+    options.forEach((option) => {
+        if (typeof option === 'string') {
+        syncMap[option] = {
+            name: option,
+            stateKey: option,
+        };
+
+        watchMap[option] = createWatch(option);
+        return;
+        }
+
+        Object.keys(option).forEach((name) => {
+        const val = option[name];
+
+        if (typeof val === 'function') {
+            const stateKey = [name, 'sync'].join('__');
+            syncMap[name] = {
+            name,
+            stateKey,
+            };
+
+            watchMap[stateKey] = createWatch(name);
+            computedMap[stateKey] = val;
+            return;
+        }
+
+        syncMap[name] = {
+            name,
+            stateKey: val,
+        };
+        watchMap[val] = createWatch(name);
+        });
+    });
+
+    return {
+        syncMap,
+        computedMap,
+        watchMap,
+    };
+    }
+
+    export default (...options: SyncOption[]) => {
+    const {
+        syncMap,
+        watchMap,
+        computedMap,
+    } = normalizeSyncOptions(options);
+    return {
+        watch: {
+        ...watchMap,
+        },
+        computed: {
+        ...computedMap,
+        },
+    } as ComponentOptions<any>;
+    };
+    ```
+
+    ```javascript
+    import sync from './sync';
+    // u-tabs.vue
+    export default {
+    mixins: [
+        sync({
+        value() {
+            const itemVM = this.selectedVM;
+            if (!itemVM) {
+            return this.value;
+            }
+
+            if (this.dataSource !== undefined) {
+            return this.$at(itemVM, this.valueField);
+            }
+
+            return itemVM.value;
+        },
+        readonly: 'readonly',
+        disabled: 'disabled',
+        }),
+    ],
+    }
+    ```
+
+## 设置组件属性状态支持赋值
+
+### 1. 功能说明
+
+支持为可访问属性赋值。
+
+例如在事件逻辑中将数据表格设置为禁用，即数据表格的可访问属性disabled（禁用）赋值为true。
+
+
+
+### 2. 功能实现
+
+在 api.ts文件中通过为相关属性设置`settable: true`即可开启属性可赋值。
+
+```typescript
+@Prop({
+  //...
+  settable: true,
+})
+```

package/packages/lcap-frontend-library/references/lcap-extension-component/platform/child.md

@@ -0,0 +1,82 @@
+---
+outline: deep
+---
+
+# 父组件和子组件
+
+## 1. 功能说明
+
+子组件在 IDE 中不会显示在右侧组件面板上，只能通过父组件 **+** 按钮添加。
+
+以 Tabs 选项卡组件为例：通过选项卡的 ***+*** -> **添加子选项** 可为父组件选项卡添加子组件标签页。
+
+
+
+
+
+## 2. 功能实现
+
+### 2.1 父组件插槽配置snippets
+
+在 api.ts 文件中定义组件。
+
+- 父组件与子组件需要写在一个api.ts文件内，先写父组件，后写子组件。
+- 子组件示例（snippets.code）书写规范可参考[区块示例说明](../block.md)template写法。
+
+
+```typescript
+// api.ts
+
+@Component({
+  title: '选项卡',
+  description: '选项卡切换组件，常用于平级区域大块内容的收纳和展现。',
+})
+export class UTabs extends ViewComponent {
+  // ...
+  constructor(options?: Partial<TabsOptions>) { super(); }
+}
+
+export class UTabsOptions extends ViewComponentOptions {
+  // ...
+
+  @Slot({
+      title: '默认',
+      description: '插入`<u-tab>`子组件。',
+      emptyBackground: 'add-sub', // 未添加子组件时背景显示配置
+      snippets: [ // 配置插入代码示例， 插入代码规则与区块示例一致
+          {
+            title: '子选项',
+            code: '<u-tab><template #title><u-text text="标签页"></u-text></template>内容</u-tab>',
+          },
+      ],
+  })
+  slotDefault: () => Array<UTab>;
+}
+
+@Component({
+  title: '子选项',
+  description: '子选项',
+})
+export class UTab extends ViewComponent {
+  // ...
+  constructor(options?: Partial<UTabOptions>) { super(); }
+}
+
+export class UTabOptions extends ViewComponentOptions {
+  // ...
+}
+```
+
+### 2.2 页面编辑器适配
+
+在 api.ts 文件中配置 ideusage 将组件接入设计器。
+
+```typescript
+@ExtensionComponent({
+  ideusage: {
+    idetype: 'container',       // 父组件需要支持插槽
+    structured: true,           // 设置为 true 才会出现 ”+“ 按钮
+    childAccept: "target.tag === 'u-tab'", // 限制子组件为 u-tab
+  }
+})
+```

package/packages/lcap-frontend-library/references/lcap-extension-component/platform/data-source.md

@@ -0,0 +1,261 @@
+---
+outline: deep
+---
+
+<script setup>
+import { VTCodeGroup, VTCodeGroupTab } from '../../../.vitepress/components'
+</script>
+
+# 数据源
+
+## 1. 功能说明
+
+平台数据属性统一为dataSource属性，可以直接绑定后端逻辑，获取远程数据。
+
+以下以选择器组件为例：
+
+
+
+## 2. 功能实现
+
+### 2.1 增加数据源相关属性
+
+向 api.ts 文件中写入数据源相关属性。
+
+以下以选择器组件为例：包含“数据源”、“数据类型”、“文本字段”、“值字段”属性以及重新加载数据源的组件逻辑(reload)。
+
+```typescript
+@Component({
+  title: '选择器',
+  description: '选择器',
+})
+export class SelectOptions<T, V> extends ViewComponent {
+  constructor(options?: Partial<SelectOptions<T, V>>) {
+    super();
+  }
+
+  @Method({
+    title: '重新加载数据',
+    description: '重新加载数据'
+  })
+  reload(): void {} // 需要提供重新加载数据源的方法
+}
+// api.ts
+export class SelectOptions<T, V> extends ViewComponentOptions {
+  @Prop({
+    group: '数据属性',
+    title: '数据源',
+    description: '展示数据的输入源，可设置为数据集对象或者返回数据集的逻辑',
+    docDescription: '列表展示的数据。数据源可以绑定变量或者逻辑。变量或逻辑的返回值可以是数组，也可以是对象。对象格式为{list:[], total:10}',
+  })
+  dataSource: { list: nasl.collection.List<T>; total: nasl.core.Integer } | nasl.collection.List<T>;
+
+  @Prop({
+    group: '数据属性',
+    title: '数据类型',
+    description: '数据源返回的数据结构的类型，自动识别类型进行展示说明',
+    docDescription: '列表每一行的数据类型。该属性为展示属性，由数据源推倒得到，无需填写。',
+  })
+  dataSchema: T;
+
+
+  @Prop({
+    group: '数据属性',
+    title: '文本字段',
+    description: '选项文本的字段名',
+    setter: {
+      concept: "PropertySelectSetter"
+    }
+  })
+  textField: (item: T) => any;
+
+
+  @Prop({
+    group: '数据属性',
+    title: '值字段',
+    description: '选项文本的字段名',
+    setter: {
+      concept: "PropertySelectSetter"
+    }
+  })
+  valueField: (item: T) => V = ((item: T) => item.value) as any;;
+}
+```
+
+### 2.2 组件内部加载数据和渲染
+
+
+<VTCodeGroup>
+  <VTCodeGroupTab label="Vue2">
+
+  参考[Element UI Select](https://element.eleme.cn/#/zh-CN/component/select)支持数据源示例。
+
+  ```typescript
+  <template>
+  <el-select v-bind="$attrs" v-on="$listeners" :loading="loading">
+    <template v-if="!!dataSource">
+      <el-option
+        v-for="item in list"
+        :key="lodashGet(item, valueField)"
+        :label="lodashGet(item, textField)"
+        :value="lodashGet(item, valueField)">
+      </el-option>
+    </template>
+    <slot v-else></slot>
+  </el-select>
+  </template>
+  <script>
+  import lodashGet from 'lodash/get';
+
+  export default {
+    props: {
+      dataSource: {
+        type: [Array, Object, Function]
+      },
+      textField: {
+        type: String,
+        default: 'text',
+      },
+      valueField: {
+        type: String,
+        default: 'value',
+      },
+    },
+    data() {
+      return {
+        list: [],
+        loading: false,
+      };
+    },
+    watch: {
+      dataSource: {
+        handler() {
+          this.$nextTick(() => {
+            this.loadDataSource();
+          });
+        },
+        immediate: true
+      },
+    },
+    methods: {
+      lodashGet,
+      normalizeData(data) {
+        if (Array.isArray(data)) {
+          return data;
+        }
+
+        if (typeof data === 'object' && Array.isArray(data.list)) {
+          return data.list;
+        }
+
+        return [];
+      },
+
+      async loadDataSource() {
+        if (typeof this.dataSource === 'function') {
+          this.loading = true;
+          const data = await this.dataSource({});
+          this.list = this.normalizeData(data);
+          this.loading = false;
+        } else {
+          this.list = this.normalizeData(this.dataSource);
+        }
+      },
+      async reload() {
+        return this.loadDataSource();
+      },
+    },
+  }
+  </script>
+  ```
+
+  </VTCodeGroupTab>
+  <VTCodeGroupTab label="React">
+
+  参考[Ant Design Select](https://ant-design.antgroup.com/components/select-cn)支持数据源示例。
+
+  ```typescript
+  import React, { useState, useEffect, useImperativeHandle, useMemo } from 'react';
+  import { Select } from 'antd';
+  import lodashGet from 'lodash/get';
+
+  const normalizeData = (data) => {
+    if (Array.isArray(data)) {
+      return data;
+    }
+
+    if (typeof data === 'object' && Array.isArray(data.list)) {
+      return data.list;
+    }
+
+    return [];
+  }
+
+  const useDataSource = (dataSource) => {
+    const [data, setData] = useState([]);
+    const [loading, setLoading] = useState(false);
+
+    const loadDataSouce = useCallback(async () => {
+      if (typeof dataSource !== 'function') {
+        return;
+      }
+
+      setLoading(true);
+      const result = await this.dataSource({});
+      setData(normalizeData(result));
+      setLoading(false);
+    }, [dataSource]);
+    
+    useEffect(() => {
+      loadDataSouce();
+    }, [loadDataSouce]);
+
+    return {
+      reload: loadDataSouce,
+      data: useMemo(() => {
+        if (typeof dataSource !== 'function') {
+          return normalizeData(dataSource);
+        }
+
+        return data;
+      }, [data, dataSource]),
+      loading,
+    }
+  }
+
+  export const Select = React.forwardRef((props, ref) => {
+    const {
+      dataSource,
+      textField = 'text',
+      valueField = 'value',
+      ...rest
+    } = props;
+
+    const { data, loading, reload } = useDataSource(dataSource);
+
+    const options = useMemo(() => {
+      return data.map((item) => {
+        return {
+          label: lodashGet(item, textField),
+          value: lodashGet(item, valueField),
+        };
+      });
+    }, [data, textField, valueField]);
+
+    useImperativeHandle(ref, () => {
+      return {
+        reload,
+      };
+    }, [reload]);
+
+    return (
+      <Select
+        {...rest}
+        options={options}
+        loading={loading}
+      />
+    );
+  });
+  ```
+  </VTCodeGroupTab>
+</VTCodeGroup>

package/packages/lcap-frontend-library/references/lcap-extension-component/platform/event.md

@@ -0,0 +1,171 @@
+---
+outline: deep
+---
+<script setup>
+import { VTCodeGroup, VTCodeGroupTab } from '../../../.vitepress/components'
+</script>
+
+
+# 事件转换
+
+## 1. 功能说明
+
+平台事件触发仅支持一个 event 对象，需要将事件的参数合并到 event 对象下。
+
+
+
+## 2. 注意事项
+
+使用`@Event`来标注支持的事件，需要注意以下几点：
+
+1.  事件名需要以on 开头的小驼峰，例如click 需要写为onClick，row-click需要写为onRowClick；
+2.  事件名须为合法属性名，**禁止**使用引号字符串键或含 `:` 的键名（如 `'onUpdate:modelValue'`）；与 Vue `update:modelValue` 对应时须写为 `onUpdateModelValue`；
+3.  事件参数仅允许有一个参数event，多个参数的情况需要转为一个匿名结构对象, 例如onSelect(value, item)需要转换为 onSelect({ value, item })；
+4.  返回参数统一为void，匿名数据结构属性也必须使用 nasl 支持的类型；
+
+## 3. 功能实现
+
+<VTCodeGroup>
+  <VTCodeGroupTab label="Vue2">
+
+  参考[Element UI 导航菜单](https://element.eleme.cn/#/zh-CN/component/menu#menu-events)组件的select，open，close事件示例。
+
+  | 事件名称   | 说明       | 回调参数                  |
+  | :----- | :------- | :-------------------- |
+  | select | 菜单激活回调   | index: 选中菜单项的 index,  |
+  | open   | 菜单项展开的回调 | index: 打开的菜单项的 index， |
+  | close  | 菜单项收起的回调 | index: 收起的菜单项的 index， |
+
+  1.  定义触发事件的处理方法。
+
+      ```vue
+      <template>
+      <el-menu  @select="handleSelect" @open="handleOpen" @close="handleClose">
+      <!-- ... -->
+      </el-menu>
+      </template>
+      <script>
+      export default {
+      // ...
+      methods: {
+          handleSelect(index, indexPath) {
+          this.$emit('select', {
+              index,
+              indexPath,
+          });
+          },
+          handleOpen(index, indexPath) {
+          this.$emit('open', {
+              index,
+              indexPath,
+          });
+          }
+          handleClose(index, indexPath) {
+          this.$emit('close', {
+              index,
+              indexPath,
+          });
+          }
+      }
+      }
+      </script>
+      ```
+
+  2.  向 api.ts 文件中写入相关事件。
+
+      ```typescript
+      // api.ts
+      @Event({
+      title: '菜单激活时',
+      description: '菜单激活回调',
+      })
+      onSelect: (event: {
+      index: nasl.core.String;
+      indexPath: nasl.core.String;
+      }) => void;
+
+      @Event({
+      title: '子菜单展开时',
+      description: '子菜单展开的回调',
+      })
+      onOpen: (event: {
+      index: nasl.core.String;
+      indexPath: nasl.core.String;
+      }) => void;
+
+      @Event({
+      title: '子菜单收起时',
+      description: '子菜单收起的回调',
+      })
+      onClose: (event: {
+      index: nasl.core.String;
+      indexPath: nasl.core.String;
+      }) => void;
+      ```
+
+  </VTCodeGroupTab>
+  <VTCodeGroupTab label="React">
+
+  参考[Ant Design 分页](https://ant-design.antgroup.com/components/pagination-cn#api)组件的onChange，onShowSizeChange事件示例。
+
+  | 事件名称             | 说明           | 回调参数            |
+  | :--------------- | :----------- | :-------------- |
+  | onChange         | 页码或每页条数改变的回调 | page：改变后的页码     |
+  | onShowSizeChange | 每页条数改变的回调    | current：当前状态或对象 |
+
+  1.  定义触发事件的处理方法。
+
+      ```typescript
+      import React from 'react';
+      import { Pagination } from 'antd';
+
+      export const CwPagination = ({ onChange = () => {}, onShowSizeChange = () => {}, ...rest }) => {
+      const handleChange = (page, pageSize) => {
+          onChange({
+          page,
+          pageSize,
+          });
+      }
+
+      const handleShowSizeChange = (current, size) => {
+          onChange({
+          current,
+          size,
+          });
+      }
+
+      return (
+          <Pagination
+          {...rest}
+          onChange={handleChange}
+          onShowSizeChange={handleShowSizeChange}
+          />
+      )
+      }
+      ```
+
+  1.  向 api.ts 文件中写入相关事件。
+
+      ```typescript
+      // api.ts
+      @Event({
+      title: '切换分页后',
+      description: '切换分页后',
+      })
+      onChange: (event: {
+      page: nasl.core.Integer;
+      pageSize: nasl.core.Integer;
+      }) => void;
+
+      @Event({
+      title: '分页大小改变时',
+      description: 'pageSize变化的回调',
+      })
+      onShowSizeChange: (event: {
+      current: nasl.core.Integer;
+      size: nasl.core.Integer;
+      }) => void;
+      ```
+
+  </VTCodeGroupTab>
+</VTCodeGroup>