放置区

概览

link

Web

tanrei-drop-zone

clock_loader_40

SwiftUI

TanreiDropZone

radio_button_unchecked

Jetpack Compose

TanreiDropZone

radio_button_unchecked

Flutter

TanreiDropZone

radio_button_unchecked

React Native

DropZone

radio_button_unchecked

生成自 docs/status/status.json, specs/drop-zone.spec.json

放在放置区里的一个视频界面。从你的电脑上把一个文件拖到它上面的任何位置：整个界面都会显示可以放下。在这里放下不会带来任何变化：页面不保留任何文件。

上传视频频道预告片 · 1:24春季更新 · 8:03幕后花絮 · 12:47

放置区把整个界面或其中任意一部分，变成可以放下文件的地方。用它包住一个文档列表、一个视频库、一段对话，或者你的应用的主区域。里面的一切照常工作：按钮、表格和字段的按下、滚动和键盘操作，都和没有放置区时一样。放置区不添加悬停，不添加按下，不添加焦点停靠点，也不添加角色。

有文件拖到它上面时，一个浮层盖住放置区：内容上方的一层暗色、围着它的一道边线，以及一块带有上传字形和你的消息的面板。文件放下后，放置区按与文件选择器相同的规则判定它们，再交给你：被接受的文件随 select 交出，被拒绝的文件随 reject 交出。把它们交给文件上传，或者交给你自己的列表。

绝不能是唯一的途径

拖动文件是一个指针动作，键盘、屏幕阅读器、语音控制和大多数触摸屏都做不到。有放置区的界面，始终还要提供一个文件选择器或文件上传——放在工具栏、应用栏或空状态里。两者都没有的页面，调试构建会报告出来。

如果放下文件的地方是表单里一块有边界的区域，并且按下它也会打开选择器，就改用文件选择器的拖放区域布局。

在 Web 上它是 <tanrei-drop-zone>。其他平台尚未实现。

用法

link

包住内容，并监听 select。

<tanrei-drop-zone id="zone" multiple accept="video/*" max-size="2000000000"
                  drop-text="放下视频即可上传" silent>
  <tanrei-file-upload id="uploads" multiple accept="video/*" max-size="2000000000"
                      constraints-text="视频，每个不超过 2 GB">
    <tanrei-button slot="trigger" variant="outlined">上传视频</tanrei-button>
  </tanrei-file-upload>
  <tanrei-table>…频道的视频…</tanrei-table>
</tanrei-drop-zone>

<script type="module">
  import '@tanrei/web/components/drop-zone';
  import '@tanrei/web/components/file-upload';
  import '@tanrei/web/components/button';

  const uploads = document.querySelector('#uploads');
  // 文件上传会列出放下的文件，并逐个说明，所以放置区保持安静。
  document.querySelector('#zone').addEventListener('select', ({ detail }) => uploads.add(detail.files));
  // 被拒绝的文件带有一个原因，它是一个名称，而不是一句话。请用你自己的话来说。
  document.querySelector('#zone').addEventListener('reject', ({ detail }) => showRefused(detail.files));
</script>

import { Button, DropZone, FileUpload } from '@tanrei/react';

<DropZone multiple accept={['video/*']} dropText="放下视频即可上传" silent
  onSelect={(event) => uploads.current?.add(event.detail.files)}
  onReject={(event) => showRefused(event.detail.files)}>
  <FileUpload ref={uploads} multiple accept={['video/*']} constraintsText="视频，每个不超过 2 GB">
    <Button slot="trigger" variant="outlined">上传视频</Button>
  </FileUpload>
  <VideoTable />
</DropZone>

放置区的盒子就是内容的布局盒子。像给任何包裹元素设置样式那样设置它：高度、display: grid、overflow。

规格

link

构成

部件	说明
1 container	The zone itself: a box around the product's content, of the size its layout gives it. It draws nothing of its own, carries no state and exposes nothing.
2 content	What the product places in the zone, in its default slot: laid out, styled and used as without the zone.
3 overlay · 可选	Drawn only while files are dragged over the zone: one layer over the whole zone's box, above all its content — the scrim, and the edge drawn inside the box. It takes no press and no scroll.
4 panel · 可选	The raised surface at the centre of the part of the zone that is in view, holding the glyph and the message.
5 icon · 可选	The glyph in the panel: the icon set's upload glyph, or its block glyph while the zone refuses what is dragged. Decorative.
6 label · 可选	The message in the panel: dropText, or refusingText while the zone refuses what is dragged.

