目錄 搜尋
Scalable Vector Graphics (SVG) 1.1 (Second Edition) 1 Introduction 1.1 About SVG 1.2 SVG MIME type 1.3 SVG Namespace 1.4 Compatibility with Other Standards Efforts 1.5 Terminology 1.6 Definitions 2 Concepts 2.1 Explaining the name: SVG 2.2 Important SVG concepts 2.3 Options for using SVG in Web pages 3 Rendering Model 3.1 Introduction 3.2 The painters model 3.3 Rendering Order 3.4 How groups are rendered 3.5 How elements are rendered 3.6 Types of graphics elements 3.6.1 Painting shapes and text 3.6.2 Painting raster images 3.7 Filtering painted regions 3.8 Clipping 3.9 Parent Compositing 4 Basic Data Types and Interfaces 4.1 Syntax 4.2 Basic data types 4.3 Real number precision 4.4 Recognized color keyword names 4.5 Basic DOM interfaces 4.5.1 Interface SVGElement 4.5.2 Interface SVGAnimatedBoolean 4.5.3 Interface SVGAnimatedString 4.5.4 Interface SVGStringList 4.5.5 Interface SVGAnimatedEnumeration 4.5.6 Interface SVGAnimatedInteger 4.5.7 Interface SVGNumber 4.5.8 Interface SVGAnimatedNumber 4.5.9 Interface SVGNumberList 4.5.10 Interface SVGAnimatedNumberList 4.5.11 Interface SVGLength 4.5.12 Interface SVGAnimatedLength 4.5.13 Interface SVGLengthList 4.5.14 Interface SVGAnimatedLengthList 4.5.15 Interface SVGAngle 4.5.16 Interface SVGAnimatedAngle 4.5.17 Interface SVGColor 4.5.18 Interface SVGICCColor 4.5.19 Interface SVGRect 4.5.20 Interface SVGAnimatedRect 4.5.21 Interface SVGUnitTypes 4.5.22 Interface SVGStylable 4.5.23 Interface SVGLocatable 4.5.24 Interface SVGTransformable 4.5.25 Interface SVGTests 4.5.26 Interface SVGLangSpace 4.5.27 Interface SVGExternalResourcesRequired 4.5.28 Interface SVGFitToViewBox 4.5.29 Interface SVGZoomAndPan 4.5.30 Interface SVGViewSpec 4.5.31 Interface SVGURIReference 4.5.32 Interface SVGCSSRule 4.5.33 Interface SVGRenderingIntent 5 Document Structure 5.1 Defining an SVG document fragment: the 憇vg?element 5.1.1 Overview 5.1.2 The 憇vg?element 5.2 Grouping: the 慻?element 5.2.1 Overview 5.2.2 The 慻?element 5.3 Defining content for reuse 5.3.1 Overview 5.3.2 The 慸efs?element 5.4 The 慸esc?and 憈itle?elements 5.5 The 憇ymbol?element 5.6 The 憉se?element 5.7 The 慽mage?element 5.8 Conditional processing 5.8.1 Conditional processing overview 5.8.2 The 憇witch?element 5.8.3 The 憆equiredFeatures?attribute 5.8.4 The 憆equiredExtensions?attribute 5.8.5 The 憇ystemLanguage?attribute 5.8.6 Applicability of test attributes 5.9 Specifying whether external resources are required for proper rendering 5.10 Common attributes 5.10.1 Attributes common to all elements: 慽d?and 憍ml:base? 5.10.2 The 憍ml:lang?and 憍ml:space?attributes 5.11 DOM interfaces 5.11.1 Interface SVGDocument 5.11.2 Interface SVGSVGElement 5.11.3 Interface SVGGElement 5.11.4 Interface SVGDefsElement 5.11.5 Interface SVGDescElement 5.11.6 Interface SVGTitleElement 5.11.7 Interface SVGSymbolElement 5.11.8 Interface SVGUseElement 5.11.9 Interface SVGElementInstance 5.11.10 Interface SVGElementInstanceList 5.11.11 Interface SVGImageElement 5.11.12 Interface SVGSwitchElement 5.11.13 Interface GetSVGDocument 6 Styling 6.1 SVG's styling properties 6.2 Usage scenarios for styling 6.3 Alternative ways to specify styling properties 6.4 Specifying properties using the presentation attributes 6.5 Styling with XSL 6.6 Styling with CSS 6.7 Case sensitivity of property names and values 6.8 Facilities from CSS and XSL used by SVG 6.9 Referencing external style sheets 6.10 The 憇tyle?element 6.11 The 慶lass?attribute 6.12 The 憇tyle?attribute 6.13 Specifying the default style sheet language 6.14 Property inheritance 6.15 The scope/range of styles 6.16 User agent style sheet 6.17 Aural style sheets 6.18 DOM interfaces 6.18.1 Interface SVGStyleElement 7 Coordinate Systems 7.1 Introduction 7.2 The initial viewport 7.3 The initial coordinate system 7.4 Coordinate system transformations 7.5 Nested transformations 7.6 The 憈ransform?attribute 7.7 The 憊iewBox?attribute 7.8 The 憄reserveAspectRatio?attribute 7.9 Establishing a new viewport 7.10 Units 7.11 Object bounding box units 7.12 Intrinsic sizing properties of the viewport of SVG content 7.13 Geographic coordinate systems 7.14 The 憇vg:transform?attribute 7.15 DOM interfaces 7.15.1 Interface SVGPoint 7.15.2 Interface SVGPointList 7.15.3 Interface SVGMatrix 7.15.4 Interface SVGTransform 7.15.5 Interface SVGTransformList 7.15.6 Interface SVGAnimatedTransformList 7.15.7 Interface SVGPreserveAspectRatio 7.15.8 Interface SVGAnimatedPreserveAspectRatio 8 Paths 8.1 Introduction 8.2 The 憄ath?element 8.3 Path data 8.3.1 General information about path data 8.3.2 The "moveto" commands 8.3.3 The "closepath" command 8.3.4 The "lineto" commands 8.3.5 The curve commands 8.3.6 The cubic B閦ier curve commands 8.3.7 The quadratic B閦ier curve commands 8.3.8 The elliptical arc curve commands 8.3.9 The grammar for path data 8.4 Distance along a path 8.5 DOM interfaces 8.5.1 Interface SVGPathSeg 8.5.2 Interface SVGPathSegClosePath 8.5.3 Interface SVGPathSegMovetoAbs 8.5.4 Interface SVGPathSegMovetoRel 8.5.5 Interface SVGPathSegLinetoAbs 8.5.6 Interface SVGPathSegLinetoRel 8.5.7 Interface SVGPathSegCurvetoCubicAbs 8.5.8 Interface SVGPathSegCurvetoCubicRel 8.5.9 Interface SVGPathSegCurvetoQuadraticAbs 8.5.10 Interface SVGPathSegCurvetoQuadraticRel 8.5.11 Interface SVGPathSegArcAbs 8.5.12 Interface SVGPathSegArcRel 8.5.13 Interface SVGPathSegLinetoHorizontalAbs 8.5.14 Interface SVGPathSegLinetoHorizontalRel 8.5.15 Interface SVGPathSegLinetoVerticalAbs 8.5.16 Interface SVGPathSegLinetoVerticalRel 8.5.17 Interface SVGPathSegCurvetoCubicSmoothAbs 8.5.18 Interface SVGPathSegCurvetoCubicSmoothRel 8.5.19 Interface SVGPathSegCurvetoQuadraticSmoothAbs 8.5.20 Interface SVGPathSegCurvetoQuadraticSmoothRel 8.5.21 Interface SVGPathSegList 8.5.22 Interface SVGAnimatedPathData 8.5.23 Interface SVGPathElement 9 Basic Shapes 9.1 Introduction 9.2 The 憆ect?element 9.3 The 慶ircle?element 9.4 The 慹llipse?element 9.5 The 憀ine?element 9.6 The 憄olyline?element 9.7 The 憄olygon?element 9.7.1 The grammar for points specifications in 憄olyline?and 憄olygon?elements 9.8 DOM interfaces 9.8.1 Interface SVGRectElement 9.8.2 Interface SVGCircleElement 9.8.3 Interface SVGEllipseElement 9.8.4 Interface SVGLineElement 9.8.5 Interface SVGAnimatedPoints 9.8.6 Interface SVGPolylineElement 9.8.7 Interface SVGPolygonElement 10 Text 10.1 Introduction 10.2 Characters and their corresponding glyphs 10.3 Fonts 10.4 The 憈ext?element 10.5 The 憈span?element 10.6 The 憈ref?element 10.7 Text layout 10.7.1 Text layout introduction 10.7.2 Setting the inline-progression-direction 10.7.3 Glyph orientation within a text run 10.7.4 Relationship with bidirectionality 10.8 Text rendering order 10.9 Alignment properties 10.9.1 Text alignment properties 10.9.2 Baseline alignment properties 10.10 Font selection properties 10.11 Spacing properties 10.12 Text decoration 10.13 Text on a path 10.13.1 Introduction to text on a path 10.13.2 The 憈extPath?element 10.13.3 Text on a path layout rules 10.14 Alternate glyphs 10.14.1 The 慳ltGlyph?element 10.14.2 The 慳ltGlyphDef? 慳ltGlyphItem?and 慻lyphRef?elements 10.15 White space handling 10.16 Text selection and clipboard operations 10.17 DOM interfaces 10.17.1 Interface SVGTextContentElement 10.17.2 Interface SVGTextPositioningElement 10.17.3 Interface SVGTextElement 10.17.4 Interface SVGTSpanElement 10.17.5 Interface SVGTRefElement 10.17.6 Interface SVGTextPathElement 10.17.7 Interface SVGAltGlyphElement 10.17.8 Interface SVGAltGlyphDefElement 10.17.9 Interface SVGAltGlyphItemElement 10.17.10 Interface SVGGlyphRefElement 11 Painting: Filling 11.1 Introduction 11.2 Specifying paint 11.3 Fill Properties 11.4 Stroke Properties 11.5 Controlling visibility 11.6 Markers 11.6.1 Introduction 11.6.2 The 憁arker?element 11.6.3 Marker properties 11.6.4 Details on how markers are rendered 11.7 Rendering properties 11.7.1 Color interpolation properties: 慶olor-interpolation?and 慶olor-interpolation-filters? 11.7.2 The 慶olor-rendering?property 11.7.3 The 憇hape-rendering?property 11.7.4 The 憈ext-rendering?property 11.7.5 The 慽mage-rendering?property 11.8 Inheritance of painting properties 11.9 DOM interfaces 11.9.1 Interface SVGPaint 11.9.2 Interface SVGMarkerElement 12 Color 12.1 Introduction 12.2 The 慶olor?property 12.3 Color profile descriptions 12.3.1 Overview of color profile descriptions 12.3.2 Alternative ways of defining a color profile description 12.3.3 The 慶olor-profile?element 12.3.4 The CSS @color-profile rule 12.3.5 The 慶olor-profile?property 12.4 DOM interfaces 12.4.1 Interface SVGColorProfileElement 12.4.2 Interface SVGColorProfileRule 13 Gradients and Patterns 13.1 Introduction 13.2 Gradients 13.2.1 Introduction 13.2.2 Linear gradients 13.2.3 Radial gradients 13.2.4 Gradient stops 13.3 Patterns 13.4 DOM interfaces 13.4.1 Interface SVGGradientElement 13.4.2 Interface SVGLinearGradientElement 13.4.3 Interface SVGRadialGradientElement 13.4.4 Interface SVGStopElement 13.4.5 Interface SVGPatternElement 14 Clipping 14.1 Introduction 14.2 Simple alpha compositing 14.3 Clipping paths 14.3.1 Introduction 14.3.2 The initial clipping path 14.3.3 The 憃verflow?and 慶lip?properties 14.3.4 Clip to viewport vs. clip to 憊iewBox? 14.3.5 Establishing a new clipping path: the 慶lipPath?element 14.3.6 Clipping paths 14.4 Masking 14.5 Object and group opacity: the 憃pacity?property 14.6 DOM interfaces 14.6.1 Interface SVGClipPathElement 14.6.2 Interface SVGMaskElement 15 Filter Effects 15.1 Introduction 15.2 An example 15.3 The 慺ilter?element 15.4 The 慺ilter?property 15.5 Filter effects region 15.6 Accessing the background image 15.7 Filter primitives overview 15.7.1 Overview 15.7.2 Common attributes 15.7.3 Filter primitive subregion 15.8 Light source elements and properties 15.8.1 Introduction 15.8.2 Light source 慺eDistantLight? 15.8.3 Light source 慺ePointLight? 15.8.4 Light source 慺eSpotLight? 15.8.5 The 憀ighting-color?property 15.9 Filter primitive 慺eBlend? 15.10 Filter primitive 慺eColorMatrix? 15.11 Filter primitive 慺eComponentTransfer? 15.12 Filter primitive 慺eComposite? 15.13 Filter primitive 慺eConvolveMatrix? 15.14 Filter primitive 慺eDiffuseLighting? 15.15 Filter primitive 慺eDisplacementMap? 15.16 Filter primitive 慺eFlood? 15.17 Filter primitive 慺eGaussianBlur? 15.18 Filter primitive 慺eImage? 15.19 Filter primitive 慺eMerge? 15.20 Filter primitive 慺eMorphology? 15.21 Filter primitive 慺eOffset? 15.22 Filter primitive 慺eSpecularLighting? 15.23 Filter primitive 慺eTile? 15.24 Filter primitive 慺eTurbulence? 15.25 DOM interfaces 15.25.1 Interface SVGFilterElement 15.25.2 Interface SVGFilterPrimitiveStandardAttributes 15.25.3 Interface SVGFEBlendElement 15.25.4 Interface SVGFEColorMatrixElement 15.25.5 Interface SVGFEComponentTransferElement 15.25.6 Interface SVGComponentTransferFunctionElement 15.25.7 Interface SVGFEFuncRElement 15.25.8 Interface SVGFEFuncGElement 15.25.9 Interface SVGFEFuncBElement 15.25.10 Interface SVGFEFuncAElement 15.25.11 Interface SVGFECompositeElement 15.25.12 Interface SVGFEConvolveMatrixElement 15.25.13 Interface SVGFEDiffuseLightingElement 15.25.14 Interface SVGFEDistantLightElement 15.25.15 Interface SVGFEPointLightElement 15.25.16 Interface SVGFESpotLightElement 15.25.17 Interface SVGFEDisplacementMapElement 15.25.18 Interface SVGFEFloodElement 15.25.19 Interface SVGFEGaussianBlurElement 15.25.20 Interface SVGFEImageElement 15.25.21 Interface SVGFEMergeElement 15.25.22 Interface SVGFEMergeNodeElement 15.25.23 Interface SVGFEMorphologyElement 15.25.24 Interface SVGFEOffsetElement 15.25.25 Interface SVGFESpecularLightingElement 15.25.26 Interface SVGFETileElement 15.25.27 Interface SVGFETurbulenceElement 16 Interactivity 16.1 Introduction 16.2 Complete list of supported events 16.3 User interface events 16.4 Pointer events 16.5 Hit-testing and processing order for user interface events 16.5.1 Hit-testing 16.5.2 Event processing 16.6 The 憄ointer-events?property 16.7 Magnification and panning 16.8 Cursors 16.8.1 Introduction to cursors 16.8.2 The 慶ursor?property 16.8.3 The 慶ursor?element 16.9 DOM interfaces 16.9.1 Interface SVGCursorElement 17 Linking 17.1 References 17.1.1 Overview 17.1.2 IRIs and URIs 17.1.3 Syntactic forms: IRI and FuncIRI 17.1.4 Processing of IRI references 17.1.5 IRI reference attributes 17.2 Links out of SVG content: the 慳?element 17.3 Linking into SVG content: IRI fragments and SVG views 17.3.1 Introduction: IRI fragments and SVG views 17.3.2 SVG fragment identifiers 17.3.3 Predefined views: the 憊iew?element 17.3.4 Highlighting views 17.4 DOM interfaces 17.4.1 Interface SVGAElement 17.4.2 Interface SVGViewElement 18 Scripting 18.1 Specifying the scripting language 18.1.1 Specifying the default scripting language 18.1.2 Local declaration of a scripting language 18.2 The 憇cript?element 18.3 Event handling 18.4 Event attributes 18.4.1 Event attribute for the SVGLoad event 18.4.2 Event attributes on graphics and container elements 18.4.3 Document-level event attributes 18.4.4 Animation event attributes 18.5 DOM interfaces 18.5.1 Interface SVGScriptElement 18.5.2 Interface SVGZoomEvent 19 Animation 19.1 Introduction 19.2 Animation elements 19.2.1 Overview 19.2.2 Relationship to SMIL Animation 19.2.3 Animation elements example 19.2.4 Attributes to identify the target element for an animation 19.2.5 Attributes to identify the target attribute or property for an animation 19.2.6 Animation with namespaces 19.2.7 Paced animation and complex types 19.2.8 Attributes to control the timing of the animation 19.2.8.1 Clock values 19.2.9 Attributes that define animation values over time 19.2.10 Attributes that control whether animations are additive 19.2.11 Inheritance 19.2.12 The 慳nimate?element 19.2.13 The 憇et?element 19.2.14 The 慳nimateMotion?element 19.2.15 The 慳nimateColor?element 19.2.16 The 慳nimateTransform?element 19.2.17 Elements 19.3 Animation using the SVG DOM 19.4 DOM interfaces 19.4.1 Interface ElementTimeControl 19.4.2 Interface TimeEvent 19.4.3 Interface SVGAnimationElement 19.4.4 Interface SVGAnimateElement 19.4.5 Interface SVGSetElement 19.4.6 Interface SVGAnimateMotionElement 19.4.7 Interface SVGMPathElement 19.4.8 Interface SVGAnimateColorElement 19.4.9 Interface SVGAnimateTransformElement 20 Fonts 20.1 Introduction 20.2 Overview of SVG fonts 20.3 The 慺ont?element 20.4 The 慻lyph?element 20.5 The 憁issing-glyph?element 20.6 Glyph selection rules 20.7 The 慼kern?and 憊kern?elements 20.8 Describing a font 20.8.1 Overview of font descriptions 20.8.2 Alternative ways for providing a font description 20.8.3 The 慺ont-face?element 20.8.4 The 慺ont-face-src?element 20.8.5 The 慺ont-face-uri?and 慺ont-face-format?elements 20.8.6 The 慺ont-face-name?element 20.9 DOM interfaces 20.9.1 Interface SVGFontElement 20.9.2 Interface SVGGlyphElement 20.9.3 Interface SVGMissingGlyphElement 20.9.4 Interface SVGHKernElement 20.9.5 Interface SVGVKernElement 20.9.6 Interface SVGFontFaceElement 20.9.7 Interface SVGFontFaceSrcElement 20.9.8 Interface SVGFontFaceUriElement 20.9.9 Interface SVGFontFaceFormatElement 20.9.10 Interface SVGFontFaceNameElement 21 Metadata 21.1 Introduction 21.2 The 憁etadata?element 21.3 An example 21.4 DOM interfaces 21.4.1 Interface SVGMetadataElement 22 Backwards Compatibility 23 Extensibility 23.1 Foreign namespaces and private data 23.2 Embedding foreign object types 23.3 The 慺oreignObject?element 23.4 An example 23.5 Adding private elements and attributes to the DTD 23.6 DOM interfaces 23.6.1 Interface SVGForeignObjectElement Appendix A: Document Type Definition A.1 Introduction A.2 Modularization A.2.1 Element and attribute collections A.2.2 Profiling the SVG specification A.2.3 Practical considerations A.3 SVG 1.1 module definitions and DTD implementations A.3.1 Modular Framework Module A.3.2 Datatypes Module A.3.3 Qualified Name Module A.3.4 Core Attribute Module A.3.5 Container Attribute Module A.3.6 Viewport Attribute Module A.3.7 Paint Attribute Module A.3.8 Basic Paint Attribute Module A.3.9 Paint Opacity Attribute Module A.3.10 Graphics Attribute Module A.3.11 Basic Graphics Attribute Module A.3.12 Document Events Attribute Module A.3.13 Graphical Element Events Attribute Module A.3.14 Animation Events Attribute Module A.3.15 XLink Attribute Module A.3.16 External Resources Attribute Module A.3.17 Structure Module A.3.18 Basic Structure Module A.3.19 Conditional Processing Module A.3.20 Image Module A.3.21 Style Module A.3.22 Shape Module A.3.23 Text Module A.3.24 Basic Text Module A.3.25 Marker Module A.3.26 Color Profile Module A.3.27 Gradient Module A.3.28 Pattern Module A.3.29 Clip Module A.3.30 Basic Clip Module A.3.31 Mask Module A.3.32 Filter Module A.3.33 Basic Filter Module A.3.34 Cursor Module A.3.35 Hyperlinking Module A.3.36 View Module A.3.37 Scripting Module A.3.38 Animation Module A.3.39 Font Module A.3.40 Basic Font Module A.3.41 Extensibility Module A.4 SVG 1.1 Document Type Definition A.4.1 SVG 1.1 DTD Driver A.4.2 SVG 1.1 Document Model A.4.3 SVG 1.1 Attribute Collection Appendix B: SVG Document Object Model (DOM) B.1 SVG DOM overview B.1.1 SVG DOM object initialization B.2 Elements in the SVG DOM B.3 Naming conventions B.4 Exception SVGException B.5 Feature strings for the hasFeature method call B.6 Relationship with DOM Level 2 Events B.7 Relationship with DOM Level 2 CSS B.7.1 Introduction B.7.2 User agents that do not support styling with CSS B.7.3 User agents that support styling with CSS B.7.4 Extended interfaces B.8 Read only nodes in the DOM B.9 Invalid values Appendix C: IDL Definitions Appendix D: Java Language Binding D.1 The Java language binding D.2 Using SVG with the Java language Appendix E: ECMAScript Language Binding E.1 Exceptions E.2 Constants E.3 Types E.4 Objects Appendix F: Implementation Requirements F.1 Introduction F.2 Error processing F.3 Version control F.4 Clamping values which are restricted to a particular range F.5 憄ath?element implementation notes F.6 Elliptical arc implementation notes F.6.1 Elliptical arc syntax F.6.2 Out-of-range parameters F.6.3 Parameterization alternatives F.6.4 Conversion from center to endpoint parameterization F.6.5 Conversion from endpoint to center parameterization F.6.6 Correction of out-of-range radii F.7 Text selection implementation notes F.8 Printing implementation notes Appendix G: Conformance Criteria G.1 Introduction G.2 Conforming SVG Document Fragments G.3 Conforming SVG Stand-Alone Files G.4 Conforming SVG Generators G.5 Conforming SVG Servers G.6 Conforming SVG DOM Subtree G.7 Conforming SVG Interpreters G.8 Conforming SVG Viewers Appendix H: Accessibility Support H.1 WAI Accessibility Guidelines H.2 SVG Content Accessibility Guidelines Appendix I: Internationalization Support I.1 Introduction I.2 Internationalization and SVG I.3 SVG Internationalization Guidelines Appendix J: Minimizing SVG File Sizes Appendix K: References K.1 Normative references K.2 Informative references Appendix L: Element Index Appendix M: Attribute Index M.1 Regular attributes M.2 Presentation attributes Appendix N: Property Index Appendix O: Feature Strings O.1 Introduction O.2 SVG 1.1 feature strings O.3 SVG 1.0 feature strings Appendix P: Media Type Registration for image/svg+xml P.1 Introduction P.2 Registration of media type image/svg+xml Appendix Q: Changes Check Update
文字

