SuperAPI AI 工具集

add-component-property

编程与开发

查看项目

更新于 10-16 07:05

技能介绍

用途

该技能用于向已存在的 Lit Web Component 添加一个新的响应式属性。适用于用户提出为组件增加新属性或属性(attribute)、组件需要新的配置选项、或通过新设置扩展组件功能的场景。

主要能力

技能按步骤引导完成以下工作:

  1. 在组件类中添加属性:根据属性类型给出对应的装饰器写法,包括:

    • 基础类型(反射到属性):使用 @property({ reflect: true }),并附 JSDoc 注释包含 @attr 与 @default;
    • 只读属性:使用 @property({ attribute: false }) 与 public readonly;
    • 布尔类型:使用 @property({ type: Boolean, reflect: true });
    • 数字类型:使用 @property({ type: Number, reflect: true });
    • 复杂类型(对象、数组,不反射):使用 @property({ attribute: false })。
  2. 更新组件渲染方法:若属性影响渲染,更新 render() 方法中的模板。

  3. 添加属性变更处理(如需要):优先使用 update() 生命周期钩子(此时 DOM 可用,适合副作用);仅在需要在渲染前计算派生状态且无需访问 DOM 时使用 willUpdate()。最佳实践包括:优先使用 update()、必要时才用 willUpdate()、重写 update() 时始终调用 super.update(changedProperties)、用 changedProperties.has() 判断以避免无谓工作。

  4. 更新测试:在 [component-name].spec.ts 中添加默认值、属性变更、反射到属性的测试用例(使用 fixture 与 elementUpdated)。

  5. 更新 Storybook 故事:在 stories/[component-name].stories.ts 中更新 argTypes、args、接口定义(IgcComponentArgs)和故事模板。

  6. 验证与测试:运行测试与类型检查,并在 Storybook 中验证。提供校验清单,涵盖装饰器、JSDoc、类型注解、默认值、反射限制、测试覆盖、Storybook 更新等检查项。

使用方式

技能中给出了示例用法,例如:

  • “Add an 'orientation' property to the divider component”
  • “Add a 'disabled' attribute to the button component”
  • “Add a 'variant' property with multiple options”

使用前需明确或确认以下上下文:组件名称、属性名(属性用 camelCase,attribute 用 kebab-case)、属性类型(基础类型或复杂类型)、默认值、是否反射到属性(仅基础类型)、属性用途说明。

验证命令包括:

# Run tests
npm run test

# Check that the project will transpile
npm run check-types

# Start Storybook
npm run storybook

适用场景

  • 为已有组件新增属性或 attribute;
  • 为组件增加新的配置选项;
  • 通过新设置扩展组件功能。

前置条件:目标组件已存在、属性名与类型已确定、默认值已确定、是否反射到 attribute 已确定。

相关技能:create-new-component(先创建组件)、update-component-styles(属性的样式变更)。

限制

  • 仅基础类型(string、number、boolean)允许 reflect: true;复杂类型(对象、数组)必须使用 attribute: false,不应尝试反射。
  • 需注意常见陷阱:反射非基础类型、属性名转换错误(camelCase 未映射为 kebab-case,可显式指定 @property({ attribute: 'custom-name' }))、缺少类型强制转换(布尔/数字需使用 { type: Boolean } 或 { type: Number })、忘记更新 Storybook。
  • 技能本身不提供具体命令之外的安装方式说明,官方文本暂未提供。