属性

属性	类型	默认值	说明
multiple	boolean	false	Whether a drop may bring more than one file, as the File picker's multiple. False: a drop of several is refused whole (reject, reason count). True: any number, up to maxFiles.
accept	strings		The kinds of file that are taken, as the File picker's accept: file name extensions with their dot (".pdf") and media types, a whole family as "image/*". A dropped file of another kind, or a folder, is refused (reject, reason type). Empty takes every kind.
maxSize	number	null	The largest size of one file, in bytes, as the File picker's maxSize. A larger file is refused (reject, reason size). Null sets no limit. Judged from the size the platform reports; the file is not read.
maxFiles	number	null	The most files one drop may bring while multiple is true, as the File picker's maxFiles: files beyond it are refused (reject, reason count). Null sets no limit; ignored while multiple is false; zero refuses every file — the room a full list has left. Nothing is counted across drops: a product that keeps a list sets this to the room that is left.
dropText	string	""	The message in the overlay while the zone will take what is dragged over it, in the product's words ("Drop files to upload them"). Empty reads the product's words; with neither, the panel draws the glyph alone and that is reported.
refusingText	string	""	The message in the overlay while the zone will not take what is dragged over it ("These files cannot be added here"). Drawn only where the platform tells before the drop that nothing dragged can be taken (DRZ-5). Empty reads the product's words; with neither, the panel draws the block glyph alone and that is reported.
droppedText	string	""	The sentence assistive technology is told after a drop in which files passed, with the place {count} filled by how many ("{count} files added"). Empty reads the product's words; with neither, nothing is said for them and that is reported (DRZ-11).
refusedText	string	""	The sentence assistive technology is told after a drop in which files were refused, with the place {count} filled by how many ("{count} files could not be added"). Empty reads the product's words; with neither, nothing is said for them and that is reported (DRZ-11).
silent	boolean	false	Whether the drop zone says nothing after a drop. Set it only where the product hands every dropped file to a component that says them itself — a File upload that keeps its own rows announces each file it keeps or refused — so that one drop is not said twice. It changes nothing that is drawn.
disabled	boolean	false	Nothing can be dropped: no overlay is drawn and nothing is emitted. It concerns dropping alone — the content is neither disabled nor dimmed, and stays as usable as it was.

插槽

插槽	说明
default	The content: any part of the product's screen — a list, a table, a working view, the main region of an app shell. In fixtures the content is a sample screen: the fixture's content string as a paragraph above an outlined Button labelled "New video", on a surface 360 wide and 240 tall.

事件

