Stencil组件开发规范指南：从命名到代码组织的专业实践-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00598/article/details/148392568

Stencil组件开发规范指南：从命名到代码组织的专业实践

stencil A toolchain for building scalable, enterprise-ready component systems on top of TypeScript and Web Component standards. Stencil components can be distributed natively to React, Angular, Vue, and traditional web developers from a single, framework-agnostic codebase. 项目地址: https://gitcode.com/gh_mirrors/st/stencil

前言

在基于Stencil构建Web Components组件库时，遵循一致的开发规范至关重要。本文将深入解析Stencil官方推荐的组件开发风格指南，帮助开发者构建可维护、可扩展的高质量组件。

文件结构规范

组件隔离原则

每个组件应当拥有独立的目录和文件结构，这种隔离带来以下优势：

便于独立维护和版本控制
文档生成更加清晰
样式和逻辑紧密耦合

典型结构示例：

├── 按钮组件
│   ├── 按钮.ios.scss    // iOS平台样式
│   ├── 按钮.md.scss     // Material Design样式
│   ├── 按钮.scss        // 基础样式
│   ├── 按钮.tsx         // 组件逻辑
│   └── 测试
│       └── 基础用例
│           ├── 端到端测试.js
│           └── 测试页面.html

命名规范体系

HTML标签命名

前缀规则：
- 必须包含连字符(-)以符合Web Components规范
- 使用品牌或项目标识作为前缀（如Ionic使用ion-）
- 避免使用"stencil"等框架相关前缀
命名原则：
- 使用名词而非动词（如ion-input而非ion-get-input）
- 相关组件采用统一前缀+修饰符（如ion-card、ion-card-header）

TypeScript类命名

类名无需前缀（得益于TypeScript的作用域隔离）
保持与标签名语义一致（去前缀后）

示例：

@Component({ tag: 'ion-button' })
export class Button { ... }  // 类名去前缀

TypeScript编码规范

装饰器使用准则

变量装饰器：单行内联

@Prop() value: string;
@State() active = false;

方法装饰器：多行声明

@Listen('click')
handleClick() {
  // 处理逻辑
}

封装性建议

优先使用private修饰符强化封装
公共API必须添加JSDoc注释
遵循TSLint规范（特别是ionic定制规则集）

代码组织哲学

报纸式布局原则

组件代码应当像报纸文章一样：

重要概览在上方（公共API）
实现细节在下方（私有方法）
相关代码就近放置

组件类结构模板

@Component({...})
export class ExampleComponent {
  // 1. 私有属性（类型优先）
  private internalState: number;
  
  // 2. 宿主元素引用
  @Element() hostEl: HTMLElement;
  
  // 3. 状态管理
  @State() isLoading = true;
  
  // 4. 公共属性（带文档注释）
  /** 控制组件可见性 */
  @Prop() visible = false;
  
  // 5. 属性监听（紧跟在相关属性后）
  @Watch('visible')
  handleVisibilityChange() { ... }
  
  // 6. 事件定义
  @Event() valueChanged: EventEmitter;
  
  // 7. 生命周期（按执行顺序排列）
  componentWillLoad() { ... }
  
  // 8. 监听器方法
  @Listen('keydown')
  handleKeyPress() { ... }
  
  // 9. 公共方法
  @Method()
  show() { ... }
  
  // 10. 私有方法
  private internalHelper() { ... }
  
  // 11. 宿主数据
  hostData() { ... }
  
  // 12. 渲染方法（始终在最后）
  render() { ... }
}