farris-vue/style-guide/vue_component_style_guide.md

Farris UI Vue 组件开发规范

为了保证 Farris UI Vue 的源代码风格一致，确保组件研发质量，方便社区开发者阅读代码参与贡献，需要所有参与Farris UI Vue 组件开发的贡献，都要遵循此组件开发规范。

组件目录和文件规范

Farris UI Vue 的组件，都包含在ui-vue包的components目录下，每一个子组件为独立目录，目录名为全小写的组件名，当组件名包含多个英文单词时，使用-分隔。

目录规范分成以下部分：

组件目录结构

以下是单个组件目录的结构

input-group
├── test                               // 单元测试
|  └── input-group.spec.tsx
├── src                                // 组件源码
|  ├── components                      // 子组件
|  |  └── input-group-sub.component.tsx
|  ├── composition                     // 组件的可复用逻辑
|  |  ├── types.ts                     // 组合式Api返利值接口类型
|  |  ├── use-append-button.ts         // 实现组件特性1的组合式Api
|  |  └── use-clear.ts                 // 实现组件特性2的组合式Api
|  ├── input-group.component.tsx       // 组件代码
|  └── input-group.props.ts            // 定义组件Api
└── index.ts                           // 组件入口文件

入口文件 index.ts

import type { App } from 'vue';
import InputGroup from './src/input-group.component';

export * from './src/input-group.props';

export { InputGroup };

export default {
  install(app: App): void {
    app.component(InputGroup.name, InputGroup);
  },
};

组件文件 input-group.component.tsx

import { defineComponent, toRefs } from 'vue';
import type { SetupContext } from 'vue';

import { InputGroupProps, inputGroupProps } from './input-group.props';
import { useClear } from './composition/use-clear';

export default defineComponent({
  name: 'FInputGroup',
  props: inputGroupProps,
  emits: ['update:modelValue'],
  setup(props: InputGroupProps, setupContext: SetupContext) {
    const { someProp } = toRefs(props);
    const { showClearButton, onClearValue } = useClear();

    return () => {
      return (
        <div class="f-input-group">{ someProp.value }</div>
      );
    };
  },
});

类型文件 input-group.props.ts

import { PropType, ExtractPropTypes } from 'vue';

export const inputGroupProps = {
  /**
   * 显示输入框的标签
   */
  enableTitle: { type: Boolean, default: false },  
  /**
   * 输入框提示文本
   */
  placeholder: { type: String, default: '' },
  /**
   * 输入框Tab键索引
   */
  tabIndex: Number
};

export type InputGroupProps = ExtractPropTypes<typeof inputGroupProps>;

组合式Api use-clear.ts

import { computed, SetupContext } from 'vue';
import { InputGroupProps } from '../input-group.props';
import { UseClear } from './types';

export function useClear(props: InputGroupProps, setupContext: SetupContext): UseClear {
  const showClearButton = computed(() => props.enableClear && !props.readonly && !props.disable);

  function onClearValue($event: Event) {
    console.log('on onClearValue');
  }

  return {
    showClearButton,
    onClearValue
  };
}

单元测试 input-group.spec.tsx

import { mount } from '@vue/test-utils';
import { InputGroup } from '..';

describe('f-input-group', () => {
  it('variant', () => {
    const wrapper = mount({
      setup() {
        return () => {
          return <InputGroup editable={false}></InputGroup>;
        };
      },
    });

    expect(wrapper.find('.f-cmp-inputgroup').exists()).toBeTruthy();
    expect(wrapper.find('div').find('div').find('input').find('[readlony]').exists).toBeTruthy();
  });
});

组件编码规范

• 组件采用中划线风格命名，组件的参数名和事件名统一使用中划线格式。
• 所有组件统一在名称前使用F前缀，组件选择器前使用f-前缀。
• 直接用v-model传递双向绑定的参数。
• 使用属性透传传递原生属性，不允许在单独定义API声明原生属性。
• 正确定义和使用TypeScript类型，代码中无TypeScript类型报错。
• 变量采用语义化命名，原则上不需要通过注释说明变量或函数功能，详细命名规则参考Farris UI TypeScript 编码指南。
• 需要将组件的props定义在独立的文件some-component.props.ts文件中，并在此文件中同时导出props和PropsType。
• 应该在setup函数返回的render函数中编写组件的Html模板。
• 必须在组件的index.ts文件中导出组件参数的类型，以便于在引用组件时，方便TypeScript进行类型提示。
• defineComponent函数接收的参数顺序为name、props、emits、inheritAttrs、setup。
• 不要在组件内显式声明components和directives。
• 需要安装字典顺序排列组件的变量。

组件文档规范

待上线Doc站点后补充

关于

本项目的 Farris UI Vue 组件开发规范遵循CC-By 3.0协议。