Stencil Web Components在Vite/Vue3中无法响应自定义属性的问题

原项目从vue-cli+Vue2选项式API迁移到create-vue构建的Vite+Vue3+TypeScript环境后，Stencil开发的Web组件出现属性绑定异常：

• 已升级Stencil至v2.16.1并在stencil.config.ts中添加experimentalImportInjection: true，组件可正常渲染
• 字符串类型属性（label/meta）无论使用绑定语法还是普通属性形式，值更新均正常生效
• 布尔/可选类型属性（valid/disabled）绑定完全无响应，修改值无法触发组件状态变化；但通过原生JavaScript直接设置属性可正常触发状态更新
• Chrome开发者工具中检查元素，仅能看到id、class等原生属性，看不到valid/disabled等自定义属性

Stencil组件属性定义：

@Prop() state: 'none' | 'focus' | 'active' = 'none';
@Prop() label: string;
@Prop() meta: string;
@Prop() disabled = false;
@Prop() valid?: true | false | null = null;

Vue组件中使用方式：

<fds-input id="loginEmail" label="Email" meta="meta text" :valid="false" :disabled="isDisabled">
  <input type="email" v-model="email" @blur="checkEmail" data-cy="input-text-email"/>
</fds-input>

核心需求：通过修改valid属性值，触发Web组件的有效/无效状态对应的CSS样式变化。

1. 强制使用DOM属性绑定（v-bind.prop） #

Vue3默认会将绑定的属性转换为HTML attribute，但Web组件的自定义Prop可能需要直接绑定到DOM属性上。对于布尔/可选类型的Prop，使用:valid.prop语法强制Vue将值作为DOM属性传递：

<fds-input 
  id="loginEmail" 
  label="Email" 
  meta="meta text" 
  :valid.prop="false" 
  :disabled.prop="isDisabled"
>
  <input type="email" v-model="email" @blur="checkEmail" data-cy="input-text-email"/>
</fds-input>

2. 配置Stencil Prop的reflect属性 #

Stencil中@Prop()默认不会将属性值同步到HTML attribute（reflect: false），设置reflect: true后，属性变化会同步到DOM，让Vue可以正确识别并更新：

@Prop({ reflect: true }) disabled = false;
@Prop({ reflect: true, nullable: true }) valid: boolean | null = null;

注意：nullable: true用于明确允许valid属性为null值，避免Stencil类型校验报错。

3. 配置Vue识别自定义元素 #

在vite.config.ts中告诉Vue哪些标签是自定义Web组件，避免Vue对其进行不必要的编译处理：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('fds-')
        }
      }
    })
  ]
})

4. 手动触发属性更新（临时兼容方案） #

如果上述方法无效，可通过Vue的ref获取组件实例，手动调用原生属性赋值来触发更新：

<template>
  <fds-input 
    ref="inputRef"
    id="loginEmail" 
    label="Email" 
    meta="meta text"
  >
    <input type="email" v-model="email" @blur="checkEmail" data-cy="input-text-email"/>
  </fds-input>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';

const inputRef = ref<HTMLElement | null>(null);
const isValid = ref(false);
const isDisabled = ref(false);

// 监听valid值变化，手动更新组件属性
watch(isValid, (newVal) => {
  inputRef.value && ((inputRef.value as any).valid = newVal);
});

// 监听disabled值变化，手动更新组件属性
watch(isDisabled, (newVal) => {
  inputRef.value && ((inputRef.value as any).disabled = newVal);
});
</script>

内容的提问来源于stack exchange，提问作者Andreasrein