SVG 1.1 (Second Edition) – 16 August 2011Top ⋅ Contents ⋅ Previous ⋅ Next ⋅ Elements ⋅ Attributes ⋅ Properties

5 Document Structure

Contents

  • 5.1 Defining an SVG document fragment: the ‘svg’ element
    • 5.1.1 Overview
    • 5.1.2 The ‘svg’ element
  • 5.2 Grouping: the ‘g’ element
    • 5.2.1 Overview
    • 5.2.2 The ‘g’ element
  • 5.3 Defining content for reuse, and the ‘defs’ element
    • 5.3.1 Overview
    • 5.3.2 The ‘defs’ element
  • 5.4 The ‘desc’ and ‘title’ elements
  • 5.5 The ‘symbol’ element
  • 5.6 The ‘use’ element
  • 5.7 The ‘image’ element
  • 5.8 Conditional processing
    • 5.8.1 Conditional processing overview
    • 5.8.2 The ‘switch’ element
    • 5.8.3 The ‘requiredFeatures’ attribute
    • 5.8.4 The ‘requiredExtensions’ attribute
    • 5.8.5 The ‘systemLanguage’ attribute
    • 5.8.6 Applicability of test attributes
  • 5.9 Specifying whether external resources are required for proper rendering
  • 5.10 Common attributes
    • 5.10.1 Attributes common to all elements: ‘id’ and ‘xml:base’
    • 5.10.2 The ‘xml:lang’ and ‘xml:space’ attributes
  • 5.11 DOM interfaces
    • 5.11.1 Interface SVGDocument
    • 5.11.2 Interface SVGSVGElement
    • 5.11.3 Interface SVGGElement
    • 5.11.4 Interface SVGDefsElement
    • 5.11.5 Interface SVGDescElement
    • 5.11.6 Interface SVGTitleElement
    • 5.11.7 Interface SVGSymbolElement
    • 5.11.8 Interface SVGUseElement
    • 5.11.9 Interface SVGElementInstance
    • 5.11.10 Interface SVGElementInstanceList
    • 5.11.11 Interface SVGImageElement
    • 5.11.12 Interface SVGSwitchElement
    • 5.11.13 Interface GetSVGDocument

5.1 Defining an SVG document fragment: the ‘svg’ element

5.1.1 Overview

An SVG document fragment consists of any number of SVG elements contained within an ‘svg’ element.

An SVG document fragment can range from an empty fragment (i.e., no content inside of the ‘svg’ element), to a very simple SVG document fragment containing a single SVG graphics element such as a ‘rect’, to a complex, deeply nested collection of container elements and graphics elements.

An SVG document fragment can stand by itself as a self-contained file or resource, in which case the SVG document fragment is an SVG document, or it can be embedded inline as a fragment within a parent XML document.

The following example shows simple SVG content embedded inline as a fragment within a parent XML document. Note the use of XML namespaces to indicate that the ‘svg’ and ‘ellipse’ elements belong to the SVG namespace:

<?xml version="1.0" standalone="yes"?>
<parent xmlns="http://example.org"
        xmlns:svg="http://www.w3.org/2000/svg">
   <!-- parent contents here -->
   <svg:svg width="4cm" height="8cm" version="1.1">
      <svg:ellipse cx="2cm" cy="4cm" rx="2cm" ry="1cm" />
   </svg:svg>
   <!-- ... -->
</parent>

This example shows a slightly more complex (i.e., it contains multiple rectangles) stand-alone, self-contained SVG document:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="5cm" height="4cm" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <desc>Four separate rectangles
  </desc>
    <rect x="0.5cm" y="0.5cm" width="2cm" height="1cm"/>
    <rect x="0.5cm" y="2cm" width="1cm" height="1.5cm"/>
    <rect x="3cm" y="0.5cm" width="1.5cm" height="2cm"/>
    <rect x="3.5cm" y="3cm" width="1cm" height="0.5cm"/>

  <!-- Show outline of canvas using 'rect' element -->
  <rect x=".01cm" y=".01cm" width="4.98cm" height="3.98cm"
        fill="none" stroke="blue" stroke-width=".02cm" />

</svg>

‘svg’ elements can appear in the middle of SVG content. This is the mechanism by which SVG document fragments can be embedded within other SVG document fragments.

Another use for ‘svg’ elements within the middle of SVG content is to establish a new viewport. (See Establishing a new viewport.)

In all cases, for compliance with the Namespaces in XML Recommendation [XML-NS], an SVG namespace declaration must be provided so that all SVG elements are identified as belonging to the SVG namespace. The following are possible ways to provide a namespace declaration. An ‘xmlns’ attribute without a namespace prefix could be specified on an ‘svg’ element, which means that SVG is the default namespace for all elements within the scope of the element with the ‘xmlns’ attribute:

<svg xmlns="http://www.w3.org/2000/svg" …>
  <rect …/>
</svg>

If a namespace prefix is specified on the ‘xmlns’ attribute (e.g., xmlns:svg="http://www.w3.org/2000/svg"), then the corresponding namespace is not the default namespace, so an explicit namespace prefix must be assigned to the elements:

<svg:svg xmlns:svg="http://www.w3.org/2000/svg" …>
  <svg:rect …/>
</svg:svg>

Namespace prefixes can be specified on ancestor elements (illustrated in the above example). For more information, refer to the Namespaces in XML Recommendation [XML-NS].

5.1.2 The ‘svg’ element

