Skip to content

Commit 89d1ae7

Browse files
author
yunshi
committed
docs.dev: improve hyperlink.rst after code review
1 parent 90237e8 commit 89d1ae7

File tree

1 file changed

+166
-116
lines changed

1 file changed

+166
-116
lines changed

‎docs/dev/analysis/features/text/hyperlink.rst

Lines changed: 166 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -2,163 +2,213 @@
22
Hyperlink
33
=========
44

5-
Word allows hyperlinks to be placed in the document or existing objects to be
6-
turned into hyperlinks.
5+
Word allows hyperlinks to be placed in the document.
76

8-
Hyperlinks can point to a named object or range within the current document or
9-
to an external resource. Hyperlinks can contain multiple runs of text.
7+
Hyperlink may link to a external location, for example, as an url. It may link to
8+
a location within the document, for example, as a bookmark. These two cases are
9+
handled differently. Until today (03/2016), we support only external links.
1010

11+
Hyperlinks can contain multiple runs of text.
1112

1213
Candidate protocol
1314
------------------
1415

16+
The hyperlink feature supports only external links.
17+
1518
Add a simple hyperlink with text and url:
1619

17-
>>> hyperlink = paragraph.add_hyperlink(text='Google', url='http://google.com')
20+
>>> hyperlink = paragraph.add_hyperlink(text='Google', address='https://google.com')
21+
>>> hyperlink
22+
<docx.text.hyperlink.Hyperlink at 0x7f...>
1823
>>> hyperlink.text
1924
'Google'
20-
>>> hyperlink.url
21-
'http://google.com'
22-
>>> hyperlink.anchor
23-
None
24-
>>> len(hyperlink.runs)
25-
1
25+
>>> hyperlink.address
26+
'https://google.com'
27+
>>> hyperlink.runs
28+
[<docx.text.run.Run at 0x7f...>]
2629

2730
Add multiple runs to a hyperlink:
2831

29-
>>> hyperlink = paragraph.add_hyperlink(url='http://github.com')
32+
>>> hyperlink = paragraph.add_hyperlink(address='https://github.com')
3033
>>> hyperlink.add_run('A')
3134
>>> hyperlink.add_run('formatted').italic = True
3235
>>> hyperlink.add_run('link').bold = True
33-
>>> len(hyperlink.runs)
34-
3
35-
36-
Add a hyperlink pointing to a named range in the current document:
36+
>>> hyperlink.runs
37+
[<docx.text.run.Run at 0x7f...>,
38+
<docx.text.run.Run at 0x7fb...>,
39+
<docx.text.run.Run at 0x7fb...>]
3740

38-
>>> hyperlink = paragraph.add_hyperlink(text='Section 1', anchor='section1')
39-
>>> hyperlink.anchor
40-
'section1'
41-
>>> hyperlink.url
42-
None
41+
Retrieve a paragraph's content:
4342

44-
Turning an existing object into a hyperlink:
43+
>>> paragraph = document.add_paragraph('A plain paragraph having some ')
44+
>>> paragraph.add_run('link such as ')
45+
>>> paragraph.add_hyperlink(address='http://github.com', text='github')
46+
>>> paragraph.iter_p_content():
47+
[<docx.text.paragraph.Run at 0x7f...>,
48+
<docx.text.paragraph.Hyperlink at 0x7f...>]
4549

46-
>>> existing_object = document.add_paragraph('Some text')
47-
>>> hyperlink = existing_object.hyperlink(url='http://google.com')
48-
>>> hyperlink.text
49-
'Some text'
50-
>>> len(hyperlink.runs)
51-
1
5250

5351

5452
Specimen XML
5553
------------
5654

5755
.. highlight:: xml
5856

59-
A simple hyperlink to an external url::
60-
61-
<w:hyperlink r:id="rId9">
62-
<w:r>
63-
<w:rPr>
64-
<w:rStyle w:val="Hyperlink"/>
65-
</w:rPr>
66-
<w:t>Google</w:t>
67-
</w:r>
68-
</w:hyperlink>
69-
7057

71-
The relationship for the above url::
58+
External links
59+
~~~~~~~~~~~~~~
7260

73-
<Relationships xmlns="…">
74-
<Relationship Id="rId9" Mode="External" Target=http://google.com />
75-
</Relationships>
61+
An external link is specified by the attribute r:id. The location of the link
62+
is defined in the relationships part of the document.
7663

77-
A hyperlink to an internal named range::
64+
A simple hyperlink to an external url::
7865