事件	说明
select	Files were dropped on the zone and passed accept, maxSize and the count of one drop. Emitted once per drop, with those files as the platform's own handles, in the order the platform gave them — what the File picker's select carries (FPK-9). The drop zone keeps none of them and reads none: the product hands them to a File upload's way in, a list of its own, or a sending of its own.
reject	Files of one drop were refused. Emitted once, after select where both happen, with each refused file and its reason — type (not among accept, or a folder), size (larger than maxSize) or count (more than one while multiple is false, or more than maxFiles in one drop) — what the File picker's reject carries (FPK-9). The reasons are names for the product's code: the product says what happened where a person sees it (a snackbar, a row of its list, a Field's errorText).

状态

行为

以 EARS 形式写成的需求。每个平台的实现都按这些 ID 逐条测试。需求原文取自规格文件，原样以英文呈现。

ID	需求
DRZ-1	THE drop zone SHALL be a box of the size its layout gives it and SHALL lay out what the product places in it as the product's own styles say, as if the zone were not there. WHILE no drag of files is over it THE drop zone SHALL draw nothing of its own — no fill, no edge, no padding, no glyph, no text. THE drop zone SHALL add to what it holds no hovered, pressed, focused or selected state, no stop in the focus order, no role and no name, and SHALL change no role, name, state or focus order of its content.
DRZ-2	WHILE a drag of files is over it and WHILE none is, THE drop zone SHALL leave every press, click, key, wheel, scroll, touch, text selection, drag of text or of an element, and focus inside it to its content and the platform. WHEN the zone is pressed THE drop zone SHALL do nothing — it opens no picker and moves no focus (unlike the File picker's drop area, FPK-12), because the zone is the content and every press in it is the content's.
DRZ-3	THE drop zone SHALL answer a drag only WHERE the platform says the drag holds files (on the web, its types include Files). A drag of text, of a link, of a picture from a page or of an element SHALL be left wholly to the content and the platform: no overlay, no effect named, and nothing taken, so that a text field inside the zone still takes a drop of text.
DRZ-4	WHILE a drag of files is over the zone, disabled is false and no drop target inside the zone has taken it (DRZ-8), THE drop zone SHALL draw the overlay over its whole box and tell the platform that letting go here copies. The overlay SHALL be the scrim, filled with comp.drop-zone.scrim.color over the whole box; an edge comp.drop-zone.outline.width wide in comp.drop-zone.outline.color, solid, drawn inside the box and following the corners the box has of its own; and a panel (DRZ-6) filled with comp.drop-zone.panel.container.color, lifted by comp.drop-zone.panel.elevation, with corners of comp.drop-zone.panel.shape eased by sys.shape.corner-smoothing, comp.drop-zone.panel.padding-block from its top and bottom and comp.drop-zone.panel.padding-inline from its sides, holding one column centred on the inline axis: the icon set's upload glyph at comp.drop-zone.icon.size in comp.drop-zone.icon.color, with sys.icon.family.unselected, sys.icon.fill.unselected, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max, then comp.drop-zone.panel.gap below it dropText in comp.drop-zone.label.typescale and comp.drop-zone.label.color, centred, on as many lines as it needs and never cut. The panel SHALL be as wide as its message needs and no wider than comp.drop-zone.panel.max-width.
DRZ-5	WHERE the platform tells before the drop that nothing dragged can be taken — every file is of a kind accept refuses, which can be known only where accept lists media types alone, or it holds more than one file while multiple is false, as the File picker's area judges it (FPK-13) — THE drop zone SHALL draw the overlay as refusing: the scrim and the panel as in DRZ-4, the edge in comp.drop-zone.refusing.outline.color, the icon set's block glyph in place of the upload glyph in comp.drop-zone.refusing.icon.color, and refusingText in place of dropText; and SHALL tell the platform that letting go here does nothing. Where the platform cannot tell (an extension, a size, a count that maxFiles limits), the zone SHALL draw it as taking and judge at the drop (DRZ-9).
DRZ-6	THE drop zone SHALL draw the overlay inside its own box and above everything it holds: never outside the box, whatever the content's own stacking order; content that must stand above the overlay stands in the platform's top layer (a dialog, a popover, a menu). THE overlay SHALL take no press, pointer, wheel, touch or scroll: each SHALL reach the content or the scrolling area beneath it, as if the overlay were not there. THE drop zone SHALL draw the panel inside the part of its box that is in view — inside the window and inside every scrolling or clipping area around it — centred in that part and at least comp.drop-zone.panel.margin from its edges, so that a zone taller than the window (a whole page, the main region of an app shell) shows its message where the person is looking. WHERE the part in view is smaller than the panel, the panel SHALL be clipped at the zone's box and its glyph SHALL be kept before its message.
DRZ-7	THE condition of DRZ-4 and DRZ-5 SHALL begin when a drag of files enters the zone's box and SHALL end when the drag leaves the box, is let go anywhere, is cancelled, or leaves the window — and SHALL NOT end, flicker or begin again when the drag crosses from one part of the content to another, onto the content's own children, or over content that appears, moves or is removed during the drag.
DRZ-8	WHERE a drop target inside the zone takes the drag — another drop zone, a File picker's drop area, or a target of the product's own — the innermost target SHALL take it: while the drag is over that target THE drop zone SHALL draw no overlay, name no effect and take no drop, and SHALL take the drag again as soon as it leaves that target for the rest of the zone. A disabled drop zone inside it takes nothing, so the enclosing zone takes a drag over it.
DRZ-9	WHEN files are let go over the zone WHILE disabled is false and no drop target inside the zone took them, THE drop zone SHALL end the condition at once, take the drop so that the platform does not open or navigate to a file, and judge what was dropped exactly as the File picker judges an arrival (FPK-9) — by multiple, accept, maxSize and maxFiles, a folder refused with the reason type, in the order the platform gave them — and SHALL then emit select once with the files that passed, where there are any, and reject once with the refused files and their reasons, where there are any, in that order. A drop over a refusing zone that the platform still delivers SHALL be judged the same way; a drop that holds no file SHALL emit nothing. THE drop zone SHALL NOT move focus because of a drop.
DRZ-10	THE drop zone SHALL keep nothing and send nothing, as the File picker (FPK-7): it SHALL open no connection, SHALL NOT read a file's bytes, copy or store a file, SHALL NOT hold a file or any record of an earlier drop beyond the turn in which it hands one drop over, and SHALL take no part in a form — no name, no value, nothing submitted, reset or restored. What is known of a file SHALL be what the platform reports of it without opening it: its name, its size and its kind.
DRZ-11	THE drop zone SHALL have exactly one live region, polite and never assertive, and WHEN a drop was judged WHILE silent is false SHALL say through it, once, as one message: droppedText with {count} filled by the number of files that passed, WHERE any passed; then refusedText with {count} filled by the number refused, WHERE any were refused. It SHALL NOT announce a drag over it, the overlay, or a drop that holds no file, and SHALL NOT move keyboard or screen-reader focus to announce. IF neither the instance nor the product's words give the sentence that is needed THE drop zone SHALL say nothing for it and in debug builds report the missing word once per page or screen. WHILE silent is true THE drop zone SHALL say nothing and need neither word.
DRZ-12	THE drop zone SHALL have no words of its own: it SHALL take dropText, refusingText, droppedText and refusedText from the instance's prop and, WHILE that is empty, from the product's words of the keys dropZoneText, dropZoneRefusingText, filesDroppedText and filesRefusedText, and from nowhere else; and SHALL need a word only where the part that shows or says it is drawn or said. IF dropText or refusingText is not given where its panel is drawn THE drop zone SHALL draw the panel with its glyph alone and in debug builds report the missing word once per page or screen. THE drop zone SHALL build no sentence from accept, maxSize, maxFiles, a count of files or a size in bytes, other than filling {count}.
DRZ-13	THE drop zone SHALL NOT be the only way to add the files it takes: dragging files is a movement that a keyboard, a switch, a screen reader, voice control and most touch screens cannot make (WCAG 2.1.1, 2.5.7). The product SHALL offer, on the same screen and while the zone takes drops, a File picker or a File upload — or a control of its own that opens the platform's picker — that adds the same files to the same place. WHEN a drag of files first enters a zone on a page or screen that holds no file picker of any kind, THE drop zone SHALL still take it and in debug builds report that files cannot be added without a pointer.
DRZ-14	WHILE disabled is true THE drop zone SHALL draw no overlay, say nothing and emit neither select nor reject, and SHALL tell the platform that letting go here does nothing; WHERE no enabled drop zone encloses it, it SHALL still take a drop of files over its box, so that a file let go by mistake does not replace the page. THE drop zone SHALL NOT disable, dim or make inert its content: disabled concerns dropping alone. WHEN disabled becomes true during a drag THE drop zone SHALL end the condition at once. The way of DRZ-15 SHALL still answer: disabled stops the person, not the product.
DRZ-15	THE drop zone SHALL offer the product, in the platform's idiom, a way to have files judged by its rule that did not arrive by a drop on it — files pasted, dropped elsewhere, or made by the product — as one arrival, answering with the files that passed and the refused files with their reasons, each in the order given, as the File picker's way does (FPK-31); it SHALL emit neither select nor reject for them, say nothing for them, and keep none of them.
DRZ-16	WHEN the overlay appears THE drop zone SHALL fade it in, and WHEN it leaves SHALL fade it out, over comp.drop-zone.motion.duration with comp.drop-zone.motion.easing, and SHALL animate a change between taking and refusing over the same; where motion is reduced it SHALL show and hide the overlay at once. The fade SHALL NOT delay the end of the condition: a drop or a press made while the overlay fades out reaches what it would reach without it.
DRZ-17	WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE drop zone SHALL draw the edge in the platform's highlight color, solid and twice comp.drop-zone.outline.width wide, so that it does not rest on the scrim the mode removes; the panel in the platform's background color with an edge comp.drop-zone.outline.width wide in its text color; the message in its text color; and the refusing overlay with its block glyph, so that refusing is told without color.
DRZ-18	WHILE the text size is enlarged THE drop zone SHALL grow its panel with its message: the message wraps and is never cut, the glyph keeps its box, and the panel grows in height up to the part of the zone in view (DRZ-6). At 200 % in a width of 320 no word of the message SHALL be lost or lie over another part.
DRZ-19	THE drop zone SHALL take its layout direction from where it is used and SHALL have no direction setting of its own. THE message SHALL be laid out as text of its own direction, isolated, taking the base direction of its first strong character, or the layout direction where it has none, and centred in the panel in either direction. WHERE the layout direction is right-to-left a glyph SHALL be mirrored exactly when the system's icon set marks its name as mirrored, by the icon helper; THE drop zone SHALL mirror no glyph itself.
DRZ-20	WHEN a prop of the drop zone changes THE drop zone SHALL draw the new value at once, during a drag too, and SHALL announce nothing because of it; WHEN multiple, accept, maxSize or maxFiles changes it SHALL judge by the new value from the next drag and drop on. IF maxSize is not a number above zero THE drop zone SHALL set no limit of size; IF maxFiles is not a whole number of zero or more it SHALL set no limit of count; IF an entry of accept is neither an extension with its dot nor a media type it SHALL ignore that entry; in each case debug builds SHALL report it, as the File picker does (FPK-27).
DRZ-21	WHILE the system's icon set cannot yet draw the overlay's glyph (its font is still loading) THE drop zone SHALL draw nothing in that glyph's place, never the glyph's name as text, SHALL keep the glyph's box, and SHALL draw the glyph once the set can.

各平台名称对照

对等并不意味着 API 完全相同。同一份契约，由各平台以自己的惯用方式表达。

规格	Web	SwiftUI	Jetpack Compose	Flutter	React Native
组件	tanrei-drop-zone	TanreiDropZone	TanreiDropZone	TanreiDropZone	DropZone
multiple · 属性	multiple	allowsMultiple	multiple	multiple	multiple
accept · 属性	accept	allowedContentTypes	mimeTypes	accept	accept
maxSize · 属性	maxSize	maxSize	maxSize	maxSize	maxSize
maxFiles · 属性	maxFiles	maxFiles	maxFiles	maxFiles	maxFiles
dropText · 属性	dropText	dropText	dropText	dropText	dropText
refusingText · 属性	refusingText	refusingText	refusingText	refusingText	refusingText
droppedText · 属性	droppedText	droppedText	droppedText	droppedText	droppedText
refusedText · 属性	refusedText	refusedText	refusedText	refusedText	refusedText
silent · 属性	silent	isSilent	silent	silent	silent
disabled · 属性	disabled	disabled	enabled	enabled	disabled
select · 事件	select	onSelect	onSelect	onSelect	onSelect
reject · 事件	reject	onReject	onReject	onReject	onReject
备注	A custom element with a shadow root around the product's own content: <tanrei-drop-zone multiple accept="video/*" drop-text="Drop videos to upload them"> … the screen … </tanrei-drop-zone>. Attributes are kebab-case (max-size, max-files, drop-text, refusing-text, dropped-text, refused-text); accept is a comma-separated list, as a native file input's. The content stays in the product's light DOM in the default slot, which is display: contents, so the host is the content's layout box: a product lays the content out by styling the host (display: grid, a height, overflow) as it would any wrapper; the host is display: block by default, position: relative and isolation: isolate (DRZ-6) — a product sets no position: static on it. The overlay is one absolutely positioned element of the shadow root over the host's padding box, after the slot, with the greatest z-index, pointer-events: none and aria-hidden="true"; its panel is placed by the element in the part of the host's box that is in view — the host's rectangle cut by the window and by every ancestor that clips or scrolls, measured on each dragenter and dragover — so a zone taller than its scrolling area shows the panel where the person looks. The element listens for dragenter, dragover, dragleave and drop on its host, in the bubbling phase: an event whose default is already prevented is an inner target's (DRZ-8); otherwise, where dataTransfer.types includes Files, it prevents the default, sets dropEffect to copy or none, and counts enters and leaves so that a child of the content does not end the condition; a dragleave whose relatedTarget is outside the host ends it at once, and while the condition holds the window's dragenter outside the host, drop, dragend and pointermove end it too (DRZ-7). During a drag the browser tells kinds and a count (DataTransfer.items), never names or sizes, so a file that is too large or of a refused extension is refused at the drop. The judging is the File picker's own, shared with it (src/primitives/file-judge.ts), not a copy. select and reject are CustomEvents that bubble: detail.files is a File[], and reject's detail.files is { file, reason }[] — the File picker's details, so one listener can serve both. judge(files: Iterable<File>) is DRZ-15. The live region is one visually hidden aria-live="polite" element. Not form-associated. Parts: overlay, panel, icon, label. Custom properties: --<namespace>-comp-drop-zone-…. Before the element is defined its content is drawn as it is and a drop of files is the browser's. Class TanreiDropZone. React: DropZone, with onSelect, onReject, and a ref with judge().	A modifier rather than a container, as SwiftUI attaches behaviour to any view: VideoList().tanreiDropZone(allowedContentTypes: [.movie], onSelect: { urls in … }). It is dropDestination(for: URL.self) with its isTargeted binding, and the overlay an .overlay with allowsHitTesting(false); SwiftUI tells the kinds before the drop, not sizes. The innermost destination takes a drop by SwiftUI's own rule. The announcement is AccessibilityNotification.Announcement. DRZ-15 is the File picker's static TanreiFilePicker.judge(_:accept:maxSize:maxFiles:multiple:). On iPhone a drag of files comes from another app in split view or from Files; the zone still adds nothing to the content.	TanreiDropZone(onSelect = { uris -> … }) { VideoList() }, a box around the content with Modifier.dragAndDropTarget(shouldStartDragAndDrop = { it.mimeTypes().isNotEmpty() }); the overlay is drawn in a layer that takes no pointer input. Content Uris are read for name and size from the resolver's metadata, never opened, and the app requests drag-and-drop permissions for the drop as the platform asks. disabled is the inverse flag enabled. The announcement is a liveRegion = Polite node. DRZ-15 is the File picker's judgeFiles(uris, limits).	The framework has no drop target for files; the package depends on no plugin. TanreiDropZone(controller: …, onSelect: …, child: VideoList()): the product's drop plugin calls TanreiDropZoneController.dragEntered(kinds) / dragExited() / dropped(files) with TanreiPickedFile(name, size, mimeType, handle), and the zone draws the overlay in an IgnorePointer layer and judges by FPK-9. Without a plugin the zone draws nothing and takes nothing; the README says so. disabled is the inverse flag enabled. The announcement is SemanticsService.announce.	React Native has no drop of files of its own; the package depends on no library. <DropZone onSelect={…}>…</DropZone> takes drops where the product's native module reports them through the zone's ref (dragEntered, dragExited, dropped(files), with { name, size, type, uri }), and draws the overlay with pointerEvents="none". On a phone with no such module it draws nothing and takes nothing; the README says so. The announcement is AccessibilityInfo.announceForAccessibility. A ref holds judge(files) (DRZ-15).

令牌

令牌	引用	解析值（浅色）
--tanrei-comp-drop-zone-icon-color	sys.color.primary	#1b1b1b
--tanrei-comp-drop-zone-icon-size	sys.icon.large	32px
--tanrei-comp-drop-zone-label-color	sys.color.on-surface	#1b1b1b
--tanrei-comp-drop-zone-motion-duration	sys.motion.role.state.large	250ms
--tanrei-comp-drop-zone-motion-easing	sys.motion.easing.state	cubic-bezier(0.2, 0, 0, 1)
--tanrei-comp-drop-zone-outline-color	sys.color.primary	#1b1b1b
--tanrei-comp-drop-zone-outline-width	sys.border.thick	2px
--tanrei-comp-drop-zone-panel-container-color	sys.color.surface-container-high	#f3f3f3
--tanrei-comp-drop-zone-panel-elevation	sys.elevation.level2	0px 0px 0px 1px rgb(0 0 0 / 0.08), 0px 1px 2px 0px rgb(0 0 0 / 0.04)
--tanrei-comp-drop-zone-panel-gap	sys.space.space150	12px
--tanrei-comp-drop-zone-panel-margin	sys.space.space200	16px
--tanrei-comp-drop-zone-panel-max-width	—	360px
--tanrei-comp-drop-zone-panel-padding-block	sys.space.space300	24px
--tanrei-comp-drop-zone-panel-padding-inline	sys.space.space300	24px
--tanrei-comp-drop-zone-panel-shape	sys.shape.corner.large	12px
--tanrei-comp-drop-zone-refusing-icon-color	sys.color.error	#cd262f
--tanrei-comp-drop-zone-refusing-outline-color	sys.color.error	#cd262f
--tanrei-comp-drop-zone-scrim-color	sys.color.scrim	#000000 · 40%
--tanrei-comp-drop-zone-label-typescale	sys.typescale.body-large	400 16px/1.625

测试样例

作为基准的渲染结果。所有平台都以相同的 ID 为每个样例截取快照，以便相互比较。

default

multiple: true dropText: Drop files to upload them

dragged

multiple: true dropText: Drop files to upload them

dragged-refusing

multiple: true accept: ["image/png","image/jpeg"] dropText: Drop images to add them refusingText: Only PNG and JPEG images can be added

dragged-long-text

multiple: true dropText: Drop the signed forms and every supporti…

dragged-disabled

multiple: true dropText: Drop files to upload them disabled: true

dragged-rtl

multiple: true dropText: Drop files to upload them direction: rtl

生成自 specs/drop-zone.spec.json, tokens/comp/drop-zone.tokens.json, design/tokens/

指南

link

放在哪里

link

包住什么	何时
你的应用的主区域	界面的主要任务是存放文件：一个媒体库、一个云盘、一个文档列表。用户在哪里工作，文件就可以放在哪里。
一个面板或一个列表	界面上只有一部分接收文件：一条记录的附件、一段对话。
改用文件选择器的拖放区域	放下文件的地方是表单里一块有边界的区域，并且按下它也会打开选择器。

放置区里的另一个放置区，在拖动经过它上方时由它自己接收放下的文件；放置区里的文件选择器拖放区域也是如此。始终由最里层的地方接收。

浮层

link

浮层只在有文件拖到放置区上方时出现，而且只针对文件：拖动的文本和链接留给内容处理，所以放置区里的文本字段照样能接收它们。拖动离开放置区、放下或取消时，浮层消失。它从不接收按下或滚动，所以从不需要关闭。

• 面板位于放置区中可见部分的中央。比窗口还高的放置区，也会在用户正看着的地方显示它的消息。
• 浮层留在放置区的盒子里，并位于其中一切内容之上。必须位于它之上的内容——对话框、菜单、弹出框——位于平台的顶层（top layer），Tanrei 的浮层就是这样。
• 如果浏览器在放下之前就能判断拖来的东西都不能接收——只要一个时拖来了多个文件，或者只有媒体类型列表排除的种类——浮层就显示拒绝：一个禁止字形、一道错误颜色的边线，以及 refusingText。浏览器只告知种类和数量，从不告知名称或大小，所以过大的文件，或扩展名被拒绝的文件，会在放下时被拒绝。

限制和消息

link

accept、maxSize、maxFiles 和 multiple 的作用与文件选择器的完全相同。请在同一界面上的文件选择器或文件上传旁边，用文字说明这些限制：用户是在那里读到它们的。

属性	它说什么	为空时从你的文字中读取
dropText	浮层里的消息：“放下文件即可上传”。	dropZoneText
refusingText	放置区拒绝拖来的东西时显示的消息。	dropZoneRefusingText
droppedText	放下后辅助技术听到的内容，带有 {count}：“已添加 {count} 个文件”。	filesDroppedText
refusedText	有文件被拒绝时它听到的内容，带有 {count}。	filesRefusedText

用 setWords() 为整个产品只给一次这些文字。Tanrei 不自带任何文字。

如果放下的文件交给一个自己保留各行的文件上传，就设置 silent：文件上传已经会逐个说明它保留或拒绝的文件，而一次放下只应说一次。

禁用

link

disabled 只停止放下，不影响别的：没有浮层，也没有事件，而内容照样可以使用。即使外面没有启用的放置区，被禁用的放置区也仍会阻止浏览器打开误放到它上面的文件。

推荐

link

• 始终在同一界面上提供文件选择器或文件上传。
• 立即把 select 交给你的东西交给显示文件的地方。
• 每一次拒绝都要在用户正看着的地方说明：消息条，或者你的列表里的一行。

避免

link

• 不要让放置区成为添加文件的唯一途径。
• 不要用放置区包住单个小控件。请使用文件选择器的拖放区域。
• 不要指望表单提交放下的内容。放置区什么都不保留，也不参与表单。

无障碍

link

角色

none

标注

None. The drop zone has no role, no name and no description, and adds none to its content. The overlay — scrim, panel, glyph and message — is drawn for the person who drags and is kept from assistive technology; the result of a drop is said through the zone's one polite live region (DRZ-11).

最小目标

即使外观尺寸更小，点击区域也满足最小目标尺寸。 minimum 32px · pointer 44px · spacing 8px · touch 48px

键盘操作

按键	动作
Tab / Shift+Tab	Moves through the content's own stops in their own order. The drop zone is not a stop and answers no key.

备注

• A drop zone is never the only way to add a file (WCAG 2.1.1 Keyboard, 2.5.7 Dragging Movements): the screen it wraps also has a File picker or a File upload whose Button opens the platform's picker — in a toolbar, an app bar or an empty state — and the documentation always shows one beside the zone. A debug build reports a page that has none (DRZ-13).
• The zone adds nothing a person operates. Unlike the File picker's drop area, it is not pressed to open the picker and takes no focus: the content under it — buttons, a table, fields — keeps every press, key and scroll (DRZ-2), so wrapping a screen in a zone changes nothing for a keyboard or a screen reader.
• What is dragged over the zone is the pointer user's own act and is not announced. The overlay is told without color too: taking by its edge and its message, refusing by the block glyph and its own message, and under forced colors by a thicker edge in the highlight color (DRZ-5, DRZ-17).
• The result of a drop is a status message (WCAG 4.1.3): one polite live region says how many files were handed over and how many were refused, in the product's words. Where the files go on to a component that says them itself — a File upload that keeps its own rows — the product sets silent, so that a drop is said once.
• A refused file must be said where a person sees it too (WCAG 3.3.1): the zone's live region says that files were refused, and the product, on reject, shows which and why — a snackbar, a failed row of its list, a Field's errorText.
• The overlay never takes a press or a scroll and disappears when the drag leaves, ends or drops, so it needs no dismissal, holds no focus and traps nothing (WCAG 2.1.2).

生成自 specs/drop-zone.spec.json, tokens/sys/measure.tokens.json

组件负责的部分

link

• 放置区不给内容添加任何东西：没有角色，没有名称，在焦点顺序中没有停靠点，也没有按键。键盘或屏幕阅读器用户遇到的内容，和没有放置区时完全一样。
• 浮层是为拖动的人绘制的，对辅助技术隐藏。
• 放下之后，一个以礼貌（polite）的方式朗读的实时区域，用你的文字说明有多少个文件被接受、多少个被拒绝。
• 浮层不只靠颜色来表达：拒绝有自己的字形和消息；在强制颜色模式下，边线用高亮颜色画得更粗。
• 文本放大到 200% 时，消息会换行，从不被截断。

它在 Web 上的构造方式：内容留在你的 DOM 里，位于默认插槽中。宿主元素是 position: relative，并自成一个层叠上下文，所以不要给它设置 position: static。select 和 reject 会冒泡，带有与文件选择器相同的 detail。

需要你做的事

link

• 为所有无法拖动的人，在同一界面上提供一个文件选择器或文件上传。
• 给出 droppedText 和 refusedText；在由文件上传说明文件的地方，则设置 silent。
• 每一次拒绝都要用用户看得见的文字说明。