‘svg’
Categories:
Container element, structural element
Content model:
Any number of the following elements, in any order:
  • animation elements‘animate’, ‘animateColor’, ‘animateMotion’, ‘animateTransform’, ‘set’
  • descriptive elements‘desc’, ‘metadata’, ‘title’
  • shape elements‘circle’, ‘ellipse’, ‘line’, ‘path’, ‘polygon’, ‘polyline’, ‘rect’
  • structural elements‘defs’, ‘g’, ‘svg’, ‘symbol’, ‘use’
  • gradient elements‘linearGradient’, ‘radialGradient’
  • ‘a’
  • ‘altGlyphDef’
  • ‘clipPath’
  • ‘color-profile’
  • ‘cursor’
  • ‘filter’
  • ‘font’
  • ‘font-face’
  • ‘foreignObject’
  • ‘image’
  • ‘marker’
  • ‘mask’
  • ‘pattern’
  • ‘script’
  • ‘style’
  • ‘switch’
  • ‘text’
  • ‘view’
Attributes:
  • conditional processing attributes‘requiredFeatures’, ‘requiredExtensions’, ‘systemLanguage’
  • core attributes‘id’, ‘xml:base’, ‘xml:lang’, ‘xml:space’
  • document event attributes‘onunload’, ‘onabort’, ‘onerror’, ‘onresize’, ‘onscroll’, ‘onzoom’
  • graphical event attributes‘onfocusin’, ‘onfocusout’, ‘onactivate’, ‘onclick’, ‘onmousedown’, ‘onmouseup’, ‘onmouseover’, ‘onmousemove’, ‘onmouseout’, ‘onload’
  • presentation attributes‘alignment-baseline’, ‘baseline-shift’, ‘clip’, ‘clip-path’, ‘clip-rule’, ‘color’, ‘color-interpolation’, ‘color-interpolation-filters’, ‘color-profile’, ‘color-rendering’, ‘cursor’, ‘direction’, ‘display’, ‘dominant-baseline’, ‘enable-background’, ‘fill’, ‘fill-opacity’, ‘fill-rule’, ‘filter’, ‘flood-color’, ‘flood-opacity’, ‘font-family’, ‘font-size’, ‘font-size-adjust’, ‘font-stretch’, ‘font-style’, ‘font-variant’, ‘font-weight’, ‘glyph-orientation-horizontal’, ‘glyph-orientation-vertical’, ‘image-rendering’, ‘kerning’, ‘letter-spacing’, ‘lighting-color’, ‘marker-end’, ‘marker-mid’, ‘marker-start’, ‘mask’, ‘opacity’, ‘overflow’, ‘pointer-events’, ‘shape-rendering’, ‘stop-color’, ‘stop-opacity’, ‘stroke’, ‘stroke-dasharray’, ‘stroke-dashoffset’, ‘stroke-linecap’, ‘stroke-linejoin’, ‘stroke-miterlimit’, ‘stroke-opacity’, ‘stroke-width’, ‘text-anchor’, ‘text-decoration’, ‘text-rendering’, ‘unicode-bidi’, ‘visibility’, ‘word-spacing’, ‘writing-mode’
  • ‘class’
  • ‘style’
  • ‘externalResourcesRequired’
  • ‘x’
  • ‘y’
  • ‘width’
  • ‘height’
  • ‘viewBox’
  • ‘preserveAspectRatio’
  • ‘zoomAndPan’
  • ‘version’
  • ‘baseProfile’
  • ‘contentScriptType’
  • ‘contentStyleType’
  • ‘x’
  • ‘y’
  • ‘width’
  • ‘height’
  • ‘version’
  • ‘baseProfile’
DOM Interfaces:
  • SVGSVGElement

Attribute definitions:

version = "<number>"
Indicates the SVG language version to which this document fragment conforms.
In SVG 1.0 [SVG10], this attribute was fixed to the value '1.0'. For SVG 1.1, the attribute should have the value '1.1'.
Animatable: no.
baseProfile = profile-name
Describes the minimum SVG language profile that the author believes is necessary to correctly render the content. The attribute does not specify any processing restrictions; It can be considered metadata. For example, the value of the attribute could be used by an authoring tool to warn the user when they are modifying the document beyond the scope of the specified base profile. Each SVG profile should define the text that is appropriate for this attribute.
If the attribute is not specified, the effect is as if a value of 'none' were specified.
Animatable: no.
x = "<coordinate>"
(Has no meaning or effect on outermost svg elements.)
The x-axis coordinate of one corner of the rectangular region into which an embedded ‘svg’ element is placed.
If the attribute is not specified, the effect is as if a value of '0' were specified.
Animatable: yes.
y = "<coordinate>"
(Has no meaning or effect on outermost svg elements.)
The y-axis coordinate of one corner of the rectangular region into which an embedded ‘svg’ element is placed.
If the attribute is not specified, the effect is as if a value of '0' were specified.
Animatable: yes.
width = "<length>"
For outermost svg elements, the intrinsic width of the SVG document fragment. For embedded ‘svg’ elements, the width of the rectangular region into which the ‘svg’ element is placed.
A negative value is an error (see Error processing). A value of zero disables rendering of the element.
If the attribute is not specified, the effect is as if a value of '100%' were specified.
Animatable: yes.
height = "<length>"
For outermost svg elements, the intrinsic height of the SVG document fragment. For embedded ‘svg’ elements, the height of the rectangular region into which the ‘svg’ element is placed.
A negative value is an error (see Error processing). A value of zero disables rendering of the element.
If the attribute is not specified, the effect is as if a value of '100%' were specified.
Animatable: yes.
preserveAspectRatio = "[defer] <align> [<meetOrSlice>]"

See ‘preserveAspectRatio’.

If the attribute is not specified, then the effect is as if a value of 'xMidYMid meet' were specified.

Animatable: yes.

contentScriptType = "content-type"

See 'contentScriptType'.

contentStyleType = "content-type"

See 'contentStyleType'.

zoomAndPan = "disable | magnify"

See 'zoomAndPan'.

If an SVG document is likely to be referenced as a component of another document, the author will often want to include a ‘viewBox’ attribute on the outermost svg element of the referenced document. This attribute provides a convenient way to design SVG documents to scale-to-fit into an arbitrary viewport.

5.2 Grouping: the ‘g’ element

5.2.1 Overview

The ‘g’ element is a container element for grouping together related graphics elements.

Grouping constructs, when used in conjunction with the ‘desc’ and ‘title’ elements, provide information about document structure and semantics. Documents that are rich in structure may be rendered graphically, as speech, or as braille, and thus promote accessibility.

A group of elements, as well as individual objects, can be given a name using the ‘id’ attribute. Named groups are needed for several purposes such as animation and re-usable objects.

An example:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg xmlns="http://www.w3.org/2000/svg"
     version="1.1" width="5cm" height="5cm">
  <desc>Two groups, each of two rectangles</desc>
  <g id="group1" fill="red">
    <rect x="1cm" y="1cm" width="1cm" height="1cm"/>
    <rect x="3cm" y="1cm" width="1cm" height="1cm"/>
  </g>
  <g id="group2" fill="blue">
    <rect x="1cm" y="3cm" width="1cm" height="1cm"/>
    <rect x="3cm" y="3cm" width="1cm" height="1cm"/>
  </g>

  <!-- Show outline of canvas using 'rect' element -->
  <rect x=".01cm" y=".01cm" width="4.98cm" height="4.98cm"
        fill="none" stroke="blue" stroke-width=".02cm"/>
</svg>

View this example as SVG (SVG-enabled browsers only)

A ‘g’ element can contain other ‘g’ elements nested within it, to an arbitrary depth. Thus, the following is possible:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg xmlns="http://www.w3.org/2000/svg"
     version="1.1" width="4in" height="3in">
  <desc>Groups can nest</desc>
  <g>
     <g>
       <g>
       </g>
     </g>
   </g>
</svg>

Any element that is not contained within a ‘g’ is treated (at least conceptually) as if it were in its own group.

5.2.2 The ‘g’ element

‘g’
Categories:
Container element, structural element
Content model:
Any number of the following elements, in any order:
  • animation elements‘animate’, ‘animateColor’, ‘animateMotion’, ‘animateTransform’, ‘set’
  • descriptive elements‘desc’, ‘metadata’, ‘title’
  • shape elements‘circle’, ‘ellipse’, ‘line’, ‘path’, ‘polygon’, ‘polyline’, ‘rect’
  • structural elements‘defs’, ‘g’, ‘svg’, ‘symbol’, ‘use’
  • gradient elements‘linearGradient’, ‘radialGradient’
  • ‘a’
  • ‘altGlyphDef’
  • ‘clipPath’
  • ‘color-profile’
  • ‘cursor’
  • ‘filter’
  • ‘font’
  • ‘font-face’
  • ‘foreignObject’
  • ‘image’
  • ‘marker’
  • ‘mask’
  • ‘pattern’
  • ‘script’
  • ‘style’
  • ‘switch’
  • ‘text’
  • ‘view’
Attributes:
  • conditional processing attributes‘requiredFeatures’, ‘requiredExtensions’, ‘systemLanguage’
  • core attributes‘id’, ‘xml:base’, ‘xml:lang’, ‘xml:space’
  • graphical event attributes‘onfocusin’, ‘onfocusout’, ‘onactivate’, ‘onclick’, ‘onmousedown’, ‘onmouseup’, ‘onmouseover’, ‘onmousemove’, ‘onmouseout’, ‘onload’
  • presentation attributes‘alignment-baseline’, ‘baseline-shift’, ‘clip’, ‘clip-path’, ‘clip-rule’, ‘color’, ‘color-interpolation’, ‘color-interpolation-filters’, ‘color-profile’, ‘color-rendering’, ‘cursor’, ‘direction’, ‘display’, ‘dominant-baseline’, ‘enable-background’, ‘fill’, ‘fill-opacity’, ‘fill-rule’, ‘filter’, ‘flood-color’, ‘flood-opacity’, ‘font-family’, ‘font-size’, ‘font-size-adjust’, ‘font-stretch’, ‘font-style’, ‘font-variant’, ‘font-weight’, ‘glyph-orientation-horizontal’, ‘glyph-orientation-vertical’, ‘image-rendering’, ‘kerning’, ‘letter-spacing’, ‘lighting-color’, ‘marker-end’, ‘marker-mid’, ‘marker-start’, ‘mask’, ‘opacity’, ‘overflow’, ‘pointer-events’, ‘shape-rendering’, ‘stop-color’, ‘stop-opacity’, ‘stroke’, ‘stroke-dasharray’, ‘stroke-dashoffset’, ‘stroke-linecap’, ‘stroke-linejoin’, ‘stroke-miterlimit’, ‘stroke-opacity’, ‘stroke-width’, ‘text-anchor’, ‘text-decoration’, ‘text-rendering’, ‘unicode-bidi’, ‘visibility’, ‘word-spacing’, ‘writing-mode’
  • ‘class’
  • ‘style’
  • ‘externalResourcesRequired’
  • ‘transform’
DOM Interfaces:
  • SVGGElement

5.3.1 Overview

SVG allows graphical objects to be defined for later reuse. To do this, it makes extensive use of IRI references [RFC3987] to these other objects. For example, to fill a rectangle with a linear gradient, you first define a ‘linearGradient’ element and give it an ID, as in:

<linearGradient id="MyGradient">...</linearGradient>

You then reference the linear gradient as the value of the ‘fill’ property for the rectangle, as in:

<rect style="fill:url(#MyGradient)"/>

Some types of element, such as gradients, will not by themselves produce a graphical result. They can therefore be placed anywhere convenient. However, sometimes it is desired to define a graphical object and prevent it from being directly rendered. it is only there to be referenced elsewhere. To do this, and to allow convenient grouping defined content, SVG provides the ‘defs’ element.

It is recommended that, wherever possible, referenced elements be defined inside of a ‘defs’ element. Among the elements that are always referenced: ‘altGlyphDef’, ‘clipPath’, ‘cursor’, ‘filter’, ‘linearGradient’, ‘marker’, ‘mask’, ‘pattern’, ‘radialGradient’ and ‘symbol’. Defining these elements inside of a ‘defs’ element promotes understandability of the SVG content and thus promotes accessibility.

5.3.2 The ‘defs’ element

‘defs’
Categories:
Container element, structural element
Content model:
Any number of the following elements, in any order:
  • animation elements‘animate’, ‘animateColor’, ‘animateMotion’, ‘animateTransform’, ‘set’
  • descriptive elements‘desc’, ‘metadata’, ‘title’
  • shape elements‘circle’, ‘ellipse’, ‘line’, ‘path’, ‘polygon’, ‘polyline’, ‘rect’
  • structural elements‘defs’, ‘g’, ‘svg’, ‘symbol’, ‘use’
  • gradient elements‘linearGradient’, ‘radialGradient’
  • ‘a’
  • ‘altGlyphDef’
  • ‘clipPath’
  • ‘color-profile’
  • ‘cursor’
  • ‘filter’
  • ‘font’
  • ‘font-face’
  • ‘foreignObject’
  • ‘image’
  • ‘marker’
  • ‘mask’
  • ‘pattern’
  • ‘script’
  • ‘style’
  • ‘switch’
  • ‘text’
  • ‘view’
Attributes:
  • conditional processing attributes‘requiredFeatures’, ‘requiredExtensions’, ‘systemLanguage’
  • core attributes‘id’, ‘xml:base’, ‘xml:lang’, ‘xml:space’
  • graphical event attributes‘onfocusin’, ‘onfocusout’, ‘onactivate’, ‘onclick’, ‘onmousedown’, ‘onmouseup’, ‘onmouseover’, ‘onmousemove’, ‘onmouseout’, ‘onload’
  • presentation attributes‘alignment-baseline’, ‘baseline-shift’, ‘clip’, ‘clip-path’, ‘clip-rule’, ‘color’, ‘color-interpolation’, ‘color-interpolation-filters’, ‘color-profile’, ‘color-rendering’, ‘cursor’, ‘direction’, ‘display’, ‘dominant-baseline’, ‘enable-background’, ‘fill’, ‘fill-opacity’, ‘fill-rule’, ‘filter’, ‘flood-color’, ‘flood-opacity’, ‘font-family’, ‘font-size’, ‘font-size-adjust’, ‘font-stretch’, ‘font-style’, ‘font-variant’, ‘font-weight’, ‘glyph-orientation-horizontal’, ‘glyph-orientation-vertical’, ‘image-rendering’, ‘kerning’, ‘letter-spacing’, ‘lighting-color’, ‘marker-end’, ‘marker-mid’, ‘marker-start’, ‘mask’, ‘opacity’, ‘overflow’, ‘pointer-events’, ‘shape-rendering’, ‘stop-color’, ‘stop-opacity’, ‘stroke’, ‘stroke-dasharray’, ‘stroke-dashoffset’, ‘stroke-linecap’, ‘stroke-linejoin’, ‘stroke-miterlimit’, ‘stroke-opacity’, ‘stroke-width’, ‘text-anchor’, ‘text-decoration’, ‘text-rendering’, ‘unicode-bidi’, ‘visibility’, ‘word-spacing’, ‘writing-mode’
  • ‘class’
  • ‘style’
  • ‘externalResourcesRequired’
  • ‘transform’
