lcap-frontend-library 0.0.1

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

@@ -0,0 +1,266 @@
+---
+outline: deep
+---
+
+<script setup>
+import { VTCodeGroup, VTCodeGroupTab } from '../../../.vitepress/components'
+</script>
+
+
+# 表单组件的能力适配
+
+在设计表单类组件时，需确保组件具备作为表单项的能力，主要包括以下两个方面：
+
+- [组件的值能够实现双向绑定](#值双向绑定处理​)；
+- [组件的值可以进行校验](#组件支持表单校验
+
+## 值双向绑定处理
+### 1. 功能说明
+
+平台需要组件支持值同步到绑定变量的能力，用于传递表单项中输入、选择的值。
+
+
+
+以单行输入组件为例，功能效果参考如下：
+
+1.  在IDE中，单行输入的“值”属性对应输入框中的内容，该数据支持编辑表达式。
+
+1.  编辑表达式时，若绑定变量，支持开启“将组件输入赋值给变量”。开启“将组件输入赋值给变量”后即表示支持值同步到绑定变量。
+
+1.  发布应用后，在制品中向输入框中输入内容，该输入内容即同步存储到绑定变量中。
+
+### 2. 功能实现
+
+1.  目前 Vue2 通过.sync修饰符来支持绑定同步，社区组件很多只适配了 v-model，需要组件内部对外抛出 \$emit('update\:value')事件。
+
+```typescript
+<template>
+<el-input v-bind="$attrs" :value="value" @input="handleInput" />
+</template>
+<script>
+export default {
+props: {
+    value: String,
+},
+methods: {
+    handleInput(val) {
+      this.$emit('update:value', val);
+      this.$emit('input', val);
+    },
+}
+}
+</script>
+```
+
+<div class="highlight">
+
+React 会自动监听onChange事件来更新绑定变量。
+
+</div>
+    
+
+1.  在 api.ts 文件中为相关属性设置sync: true即为允许同步。
+
+  ```typescript
+  @Prop({
+  group: '数据属性',
+  title: '值',
+  sync: true, // 开启值同步
+  })
+  value: V;
+  ```
+
+## 组件支持表单校验
+
+### Vue2 框架下表单验证支持
+
+默认 `Vue2` 组件 `option` 中设置了 `model` 既可以支持表单验证， 例如：
+
+```vue
+<template>
+  <input :value="value" @input="handleInput" />
+</template>
+<script>
+export default {
+  model: {
+    prop: 'value',
+    event: 'update:value',
+  },
+  props: {
+    value: String,
+  },
+  methods: {
+    handleInput(val) {
+      this.$emit('update:value', val);
+      this.$emit('input', val);
+    },
+  }
+}
+</script>
+```
+
+### Vue3 / React 框架下表单验证支持
+
+Vue3 / React 框架下组件能默认支持表单验证，无需修改代码；
+
+
+
+### Vue2 CloudUI 下的表单验证支持
+
+(CloudUI)表单类组件支持验证
+
+需要同步值给负责验证的组件，步骤如下
+
+
+#### 创建mixins 相关文件
+
+
+```js
+// mixins/field.js
+const broadcast = function (condition, eventName, ...args) {
+  this.$children.forEach(($child) => {
+    if (condition($child)) $child.$emit(eventName, ...args);
+    else broadcast.apply($child, [condition, eventName].concat(args));
+  });
+};
+
+
+export default {
+  name: 'm-emitter',
+  methods: {
+    $dispatch(condition, eventName, ...args) {
+      if (typeof condition === 'string') {
+        const name = condition;
+        condition = ($parent) => $parent.$options.name === name;
+      }
+      let $parent = this.$parent || this.$root;
+      while ($parent && !condition($parent)) $parent = $parent.$parent;
+      $parent && $parent.$emit(eventName, ...args);
+    },
+    $broadcast(condition, eventName, ...args) {
+      if (typeof condition === 'string') {
+        const name = condition;
+        condition = ($child) => $child.$options.name === name;
+      }
+      broadcast.apply(this, [condition, eventName].concat(args));
+    },
+    $contact(condition, callback) {
+      if (typeof condition === 'string') {
+        const name = condition;
+        condition = ($parent) => $parent.$options.name === name;
+      }
+      let $parent = this.$parent || this.$root;
+      while ($parent && !condition($parent)) $parent = $parent.$parent;
+      return $parent && callback($parent);
+    },
+    $emitPrevent(name, $event, senderVM, ...args) {
+      let cancel = false;
+      this.$emit(
+        name,
+        Object.assign($event || {}, {
+          preventDefault: () => (cancel = true),
+        }),
+        senderVM,
+        ...args,
+      );
+      return cancel;
+    },
+  },
+};
+```
+
+
+```js
+// mixins/field.js
+/* eslint-disable no-unused-expressions */
+import MEmitter from './emitter';
+
+
+export default {
+  name: 'm-field',
+  isField: true,
+  mixins: [MEmitter],
+  data() {
+    return {
+      validatorVM: undefined,
+      formItemVM: undefined, // @compat
+    };
+  },
+  created() {
+    this.$dispatch(
+      ($parent) => ($parent.$options.name && $parent.$options.name.endsWith('u-form-item'))
+          || $parent.$options.isField || $parent.$options.isValidator,
+      'add-field-vm',
+      this,
+    );
+    this.$on('update', (value) => {
+      const validatorVM = this.validatorVM || this.formItemVM; // @compat
+      validatorVM && validatorVM.$emit('update', value);
+    });
+    this.$on('input', (value) => {
+      const validatorVM = this.validatorVM || this.formItemVM; // @compat
+      validatorVM && validatorVM.$emit('input', value);
+    });
+    this.$on('change', ($event) => {
+      const validatorVM = this.validatorVM || this.formItemVM; // @compat
+      validatorVM && validatorVM.$emit('change', $event);
+    });
+    this.$on('focus', () => {
+      const validatorVM = this.validatorVM || this.formItemVM; // @compat
+      validatorVM && validatorVM.$emit('focus');
+    });
+    this.$on('blur', () => {
+      const validatorVM = this.validatorVM || this.formItemVM; // @compat
+      validatorVM && validatorVM.$emit('blur');
+    });
+  },
+  destroyed() {
+    const validatorVM = this.validatorVM || this.formItemVM; // @compat
+    validatorVM && validatorVM.$emit('remove-field-vm', this);
+  },
+};
+```
+
+
+#### 引入mixins
+
+
+```vue
+// index.vue
+<template>
+  <div>
+    <input :value="value" @change="handleChange" @input="handleInput" @focus="handleFocus" @blur="handleBlur"` />
+  </div>
+</template>
+<script>
+import MField from './mixins/field';
+
+
+export default {
+  name: 'index',
+  mixins: [MField],
+  data() {
+    return {
+      value: '',
+    };
+  },
+  methods: {
+    handleChange(value) {
+      this.value = value;
+      this.$emit('change', { value });
+    },
+    handleInput(value) {
+      this.value = value;
+      this.$emit('update:value', value);
+      this.$emit('input', value);
+    },
+    handleFocus() {
+      this.$emit('focus');
+    },
+    handleBlur() {
+      this.$emit('blur');
+    },
+  },
+};
+</script>
+```

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

@@ -0,0 +1,80 @@
+---
+outline: deep
+---
+
+# 函数设置器 <Badge type="tip" text="^3.10.0" />
+
+## 1. 功能说明
+
+用于Function类型的函数设置 (AnonymousFunctionSetter)，例如： 表格行样式、文本格式化、日期格式化函数等等...
+
+以下以数据表格组件的“表格行动态样式”属性为例：
+
+
+
+## 2. 功能实现
+
+向 api.ts 文件中写入“表格行动态样式样式”属性：
+
+- `bindOpen: true` ：表明属性的编辑表达式模式处于开启状态；
+- `concept: 'AnonymousFunctionSetter'` ：表明设置器的概念是匿名函数设置器；
+- `rowStyle` 是一个函数类型的属性，接收一个 Current 类型参数 current ，这个函数返回一个对象，包含两个可选的属性：
+
+
+
+  - backgroundColor：用于设置列表行的背景颜色，类型为String。
+  - color：用于设置列表行的字体颜色，类型为String。
+
+```typescript
+// api.ts
+@Prop({
+    group: '样式属性',
+    title: '列表行动态样式',
+    description: '动态设置列表项背景色、字体颜色等样式',
+    docDescription: '动态设置列表项背景色、字体颜色等样式',
+    bindOpen: true,
+    setter: {
+        concept: 'AnonymousFunctionSetter',
+    }
+})
+rowStyle: (current: Current<T>) => { 
+    /**
+   - @title 列表行背景颜色
+     */
+    backgroundColor?: nasl.core.String, 
+    /**
+   - @title 列表行字体颜色
+     */
+    color?: nasl.core.String 
+};
+```
+
+<div class="highlight">
+
+目前仅支持同步函数，返回值不允许是Promise
+
+</div>
+
+
+## 3. 使用效果演示
+
+- 进入编辑表达式界面时，表达式中已有包含 backgroundColor 和 color 属性的匿名数据结构，变量可选参数 current。
+
+    
+
+- 支持初始化表格的列表行背景颜色、列表行字体颜色，甚至新增表格已定义的其他属性。
+
+    
+
+制品效果如下：
+
+
+
+<div class="highlight">
+
+使用“表格行动态样式”属性的常见场景具体请参考[如何实现动态展示表格行样式](https://community.codewave.163.com/CommunityParent/fileIndex?filePath=80.%E5%B8%B8%E8%A7%81%E5%9C%BA%E6%99%AF%E6%A1%88%E4%BE%8B%2F80.%E4%B8%9A%E5%8A%A1%E5%9C%BA%E6%99%AF%2F145.%E5%A6%82%E4%BD%95%E5%AE%9E%E7%8E%B0%E5%8A%A8%E6%80%81%E5%B1%95%E7%A4%BA%E8%A1%A8%E6%A0%BC%E8%A1%8C%E6%A0%B7%E5%BC%8F.md&version=3.13)。
+
+</div>
+
+
+

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

@@ -0,0 +1,137 @@
+---
+outline: deep
+---
+
+<script setup>
+import { VTCodeGroup, VTCodeGroupTab } from '../../../.vitepress/components'
+</script>
+
+# 链接跳转
+
+## 1. 功能说明
+
+为了便于CodeWave开发者配置，平台对链接跳转功能做了优化。
+
+
+
+配置页面跳转的“链接地址”属性时，支持通过“链接设置器”设置需要跳转的页面。跳转的页面支持直接选择应用内页面，也支持将链接地址作为“页面跳转到”编辑表达式的输出结果。
+
+
+
+## 2. 功能实现
+
+### 2.1 增加链接跳转相关属性
+
+向 api.ts 文件中写入链接跳转相关属性。设置“链接地址”的属性无需设置setter，而使用hrefAndTo属性设置，IDE会识别该属性启用如上“链接设置器”。
+
+```typescript
+@Prop({
+  group: '交互属性',
+  title: '链接地址'
+})
+hrefAndTo: nasl.core.String;
+```
+
+### 2.2 组件内部实现跳转
+
+平台在组件上会设置link和destination两个属性：
+
+- link：外部链接，例如<https://codewave.163.com>
+- destination：内部链接，例如 /dashboard
+
+组件内部需要对这两个属性增加对应的代码，使组件被点击时发生页面跳转。
+
+<VTCodeGroup>
+  <VTCodeGroupTab label="Vue2">
+
+  ```vue
+  <template>
+  <a :href="linkURL" :target="target" @click="handleClick">链接</a>
+  </template>
+  <script>
+  export default {
+    props: {
+      link: String,
+      destination: String,
+      target: String,
+      replace: Boolean,
+    },
+    computed: {
+      linkURL() {
+        return destination || link;
+      },
+    },
+    methods: {
+      handleClick(e) {
+        this.$emit('click', e);
+        
+        if (!this.destination || this.target === '_blank' || !this.$router) {
+          return;
+        }
+
+        // 阻止默认行为
+        e.preventDefault();
+        e.returnValue = false;
+
+        // vue router 跳转
+        this.routerNavigate(this.destination);
+      },
+      routerNavigate(url) {
+        if (this.replace) {
+          this.$router.replace(url);
+          return;
+        }
+        
+        this.$router.push(url);
+      },
+    },
+  };
+  </script>
+  ```
+
+  </VTCodeGroupTab>
+  <VTCodeGroupTab label="React">
+
+  ```tsx
+  import React, { FC, HTMLAttributes } from 'react';
+  import { useNavigate } from 'react-router-dom';
+
+  export interface CwLinkProps extends HTMLAttributes<HTMLLinkElement> {
+    link: string;
+    destination: string;
+    target: string;
+    replace: boolean;
+  }
+
+  const CwLink: FC<CwLinkProps> = (props) => {
+    const {
+      link,
+      destination,
+      target,
+      replace,
+      ...rest
+    } = props;
+
+    const navigate = useNavigate();
+
+    const handleClick = (e: Event) => {
+      if (!destination || target === '_blank') {
+        return;
+      }
+
+      // 阻止默认行为
+      e.preventDefault();
+      e.returnValue = false;
+
+      // 此处走 react router 跳转
+      navigate(destination, { replace });
+    }
+
+    return (
+      <a {...rest} href={destination || link} onClick={handleClick}>链接</a>
+    );
+  };
+  ```
+
+  </VTCodeGroupTab>
+</VTCodeGroup>

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

@@ -0,0 +1,128 @@
+---
+outline: deep
+---
+
+# 插槽处理
+
+## 1. 功能说明
+
+组件的插槽是一种用于在组件中传递内容的机制，它允许父组件向子组件传递内容，使得子组件可以更加灵活地展示不同的内容。
+
+## 2. 功能实现
+
+### 2.1 插槽配置
+
+在 api.ts 文件中使用@Slot来描述组件插槽。插槽属性名以slot开头的小驼峰命名，例如：默认插槽slotDefault；具名插槽例如写为slotHeader。
+
+以下简单描述插槽常见的处理方式：
+
+#### 默认插槽
+
+没有特定的名称标识，它提供了一种简单的方式让父组件向子组件传递内容，并在子组件的特定位置进行渲染。
+
+以 Dropdown 下拉菜单组件为例：
+
+
+
+```typescript
+// 在 @Component 上增加ide 配置
+@ExtensionComponent({
+  // ...
+  ideusage: {
+    idetype: 'container',
+    structured: true,           // 设置为 true 才会出现 ”+“ 按钮
+  }
+})
+export class ElMenuOptions extends ViewComponentOptions {
+  // 以Menu 为例
+  // ...
+  @Slot({
+    title: 'Default',  // 名称
+    description: '内容', // 描述
+    snippets: [ // ide 编辑 “+” 点击后的提示，  title提示描述， code 点击后默认添加代码
+    {
+        title: '添加下拉菜单分组',
+        code: '<el-menu-item-group></el-menu-item-group>',
+      },
+      { title: '菜单项', code: '<el-menu-item></el-menu-item>' },
+    ],
+  })
+  slotDefault: () => Array<nasl.ui.ViewComponent>;
+}
+```
+
+#### 具名插槽
+
+允许父组件在使用子组件时，可以将不同的内容插入到子组件的特定插槽位置，并且通过名称来区分不同的插槽。
+
+```typescript
+export class XxxOptions extends ViewComponentOptions {
+  // ...
+  @Slot({
+      title: '头部内容',
+      description: '头部内容',
+  })
+  slotHeader: () => Array<nasl.ui.ViewComponent>;
+}
+```
+
+#### 作用域插槽
+
+允许子组件向父组件传递数据，以便父组件可以根据这些数据来渲染插槽内容。
+
+```typescript
+export class XxxOptions extends ViewComponentOptions {
+  // ...
+  @Slot({
+      title: '循环项的插槽',
+      description: '自定义选项的结构和样式',
+  })
+  slotItem: (current: Current<T>) => Array<nasl.ui.ViewComponent>;
+}
+
+// current 参数类型
+declare namespace nasl.ui {
+  export class Current<T> {
+    item: T;
+    index: nasl.core.Integer;
+    rowIndex: nasl.core.Integer;
+    columnIndex: nasl.core.Integer;
+    value: nasl.core.String;
+  }
+}
+```
+
+- Current 为平台默认插槽参数类型，也支持自定义类型。
+
+```typescript
+slotItem: (current: {
+  row: T,
+  disabled: nasl.core.Boolean,
+  // .... 
+})
+```
+
+### 2.2 页面编辑器适配
+
+在 api.ts 文件中配置 ideusage 将组件接入设计器。
+
+```typescript
+// 在 @Component 上增加ide 配置
+@ExtensionComponent({
+  // ...
+  ideusage: {
+    idetype: 'container',
+  }
+})
+```
+
+- idetype为 container的组件可以插入子节点。
+
+<div class="highlight">
+
+更多配置项可查看文档[页面编辑器适配说明-container配置](../ide/container.md)。
+
+</div>
+
+
+