79-
<w:hyperlink r:anchor="section1">
66+
<w:p>
8067
<w:r>
81-
<w:rPr>
82-
<w:rStyle w:val="Hyperlink"/>
83-
</w:rPr>
84-
<w:t>Google</w:t>
68+
<w:t xml:space="preserve">This is an external link to </w:t>
8569
</w:r>
86-
</w:hyperlink>
70+
<w:hyperlink r:id="rId4">
71+
<w:r>
72+
<w:rPr>
73+
<w:rStyle w:val="Hyperlink"/>
74+
</w:rPr>
75+
<w:t>Google</w:t>
76+
</w:r>
77+
</w:hyperlink>
78+
</w:p>
79+
80+
81+
The r:id="rId4" references the following relationship within the relationships
82+
part for the document document.xml.rels.::
83+
84+
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
85+
<Relationship Id="rId4" Mode="External"
86+
Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
87+
Target="http://google.com/"/>
88+
</Relationships>
8789

8890
A hyperlink with multiple runs of text::
8991

90-
<w:hyperlink r:id="rId2">
92+
<w:p>
93+
<w:hyperlink r:id="rId2">
94+
<w:r>
95+
<w:rPr>
96+
<w:rStyle w:val="Hyperlink"/>
97+
</w:rPr>
98+
<w:t>A</w:t>
99+
</w:r>
100+
<w:r>
101+
<w:rPr>
102+
<w:rStyle w:val="Hyperlink"/>
103+
<w:i/>
104+
</w:rPr>
105+
<w:t xml:space="preserve"> formatted</w:t>
106+
</w:r>
107+
<w:r>
108+
<w:rPr>
109+
<w:rStyle w:val="Hyperlink"/>
110+
<w:b/>
111+
</w:rPr>
112+
<w:t xml:space="preserve"> link</w:t>
113+
</w:r>
114+
</w:hyperlink>
115+
</w:p>
116+
117+
118+
Internal links
119+
~~~~~~~~~~~~~~
120+
121+
**Note that internal links are not supported.**
122+
123+
An internal link, that link to a location in the document, do not have the r:id attribute
124+
and is specified by the anchor attribute.
125+
The value of the anchor attribute is the name of a bookmark in the document.
126+
127+
Example::
128+
129+
<w:p>
91130
<w:r>
92-
<w:rPr>
93-
<w:rStyle w:val="Hyperlink"/>
94-
</w:rPr>
95-
<w:t>A</w:t>
131+
<w:t xml:space="preserve">This is an </w:t>
96132
</w:r>
133+
<w:hyperlink w:anchor="myAnchor">
134+
<w:r>
135+
<w:rPr>
136+
<w:rStyle w:val="Hyperlink"/>
137+
</w:rPr>
138+
<w:t>internal link</w:t>
139+
</w:r>
140+
</w:hyperlink>
141+
</w:p>
142+
143+
...
144+
145+
<w:p>
97146
<w:r>
98-
<w:rPr>
99-
<w:rStyle w:val="Hyperlink"/>
100-
<w:i/>
101-
</w:rPr>
102-
<w:t xml:space="preserve">formatted</w:t>
147+
<w:t xml:space="preserve">This is text with a </w:t>
103148
</w:r>
104-
<w:r>
105-
<w:rPr>
106-
<w:rStyle w:val="Hyperlink"/>
107-
<w:b/>
108-
</w:rPr>
109-
<w:t xml:space="preserve">link</w:t>
110-
</w:r>
111-
</w:hyperlink>
112-
149+
<w:bookmarkStart w:id="0" w:name="myAnchor"/>
150+
<w:r>
151+
<w:t>bookmark</w:t>
152+
</w:r>
153+
<w:bookmarkEnd w:id="0"/>
154+
</w:p>
113155

114-
Resources
115-
---------
116156