DOM Interfaces:
  • SVGDefsElement

The ‘defs’ element is a container element for referenced elements. For understandability and accessibility reasons, it is recommended that, whenever possible, referenced elements be defined inside of a ‘defs’.

The content model for ‘defs’ is the same as for the ‘g’ element; thus, any element that can be a child of a ‘g’ can also be a child of a ‘defs’, and vice versa.

Elements that are descendants of a ‘defs’ are not rendered directly; they are prevented from becoming part of the rendering tree just as if the ‘defs’ element were a ‘g’ element and the ‘display’ property were set to none. Note, however, that the descendants of a ‘defs’ are always present in the source tree and thus can always be referenced by other elements; thus, the value of the ‘display’ property on the ‘defs’ element or any of its descendants does not prevent those elements from being referenced by other elements.

To provide some SVG user agents with an opportunity to implement efficient implementations in streaming environments, creators of SVG content are encouraged to place all elements which are targets of local IRI references within a ‘defs’ element which is a direct child of one of the ancestors of the referencing element. For example:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="8cm" height="3cm"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Local URI references within ancestor's 'defs' element.</desc>
  <defs>
    <linearGradient id="Gradient01">
      <stop offset="20%" stop-color="#39F" />
      <stop offset="90%" stop-color="#F3F" />
    </linearGradient>
  </defs>
  <rect x="1cm" y="1cm" width="6cm" height="1cm" 
        fill="url(#Gradient01)"  />

  <!-- Show outline of canvas using 'rect' element -->
  <rect x=".01cm" y=".01cm" width="7.98cm" height="2.98cm"
        fill="none" stroke="blue" stroke-width=".02cm" />

</svg>

View this example as SVG (SVG-enabled browsers only)

In the document above, the linear gradient is defined within a ‘defs’ element which is the direct child of the ‘svg’ element, which in turn is an ancestor of the ‘rect’ element which references the linear gradient. Thus, the above document conforms to the guideline.

5.4 The ‘desc’ and ‘title’ elements

‘desc’
Categories:
Descriptive element
Content model:
Any elements or character data.
Attributes:
  • core attributes‘id’, ‘xml:base’, ‘xml:lang’, ‘xml:space’
  • ‘class’
  • ‘style’
DOM Interfaces:
  • SVGDescElement
‘title’
Categories:
Descriptive element
Content model:
Any elements or character data.
Attributes:
  • core attributes‘id’, ‘xml:base’, ‘xml:lang’, ‘xml:space’
  • ‘class’
  • ‘style’
DOM Interfaces:
  • SVGTitleElement

Each container element or graphics element in an SVG drawing can supply a ‘desc’ and/or a ‘title’ description string where the description is text-only. When the current SVG document fragment is rendered as SVG on visual media, ‘desc’ and ‘title’ elements are not rendered as part of the graphics. User agents may, however, for example, display the ‘title’ element as a tooltip, as the pointing device moves over particular elements. Alternate presentations are possible, both visual and aural, which display the ‘desc’ and ‘title’ elements but do not display ‘path’ elements or other graphics elements. This is readily achieved by using a different (perhaps user) style sheet. For deep hierarchies, and for following ‘use’ element references, it is sometimes desirable to allow the user to control how deep they drill down into descriptive text.

In conforming SVG document fragments, any ‘title’ element should be the first child element of its parent. Note that those implementations that do use ‘title’ to display a tooltip often will only do so if the ‘title’ is indeed the first child element of its parent.

The following is an example. In typical operation, the SVG user agent would not render the ‘desc’ and ‘title’ elements but would render the remaining contents of the ‘g’ element.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg SYSTEM "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg xmlns="http://www.w3.org/2000/svg"
     version="1.1" width="4in" height="3in">
  <g>
    <title>Company sales by region</title>
    <desc>
      This is a bar chart which shows 
      company sales by region.
    </desc>
    <!-- Bar chart defined as vector data -->
  </g>
</svg>

Description and title elements can contain marked-up text from other namespaces. Here is an example:

<?xml version="1.0" standalone="yes"?>
<svg xmlns="http://www.w3.org/2000/svg"
     version="1.1" width="4in" height="3in">
  <desc xmlns:mydoc="http://example.org/mydoc">
    <mydoc:title>This is an example SVG file</mydoc:title>
    <mydoc:para>The global description uses markup from the 
      <mydoc:emph>mydoc</mydoc:emph> namespace.</mydoc:para>
  </desc>
  <g>
    <!-- the picture goes here -->
  </g>
</svg>

Authors should always provide a ‘title’ child element to the outermost svg element within a stand-alone SVG document. The ‘title’ child element to an ‘svg’ element serves the purposes of identifying the content of the given SVG document fragment. Since users often consult documents out of context, authors should provide context-rich titles. Thus, instead of a title such as "Introduction", which doesn't provide much contextual background, authors should supply a title such as "Introduction to Medieval Bee-Keeping" instead. For reasons of accessibility, user agents should always make the content of the ‘title’ child element to the outermost svg element available to users. The mechanism for doing so depends on the user agent (e.g., as a caption, spoken).

The DTD definitions of many of SVG's elements (particularly, container and text elements) place no restriction on the placement or number of the ‘desc’ and ‘title’ sub-elements. This flexibility is only present so that there will be a consistent content model for container elements, because some container elements in SVG allow for mixed content, and because the mixed content rules for XML ([XML10], section 3.2.2) do not permit the desired restrictions. Representations of future versions of the SVG language might use more expressive representations than DTDs which allow for more restrictive mixed content rules. It is strongly recommended that at most one ‘desc’ and at most one ‘title’ element appear as a child of any particular element, and that these elements appear before any other child elements (except possibly ‘metadata’ elements) or character data content. If user agents need to choose among multiple ‘desc’ or ‘title’ elements for processing (e.g., to decide which string to use for a tooltip), the user agent shall choose the first one.

5.5 The ‘symbol’ element

‘symbol’
Categories:
Container element, structural element
Content model:
Any number of the following elements, in any order:
  • animation elements‘animate’, ‘animateColor’, ‘animateMotion’, ‘animateTransform’, ‘set’
  • descriptive elements‘desc’, ‘metadata’, ‘title’
  • shape elements‘circle’, ‘ellipse’, ‘line’, ‘path’, ‘polygon’, ‘polyline’, ‘rect’
  • structural elements‘defs’, ‘g’, ‘svg’, ‘symbol’, ‘use’
  • gradient elements‘linearGradient’, ‘radialGradient’
  • ‘a’
  • ‘altGlyphDef’
  • ‘clipPath’
  • ‘color-profile’
  • ‘cursor’
  • ‘filter’
  • ‘font’
  • ‘font-face’
  • ‘foreignObject’
  • ‘image’
  • ‘marker’
  • ‘mask’
  • ‘pattern’
  • ‘script’
  • ‘style’
  • ‘switch’
  • ‘text’
  • ‘view’
Attributes:
  • core attributes‘id’, ‘xml:base’, ‘xml:lang’, ‘xml:space’
  • graphical event attributes‘onfocusin’, ‘onfocusout’, ‘onactivate’, ‘onclick’, ‘onmousedown’, ‘onmouseup’, ‘onmouseover’, ‘onmousemove’, ‘onmouseout’, ‘onload’
  • presentation attributes‘alignment-baseline’, ‘baseline-shift’, ‘clip’, ‘clip-path’, ‘clip-rule’, ‘color’, ‘color-interpolation’, ‘color-interpolation-filters’, ‘color-profile’, ‘color-rendering’, ‘cursor’, ‘direction’, ‘display’, ‘dominant-baseline’, ‘enable-background’, ‘fill’, ‘fill-opacity’, ‘fill-rule’, ‘filter’, ‘flood-color’, ‘flood-opacity’, ‘font-family’, ‘font-size’, ‘font-size-adjust’, ‘font-stretch’, ‘font-style’, ‘font-variant’, ‘font-weight’, ‘glyph-orientation-horizontal’, ‘glyph-orientation-vertical’, ‘image-rendering’, ‘kerning’, ‘letter-spacing’, ‘lighting-color’, ‘marker-end’, ‘marker-mid’, ‘marker-start’, ‘mask’, ‘opacity’, ‘overflow’, ‘pointer-events’, ‘shape-rendering’, ‘stop-color’, ‘stop-opacity’, ‘stroke’, ‘stroke-dasharray’, ‘stroke-dashoffset’, ‘stroke-linecap’, ‘stroke-linejoin’, ‘stroke-miterlimit’, ‘stroke-opacity’, ‘stroke-width’, ‘text-anchor’, ‘text-decoration’, ‘text-rendering’, ‘unicode-bidi’, ‘visibility’, ‘word-spacing’, ‘writing-mode’
  • ‘class’
  • ‘style’
  • ‘externalResourcesRequired’
  • ‘preserveAspectRatio’
  • ‘viewBox’
DOM Interfaces:
  • SVGSymbolElement

The ‘symbol’ element is used to define graphical template objects which can be instantiated by a ‘use’ element.

The use of ‘symbol’ elements for graphics that are used multiple times in the same document adds structure and semantics. Documents that are rich in structure may be rendered graphically, as speech, or as braille, and thus promote accessibility.

The key distinctions between a ‘symbol’ and a ‘g’ are:

  • A ‘symbol’ element itself is not rendered. Only instances of a ‘symbol’ element (i.e., a reference to a ‘symbol’ by a ‘use’ element) are rendered.
  • A ‘symbol’ element has attributes ‘viewBox’ and ‘preserveAspectRatio’ which allow a ‘symbol’ to scale-to-fit within a rectangular viewport defined by the referencing ‘use’ element.

Closely related to the ‘symbol’ element are the ‘marker’ and ‘pattern’ elements.

‘symbol’ elements are never rendered directly; their only usage is as something that can be referenced using the ‘use’ element. The ‘display’ property does not apply to the ‘symbol’ element; thus, ‘symbol’ elements are not directly rendered even if the ‘display’ property is set to a value other than none, and ‘symbol’ elements are available for referencing even when the ‘display’ property on the ‘symbol’ element or any of its ancestors is set to none.

5.6 The ‘use’ element

‘use’
Categories:
Graphics element, graphics referencing element, structural element
Content model:
Any number of the following elements, in any order:
  • animation elements‘animate’, ‘animateColor’, ‘animateMotion’, ‘animateTransform’, ‘set’
  • descriptive elements‘desc’, ‘metadata’, ‘title’
Attributes:
  • core attributes‘id’, ‘xml:base’, ‘xml:lang’, ‘xml:space’
  • conditional processing attributes‘requiredFeatures’, ‘requiredExtensions’, ‘systemLanguage’
  • graphical event attributes‘onfocusin’, ‘onfocusout’, ‘onactivate’, ‘onclick’, ‘onmousedown’, ‘onmouseup’, ‘onmouseover’, ‘onmousemove’, ‘onmouseout’, ‘onload’
  • presentation attributes‘alignment-baseline’, ‘baseline-shift’, ‘clip’, ‘clip-path’, ‘clip-rule’, ‘color’, ‘color-interpolation’, ‘color-interpolation-filters’, ‘color-profile’, ‘color-rendering’, ‘cursor’, ‘direction’, ‘display’, ‘dominant-baseline’, ‘enable-background’, ‘fill’, ‘fill-opacity’, ‘fill-rule’, ‘filter’, ‘flood-color’, ‘flood-opacity’, ‘font-family’, ‘font-size’, ‘font-size-adjust’, ‘font-stretch’, ‘font-style’, ‘font-variant’, ‘font-weight’, ‘glyph-orientation-horizontal’, ‘glyph-orientation-vertical’, ‘image-rendering’, ‘kerning’, ‘letter-spacing’, ‘lighting-color’, ‘marker-end’, ‘marker-mid’, ‘marker-start’, ‘mask’, ‘opacity’, ‘overflow’, ‘pointer-events’, ‘shape-rendering’, ‘stop-color’, ‘stop-opacity’, ‘stroke’, ‘stroke-dasharray’, ‘stroke-dashoffset’, ‘stroke-linecap’, ‘stroke-linejoin’, ‘stroke-miterlimit’, ‘stroke-opacity’, ‘stroke-width’, ‘text-anchor’, ‘text-decoration’, ‘text-rendering’, ‘unicode-bidi’, ‘visibility’, ‘word-spacing’, ‘writing-mode’
  • xlink attributes‘xlink:href’, ‘xlink:show’, ‘xlink:actuate’, ‘xlink:type’, ‘xlink:role’, ‘xlink:arcrole’, ‘xlink:title’
  • ‘class’
  • ‘style’
  • ‘externalResourcesRequired’
  • ‘transform’
  • ‘x’
  • ‘y’
  • ‘width’
  • ‘height’
  • ‘xlink:href’
DOM Interfaces:
  • SVGUseElement

Any ‘svg’, ‘symbol’, ‘g’, graphics element or other ‘use’ is potentially a template object that can be re-used (i.e., "instanced") in the SVG document via a ‘use’ element. The ‘use’ element references another element and indicates that the graphical contents of that element is included/drawn at that given point in the document.

Unlike ‘image’, the ‘use’ element cannot reference entire files.

The ‘use’ element has optional attributes ‘x’, ‘y’, ‘width’ and ‘height’ which are used to map the graphical contents of the referenced element onto a rectangular region within the current coordinate system.

The effect of a ‘use’ element is as if the contents of the referenced element were deeply cloned into a separate non-exposed DOM tree which had the ‘use’ element as its parent and all of the ‘use’ element's ancestors as its higher-level ancestors. Because the cloned DOM tree is non-exposed, the SVG Document Object Model (DOM) only contains the ‘use’ element and its attributes. The SVG DOM does not show the referenced element's contents as children of ‘use’ element.

For user agents that support Styling with CSS, the conceptual deep cloning of the referenced element into a non-exposed DOM tree also copies any property values resulting from the CSS cascade ([CSS2], chapter 6) on the referenced element and its contents. CSS2 selectors can be applied to the original (i.e., referenced) elements because they are part of the formal document structure. CSS2 selectors cannot be applied to the (conceptually) cloned DOM tree because its contents are not part of the formal document structure.

Property inheritance, however, works as if the referenced element had been textually included as a deeply cloned child of the ‘use’ element. The referenced element inherits properties from the ‘use’ element and the ‘use’ element's ancestors. An instance of a referenced element does not inherit properties from the referenced element's original parents.

