Başlarken (V1)

Kurulum

Terminalinize şunu yazın:

# npm
npm i effdnd

# pnpm
pnpm add effdnd

# yarn
yarn add effdnd

Hızlı başlangıç

Özetle effdnd, standart HTML öğelerinin rollerini belirlemek için veri özniteliklerini (data attributes) kullanır:

• sürüklenecek öğe (item),
• sürükleme hedefi (target),
• sürükleme alanı (scope).

effdnd-trigger özel öğesi, kendisine en yakın item için sürükle-bırak işlemini başlatır. Bu öğe, öznitelikler aracılığıyla yapılandırılabilir (ayrıntılar için ITriggerAttrs arayüzüne bakın). effdnd-trigger öğesinin kendisi de item rolüne sahip olabilir; bu, söz konusu öğenin kendi sürüklenme sürecini başlatabileceği anlamına gelir.

effdnd-trigger öğesini tanımlamak için useDnD işlevini çağırmanız ve bu işlevden dönen sonucu kullanarak özel veri öznitelikleri oluşturmanız yeterlidir.

import { useDnD } from 'effdnd';

// you can pass style params to useDnD to override global CSS for DnD elements (see `TUseDnD` type for details)
const { scope, item, target, css, observe } = useDnD();
// create scope attrs
const scopeAttrs = scope('local');
// create target attrs
const fisrtTargetAttrs = target('first');
// targets can be grouped
const secondTargetAttrs = target('second', 'group');
// create item attrs
const fisrtItemAttrs = item('first');
const secondItemAttrs = item('second');
// you can even set up separate styles for different DnD elements
const separateStyleAttrs = css({
    passiveTarget: 'border: 4px solid grey',
});

export const Component = () => {
    const ref = useRef();
    useEffect(() => {
      // you can observe DnD events
      const unobserve = observe((e) => {
        // DnD event reaction
      }, ref.current);
      // and you can unobserve
      return () => unobserve();
    })
    // just apply ready attrs - and magic happen
    // don't forget to use `effdnd-trigger` inside items
    return <div ref={ref} {...scopeAttrs}>
        <div className="targets-wrapper">
            <div {...fisrtTargetAttrs}>...</div>
            <div {...secondTargetAttrs} {...separateStyleAttrs}>...</div>
        </div>
        <div id="items-wrapper">
            <div {...fisrtItemAttrs}>
                <effdnd-trigger>Trigger #1</effdnd-trigger>
            </div>
            <div {...secondItemAttrs}>
                <effdnd-trigger>Trigger #2</effdnd-trigger>
            </div>
        </div>
    </div>;
}

Aktif ve pasif öğeler

Sürükleme işlemi sırasında effdnd, öğelerin durumunu gösteren dinamik öznitelikler (attributes) atar. Öğeler şu durumlarda olabilir:

• herhangi bir durum olmaksızın,
• pasif durumda,
• aktif durumda.

item (öğe), sürükleme sırasında aktif durumdadır.

Bir scope (kapsam), sürüklenen item onun içindeyse ve aşağıdaki koşullardan en az biri sağlanıyorsa pasif durumdadır:

• effdnd-trigger, scope anahtarına eşit bir değere sahip scope özniteliğini içeriyorsa,
• effdnd-trigger herhangi bir scope özniteliği içermiyorsa ve söz konusu scope, item'a en yakın kapsam ise.

Bir scope öğesi, pasif durumdayken item onun sınırlarının dışına çıkmaya çalıştığında aktif hale gelir. Bu durum, kullanıcıya sürükleme için mevcut sınırları göstermeye yardımcı olur.

Bir target (hedef) öğesi, aktif veya pasif durumdaki bir scope içinde yer alıyorsa ve aşağıdaki koşullardan herhangi biri sağlanıyorsa pasif durumdadır:

• effdnd-trigger, target öğesinin grubuna eşit bir değere sahip target özniteliğini içeriyorsa,
• effdnd-trigger herhangi bir target özniteliği içermiyorsa (bu durumda tüm target öğeleri uygun kabul edilir).

Bir target öğesi, pasif durumdayken item onun üzerine sürüklendiğinde aktif hale gelir.

useDnD

İşlev, ilk argüman olarak geçiş ayarlarını, ikinci argüman olarak ise özel stilleri kabul eder. Geri dönüş değeri olarak öznitelik çözümleyicileri ve olay işleyicileri sunar:

type TEventDetail = {
    type: TEventType;
    refs: TRefs;
    keys: TKeys;
    event: MouseEvent | TouchEvent;
};

interface TDnDEvent extends CustomEvent {
    detail: TEventDetail;
}

type TDnDCallback = (event: TDnDEvent) => void;

type TDynamicAttrs = Partial<{
    /**
     * Active DnD item styles
     */
    activeItem: string;
    /**
     * Passive DnD target styles
     */
    passiveTarget: string;
    /**
     * Active DnD target styles
     */
    activeTarget: string;
    /**
     * Passive DnD scope styles
     */
    passiveScope: string;
    /**
     * Active DnD scope styles
     */
    activeScope: string;
}>;

type TUseDnD = {
    (transition?: Partial<{
        /**
         * Duration
         */
        dur: string | number;
        /**
         * Delay
         */
        del: string | number;
        /**
         * Transition-timing-function
         */
        tf: string;
    }>, css?: TDynamicAttrs): {
        /**
         * Observe DnD events
         * @param callback - event handler
         * @param element - HTML element
         */
        observe: (callback: TDnDCallback, element?: HTMLElement) => () => void;
        /**
         * Unobserve DnD events
         * @param callback - event handler
         * @param element - HTML element
         */
        unobserve: (callback: TDnDCallback, element?: HTMLElement) => void;
        /**
         * Use DnD item
         * @param key - item key
         */
        item: (key: string) => object;
        /**
         * Use DnD target
         * @param key - target key
         */
        target: (key: string, group?: string) => object;
        /**
         * Use DnD scope
         * @param key - scope key
         */
        scope: (key?: string) => object;
        /**
         * Use different CSS for DnD elements
         */
        css: (params: TDynamicAttrs) => object;
    };
    customCount?: number;
    stylesheet?: CSSStyleSheet;
}

effdnd-trigger

Öğe, öznitelikler aracılığıyla yapılandırılabilir:

interface ITriggerAttrs {
    /**
     * Bounding scope key
     */
    scope?: string;
    /**
     * Targets group
     */
    target?: string;
    /**
     * Triggering distance
     */
    dist?: string;
    /**
     * Triggering event
     * @description
     * Both 'touch' and 'mouse' by default
     */
    event?: 'touch' | 'mouse';
}