117-
* `Document Members (Word) on MSDN`_
118-
* `Hyperlink Members (Word) on MSDN`_
119-
* `Hyperlinks Members (Word) on MSDN`_
120-
* `Hyperlink Class (OpenXML.Office2010.CustomUI) on MSDN`_
121-
* `Hyperlink Class (OpenXML.Wordprocessing) on MSDN`_
122-
123-
124-
.. _Document Members (Word) on MSDN:
125-
http://msdn.microsoft.com/en-us/library/office/ff840898.aspx
126-
127-
.. _Hyperlink Members (Word) on MSDN:
128-
http://msdn.microsoft.com/en-us/library/office/ff195109.aspx
129-
130-
.. _Hyperlinks Members (Word) on MSDN:
131-
http://msdn.microsoft.com/en-us/library/office/ff192421.aspx
132-
133-
.. _Hyperlink Class (OpenXML.Office2010.CustomUI) on MSDN:
134-
http://msdn.microsoft.com/en-us/library/documentformat.openxml.office2010.customui.hyperlink.aspx
135-
136-
.. _Hyperlink Class (OpenXML.Wordprocessing) on MSDN:
137-
http://msdn.microsoft.com/en-us/library/documentformat.openxml.wordprocessing.hyperlink.aspx
138-
139-
140-
MS API
141-
------
142-
143-
The Hyperlinks property on Document holds references to hyperlink
144-
objects in the MS API.
145-
146-
Hyperlinks contain the following properties:
147-
148-
* Address
149-
* SubAddress
150-
* EmailSubject
151-
* ExtraInfoRequired
152-
* Range (In python-docx this would be the runs inside the hyperlink)
153-
* ScreenTip
154-
* Shape
155-
* Target (where to open the hyperlink. e.g. "_blank", "_left", "_top", "_self", "_parent" etc)
156-
* TextToDisplay
157-
* Type (msoHyperlinkRange, msoHyperlinkShape or msoHyperlinkInlineShape)
157+
Schema excerpt
158+
--------------
158159

160+
.. highlight:: xml
159161

160-
Spec references
161-
---------------
162+
::
163+
164+
<xsd:complexType name="CT_P">
165+
<xsd:sequence>
166+
<xsd:element name="pPr" type="CT_PPr" minOccurs="0"/>
167+
<xsd:group ref="EG_PContent" minOccurs="0" maxOccurs="unbounded"/>
168+
</xsd:sequence>
169+
<xsd:attribute name="rsidRPr" type="ST_LongHexNumber"/>
170+
<xsd:attribute name="rsidR" type="ST_LongHexNumber"/>
171+
<xsd:attribute name="rsidDel" type="ST_LongHexNumber"/>
172+
<xsd:attribute name="rsidP" type="ST_LongHexNumber"/>
173+
<xsd:attribute name="rsidRDefault" type="ST_LongHexNumber"/>
174+
</xsd:complexType>
175+
176+
<xsd:complexType name="CT_Hyperlink">
177+
<xsd:group ref="EG_PContent" minOccurs="0" maxOccurs="unbounded"/>
178+
<xsd:attribute name="tgtFrame" type="s:ST_String" use="optional"/>
179+
<xsd:attribute name="tooltip" type="s:ST_String" use="optional"/>
180+
<xsd:attribute name="docLocation" type="s:ST_String" use="optional"/>
181+
<xsd:attribute name="history" type="s:ST_OnOff" use="optional"/>
182+
<xsd:attribute name="anchor" type="s:ST_String" use="optional"/>
183+
<xsd:attribute ref="r:id"/>
184+
</xsd:complexType>
185+
186+
<xsd:group name="EG_PContent"> <!-- denormalized -->
187+
<xsd:choice>
188+
<xsd:element name="r" type="CT_R"/>
189+
<xsd:element name="hyperlink" type="CT_Hyperlink"/>
190+
<xsd:element name="fldSimple" type="CT_SimpleField"/>
191+
<xsd:element name="sdt" type="CT_SdtRun"/>
192+
<xsd:element name="customXml" type="CT_CustomXmlRun"/>
193+
<xsd:element name="smartTag" type="CT_SmartTagRun"/>
194+
<xsd:element name="dir" type="CT_DirContentRun"/>
195+
<xsd:element name="bdo" type="CT_BdoContentRun"/>
196+
<xsd:element name="subDoc" type="CT_Rel"/>
197+
<xsd:group ref="EG_RunLevelElts"/>
198+
</xsd:choice>
199+
</xsd:group>
200+
201+
<xsd:complexType name="CT_R">
202+
<xsd:sequence>
203+
<xsd:group ref="EG_RPr" minOccurs="0"/>
204+
<xsd:group ref="EG_RunInnerContent" minOccurs="0" maxOccurs="unbounded"/>
205+
</xsd:sequence>
206+
<xsd:attribute name="rsidRPr" type="ST_LongHexNumber"/>
207+
<xsd:attribute name="rsidDel" type="ST_LongHexNumber"/>
208+
<xsd:attribute name="rsidR" type="ST_LongHexNumber"/>
209+
</xsd:complexType>
210+
211+
<xsd:simpleType name="ST_RelationshipId">
212+
<xsd:restriction base="xsd:string"/>
213+
</xsd:simpleType>
162214

163-
* 17.16.17 hyperlink (Hyperlink)
164-
* 2.3.61 CT_Hyperlink

0 commit comments

Comments
 (0)