If event attributes are assigned to referenced elements, then the actual target for the event will be the SVGElementInstance object within the "instance tree" corresponding to the given referenced element.

The event handling for the non-exposed tree works as if the referenced element had been textually included as a deeply cloned child of the ‘use’ element, except that events are dispatched to the SVGElementInstance objects. The event's target and currentTarget attributes are set to the SVGElementInstance that corresponds to the target and current target elements in the referenced subtree. An event propagates through the exposed and non-exposed portions of the tree in the same manner as it would in the regular document tree: first going from the root element to the ‘use’ element and then through non-exposed tree elements in the capture phase, followed by the target phase at the target of the event, then bubbling back through non-exposed tree to the use element and then back through regular tree to the root element in bubbling phase.

An element and all its corresponding SVGElementInstance objects share an event listener list. The currentTarget attribute of the event can be used to determine through which object an event listener was invoked.

The behavior of the ‘visibility’ property conforms to this model of property inheritance. Thus, specifying 'visibility:hidden' on a ‘use’ element does not guarantee that the referenced content will not be rendered. If the ‘use’ element specifies 'visibility:hidden' and the element it references specifies 'visibility:hidden' or 'visibility:inherit', then that one element will be hidden. However, if the referenced element instead specifies 'visibility:visible', then that element will be visible even if the ‘use’ element specifies 'visibility:hidden'.

Animations on a referenced element will cause the instances to also be animated.

A ‘use’ element has the same visual effect as if the ‘use’ element were replaced by the following generated content:

  • If the ‘use’ element references a ‘symbol’ element:

    In the generated content, the ‘use’ will be replaced by ‘g’, where all attributes from the ‘use’ element except for ‘x’, ‘y’, ‘width’, ‘height’ and ‘xlink:href’ are transferred to the generated ‘g’ element. An additional transformation translate(x,y) is appended to the end (i.e., right-side) of the ‘transform’ attribute on the generated ‘g’, where x and y represent the values of the ‘x’ and ‘y’ attributes on the ‘use’ element. The referenced ‘symbol’ and its contents are deep-cloned into the generated tree, with the exception that the ‘symbol’ is replaced by an ‘svg’. This generated ‘svg’ will always have explicit values for attributes ‘width’ and ‘height’. If attributes ‘width’ and/or ‘height’ are provided on the ‘use’ element, then these attributes will be transferred to the generated ‘svg’. If attributes ‘width’ and/or ‘height’ are not specified, the generated ‘svg’ element will use values of '100%' for these attributes.

  • If the ‘use’ element references an ‘svg’ element:

    In the generated content, the ‘use’ will be replaced by ‘g’, where all attributes from the ‘use’ element except for ‘x’, ‘y’, ‘width’, ‘height’ and ‘xlink:href’ are transferred to the generated ‘g’ element. An additional transformation translate(x,y) is appended to the end (i.e., right-side) of the ‘transform’ attribute on the generated ‘g’, where x and y represent the values of the ‘x’ and ‘y’ attributes on the ‘use’ element. The referenced ‘svg’ and its contents are deep-cloned into the generated tree. If attributes ‘width’ and/or ‘height’ are provided on the ‘use’ element, then these values will override the corresponding attributes on the ‘svg’ in the generated tree.

  • Otherwise:

    In the generated content, the ‘use’ will be replaced by ‘g’, where all attributes from the ‘use’ element except for ‘x’, ‘y’, ‘width’, ‘height’ and ‘xlink:href’ are transferred to the generated ‘g’ element. An additional transformation translate(x,y) is appended to the end (i.e., right-side) of the ‘transform’ attribute on the generated ‘g’, where x and y represent the values of the ‘x’ and ‘y’ attributes on the ‘use’ element. The referenced object and its contents are deep-cloned into the generated tree.

For user agents that support Styling with CSS, the generated ‘g’ element carries along with it the "cascaded" property values on the ‘use’ element which result from the CSS cascade ([CSS2], chapter 6). Additionally, the copy (deep clone) of the referenced resource carries along with it the "cascaded" property values resulting from the CSS cascade on the original (i.e., referenced) elements. Thus, the result of various CSS selectors in combination with the ‘class’ and ‘style’ attributes are, in effect, replaced by the functional equivalent of a ‘style’ attribute in the generated content which conveys the "cascaded" property values.

Example Use01 below has a simple ‘use’ on a ‘rect’.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1"
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
  <desc>Example Use01 - Simple case of 'use' on a 'rect'</desc>
  <defs>
    <rect id="MyRect" width="60" height="10"/>
  </defs>
  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <use x="20" y="10" xlink:href="#MyRect" />
</svg>
Example Use01
Example Use01 — Simple case of 'use' on a 'rect'

View this example as SVG (SVG-enabled browsers only)

The visual effect would be equivalent to the following document:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="10cm" height="3cm" viewBox="0 0 100 30"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example Use01-GeneratedContent - Simple case of 'use' on a 'rect'</desc>
  <!-- 'defs' section left out -->

  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />

  <!-- Start of generated content. Replaces 'use' -->
  <g transform="translate(20,10)">
    <rect width="60" height="10"/>
  </g>
  <!-- End of generated content -->

</svg>

View this example as SVG (SVG-enabled browsers only)

Example Use02 below has a ‘use’ on a ‘symbol’.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1"
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
  <desc>Example Use02 - 'use' on a 'symbol'</desc>
  <defs>
    <symbol id="MySymbol" viewBox="0 0 20 20">
      <desc>MySymbol - four rectangles in a grid</desc>
      <rect x="1" y="1" width="8" height="8"/>
      <rect x="11" y="1" width="8" height="8"/>
      <rect x="1" y="11" width="8" height="8"/>
      <rect x="11" y="11" width="8" height="8"/>
    </symbol>
  </defs>
  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <use x="45" y="10" width="10" height="10" 
       xlink:href="#MySymbol" />
</svg>
Example Use02
Example Use02 — 'use' on a 'symbol'

View this example as SVG (SVG-enabled browsers only)

The visual effect would be equivalent to the following document:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="10cm" height="3cm" viewBox="0 0 100 30"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example Use02-GeneratedContent - 'use' on a 'symbol'</desc>

  <!-- 'defs' section left out -->

  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />

  <!-- Start of generated content. Replaces 'use' -->
  <g transform="translate(45, 10)" >
    <!-- Start of referenced 'symbol'. 'symbol' replaced by 'svg',
         with x,y,width,height=0,0,100%,100% -->
    <svg width="10" height="10" 
         viewBox="0 0 20 20">
      <rect x="1" y="1" width="8" height="8"/>
      <rect x="11" y="1" width="8" height="8"/>
      <rect x="1" y="11" width="8" height="8"/>
      <rect x="11" y="11" width="8" height="8"/>
    </svg>
    <!-- End of referenced symbol -->
  </g>
  <!-- End of generated content -->

</svg>

View this example as SVG (SVG-enabled browsers only)

Example Use03 illustrates what happens when a ‘use’ has a ‘transform’ attribute.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1"
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
  <desc>Example Use03 - 'use' with a 'transform' attribute</desc>
  <defs>
    <rect id="MyRect" x="0" y="0" width="60" height="10"/>
  </defs>
  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <use xlink:href="#MyRect"
       transform="translate(20,2.5) rotate(10)" />
</svg>
Example Use03
Example Use03 — 'use' with a 'transform' attribute

View this example as SVG (SVG-enabled browsers only)

The visual effect would be equivalent to the following document:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="10cm" height="3cm" viewBox="0 0 100 30"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example Use03-GeneratedContent - 'use' with a 'transform' attribute</desc>

  <!-- 'defs' section left out -->

  <rect x=".1" y=".1" width="99.8" height="29.8"
        fill="none" stroke="blue" stroke-width=".2" />

  <!-- Start of generated content. Replaces 'use' -->
  <g transform="translate(20,2.5) rotate(10)">
    <rect x="0" y="0" width="60" height="10"/>
  </g>
  <!-- End of generated content -->

</svg>

View this example as SVG (SVG-enabled browsers only)

Example Use04 illustrates a ‘use’ element with various methods of applying CSS styling.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="12cm" height="3cm" viewBox="0 0 1200 300" version="1.1"
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
  <desc>Example Use04 - 'use' with CSS styling</desc>
  <defs style=" /* rule 9 */ stroke-miterlimit: 10" >
    <path id="MyPath" d="M300 50 L900 50 L900 250 L300 250"
                     class="MyPathClass"
                     style=" /* rule 10 */ stroke-dasharray:300,100" />
  </defs>
  <style type="text/css">
    <![CDATA[
      /* rule 1 */ #MyUse { fill: blue }
      /* rule 2 */ #MyPath { stroke: red }
      /* rule 3 */ use { fill-opacity: .5 }
      /* rule 4 */ path { stroke-opacity: .5 }
      /* rule 5 */ .MyUseClass { stroke-linecap: round }
      /* rule 6 */ .MyPathClass { stroke-linejoin: bevel }
      /* rule 7 */ use > path { shape-rendering: optimizeQuality }
      /* rule 8 */ g > path { visibility: hidden }
    ]]>
  </style>

  <rect x="0" y="0" width="1200" height="300"
         style="fill:none; stroke:blue; stroke-width:3"/>
  <g style=" /* rule 11 */ stroke-width:40">
    <use id="MyUse" xlink:href="#MyPath" 
         class="MyUseClass"
         style="/* rule 12 */ stroke-dashoffset:50" />
  </g>
</svg>
Example Use04
Example Use04 — 'use' with CSS styling

View this example as SVG (SVG-enabled browsers only)

The visual effect would be equivalent to the following document. Observe that some of the style rules above apply to the generated content (i.e., rules 1-6, 10-12), whereas others do not (i.e., rules 7-9). The rules which do not affect the generated content are:

  • Rules 7 and 8: CSS selectors only apply to the formal document tree, not on the generated tree; thus, these selectors will not yield a match.
  • Rule 9: The generated tree only inherits from the ancestors of the ‘use’ element and does not inherit from the ancestors of the referenced element; thus, this rule does not affect the generated content.

In the generated content below, the selectors that yield a match have been transferred into inline ‘style’ attributes for illustrative purposes.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="12cm" height="3cm" viewBox="0 0 1200 300"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example Use04-GeneratedContent - 'use' with a 'transform' attribute</desc>

  <!-- 'style' and 'defs' sections left out -->

  <rect x="0" y="0" width="1200" height="300"
         style="fill:none; stroke:blue; stroke-width:3"/>
  <g style="/* rule 11 */ stroke-width:40">

    <!-- Start of generated content. Replaces 'use' -->
    <g style="/* rule 1 */ fill:blue;
                 /* rule 3 */ fill-opacity:.5;
                 /* rule 5 */ stroke-linecap:round;
                 /* rule 12 */ stroke-dashoffset:50" >
      <path d="M300 50 L900 50 L900 250 L300 250"
            style="/* rule 2 */ stroke:red; 
                   /* rule 4 */ stroke-opacity:.5; 
                   /* rule 6 */ stroke-linejoin: bevel; 
                   /* rule 10 */ stroke-dasharray:300,100" />
    </g> 
    <!-- End of generated content -->

  </g>
</svg>

View this example as SVG (SVG-enabled browsers only)

When a ‘use’ references another element which is another ‘use’ or whose content contains a ‘use’ element, then the deep cloning approach described above is recursive. However, a set of references that directly or indirectly reference a element to create a circular dependency is an error, as described in References and the ‘defs’ element.

Attribute definitions:

x = "<coordinate>"
The x-axis coordinate of one corner of the rectangular region into which the referenced element is placed.
If the attribute is not specified, the effect is as if a value of "0" were specified.
Animatable: yes.
y = "<coordinate>"
The y-axis coordinate of one corner of the rectangular region into which the referenced element is placed.
If the attribute is not specified, the effect is as if a value of "0" were specified.
Animatable: yes.
width = "<length>"
The width of the rectangular region into which the referenced element is placed. A negative value is an error (see Error processing). A value of zero disables rendering of this element.
Animatable: yes.
height = "<length>"
The height of the rectangular region into which the referenced element is placed. A negative value is an error (see Error processing). A value of zero disables rendering of this element.
Animatable: yes.
xlink:href = "<iri>"
A IRI reference to an element/fragment within an SVG document.
Animatable: yes.

5.7 The ‘image’ element

‘image’
Categories:
Graphics element, graphics referencing element
Content model:
Any number of the following elements, in any order:
  • animation elements‘animate’, ‘animateColor’, ‘animateMotion’, ‘animateTransform’, ‘set’
  • descriptive elements‘desc’, ‘metadata’, ‘title’
Attributes:
  • core attributes‘id’, ‘xml:base’, ‘xml:lang’, ‘xml:space’
  • conditional processing attributes‘requiredFeatures’, ‘requiredExtensions’, ‘systemLanguage’
  • graphical event attributes‘onfocusin’, ‘onfocusout’, ‘onactivate’, ‘onclick’, ‘onmousedown’, ‘onmouseup’, ‘onmouseover’, ‘onmousemove’, ‘onmouseout’, ‘onload’
  • xlink attributes‘xlink:href’, ‘xlink:show’, ‘xlink:actuate’, ‘xlink:type’, ‘xlink:role’, ‘xlink:arcrole’, ‘xlink:title’
  • presentation attributes‘alignment-baseline’, ‘baseline-shift’, ‘clip’, ‘clip-path’, ‘clip-rule’, ‘color’, ‘color-interpolation’, ‘color-interpolation-filters’, ‘color-profile’, ‘color-rendering’, ‘cursor’, ‘direction’, ‘display’, ‘dominant-baseline’, ‘enable-background’, ‘fill’, ‘fill-opacity’, ‘fill-rule’, ‘filter’, ‘flood-color’, ‘flood-opacity’, ‘font-family’, ‘font-size’, ‘font-size-adjust’, ‘font-stretch’, ‘font-style’, ‘font-variant’, ‘font-weight’, ‘glyph-orientation-horizontal’, ‘glyph-orientation-vertical’, ‘image-rendering’, ‘kerning’, ‘letter-spacing’, ‘lighting-color’, ‘marker-end’, ‘marker-mid’, ‘marker-start’, ‘mask’, ‘opacity’, ‘overflow’, ‘pointer-events’, ‘shape-rendering’, ‘stop-color’, ‘stop-opacity’, ‘stroke’, ‘stroke-dasharray’, ‘stroke-dashoffset’, ‘stroke-linecap’, ‘stroke-linejoin’, ‘stroke-miterlimit’, ‘stroke-opacity’, ‘stroke-width’, ‘text-anchor’, ‘text-decoration’, ‘text-rendering’, ‘unicode-bidi’, ‘visibility’, ‘word-spacing’, ‘writing-mode’
  • ‘class’
  • ‘style’
  • ‘externalResourcesRequired’
  • ‘preserveAspectRatio’
  • ‘transform’
  • ‘x’
  • ‘y’
  • ‘width’
  • ‘height’
  • ‘xlink:href’
