कस्टम बटन ऐक्शन

Invoker Commands API की मदद से, एचटीएमएल एट्रिब्यूट का इस्तेमाल करके, टारगेट एलिमेंट पर कार्रवाइयां ट्रिगर करने के लिए बटन बनाए जा सकते हैं. इस तरीके से, मैन्युअल इवेंट लिसनर की ज़रूरत कम हो जाती है. साथ ही, यूज़र इंटरफ़ेस (यूआई) को लागू करने की जानकारी से अलग कर दिया जाता है. ऐप्लिकेशन के हिसाब से की जाने वाली कार्रवाइयों के लिए, अपनी पसंद के मुताबिक कमांड के नाम तय किए जा सकते हैं. कस्टम कमांड के आगे डबल डैश (--) लगाना ज़रूरी है, ताकि आने वाले समय में ब्राउज़र के पहले से मौजूद कमांड के साथ कोई टकराव न हो.

लागू करने के चरण

1. टारगेट एलिमेंट तय करना: उस एलिमेंट की पहचान करें जो कार्रवाई के हिसाब से काम करेगा. अगर इसमें कोई यूनीक id नहीं है, तो एक जोड़ें.
2. इनवोकर बटन को कॉन्फ़िगर करें: टारगेट के id पर ले जाने के लिए, commandfor एट्रिब्यूट का इस्तेमाल करें. साथ ही, कस्टम कमांड का नाम बताने के लिए, command एट्रिब्यूट का इस्तेमाल करें. इसके पहले -- लगाएं.
3. कमांड इवेंट को मैनेज करना: टारगेट एलिमेंट पर सीधे तौर पर command इवेंट लिसनर अटैच करें. इवेंट ऑब्जेक्ट में एक command प्रॉपर्टी और एक target प्रॉपर्टी होती है. यह commandfor से पहचाने गए एलिमेंट के बारे में बताती है.
4. एआरआईए स्टेट मैनेज करना: कस्टम कमांड में पहले से कोई सिमैंटिक नहीं होता है. इसलिए, आपको aria-pressed या aria-expanded जैसे स्टेट मैनेज करने होंगे.

उदाहरण: कस्टम ऐनिमेशन कंट्रोल

<!-- The target element that will respond to custom commands -->
<div id="action-target" class="target">
  Action Target
</div>

<!-- Buttons declaratively linked to the target element -->
<!-- Each button sends a unique custom command starting with '--' -->
<button commandfor="action-target" command="--spin">
  Spin
</button>

<button commandfor="action-target" command="--grow">
  Grow
</button>

<button commandfor="action-target" command="--reset">
  Reset All
</button>

<script>
  // 1. **Optional:** Define a registry of requested actions for cleaner logic
const commandRegistry = {
  '--spin': (target, source) => {
    const isSpun = target.classList.toggle('is-spun');
    // Set ARIA states, as custom commands have no inherent semantics.
    source?.setAttribute('aria-pressed', isSpun);
  },
  '--grow': (target, source) => {
    const isGrown = target.classList.toggle('is-grown');
    source?.setAttribute('aria-pressed', isGrown);
  },
  '--reset': (target) => {
    target.classList.remove('is-spun', 'is-grown');
    // Reset all associated buttons' ARIA states
    document.querySelectorAll(`button[commandfor="${target.id}"]`).forEach(btn => {
      btn.setAttribute('aria-pressed', 'false');
    });
  },
};

  // 2. **Mandatory:** Listen for the 'command' event directly on the target element
  // (This is necessary because the native 'command' event does not bubble)
  document.getElementById('action-target').addEventListener('command', (event) => {
    const command = event.command;
    const target = event.target;
    const source = event.source; // event.source refers to the triggering button
    const action = commandRegistry[command];

    if (action) {
      action(target, source);
    }
  });
</script>

मुख्य शर्तें

• पसंद के मुताबिक बनाए गए निर्देशों के लिए प्रीफ़िक्स: ज़रूरी: पसंद के मुताबिक बनाए गए सभी निर्देशों के नाम -- से शुरू होने चाहिए. उदाहरण के लिए, command="--my-action".
• टारगेटिंग: commandfor एट्रिब्यूट की वैल्यू, उसी दस्तावेज़ ट्री में मौजूद किसी एलिमेंट के id एट्रिब्यूट की वैल्यू से मेल खानी चाहिए.
• कोई बबलिंग नहीं: command इवेंट बबल नहीं होता. अगर एक से ज़्यादा टारगेट हो सकते हैं, तो इवेंट हैंडलर में { capture: true } जोड़ें और एंसेस्टर पर सुनें.
• शैडो रूट: अगर टारगेट किसी शैडो रूट में हो सकता है, तो event.target के बजाय event.composedPath()[0] का इस्तेमाल करें.
• सुलभता: कस्टम कमांड में कोई पहले से तय सिमैंटिक नहीं होता. आपको हर स्थिति को साफ़ तौर पर लागू करना होगा.

सुलभता से जुड़ी ज़रूरी बातें

