用途
该技能用于向已存在的 Lit Web Component 添加一个新的响应式属性。适用于用户提出为组件增加新属性或属性(attribute)、组件需要新的配置选项、或通过新设置扩展组件功能的场景。
主要能力
技能按步骤引导完成以下工作:
-
在组件类中添加属性:根据属性类型给出对应的装饰器写法,包括:
- 基础类型(反射到属性):使用
@property({ reflect: true }),并附 JSDoc 注释包含@attr与@default; - 只读属性:使用
@property({ attribute: false })与public readonly; - 布尔类型:使用
@property({ type: Boolean, reflect: true }); - 数字类型:使用
@property({ type: Number, reflect: true }); - 复杂类型(对象、数组,不反射):使用
@property({ attribute: false })。
- 基础类型(反射到属性):使用
-
更新组件渲染方法:若属性影响渲染,更新
render()方法中的模板。 -
添加属性变更处理(如需要):优先使用
update()生命周期钩子(此时 DOM 可用,适合副作用);仅在需要在渲染前计算派生状态且无需访问 DOM 时使用willUpdate()。最佳实践包括:优先使用update()、必要时才用willUpdate()、重写update()时始终调用super.update(changedProperties)、用changedProperties.has()判断以避免无谓工作。 -
更新测试:在
[component-name].spec.ts中添加默认值、属性变更、反射到属性的测试用例(使用fixture与elementUpdated)。 -
更新 Storybook 故事:在
stories/[component-name].stories.ts中更新argTypes、args、接口定义(IgcComponentArgs)和故事模板。 -
验证与测试:运行测试与类型检查,并在 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。 - 技能本身不提供具体命令之外的安装方式说明,官方文本暂未提供。