DOM Interfaces:
  • SVGImageElement

The ‘image’ element indicates that the contents of a complete file are to be rendered into a given rectangle within the current user coordinate system. The ‘image’ element can refer to raster image files such as PNG or JPEG or to files with MIME type of "image/svg+xml". Conforming SVG viewers need to support at least PNG, JPEG and SVG format files.

The result of processing an ‘image’ is always a four-channel RGBA result. When an ‘image’ element references a raster image file such as PNG or JPEG files which only has three channels (RGB), then the effect is as if the object were converted into a 4-channel RGBA image with the alpha channel uniformly set to 1. For a single-channel raster image, the effect is as if the object were converted into a 4-channel RGBA image, where the single channel from the referenced object is used to compute the three color channels and the alpha channel is uniformly set to 1.

An ‘image’ element establishes a new viewport for the referenced file as described in Establishing a new viewport.  The bounds for the new viewport are defined by attributes ‘x’, ‘y’, ‘width’ and ‘height’. The placement and scaling of the referenced image are controlled by the ‘preserveAspectRatio’ attribute on the ‘image’ element.

When an ‘image’ element references an SVG image, the ‘clip’ and ‘overflow’ properties on the root element in the referenced SVG image are ignored (in the same manner as the ‘x’, ‘y’, ‘width’ and ‘height’ attributes are ignored). Unless the value of ‘preserveAspectRatio’ on the ‘image’ element starts with 'defer', the ‘preserveAspectRatio’ attribute on the root element in the referenced SVG image is also ignored (see ‘preserveAspectRatio’ for details). Instead, the ‘preserveAspectRatio’ attribute on the referencing ‘image’ element defines how the SVG image content is fitted into the viewport and the ‘clip’ and ‘overflow’ properties on the ‘image’ element define how the SVG image content is clipped (or not) relative to the viewport.

The value of the ‘viewBox’ attribute to use when evaluating the ‘preserveAspectRatio’ attribute is defined by the referenced content. For content that clearly identifies a viewBox (e.g. an SVG file with the ‘viewBox’ attribute on the outermost svg element) that value should be used. For most raster content (PNG, JPEG) the bounds of the image should be used (i.e. the ‘image’ element has an implicit ‘viewBox’ of '0 0 raster-image-width raster-image-height'). Where no value is readily available (e.g. an SVG file with no ‘viewBox’ attribute on the outermost svg element) the ‘preserveAspectRatio’ attribute is ignored, and only the translation due to the ‘x’ & ‘y’ attributes of the viewport is used to display the content.