• अगर बटन में अतिरिक्त कॉन्टेंट दिखता है, तो aria-expanded एट्रिब्यूट का इस्तेमाल करें. इसे डिफ़ॉल्ट रूप से aria-expanded="false" पर सेट करें. साथ ही, साथ में दिखने वाला कॉन्टेंट दिखने पर, इसे aria-expanded="true" पर सेट करें
• अगर बटन खुद ही इंटरैक्शन की सुविधा देता है, तो aria-pressed एट्रिब्यूट का इस्तेमाल करें. उदाहरण के लिए, टॉगल बटन, जो वीडियो को चला सकते हैं और रोक सकते हैं. इसके अलावा, आवाज़ कम या ज़्यादा करने वाले बटन, जो आवाज़ को म्यूट और अनम्यूट कर सकते हैं. इस एट्रिब्यूट को इनऐक्टिव होने पर aria-pressed="false" और ऐक्टिव होने पर aria-pressed="true" पर सेट करें
• अगर बटन से menu, listbox, tree, grid या dialog में से किसी एक भूमिका वाला एलिमेंट खुलता है, तो कंट्रोल में aria-haspopup एट्रिब्यूट होना चाहिए. साथ ही, इसकी वैल्यू उस एलिमेंट की भूमिका पर सेट होनी चाहिए जिसे यह खोलता है
• अगर बटन चालू होने पर बंद हो जाता है, तो disabled के बजाय aria-disabled="true" का इस्तेमाल करें, ताकि फ़ोकस बना रहे

फ़ॉलबैक रणनीतियां

अगर Invoker Commands API काम नहीं करता है, तो command इवेंट ट्रिगर नहीं होगा. सभी मॉडर्न ब्राउज़र पर पूरी तरह से काम करने के लिए, हमारा सुझाव है कि आप npm install या सीडीएन के ज़रिए, https://github.com/keithamus/invokers-polyfill से invokers-polyfill का इस्तेमाल करें.

यह पॉलीफ़िल, कस्टम ऐक्शन (-- से शुरू होने वाले) के साथ पूरी तरह काम करता है. साथ ही, नेटिव एपीआई की तरह ही command इवेंट को डिस्पैच करता है.

डाइनैमिक इंपोर्ट (परफ़ॉर्मेंस ऑप्टिमाइज़ेशन)

बेहतरीन परफ़ॉर्मेंस के लिए, आपको polyfill को सिर्फ़ तब लोड करना चाहिए, जब ब्राउज़र में एपीआई नेटिव तौर पर काम न करता हो. इससे बैंडविड्थ की बचत होती है और मॉडर्न ब्राउज़र इस्तेमाल करने वाले लोगों के लिए, स्क्रिप्ट को लागू करने में कम समय लगता है.

ध्यान दें: यह पॉलीफ़िल, कस्टम कमांड के लिए एआरआईए स्टेटस (जैसे, aria-pressed या aria-expanded) को मैनेज नहीं करता. आपको अपने इवेंट लिसनर में इन स्थितियों को मैन्युअल तरीके से सिंक करना होगा, ताकि यह पक्का किया जा सके कि आपकी साइट को ऐक्सेस किया जा सकता है.

// 1. Conditionally load the polyfill
const hasNativeSupport = 'commandForElement' in HTMLButtonElement.prototype;

if (!hasNativeSupport) {
  // Wrap in an async IIFE to avoid top-level await issues in older browsers
  (async () => {
    try {
      await import('https://esm.run/invokers-polyfill');
    } catch (err) {
      console.error('Error loading fallback:', err);
    }
  })();
}

// 2. Manually manage ARIA states in your listener
document.getElementById('action-target').addEventListener('command', (event) => {
  const command = event.command;
  const target = event.target;
  const source = event.source; // The button that triggered the command

  if (command === '--spin') {
    const isSpun = target.classList.toggle('is-spun');
    
    // Polyfill tip: Manually update ARIA to match the new state
    source?.setAttribute('aria-pressed', isSpun);
  }
});

मैन्युअल फ़ॉलबैक (पारंपरिक पैटर्न)

अगर आपको पॉलीफ़िल का इस्तेमाल नहीं करना है, तो इवेंट डिस्पैच करने के लिए इवेंट डेलिगेशन और कार्रवाइयों को मैनेज करने के लिए कमांड रजिस्ट्री का इस्तेमाल किया जा सकता है. यह JavaScript डेवलपमेंट का एक सामान्य आर्किटेक्चरल पैटर्न है. यह अब भी काफ़ी असरदार है और इसे आसानी से बढ़ाया जा सकता है.

// 1. **Optional:** Define a registry of requested actions for cleaner logic
const commandRegistry = {
  '--spin': (target) => target.classList.toggle('is-spun'),
  '--grow': (target) => target.classList.toggle('is-grown'),
  '--reset': (target) => target.classList.remove('is-spun', 'is-grown'),
};

// 2. If CommandEvent doesn't exist, we assume no native support and provide the fallback
if (!globalThis.CommandEvent) {
  globalThis.CommandEvent = class CommandEvent extends Event {
    constructor(type, { source, command, ...options } = {}) {
      super(type, options);
      this.source = source;
      this.command = command;
    }
  }
}

// 3. The fallback: Dispatch events manually if native support is missing
  document.addEventListener('click', (event) => {
    const button = event.composedPath().find((el) => el.matches?.("button[commandfor]"));
    if (!button) return;

    const target = document.getElementById(button.getAttribute('commandfor'));
    const command = button.getAttribute('command');

    if (target && command) {
      target.dispatchEvent(new CommandEvent('command', { 
        command, 
        source: button,
      }));
    }
  });

// 4. **Mandatory:** Register the unified listener directly on the target element
document.getElementById('action-target').addEventListener('command', (event) => {
  const command = event.command;
  const target = event.target;
  const action = commandRegistry[command];

  if (action) {
    action(target);
  }
 });