farris-vue/style-guid/vue_component_style_guid.md

Farris UI Vue 组件开发规范

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

组件目录和文件规范

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

目录规范分成以下部分：

组件目录结构

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

farris-component
├── specs                              // 单元测试
|  └── farris-component.spec.ts
├── src                                // 组件源码
|  ├── components                      // 子组件
|  |  └── farris-child-component.ts
|  ├── services                        // 组件的可复用逻辑
|  |  ├── some-feature.service.ts
|  |  ├── some-feature.render.ts
|  |  ├── some-feature.template.ts
|  |  └── some-event.handler.ts            
|  ├── farris-component.types.ts       // 组件类型
|  └── farris-component.tsx            // 组件代码
└── index.ts                           // 组件入口文件

入口文件 index.ts

import type { App } from 'vue';
import FarrisComponent from './src/farris-component';

export * from './src/farris-component.types';

export { FarrisComponent };

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

组件文件 my-component.tsx

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

import { someComponentProps, SomeComponentProps } from './farris-component.types';
import { someFeatureService } from './services/some-feature.service';

export default defineComponent({
  name: 'f-some-component',
  props: someComponentProps,
  emits: ['update:modelValue'],
  setup(props: SomeComponentProps, setupContext: SetupContext) {
    const { someProp } = toRefs(props);
    const { someVarieble, someMethod } = someFeatureService();

    return () => {
      return (
        <div class="f-some-component">{ someProp.value }</div>
      );

    };
  },
});

类型文件 farris-component.types.ts

import { PropType, ExtractPropTypes } from 'vue';

export const someComponentProps = {
  pageIndex: {
    type: Number,
    default: 1
  },
  pageSize: {
    type: Array as PropType<number[]>,
    default: [5, 10, 20, 50]
  }
};

export type SomeComponentProps = ExtractPropTypes<typeof someComponentProps>;

控制逻辑 some-feature.service.ts

import { ref } from 'vue';

export function someFeatureService() {
  const someVarieble = ref(xxx);

  const someMethod = () => {
    
  };

  return { someVarieble, someMethod };
}

单元测试 farris-component.spec.ts

import { mount, DOMWrapper } from '@vue/test-utils';
import { ref } from 'vue';
import FSomeComponent from '../src/farris-component';

describe('SomeComponent', () => {
  it('should render correctly', async () => {
    const wrapper = mount({
      components: { FSomeComponent },
      template: `
        <f-some-component some-prop="xxx" />
      `,
      setup() {
        const someVarieble = ref(xxx);
        return { someVarieble };
      }
    });

    expect(xxx).toEqual(xxx);
  });
});

组件编码规范

• 组件采用中划线风格命名，组件的参数名和事件名统一使用中划线格式。
• 所有组件统一在名称前使用F前缀，组件选择器前使用f-前缀。
• 直接用v-model传递双向绑定的参数。
• 使用属性透传传递原生属性，不允许在单独定义API声明原生属性。
• 正确定义和使用TypeScript类型，代码中无TypeScript类型报错。
• 变量采用语义化命名，原则上不需要通过注释说明变量或函数功能，详细命名规则参考Farris UI TypeScript 编码指南。
• 需要将组件的props定义在独立的文件some-component.types.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协议。