Käyttötarkoitus
Käytä valintalassoa, kun haluat mahdollistaa esimerkiksi useamman valintaruudun valinnan yhdellä kertaa.
Valintalasso on tarkoitettu käytettäväksi asiantuntijoiden käyttöliittymissä apuvälineenä valintojen teon nopeuttamiseen.
Rajoitukset
- Valintalasso ei toimi pelkällä näppäimistöllä, eikä kosketuslaitteissa.
- Valintalasso estää oletuksena tekstin valitsemisen.
- Jos tekstin valinta on tärkeää, voi valintalasson rajoittaa tietyn elementin sisään tai laittaa sen aktivoitumaan ainoastaan jonkin näppäimen kanssa.
- Interaktiot voi myös palauttaa
preventInteraction-parametrilla. Tällöin lasso ja tekstin valinta toimivat yhtäaikaa.
Konfigurointi
Valintalassotyökalu koostuu SelectionLasso-komponentista ja useammasta React-hookista:
useSelectionLasso: Määrittää valintalasson näyttämisen, koon ja sijainnin ruudulla.useSelectionLassoSelect: Mahdollistaa kohteiden valinnan valmiiden sääntöjen pohjalta (vapaaehtoinen).useSelectionLassoScroll: Mahdollistaa sivun vierittämisen valinnan mukana, kun hiiri siirtyy näytön ylä- tai alareunaan (vapaaehtoinen).
Valintalasson voi siirtää Portal-komponentilla sivun loppuun, jos ympäröivien elementtien tyylimääritykset häiritsevät sen toimintaa.
const { onMouseMove, onMouseUp } = useSelectionLassoScroll({ scrollSpeed: 20, scrollThreshold: 50 });
useSelectionLassoSelect
const { select, onChange } = useSelectionLassoSelect({
selectItem(item) {
item.checked = true;
},
deselectItem(item) {
item.checked = false;
},
multiSelectKey: "Control",
selectableItems,
});
useSelectionLasso
const ref = useRef<HTMLDivElement>(null);
const { props } = useSelectionLasso(ref, {
container: document.documentElement,
enabled: true,
onMouseDown: undefined,
onMouseMove: (e, insideItems, outsideItems) => {
onMouseMove(e);
select(insideItems, outsideItems);
},
onMouseUp,
preventInteraction: true,
root: document.documentElement,
selectableItems,
selectionThreshold: 3,
});
Esimerkit
Valintaruutujen valinta
Useamman erillisen valintaruudun valitseminen onnistuu pitämällä ctrl-painiketta pohjassa.
function UseSelectionLassoExample() {
const [isLassoEnabled, setIsLassoEnabled] = useState(false);
const selectableItems = useRef<HTMLInputElement[]>([]);
const ref = useRef<HTMLDivElement>(null);
const { onMouseMove, onMouseUp } = useSelectionLassoScroll();
const { select, onChange } = useSelectionLassoSelect<HTMLInputElement>({
selectItem(item) {
item.checked = true;
},
deselectItem(item) {
item.checked = false;
},
selectableItems() {
return selectableItems.current;
},
});
const { props } = useSelectionLasso<HTMLInputElement>(ref, {
onMouseUp,
onMouseMove: (e, insideItems, outsideItems) => {
onMouseMove(e);
select(insideItems, outsideItems);
},
selectableItems() {
return selectableItems.current;
},
enabled: isLassoEnabled,
});
return (
<>
<Button onClick={() => setIsLassoEnabled(!isLassoEnabled)} className="kds-mb-6">
{isLassoEnabled ? "Poista lasso käytöstä" : "Ota lasso käyttöön"}
</Button>
<div>
{[...Array(20)].map((x, i) => (
<Checkbox
key={`checkbox-${i}`}
ref={(el) => (selectableItems.current[i] = el)}
labelText={`Valinta ${i + 1}`}
onChange={() => onChange(selectableItems.current[i], selectableItems.current[i].checked)}
/>
))}
</div>
<Portal>
<SelectionLasso ref={ref} {...props} />
</Portal>
</>
);
}
Taulukon rivien valinta
Esimerkki taulukon rivien valinnasta. Useamman erillisen valintaruudun valitseminen onnistuu pitämällä ctrl-painiketta pohjassa.
function UseSelectionLassoExample() {
const [rowAmount, setRowAmount] = useState(20);
const [isLassoEnabled, setIsLassoEnabled] = useState(false);
const selectableItems = useRef<HTMLInputElement[]>([]);
const ref = useRef<HTMLDivElement>(null);
const {
isToggleOn: isSelected,
flipToggle: toggleSelect,
flipAll: toggleAllSelected,
setToggleOn,
setToggleOff,
} = useToggle();
const { onMouseMove, onMouseUp } = useSelectionLassoScroll();
const { select, onChange } = useSelectionLassoSelect<HTMLInputElement>({
selectItem(item) {
setToggleOn(`row-${selectableItems.current.indexOf(item)}`);
},
deselectItem(item) {
setToggleOff(`row-${selectableItems.current.indexOf(item)}`);
},
selectableItems() {
return selectableItems.current;
},
});
const { props } = useSelectionLasso<HTMLInputElement>(ref, {
onMouseUp,
onMouseMove: (e, insideItems, outsideItems) => {
onMouseMove(e);
select(insideItems, outsideItems);
},
selectableItems() {
return selectableItems.current;
},
enabled: isLassoEnabled,
});
const rows = [...Array(rowAmount)].map((x, i) => `row-${i}`);
const allRows = ["row-select-all", ...rows];
const handleToggle = (index, key, isSelected) => {
toggleSelect(key);
onChange(selectableItems.current[index], isSelected);
};
const handleToggleAll = () => {
toggleAllSelected(allRows);
selectableItems.current.forEach((row) => {
onChange(row, !row.checked);
});
};
return (
<>
<ButtonGroup className="kds-mb-6" horizontal>
<Button onClick={() => setIsLassoEnabled(!isLassoEnabled)}>
{isLassoEnabled ? "Poista lasso käytöstä" : "Ota lasso käyttöön"}
</Button>
<Button onClick={() => setRowAmount(rowAmount + 10)} appearance="outline">
Lisää rivejä
</Button>
</ButtonGroup>
<TableV2>
<TableV2Head>
<TableV2HeadRow
isSelected={isSelected("row-select-all")}
onSelectChange={handleToggleAll}
selectLabel="Valitse kaikki rivit"
>
<TableV2HeadCell scope="col">Lorem</TableV2HeadCell>
<TableV2HeadCell scope="col">Ipsum</TableV2HeadCell>
<TableV2HeadCell scope="col">Dolor</TableV2HeadCell>
</TableV2HeadRow>
</TableV2Head>
<TableV2Body>
{rows.map((key, i) => (
<TableV2Row
inputRef={(el) => (selectableItems.current[i] = el)}
isSelected={isSelected(key)}
key={key}
onSelectChange={() => handleToggle(i, key, !isSelected(key))}
selectLabel="Valitse rivi"
selectType="multiple"
>
<TableV2Cell>Rivi {i + 1}</TableV2Cell>
<TableV2Cell>Ipsum</TableV2Cell>
<TableV2Cell>Dolor</TableV2Cell>
</TableV2Row>
))}
</TableV2Body>
</TableV2>
<Portal>
<SelectionLasso ref={ref} {...props} />
</Portal>
</>
);
}
Valintalasson rajoittaminen tietyn elementin sisään
Esimerkissä valintalasso aktivoituu pitämällä ctrl-painiketta pohjassa. Useampien valintojen tekeminen tapahtuu ctrl- ja alt-painikkeilla.
Valintalasso on myös asetettu valitsemaan ainoastaan valintaruutuja ympäröivän elementin sisällä root- ja container-parametrien avulla.
root-parametri asettaa elementin, jonka sisällä muiden elementtien interaktiot estetään lasson ollessa aktiivisena (esimerkiksi tekstin valinta, hover-efektit).container-parametri asettaa valintalasson aktivoitumaan ja valitsemaan vain annetun HTML-elementin sisällä.
function UseSelectionLassoExample() {
const [isLassoEnabled, setIsLassoEnabled] = useState(false);
const selectableItems = useRef<HTMLInputElement[]>([]);
const containerRef = useRef<HTMLDivElement>(null);
const ref = useRef<HTMLDivElement>(null);
const { select, onChange } = useSelectionLassoSelect<HTMLInputElement>({
selectItem(item) {
item.checked = true;
},
deselectItem(item) {
item.checked = false;
},
multiSelectKey: ["Control", "Alt"],
selectableItems() {
return selectableItems.current;
},
});
const { props } = useSelectionLasso<HTMLInputElement>(ref, {
root: containerRef.current,
container: containerRef.current,
onMouseMove: (e, insideItems, outsideItems) => {
select(insideItems, outsideItems);
},
selectableItems() {
return selectableItems.current;
},
enabled: isLassoEnabled,
});
useEffect(() => {
const handleKeyDown = (e: KeyboardEvent) => {
if (e.key === "Control" && !isLassoEnabled) {
setIsLassoEnabled(true);
}
};
const handleKeyUp = (e: KeyboardEvent) => {
if (e.key === "Control" && isLassoEnabled) {
setIsLassoEnabled(false);
}
};
window.addEventListener("keydown", handleKeyDown);
window.addEventListener("keyup", handleKeyUp);
return () => {
window.removeEventListener("keydown", handleKeyDown);
window.removeEventListener("keyup", handleKeyUp);
};
}, [isLassoEnabled]);
return (
<>
<div ref={containerRef} className="kds--m-4 sm:kds--m-6 kds-p-4 sm:kds-p-6">
{[...Array(20)].map((x, i) => (
<Checkbox
key={`checkbox-${i}`}
ref={(el) => (selectableItems.current[i] = el)}
labelText={`Valinta ${i + 1}`}
onChange={() => onChange(selectableItems.current[i], selectableItems.current[i].checked)}
/>
))}
</div>
<SelectionLasso ref={ref} {...props} />
</>
);
}
Huomioitavaa selaintuessa