For example, if the image element referenced a PNG or JPEG and preserveAspectRatio="xMinYMin meet", then the aspect ratio of the raster would be preserved (which means that the scale factor from image's coordinates to current user space coordinates would be the same for both X and Y), the raster would be sized as large as possible while ensuring that the entire raster fits within the viewport, and the top/left of the raster would be aligned with the top/left of the viewport as defined by the attributes ‘x’, ‘y’, ‘width’ and ‘height’ on the ‘image’ element.  If the value of ‘preserveAspectRatio’ was 'none' then aspect ratio of the image would not be preserved. The image would be fitted such that the top/left corner of the raster exactly aligns with coordinate (‘x’, ‘y’) and the bottom/right corner of the raster exactly aligns with coordinate (‘x’+‘width’, ‘y’+‘height’).

The resource referenced by the ‘image’ element represents a separate document which generates its own parse tree and document object model (if the resource is XML). Thus, there is no inheritance of properties into the image.

Unlike ‘use’, the ‘image’ element cannot reference elements within an SVG file.

Attribute definitions:

x = "<coordinate>"
The x-axis coordinate of one corner of the rectangular region into which the referenced document is placed.
If the attribute is not specified, the effect is as if a value of '0' were specified.
Animatable: yes.
y = "<coordinate>"
The y-axis coordinate of one corner of the rectangular region into which the referenced document is placed.
If the attribute is not specified, the effect is as if a value of '0' were specified.
Animatable: yes.
width = "<length>"
The width of the rectangular region into which the referenced document is placed.
A negative value is an error (see Error processing). A value of zero disables rendering of the element.
Animatable: yes.
height = "<length>"
The height of the rectangular region into which the referenced document is placed.
A negative value is an error (see Error processing). A value of zero disables rendering of the element.
Animatable: yes.
xlink:href = "<iri>"
A IRI reference.
Animatable: yes.
preserveAspectRatio = "[defer] <align> [<meetOrSlice>]"

See ‘preserveAspectRatio’.

If attribute ‘preserveAspectRatio’ is not specified, then the effect is as if a value of xMidYMid meet were specified.

Animatable: yes.

An example:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="4in" height="3in" version="1.1"
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
  <desc>This graphic links to an external image
  </desc>
  <image x="200" y="200" width="100px" height="100px"
         xlink:href="myimage.png">
    <title>My image</title>
  </image>
</svg>

5.8 Conditional processing

5.8.1 Conditional processing overview

SVG contains a ‘switch’ element along with attributes ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ to provide an ability to specify alternate viewing depending on the capabilities of a given user agent or the user's language.

Attributes ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ act as tests and return either true or false results. The ‘switch’ renders the first of its children for which all of these attributes test true. If the given attribute is not specified, then a true value is assumed.

Similar to the ‘display’ property, conditional processing attributes only affect the direct rendering of elements and do not prevent elements from being successfully referenced by other elements (such as via a ‘use’).

In consequence:

  • ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ attributes affect ‘a’, ‘altGlyph’, ‘foreignObject’, ‘textPath’, ‘tref’, and ‘tspan’ elements.
  • ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ attributes will have no effect on ‘mask’, ‘clipPath’, and ‘pattern’ elements.
  • ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ attributes do not apply to the ‘defs’, and ‘cursor’ elements because they are not part of the rendering tree.
  • ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ attributes affect ‘animate’, ‘animateColor’, ‘animateMotion’, ‘animateTransform’, and ‘set’ elements. If the conditional statement on these animation elements fails, the animation will never be triggered.

5.8.2 The ‘switch’ element

‘switch’
Categories:
Container element
Content model:
Any number of the following elements, in any order:
  • animation elements‘animate’, ‘animateColor’, ‘animateMotion’, ‘animateTransform’, ‘set’
  • descriptive elements‘desc’, ‘metadata’, ‘title’
  • shape elements‘circle’, ‘ellipse’, ‘line’, ‘path’, ‘polygon’, ‘polyline’, ‘rect’
  • ‘a’
  • ‘foreignObject’
  • ‘g’
  • ‘image’
  • ‘svg’
  • ‘switch’
  • ‘text’
  • ‘use’
Attributes:
  • conditional processing attributes‘requiredFeatures’, ‘requiredExtensions’, ‘systemLanguage’
  • core attributes‘id’, ‘xml:base’, ‘xml:lang’, ‘xml:space’
  • graphical event attributes‘onfocusin’, ‘onfocusout’, ‘onactivate’, ‘onclick’, ‘onmousedown’, ‘onmouseup’, ‘onmouseover’, ‘onmousemove’, ‘onmouseout’, ‘onload’
  • presentation attributes‘alignment-baseline’, ‘baseline-shift’, ‘clip’, ‘clip-path’, ‘clip-rule’, ‘color’, ‘color-interpolation’, ‘color-interpolation-filters’, ‘color-profile’, ‘color-rendering’, ‘cursor’, ‘direction’, ‘display’, ‘dominant-baseline’, ‘enable-background’, ‘fill’, ‘fill-opacity’, ‘fill-rule’, ‘filter’, ‘flood-color’, ‘flood-opacity’, ‘font-family’, ‘font-size’, ‘font-size-adjust’, ‘font-stretch’, ‘font-style’, ‘font-variant’, ‘font-weight’, ‘glyph-orientation-horizontal’, ‘glyph-orientation-vertical’, ‘image-rendering’, ‘kerning’, ‘letter-spacing’, ‘lighting-color’, ‘marker-end’, ‘marker-mid’, ‘marker-start’, ‘mask’, ‘opacity’, ‘overflow’, ‘pointer-events’, ‘shape-rendering’, ‘stop-color’, ‘stop-opacity’, ‘stroke’, ‘stroke-dasharray’, ‘stroke-dashoffset’, ‘stroke-linecap’, ‘stroke-linejoin’, ‘stroke-miterlimit’, ‘stroke-opacity’, ‘stroke-width’, ‘text-anchor’, ‘text-decoration’, ‘text-rendering’, ‘unicode-bidi’, ‘visibility’, ‘word-spacing’, ‘writing-mode’
  • ‘class’
  • ‘style’
  • ‘externalResourcesRequired’
  • ‘transform’
DOM Interfaces:
  • SVGSwitchElement

The ‘switch’ element evaluates the ‘requiredFeatures’, ‘requiredExtensions’ and ‘systemLanguage’ attributes on its direct child elements in order, and then processes and renders the first child for which these attributes evaluate to true. All others will be bypassed and therefore not rendered. If the child element is a container element such as a ‘g’, then the entire subtree is either processed/rendered or bypassed/not rendered.

Note that the values of properties ‘display’ and ‘visibility’ have no effect on ‘switch’ element processing. In particular, setting ‘display’ to none on a child of a ‘switch’ element has no effect on true/false testing associated with ‘switch’ element processing.

For more information and an example, see Embedding foreign object types.

5.8.3 The ‘requiredFeatures’ attribute

Definition of requiredFeatures:

requiredFeatures = list-of-features
The value is a list of feature strings, with the individual values separated by white space. Determines whether all of the named features are supported by the user agent. Only feature strings defined in the Feature String appendix are allowed. If all of the given features are supported, then the attribute evaluates to true; otherwise, the current element and its children are skipped and thus will not be rendered.
Animatable: no.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute ‘requiredFeatures’, the attribute returns "false".

‘requiredFeatures’ is often used in conjunction with the ‘switch’ element. If the ‘requiredFeatures’ is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

5.8.4 The ‘requiredExtensions’ attribute

The ‘requiredExtensions’ attribute defines a list of required language extensions. Language extensions are capabilities within a user agent that go beyond the feature set defined in this specification. Each extension is identified by an IRI reference.

Definition of requiredExtensions:

requiredExtensions = list-of-extensions
The value is a list of IRI references which identify the required extensions, with the individual values separated by white space. Determines whether all of the named extensions are supported by the user agent. If all of the given extensions are supported, then the attribute evaluates to true; otherwise, the current element and its children are skipped and thus will not be rendered.
Animatable: no.

If a given IRI reference contains white space within itself, that white space must be escaped.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute ‘requiredExtensions’, the attribute returns "false".

‘requiredExtensions’ is often used in conjunction with the ‘switch’ element. If the ‘requiredExtensions’ is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

The IRI names for the extension should include versioning information, such as "http://example.org/SVGExtensionXYZ/1.0", so that script writers can distinguish between different versions of a given extension.

5.8.5 The ‘systemLanguage’ attribute

The attribute value is a comma-separated list of language names as defined in BCP 47 [BCP47].

Evaluates to "true" if one of the languages indicated by user preferences exactly equals one of the languages given in the value of this parameter, or if one of the languages indicated by user preferences exactly equals a prefix of one of the languages given in the value of this parameter such that the first tag character following the prefix is "-".

Evaluates to "false" otherwise.

Note: This use of a prefix matching rule does not imply that language tags are assigned to languages in such a way that it is always true that if a user understands a language with a certain tag, then this user will also understand all languages with tags for which this tag is a prefix.

The prefix rule simply allows the use of prefix tags if this is the case.

Implementation note: When making the choice of linguistic preference available to the user, implementers should take into account the fact that users are not familiar with the details of language matching as described above, and should provide appropriate guidance. As an example, users may assume that on selecting "en-gb", they will be served any kind of English document if British English is not available. The user interface for setting user preferences should guide the user to add "en" to get the best matching behavior.

Multiple languages MAY be listed for content that is intended for multiple audiences. For example, content that is presented simultaneously in the original Maori and English versions, would call for:

<text systemLanguage="mi, en"><!-- content goes here --></text>

However, just because multiple languages are present within the object on which the ‘systemLanguage’ test attribute is placed, this does not mean that it is intended for multiple linguistic audiences. An example would be a beginner's language primer, such as "A First Lesson in Latin," which is clearly intended to be used by an English-literate audience. In this case, the ‘systemLanguage’ test attribute should only include "en".

Authoring note: Authors should realize that if several alternative language objects are enclosed in a ‘switch’, and none of them matches, this may lead to situations where no content is displayed. It is thus recommended to include a "catch-all" choice at the end of such a ‘switch’ which is acceptable in all cases.

For the ‘systemLanguage’ attribute: Animatable: no.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute ‘systemLanguage’, the attribute returns "false".

‘systemLanguage’ is often used in conjunction with the ‘switch’ element. If the ‘systemLanguage’ is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

5.8.6 Applicability of test attributes

The following list describes the applicability of the test attributes to the elements that do not directly produce rendering.

  • the test attributes do not effect the ‘mask’, ‘clipPath’, ‘linearGradient’, ‘radialGradient’ and ‘pattern’ elements. The test attributes on a referenced element do not affect the rendering of the referencing element.
  • the test attributes do not effect the ‘defs’, and ‘cursor’ elements as they are not part of the rendering tree.
  • an animation element (‘animate’, ‘animateMotion’, ‘animateTransform’, ‘animateColor’ and ‘set’) will never be triggered if it has a test attribute that evaluates to false.

5.9 Specifying whether external resources are required for proper rendering

Documents often reference and use the contents of other files (and other Web resources) as part of their rendering. In some cases, authors want to specify that particular resources are required for a document to be considered correct.

Attribute ‘externalResourcesRequired’ is available on all container elements and to all elements which potentially can reference external resources. It specifies whether referenced resources that are not part of the current document are required for proper rendering of the given container element or graphics element.

Attribute definition:

externalResourcesRequired = "false | true"
false
(The default value.) Indicates that resources external to the current document are optional. Document rendering can proceed even if external resources are unavailable to the current element and its descendants.
true
Indicates that resources external to the current document are required. If an external resource is not available, progressive rendering is suspended, the document's SVGLoad event is not fired and the animation timeline does not begin until that resource and all other required resources become available, have been parsed and are ready to be rendered. If a timeout event occurs on a required resource, then the document goes into an error state (see Error processing). The document remains in an error state until all required resources become available.

This attribute applies to all types of resource references, including style sheets, color profiles (see Color profile descriptions) and fonts specified by an IRI reference using a ‘font-face’ element or a CSS @font-face specification. In particular, if an element sets externalResourcesRequired="true", then all style sheets must be available since any style sheet might affect the rendering of that element.

Attribute ‘externalResourcesRequired’ is not inheritable (from a sense of attribute value inheritance), but if set on a container element, its value will apply to all elements within the container.

Because setting externalResourcesRequired="true" on a container element will have the effect of disabling progressive display of the contents of that container, if that container includes elements that reference external resources, tools that generate SVG content are cautioned against simply setting externalResourcesRequired="true" on the outermost svg element on a universal basis. Instead, it is better to specify externalResourcesRequired="true" on those particular graphics elements or container elements which specifically need the availability of external resources in order to render properly.

For ‘externalResourcesRequired’: Animatable: no.

5.10 Common attributes

5.10.1 Attributes common to all elements: ‘id’ and ‘xml:base’

The ‘id’ and ‘xml:base’ attributes are available on all SVG elements:

Attribute definitions:

id = "name"
Standard XML attribute for assigning a unique name to an element. Refer to the Extensible Markup Language (XML) 1.0 Recommendation [XML10].
Animatable: no.
xml:base = "<iri>"
Specifies a base IRI other than the base IRI of the document or external entity. Refer to the XML Base specification [XML-BASE].
Animatable: no.

5.10.2 The ‘xml:lang’ and ‘xml:space’ attributes

Elements that might contain character data content have attributes ‘xml:lang’ and ‘xml:space’.

Attribute definitions:

xml:lang = "languageID"
Standard XML attribute to specify the language (e.g., English) used in the contents and attribute values of particular elements. Refer to the Extensible Markup Language (XML) 1.0 Recommendation [XML10].
Animatable: no.
xml:space = "{default | preserve}"
Standard XML attribute to specify whether white space is preserved in character data. The only possible values are 'default' and 'preserve'. Refer to the Extensible Markup Language (XML) 1.0 Recommendation [XML10] and to the discussion white space handling in SVG.
Animatable: no.

5.11 DOM interfaces

5.11.1 Interface SVGDocument

When an ‘svg’ element is embedded inline as a component of a document from another namespace, such as when an ‘svg’ element is embedded inline within an XHTML document [XHTML], then an SVGDocument object will not exist; instead, the root object in the document object hierarchy will be a Document object of a different type, such as an HTMLDocument object.

However, an SVGDocument object will indeed exist when the root element of the XML document hierarchy is an ‘svg’ element, such as when viewing a stand-alone SVG file (i.e., a file with MIME type "image/svg+xml"). In this case, the SVGDocument object will be the root object of the document object model hierarchy.

In the case where an SVG document is embedded by reference, such as when an XHTML document has an ‘object’ element whose ‘href’ attribute references an SVG document (i.e., a document whose MIME type is "image/svg+xml" and whose root element is thus an ‘svg’ element), there will exist two distinct DOM hierarchies. The first DOM hierarchy will be for the referencing document (e.g., an XHTML document). The second DOM hierarchy will be for the referenced SVG document. In this second DOM hierarchy, the root object of the document object model hierarchy is an SVGDocument object.

The SVGDocument interface contains a similar list of attributes and methods to the HTMLDocument interface described in the Document Object Model (HTML) Level 1 chapter of the [DOM1] specification.

interface SVGDocument : Document,
                        DocumentEvent {
  readonly attribute DOMString title;
  readonly attribute DOMString referrer;
  readonly attribute DOMString domain;
  readonly attribute DOMString URL;
  readonly attribute SVGSVGElement rootElement;
};
Attributes:
title (readonly DOMString)
The title of a document as specified by the ‘title’ sub-element of the ‘svg’ root element (i.e., <svg><title>Here is the title</title>...</svg>)
referrer (readonly DOMString)
Returns the URI of the page that linked to this page. The value is an empty string if the user navigated to the page directly (not through a link, but, for example, via a bookmark).
domain (readonly DOMString)
The domain name of the server that served the document, or a null string if the server cannot be identified by a domain name.
URL (readonly DOMString)
The complete URI of the document.
rootElement (readonly SVGSVGElement)
The root ‘svg’ in the document hierarchy.

5.11.2 Interface SVGSVGElement

A key interface definition is the SVGSVGElement interface, which is the interface that corresponds to the ‘svg’ element. This interface contains various miscellaneous commonly-used utility methods, such as matrix operations and the ability to control the time of redraw on visual rendering devices.

SVGSVGElement extends ViewCSS and DocumentCSS to provide access to the computed values of properties and the override style sheet as described in DOM Level 2 Style [DOM2STYLE].

interface SVGSVGElement : SVGElement,
                          SVGTests,
                          SVGLangSpace,
                          SVGExternalResourcesRequired,
                          SVGStylable,
                          SVGLocatable,
                          SVGFitToViewBox,
                          SVGZoomAndPan,
                          DocumentEvent,
                          ViewCSS,
                          DocumentCSS {

  readonly attribute SVGAnimatedLength x;
  readonly attribute SVGAnimatedLength y;
  readonly attribute SVGAnimatedLength width;
  readonly attribute SVGAnimatedLength height;
           attribute DOMString contentScriptType setraises(DOMException);
           attribute DOMString contentStyleType setraises(DOMException);
  readonly attribute SVGRect viewport;
  readonly attribute float pixelUnitToMillimeterX;
  readonly attribute float pixelUnitToMillimeterY;
  readonly attribute float screenPixelToMillimeterX;
  readonly attribute float screenPixelToMillimeterY;
  readonly attribute boolean useCurrentView;
  readonly attribute SVGViewSpec currentView;
           attribute float currentScale;
  readonly attribute SVGPoint currentTranslate;

  unsigned long suspendRedraw(in unsigned long maxWaitMilliseconds);
  void unsuspendRedraw(in unsigned long suspendHandleID);
  void unsuspendRedrawAll();
  void forceRedraw();
  void pauseAnimations();
  void unpauseAnimations();
  boolean animationsPaused();
  float getCurrentTime();
  void setCurrentTime(in float seconds);
  NodeList getIntersectionList(in SVGRect rect, in SVGElement referenceElement);
  NodeList getEnclosureList(in SVGRect rect, in SVGElement referenceElement);
  boolean checkIntersection(in SVGElement element, in SVGRect rect);
  boolean checkEnclosure(in SVGElement element, in SVGRect rect);
  void deselectAll();
  SVGNumber createSVGNumber();
  SVGLength createSVGLength();
  SVGAngle createSVGAngle();
  SVGPoint createSVGPoint();
  SVGMatrix createSVGMatrix();
  SVGRect createSVGRect();
  SVGTransform createSVGTransform();
  SVGTransform createSVGTransformFromMatrix(in SVGMatrix matrix);
  Element getElementById(in DOMString elementId);
};
Attributes:
x (readonly SVGAnimatedLength)
Corresponds to attribute ‘x’ on the given ‘svg’ element.
y (readonly SVGAnimatedLength)
Corresponds to attribute ‘y’ on the given ‘svg’ element.
width (readonly SVGAnimatedLength)
Corresponds to attribute ‘width’ on the given ‘svg’ element.
height (readonly SVGAnimatedLength)
Corresponds to attribute ‘height’ on the given ‘svg’ element.
contentScriptType (DOMString)
Corresponds to attribute ‘contentScriptType’ on the given ‘svg’ element.
Exceptions on setting
DOMException, code NO_MODIFICATION_ALLOWED_ERR
Raised on an attempt to change the value of a read only attribute.
contentStyleType (DOMString)
Corresponds to attribute ‘contentStyleType’ on the given ‘svg’ element.
Exceptions on setting
DOMException, code NO_MODIFICATION_ALLOWED_ERR
Raised on an attempt to change the value of a read only attribute.
viewport (readonly SVGRect)

The position and size of the viewport (implicit or explicit) that corresponds to this ‘svg’ element. When the user agent is actually rendering the content, then the position and size values represent the actual values when rendering. The position and size values are unitless values in the coordinate system of the parent element. If no parent element exists (i.e., ‘svg’ element represents the root of the document tree), if this SVG document is embedded as part of another document (e.g., via the HTML ‘object’ element), then the position and size are unitless values in the coordinate system of the parent document. (If the parent uses CSS or XSL layout, then unitless values represent pixel units for the current CSS or XSL viewport, as described in the CSS2 specification.) If the parent element does not have a coordinate system, then the user agent should provide reasonable default values for this attribute.

The SVGRect object is read only.

pixelUnitToMillimeterX (readonly float)
Size of a pixel units (as defined by CSS2) along the x-axis of the viewport, which represents a unit somewhere in the range of 70dpi to 120dpi, and, on systems that support this, might actually match the characteristics of the target medium. On systems where it is impossible to know the size of a pixel, a suitable default pixel size is provided.
pixelUnitToMillimeterY (readonly float)
Corresponding size of a pixel unit along the y-axis of the viewport.
screenPixelToMillimeterX (readonly float)
User interface (UI) events in DOM Level 2 indicate the screen positions at which the given UI event occurred. When the user agent actually knows the physical size of a "screen unit", this attribute will express that information; otherwise, user agents will provide a suitable default value such as .28mm.
screenPixelToMillimeterY (readonly float)
Corresponding size of a screen pixel along the y-axis of the viewport.
useCurrentView (readonly boolean)
The initial view (i.e., before magnification and panning) of the current innermost SVG document fragment can be either the "standard" view (i.e., based on attributes on the ‘svg’ element such as ‘viewBox’) or to a "custom" view (i.e., a hyperlink into a particular ‘view’ or other element - see Linking into SVG content: IRI fragments and SVG views). If the initial view is the "standard" view, then this attribute is false. If the initial view is a "custom" view, then this attribute is true.
currentView (readonly SVGViewSpec)

The definition of the initial view (i.e., before magnification and panning) of the current innermost SVG document fragment. The meaning depends on the situation:

  • If the initial view was a "standard" view, then:
    • the values for viewBox, preserveAspectRatio and zoomAndPan within currentView will match the values for the corresponding DOM attributes that are on SVGSVGElement directly
    • the values for transform and viewTarget within currentView will be null
  • If the initial view was a link into a ‘view’ element, then:
    • the values for viewBox, preserveAspectRatio and zoomAndPan within currentView will correspond to the corresponding attributes for the given ‘view’ element
    • the values for transform and viewTarget within currentView will be null
  • If the initial view was a link into another element (i.e., other than a ‘view’), then:
    • the values for viewBox, preserveAspectRatio and zoomAndPan within currentView will match the values for the corresponding DOM attributes that are on SVGSVGElement directly for the closest ancestor ‘svg’ element
    • the values for transform within currentView will be null
    • the viewTarget within currentView will represent the target of the link
  • If the initial view was a link into the SVG document fragment using an SVG view specification fragment identifier (i.e., #svgView(...)), then:
    • the values for viewBox, preserveAspectRatio, zoomAndPan, transform and viewTarget within currentView will correspond to the values from the SVG view specification fragment identifier

The object itself and its contents are both read only.

currentScale (float)
On an outermost svg element, this attribute indicates the current scale factor relative to the initial view to take into account user magnification and panning operations, as described under Magnification and panning. DOM attributes currentScale and currentTranslate are equivalent to the 2x3 matrix [a b c d e f] = [currentScale 0 0 currentScale currentTranslate.x currentTranslate.y]. If "magnification" is enabled (i.e., zoomAndPan="magnify"), then the effect is as if an extra transformation were placed at the outermost level on the SVG document fragment (i.e., outside the outermost svg element).

When accessed on an ‘svg’ element that is not an outermost svg element, it is undefined what behavior this attribute has.

currentTranslate (readonly SVGPoint)
On an outermost svg element, the corresponding translation factor that takes into account user "magnification".

When accessed on an ‘svg’ element that is not an outermost svg element, it is undefined what behavior this attribute has.

Operations:
unsigned long suspendRedraw(in unsigned long maxWaitMilliseconds)
Takes a time-out value which indicates that redraw shall not occur until:
  1. the corresponding unsuspendRedraw() call has been made,
  2. an unsuspendRedrawAll() call has been made, or
  3. its timer has timed out.

In environments that do not support interactivity (e.g., print media), then redraw shall not be suspended. Calls to suspendRedraw() and unsuspendRedraw() should, but need not be, made in balanced pairs.

To suspend redraw actions as a collection of SVG DOM changes occur, precede the changes to the SVG DOM with a method call similar to:

suspendHandleID = suspendRedraw(maxWaitMilliseconds);

and follow the changes with a method call similar to:

unsuspendRedraw(suspendHandleID);

Note that multiple suspendRedraw calls can be used at once and that each such method call is treated independently of the other suspendRedraw method calls.

Parameters
  1. unsigned long maxWaitMilliseconds
    The amount of time in milliseconds to hold off before redrawing the device. Values greater than 60 seconds will be truncated down to 60 seconds.
Returns
A number which acts as a unique identifier for the given suspendRedraw() call. This value must be passed as the parameter to the corresponding unsuspendRedraw() method call.
void unsuspendRedraw(in unsigned long suspendHandleID)
Cancels a specified suspendRedraw() by providing a unique suspend handle ID that was returned by a previous suspendRedraw() call.
Parameters
  1. unsigned long suspendHandleID
    A number which acts as a unique identifier for the desired suspendRedraw() call. The number supplied must be a value returned from a previous call to suspendRedraw(). If an invalid handle ID value is provided then the request to unsuspendRedraw() is silently ignored.
void unsuspendRedrawAll()
Cancels all currently active suspendRedraw() method calls. This method is most useful at the very end of a set of SVG DOM calls to ensure that all pending suspendRedraw() method calls have been cancelled.
void forceRedraw()
In rendering environments supporting interactivity, forces the user agent to immediately redraw all regions of the viewport that require updating.
void pauseAnimations()
Suspends (i.e., pauses) all currently running animations that are defined within the SVG document fragment corresponding to this ‘svg’ element, causing the animation clock corresponding to this document fragment to stand still until it is unpaused.
void unpauseAnimations()
Unsuspends (i.e., unpauses) currently running animations that are defined within the SVG document fragment, causing the animation clock to continue from the time at which it was suspended.
boolean animationsPaused()
Returns true if this SVG document fragment is in a paused state.
Returns
Boolean indicating whether this SVG document fragment is in a paused state.
float getCurrentTime()
Returns the current time in seconds relative to the start time for the current SVG document fragment. If getCurrentTime is called before the document timeline has begun (for example, by script running in a ‘script’ element before the document's SVGLoad event is dispatched), then 0 is returned.
Returns
The current time in seconds, or 0 if the document timeline has not yet begun.
void setCurrentTime(in float seconds)
Adjusts the clock for this SVG document fragment, establishing a new current time. If setCurrentTime is called before the document timeline has begun (for example, by script running in a ‘script’ element before the document's SVGLoad event is dispatched), then the value of seconds in the last invocation of the method gives the time that the document will seek to once the document timeline has begun.
Parameters
  1. float seconds
    The new current time in seconds relative to the start time for the current SVG document fragment.
NodeList getIntersectionList(in SVGRect rect, in SVGElement referenceElement)
Returns the list of graphics elements whose rendered content intersects the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in ‘pointer-events’ processing.
Parameters
  1. SVGRect rect
    The test rectangle. The values are in the initial coordinate system for the current ‘svg’ element.
  2. SVGElement referenceElement
    If not null, then any intersected element that doesn't have the referenceElement as ancestor must not be included in the returned NodeList.
Returns
A list of Elements whose content intersects the supplied rectangle. This NodeList must be implemented identically to the NodeList interface as defined in DOM Level 2 Core ([DOM2], section 1.2) with the exception that the interface is not live.
NodeList getEnclosureList(in SVGRect rect, in SVGElement referenceElement)
Returns the list of graphics elements whose rendered content is entirely contained within the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in ‘pointer-events’ processing.
Parameters
  1. SVGRect rect
    The test rectangle. The values are in the initial coordinate system for the current ‘svg’ element.
  2. SVGElement referenceElement
    If not null, then any intersected element that doesn't have the referenceElement as ancestor must not be included in the returned NodeList.
Returns
A list of Elements whose content is enclosed by the supplied rectangle. This NodeList must be implemented identically to the NodeList interface as defined in DOM Level 2 Core ([DOM2], section 1.2) with the exception that the interface is not live.
boolean checkIntersection(in SVGElement element, in SVGRect rect)
Returns true if the rendered content of the given element intersects the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in ‘pointer-events’ processing.
Parameters
  1. SVGElement element
    The element on which to perform the given test.
  2. SVGRect rect
    The test rectangle. The values are in the initial coordinate system for the current ‘svg’ element.
Returns
True or false, depending on whether the given element intersects the supplied rectangle.
boolean checkEnclosure(in SVGElement element, in SVGRect rect)
Returns true if the rendered content of the given element is entirely contained within the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in ‘pointer-events’ processing.
Parameters
  1. SVGElement element
    The element on which to perform the given test.
  2. SVGRect rect
    The test rectangle. The values are in the initial coordinate system for the current ‘svg’ element.
Returns
True or false, depending on whether the given element is enclosed by the supplied rectangle.
void deselectAll()
Unselects any selected objects, including any selections of text strings and type-in bars.
SVGNumber createSVGNumber()
Creates an SVGNumber object outside of any document trees. The object is initialized to a value of zero.
Returns
An SVGNumber object.
SVGLength createSVGLength()
Creates an SVGLength object outside of any document trees. The object is initialized to the value of 0 user units.
Returns
An SVGLength object.
SVGAngle createSVGAngle()
Creates an SVGAngle object outside of any document trees. The object is initialized to the value 0 degrees (unitless).
Returns
An SVGAngle object.
SVGPoint createSVGPoint()
Creates an SVGPoint object outside of any document trees. The object is initialized to the point (0,0) in the user coordinate system.
Returns
An SVGPoint object.
SVGMatrix createSVGMatrix()
Creates an SVGMatrix object outside of any document trees. The object is initialized to the identity matrix.
Returns
An SVGMatrix object.
SVGRect createSVGRect()
Creates an SVGRect object outside of any document trees. The object is initialized such that all values are set to 0 user units.
Returns
An SVGRect object.
SVGTransform createSVGTransform()
Creates an SVGTransform object outside of any document trees. The object is initialized to an identity matrix transform (SVG_TRANSFORM_MATRIX).
Returns
An SVGTransform object.
SVGTransform createSVGTransformFromMatrix(in SVGMatrix matrix)

Creates an SVGTransform object outside of any document trees. The object is initialized to the given matrix transform (i.e., SVG_TRANSFORM_MATRIX). The values from the parameter matrix are copied, the matrix parameter is not adopted as SVGTransform::matrix.

Parameters
  1. SVGMatrix matrix
    The transform matrix.
Returns
An SVGTransform object.
Element getElementById(in DOMString elementId)
Searches this SVG document fragment (i.e., the search is restricted to a subset of the document tree) for an Element whose id is given by elementId. If an Element is found, that Element is returned. If no such element exists, returns null. Behavior is not defined if more than one element has this id.
Parameters
  1. DOMString elementId
    The unique id value for an element.
Returns
The matching element.

5.11.3 Interface SVGGElement

The SVGSVGElement interface corresponds to the ‘g’ element.
interface SVGGElement : SVGElement,
                        SVGTests,
                        SVGLangSpace,
                        SVGExternalResourcesRequired,
                        SVGStylable,
                        SVGTransformable {
};

5.11.4 Interface SVGDefsElement

The SVGDefsElement interface corresponds to the ‘defs’ element.
interface SVGDefsElement : SVGElement,
                           SVGTests,
                           SVGLangSpace,
                           SVGExternalResourcesRequired,
                           SVGStylable,
                           SVGTransformable {
};

5.11.5 Interface SVGDescElement

The SVGDescElement interface corresponds to the ‘desc’ element.
interface SVGDescElement : SVGElement,
                           SVGLangSpace,
                           SVGStylable {
};

5.11.6 Interface SVGTitleElement

The SVGTitleElement interface corresponds to the ‘title’ element.
interface SVGTitleElement : SVGElement,
                            SVGLangSpace,
                            SVGStylable {
};

5.11.7 Interface SVGSymbolElement

The SVGSymbolElement interface corresponds to the ‘symbol’ element.
interface SVGSymbolElement : SVGElement,
                             SVGLangSpace,
                             SVGExternalResourcesRequired,
                             SVGStylable,
                             SVGFitToViewBox {
};

5.11.8 Interface SVGUseElement

The SVGUseElement interface corresponds to the ‘use’ element.
interface SVGUseElement : SVGElement,
                          SVGURIReference,
                          SVGTests,
                          SVGLangSpace,
                          SVGExternalResourcesRequired,
                          SVGStylable,
                          SVGTransformable {
  readonly attribute SVGAnimatedLength x;
  readonly attribute SVGAnimatedLength y;
  readonly attribute SVGAnimatedLength width;
  readonly attribute SVGAnimatedLength height;
  readonly attribute SVGElementInstance instanceRoot;
  readonly attribute SVGElementInstance animatedInstanceRoot;
};
Attributes:
x (readonly SVGAnimatedLength)
Corresponds to attribute ‘x’ on the given ‘use’ element.
y (readonly SVGAnimatedLength)
Corresponds to attribute ‘y’ on the given ‘use’ element.
width (readonly SVGAnimatedLength)
Corresponds to attribute ‘width’ on the given ‘use’ element.
height (readonly SVGAnimatedLength)
Corresponds to attribute ‘height’ on the given ‘use’ element.
instanceRoot (readonly SVGElementInstance)
The root of the "instance tree". See description of SVGElementInstance for a discussion on the instance tree.
animatedInstanceRoot (readonly SVGElementInstance)
If the ‘xlink:href’ attribute is being animated, contains the current animated root of the "instance tree". If the ‘xlink:href’ attribute is not currently being animated, contains the same value as instanceRoot. See description of SVGElementInstance for a discussion on the instance tree.

5.11.9 Interface SVGElementInstance

For each ‘use’ element, the SVG DOM maintains a shadow tree (the "instance tree") of objects of type SVGElementInstance. An SVGElementInstance represents a single node in the instance tree. The root object in the instance tree is pointed to by the instanceRoot attribute on the SVGUseElement object for the corresponding ‘use’ element.

If the ‘use’ element references a simple graphics element such as a ‘rect’, then there is only a single SVGElementInstance object, and the correspondingElement attribute on this SVGElementInstance object is the SVGRectElement that corresponds to the referenced ‘rect’ element.

If the ‘use’ element references a ‘g’ which contains two ‘rect’ elements, then the instance tree contains three SVGElementInstance objects, a root SVGElementInstance object whose correspondingElement is the SVGGElement object for the ‘g’, and then two child SVGElementInstance objects, each of which has its correspondingElement that is an SVGRectElement object.

If the referenced object is itself a ‘use’, or if there are ‘use’ subelements within the referenced object, the instance tree will contain recursive expansion of the indirect references to form a complete tree. For example, if a ‘use’ element references a ‘g’, and the ‘g’ itself contains a ‘use’, and that ‘use’ references a ‘rect’, then the instance tree for the original (outermost) ‘use’ will consist of a hierarchy of SVGElementInstance objects, as follows:

SVGElementInstance #1 (parentNode=null, firstChild=#2, correspondingElement is the 'g')
  SVGElementInstance #2 (parentNode=#1, firstChild=#3, correspondingElement is the other 'use')
    SVGElementInstance #3 (parentNode=#2, firstChild=null, correspondingElement is the 'rect')
interface SVGElementInstance : EventTarget {
  readonly attribute SVGElement correspondingElement;
  readonly attribute SVGUseElement correspondingUseElement;
  readonly attribute SVGElementInstance parentNode;
  readonly attribute SVGElementInstanceList childNodes;
  readonly attribute SVGElementInstance firstChild;
  readonly attribute SVGElementInstance lastChild;
  readonly attribute SVGElementInstance previousSibling;
  readonly attribute SVGElementInstance nextSibling;
};
Attributes:
correspondingElement (readonly SVGElement)
The corresponding element to which this object is an instance. For example, if a ‘use’ element references a ‘rect’ element, then an SVGElementInstance is created, with its correspondingElement being the SVGRectElement object for the ‘rect’ element.
correspondingUseElement (readonly SVGUseElement)
The corresponding ‘use’ element to which this SVGElementInstance object belongs. When ‘use’ elements are nested (e.g., a ‘use’ references another ‘use’ which references a graphics element such as a ‘rect’), then the correspondingUseElement is the outermost ‘use’ (i.e., the one which indirectly references the ‘rect’, not the one with the direct reference).
parentNode (readonly SVGElementInstance)
The parent of this SVGElementInstance within the instance tree. All SVGElementInstance objects have a parent except the SVGElementInstance which corresponds to the element which was directly referenced by the ‘use’ element, in which case parentNode is null.
childNodes (readonly SVGElementInstanceList)
An SVGElementInstanceList that contains all children of this SVGElementInstance within the instance tree. If there are no children, this is an SVGElementInstanceList containing no entries (i.e., an empty list).
firstChild (readonly SVGElementInstance)
The first child of this SVGElementInstance within the instance tree. If there is no such SVGElementInstance, this returns null.
lastChild (readonly SVGElementInstance)
The last child of this SVGElementInstance within the instance tree. If there is no such SVGElementInstance, this returns null.
previousSibling (readonly SVGElementInstance)
The SVGElementInstance immediately preceding this SVGElementInstance. If there is no such SVGElementInstance, this returns null.
nextSibling (readonly SVGElementInstance)
The SVGElementInstance immediately following this SVGElementInstance. If there is no such SVGElementInstance, this returns null.

5.11.10 Interface SVGElementInstanceList

The SVGElementInstanceList interface provides the abstraction of an ordered collection of SVGElementInstance objects, without defining or constraining how this collection is implemented.
interface SVGElementInstanceList {

  readonly attribute unsigned long length;

  SVGElementInstance item(in unsigned long index);
};
Attributes:
length (readonly unsigned long)
The number of SVGElementInstance objects in the list. The range of valid child indices is 0 to length-1 inclusive.
Operations:
SVGElementInstance item(in unsigned long index)
Returns the indexth item in the collection. If index is greater than or equal to the number of nodes in the list, this returns null.
Parameters
  1. unsigned long index
    Index into the collection.
Returns
The SVGElementInstance object at the indexth position in the SVGElementInstanceList, or null if that is not a valid index.

5.11.11 Interface SVGImageElement

The SVGImageElement interface corresponds to the ‘image’ element.
interface SVGImageElement : SVGElement,
                            SVGURIReference,
                            SVGTests,
                            SVGLangSpace,
                            SVGExternalResourcesRequired,
                            SVGStylable,
                            SVGTransformable {
  readonly attribute SVGAnimatedLength x;
  readonly attribute SVGAnimatedLength y;
  readonly attribute SVGAnimatedLength width;
  readonly attribute SVGAnimatedLength height;
  readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio;
};
Attributes:
x (readonly SVGAnimatedLength)
Corresponds to attribute ‘x’ on the given ‘image’ element.
y (readonly SVGAnimatedLength)
Corresponds to attribute ‘y’ on the given ‘image’ element.
width (readonly SVGAnimatedLength)
Corresponds to attribute ‘width’ on the given ‘image’ element.
height (readonly SVGAnimatedLength)
Corresponds to attribute ‘height’ on the given ‘image’ element.
preserveAspectRatio (readonly SVGAnimatedPreserveAspectRatio)
Corresponds to attribute ‘preserveAspectRatio’ on the given ‘image’ element.

5.11.12 Interface SVGSwitchElement

The SVGSwitchElement interface corresponds to the ‘switch’ element.
interface SVGSwitchElement : SVGElement,
                             SVGTests,
                             SVGLangSpace,
                             SVGExternalResourcesRequired,
                             SVGStylable,
                             SVGTransformable {
};

5.11.13 Interface GetSVGDocument

This interface provides access to an SVG document embedded by reference in another DOM-based language. The expectation is that the interface is implemented on DOM objects that allow such SVG document references, such as the DOM Element object that corresponds to an HTML ‘object’ element. Such DOM objects are often also required to implement the EmbeddingElement defined in the Window specification [WINDOW].

This interface is deprecated and may be dropped from future versions of the SVG specification. Authors are suggested to use the contentDocument attribute on the EmbeddingElement interface to obtain a referenced SVG document, if that interface is available.

interface GetSVGDocument {
  SVGDocument getSVGDocument();
};
Operations:
SVGDocument getSVGDocument()

This method must return the Document object embedded content in an embedding element, or null if there is no document.

Note that this is equivalent to fetching the value of the EmbeddingElement::contentDocument attribute of the embedding element, if the EmbeddingElement interface is also implemented. The author is advised to check that the document element of the returned Document is indeed an ‘svg’ element instead of assuming that that will always be the case.

Returns
The Document object for the referenced document, or null if there is no document.
SVG 1.1 (Second Edition) – 16 August 2011Top ⋅ Contents ⋅ Previous ⋅ Next ⋅ Elements ⋅ Attributes ⋅ Properties
上一篇: 下一篇: